@stnd/core

The Standard core integration is the technological foundation of the Utopie ecosystem. It provides a coherent framework for design, content rendering, module management, and server utilities.

This document serves as a technical reference for developers and AI agents working on the project.

ELI5

This is the one line you put in every Standard site’s astro.config.mjs. It does the heavy lifting so nothing else has to: finds your feature folders (modules/), wires up styles/fonts/SEO automatically (the “Gold Standard”), and makes every other @stnd/* package available without extra setup. Think of it as the light socket every appliance plugs into.

Install: pnpm add @stnd/core (or use stnd new — see packages/cli).

Use it:

// astro.config.mjs
import { defineConfig } from "astro/config";
import standard from "@stnd/core";

export default defineConfig({
  integrations: [standard({ title: "My Site" })],
});

That’s the whole setup. Styling, fonts, SEO basics, and the command palette are already on. Add your own feature folders under modules/ and they’re picked up automatically.

Architecture

The concept relies on a strict separation between the Core (static, tested) and Modules/Spores (dynamic, project-specific).

• Standard Integration (standard.js): The orchestrator. It manages the auto-discovery of modules, injects routes and styles, and configures virtual modules.
• Core Helpers (core/): Libraries of pure functions for authentication, formatting, logging, and data manipulation.
• Press Engine (@stnd/press): High-end Markdown rendering engine (based on markdown-it) with support for runes, Obsidian callouts, and fine typography.
• Design System (@stnd/styles): Mathematical design tokens, typographic scales, and the OKLCH color system.

🔌 Module System (Spores)

Modules are auto-discovered and orchestrate both logic and interface via a Unified Hooks system.

Anatomy of a module (index.module.js):

export default {
  id: "module-name",

  // Hooks: The brain of the module
  // - .js, .ts -> LOGIC (e.g., astro hooks, app events)
  // - .astro, .svelte, .md -> INTERFACE (e.g., header, footer)
  hooks: {
    "astro:config:setup": "./hooks/setup.js", // Astro logic
    "header:top": "./components/Banner.astro", // UI injection point
    "app:init": ["./init.ts", "./Widget.astro"], // Mixed is possible
  },

  routes: [{ path: "/my-route", entrypoint: "./routes/index.astro" }],
  styles: ["./styles.scss"],
  scripts: ["./client-side.js"],
  middleware: "./middleware.js",
};

Virtual Modules & Rendering:

• virtual:stnd/hooks: To execute logic (runHook).
• virtual:stnd/components: Used by the <Hook /> component for UI rendering.

UI Consumption:

import Hook from "@stnd/core/Hook.astro";
<Hook id="header:top" />

🛠 Helpers Reference (Core & Server)

Importable via @stnd/server/[filename] or @stnd/utils/[filename].

Authentication (@stnd/server/auth.js)

Browser & Client (@stnd/client)

Document Converter (@stnd/ingest)

E-Ink Optimization (@stnd/client/eink.js)

Utils & Data (@stnd/utils/index.js & @stnd/utils/slugify.js)

Other Helpers:

• @stnd/server/cors.js: getCorsHeaders, handleCorsPreflight.
• @stnd/server/errors.js: Standardized error classes (StandardError, AuthError, etc.).
• @stnd/server/filename.js: sanitizeFilename, makeUniqueFilename.
• @stnd/log: Scoped color logging system (log.info, log.success, log.banner).
• @stnd/core/src/collections.js: defineStandardCollection (Astro Content Layer helper).

🎨 Design Tokens (CSS Variables)

The system uses CSS variables (--stnd-* or root variables :root) for consistency.

📐 Geometry & Rhythm (packages/styles/_standard-01-token.scss)

🎨 Colors (packages/styles/_standard-02-color.scss)

OKLCH-based system generating harmony from --color-accent.

🛠 SCSS Breakpoints

• $mobile: 600px
• $small: 768px
• $large: 1024px
• $wide: 1440px

💡 Notes for AI

• Module Integration: Standardized on “Module” terminology (formerly Folios/Spores).
• Actions: Core actions are now fully decanted into their respective modules and aggregated via virtual:stnd/actions.
• Data Model: Business logic belongs in models (model/) or core/ helpers. Astro components are reserved for rendering.
• Typography: Respect vertical rhythm by using var(--space-*) for margins and var(--scale-*) for font sizes.

Notes / Observations

(jot down anything noticed here — quirks, gotchas, ideas)

Todo

Part of the Road to Public Release (Phases 1–2). These roll up into the project board.

• [ ] Purge dead dependencies — astro-icon, pdfjs-dist, html-to-md,
  dotenv, unist-util-visit, toposort, modern-normalize, dompurify, linkedom, markdown-it* are declared in package.json but not referenced by core’s own code (press owns its own copies). Run pnpm audit:depedencies.
• [ ] wrangler is declared here, in press, and in bin — one owner.
• [ ] Silent no-op — prefetch and experimental.clientPrerender set on the
  integration object at standard.js:63 do nothing (Astro only reads name + hooks on an integration). Route through updateConfig or remove.
• [x] Alias list is now dynamic — derived from core’s declared @stnd/*
  deps in standard.js, so it can never drift. @stnd/icon added to deps.
• [x] Delete src/___collections.___js — done (disabled dead file removed).
• [x] Layering paradox resolved — core is documented as the sanctioned
  meta-package (its code imports only log + utils; it declares the rest). See the Import Hierarchy note in packages/README.
• [ ] adeSsrDeps → @stnd/cloudflare (not core) — decided during Phase 2:
  the SSR/workerd optimizeDeps fix belongs with the Cloudflare package, split from the app-specific deps that stay in the app.

🔗 Liens & Normes

Ce paquet implémente les principes directeurs de l’écosystème Standard. Pour plus de détails sur le fonctionnement global, consultez les documents suivants :

• Architecture Système : 4.1 Architecture
• Principes de Code : 4.2 Code Standards
• Normes de Documentation : 4.9 Normes README
• Le Standard : packages/README.md
• Entrée Monorepo : README.md