@stnd/core
Circle 1 — Core Framework (Inviolable Pillar) · Stable · Load-Bearing
Role: Application engine, Astro integration (
standard()), vertical-slice module loader, and virtual hooks (virtual:stnd/hooks).When to use: Every Standard app boots through
@stnd/coreinastro.config.mjs. See also Building a Module and Hooks.
Quick Start (TL;DR)
// astro.config.mjs
import { defineConfig } from "astro/config";
import standard from "@stnd/core";
export default defineConfig({ integrations: [standard()] });
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 onmarkdown-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
The module loader compiles hooks: registrations into two dedicated virtual modules based on entry classification:
| Virtual Module | Entry Classification | Primary Consumers |
|---|---|---|
virtual:stnd/hooks |
Logic hooks — .js / .ts entries (excluding launcher:* and *:action) |
runHook() and runPipeline() |
virtual:stnd/components |
UI & action zones — .astro / .svelte / .md components, plus all launcher:* and *:action entries |
<Hook zone="..." /> and extensions[zone] |
Calling Conventions (virtual:stnd/hooks)
- Fan-out (
runHook(name, ...args)): Calls every registered handler fornameand collects their return values into an array (e.g.astro:build:done,stnd:rss:register). - Sequential Pipeline (
runPipeline(name, initialValue, ...args)): Threads a single value through every registered handler in sequence. Each handler must explicitly return the (optionally transformed) value — ideal when modules inspect and override a shared descriptor (e.g.note:renderinapps/stnd.gd).
Isolation & Bundling Guarantees
- Failure Isolation: Both
runHookandrunPipelineisolate handler exceptions — a throwing handler is logged and skipped so it cannot abort sibling handlers. - Server-Only Filtering (
server: true): Handlers marked withserver: trueare stripped from the client bundle ofvirtual:stnd/hooks. Use this for any handler touching databases or secrets when client modules (like@stnd/launcher) also import fromvirtual:stnd/hooks. - Build-Time Classification Guards:
- Registering the same hook name as both a logic hook and a UI/action zone across modules throws a build-time fatal error (
hook-kind-mismatch). - Setting
server: trueon alauncher:*or*:actionentry throws a build-time fatal error (hook-server-flag-ignored), sincevirtual:stnd/componentshas no SSR/client split.
- Registering the same hook name as both a logic hook and a UI/action zone across modules throws a build-time fatal error (
UI Consumption
---
import Hook from "@stnd/core/Hook.astro";
---
<Hook zone="header:top" />
Helpers Reference (Core & Server)
Importable via @stnd/server/[filename] or @stnd/utils/[filename].
Browser & Client (@stnd/client)
| Function | Signature | Description |
|---|---|---|
copyToClipboard |
copyToClipboard(text) |
Copies to clipboard (with fallback). |
emit |
emit(name, detail) |
Global event bus (window.dispatchEvent). |
on |
on(name, callback) |
Global event listener. |
standardGateView |
standardGateView(view) |
Opens a specific view in the Gate. |
standardGatePrompt |
standardGatePrompt(text) |
Opens the Gate with pre-filled text. |
Document Converter (@stnd/ingest)
| Function | Signature | Description |
|---|---|---|
convertDocumentToMarkdown |
convertDocumentToMarkdown(file) |
Converts DOCX, PDF, HTML, or RTF into Markdown. |
isSupportedDocument |
isSupportedDocument(file) |
Checks if the file is convertible. |
E-Ink Optimization (@stnd/client/eink.js)
| Function | Signature | Description |
|---|---|---|
initEInk |
initEInk(options) |
Initializes E-Ink detection and styles. |
toggleEInkMode |
toggleEInkMode() |
Manually toggles E-Ink mode. |
Utils & Data (@stnd/utils/index.js & @stnd/utils/slugify.js)
| Function | Signature | Description |
|---|---|---|
slugify |
slugify(text) |
Robust and universal slugifier. |
deepMerge |
deepMerge(target, source) |
Deeply merges objects. |
getExcerpt |
getExcerpt(content, opts) |
Extracts a summary (HTML/MD). |
formatDate |
formatDate(date, format) |
Multilingual date formatting. |
getReadingTime |
getReadingTime(text) |
Estimated reading time. |
validateEmail |
validateEmail(email) |
Simplified email validation. |
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)
| Variable | Default Value | Description |
|---|---|---|
--ratio-golden |
1.618 |
Golden Ratio for layouts. |
--ratio-silver |
1.414 |
Silver Ratio for scales. |
--baseline |
1rlh |
Base unit of vertical rhythm. |
--space |
var(--baseline) |
Base spacing. |
--space-[1-12] |
var(--space) * n |
Modular spacing scale. |
--scale-[2-8] |
modular scale |
Exponential typographic scale. |
--page-max-width |
1400px |
Page container maximum width constraint. |
--page-padding |
clamp(1rem, 3vw, 2.5rem) |
Fluid horizontal page gutters. |
--prose-width |
~42rem |
Optimal reading width (measure). |
--rhythm-block-scale |
2 |
Multiplier for non-text block elements. |
--radius |
--leading |
Border radius consistent with rhythm. |
Colors (packages/styles/_standard-02-color.scss)
OKLCH-based system generating harmony from --color-accent.
| Semantic Token | Description |
|---|---|
--color-background |
Canvas background (paper in light, retro black in dark). |
--color-foreground |
Primary text color. |
--color-accent |
Brand/action color (generates all other colors). |
--color-surface |
Card/container background. |
--color-border |
Subtle borders. |
--color-[green|red|yellow|blue] |
Pigment colors derived from accent. |
--color-success|error|warning |
Semantic states. |
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/) orcore/helpers. Astro components are reserved for rendering. - Typography: Respect vertical rhythm by using
var(--space-*)for margins andvar(--scale-*)for font sizes.
Links & Standards
This package implements the core architectural principles of the Standard ecosystem. For further details on how the framework operates globally, see:
- System Architecture: Framework Guide & Invariants
- Engineering Philosophy: Engineering Philosophy
- Package Ecosystem: packages/README.md
- Monorepo Root: README.md