@stnd/core 🌿

L’intégration Standard est le socle technologique de l’écosystème Utopie. Elle fournit un framework cohérent pour le design, le rendu des contenus, la gestion des modules et des utilitaires serveurs.

Ce document sert de référence technique pour les développeurs et les agents IA travaillant sur le projet.

🏗 Structure de l’Architecture

Le concept repose sur une séparation stricte entre le Core (statique, testé) et les Modules/Spores (dynamiques, spécifiques au projet).

• Standard Integration (standard.js) : L’orchestrateur. Il gère l’auto-discovery des modules, injecte les routes, les styles et configure les modules virtuels.
• Core Helpers (core/) : Bibliothèques de fonctions pures pour l’authentification, le formatage, la journalisation et les manipulations de données.
• Press Engine (@stnd/press) : Moteur de rendu Markdown haut de gamme (basé sur markdown-it) avec support des runes, callouts Obsidian et typographie fine.
• Design System (@stnd/styles) : Tokens de design mathématiques, échelles typographiques et système de couleurs OKLCH.

🔌 Système de Modules (Spores)

Les modules sont auto-découverts et orchestrent à la fois la logique et l’interface via un système de Hooks Unifiés.

Anatomie d’un module (index.module.js) :

export default {
  id: “nom-du-module”,

  // Hooks : Le cerveau du module
  // – .js, .ts → LOGIQUE (ex: astro hooks, app events)
  // – .astro, .svelte, .md → INTERFACE (ex: header, footer)
  hooks: {
    “astro:config:setup”: “./hooks/setup.js”, // Logique Astro
    “header:top”: “./components/Banner.astro”, // Point d’injection UI
    “app:init”: [“./init.ts”, “./Widget.astro”], // Mixte possible
  },

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

Modules Virtuels & Rendu :

• virtual:standard/hooks : Pour exécuter la logique (runHook).
• virtual:standard/components : Utilisé par le composant <Hook /> pour le rendu UI.

Consommation UI :

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

🛠 Référence des Helpers (Core & Server)

Importables via @stnd/server/[nom_du_fichier] ou @stnd/utils/[nom_du_fichier].

Authentification (@stnd/server/auth.js)

Browser & Client (@stnd/client)

Document Converter (@stnd/server/document-converter.js)

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

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

Autres Helpers :

• @stnd/server/cors.js : getCorsHeaders, handleCorsPreFlight.
• @stnd/server/errors.js : Classes d’erreurs standardisées (StandardError, AuthError, etc.).
• @stnd/server/filename.js : sanitizeFilename, makeUniqueFilename.
• @stnd/log : Système de log coloré (log.info, log.success, log.banner).
• @stnd/core/src/collections.js : defineStandardCollection (Astro Content Layer helper).

🎨 Design Tokens (CSS Variables)

Le système utilise des variables CSS (—stnd-* ou variables racines :root) pour la cohérence.

📐 Géométrie & Rythme (packages/styles/_standard-01-token.scss)

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

Système basé sur OKLCH générant une harmonie à partir de —color-accent.

🛠 Breakpoints SCSS

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

💡 Notes pour l’IA

• Module Integration: Standardized on “Module” terminology (formerly Folios/Spores).
• Actions: Core actions are now fully decanted into their respective modules and aggregated via virtual:standard/actions.
• Modèle de Données : La logique métier doit être dans les modèles (model/) ou les helpers core/. Les composants Astro sont réservés à l’affichage.
• Typographie : Respectez le rythme vertical en utilisant var(—space-*) pour les marges et var(—scale-*) pour les tailles de police.