stnd.build

@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/core in astro.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).


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)

Isolation & Bundling Guarantees

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


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


Notes for AI

This package implements the core architectural principles of the Standard ecosystem. For further details on how the framework operates globally, see: