@zefish/standard 🌿

L'intégration Standard est le socle technologique de l'écosystème Standard Garden. Elle fournit un framework cohérent pour le design, le rendu des contenus, la gestion des plugins ("spores") 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 Plugins/Spores (dynamiques, spécifiques au projet).

• Standard Integration (standard.js) : L'orchestrateur. Il gère l'auto-discovery des plugins, 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 (md/) : Moteur de rendu Markdown haut de gamme (basé sur markdown-it) avec support des runes, callouts Obsidian et typographie fine.
• Design System (design/) : Tokens de design mathématiques, échelles typographiques et système de couleurs OKLCH.

🔌 Système de Plugins (Spores)

Les plugins sont auto-découverts dans le dossier configuré (par défaut src/spores/).

Anatomie d'un plugin (*.plugin.js) :

export default {
  id: "nom-du-plugin",
  roots: {
    routes: [{ path: "/ma-route", entrypoint: "./routes/index.astro" }],
    styles: ["./styles.scss"], // CSS/SCSS injecté globalement
    scripts: ["./client-side.js"], // JS client injecté globalement
    middleware: "./middleware.js" // Middleware Astro (supporte l'ordre)
  },
  extensions: {
    "zone-ui": [{ 
      component: "./MonComposant.astro", 
      trigger: "toggle-event", // Optionnel
      meta: { title: "Mon Widget" } 
    }]
  }
};

Modules Virtuels :

• virtual:standard/config : Accès à la configuration finale fusionnée.
• virtual:standard/plugins : Liste de tous les plugins chargés (métadonnées + modules).
• virtual:standard/ui : Accès aux points d'extension UI pour injection dynamique.
• virtual:standard/middleware : Liste ordonnée des middlewares injectés.

🛠 Référence des Helpers (Core)

Importables via @zefish/standard/core/[nom_du_fichier].

Authentification (core/auth.js)

| Fonction | Signature | Description | | :--- | :--- | :--- | | signJWT | signJWT(payload, secret) | Signe un token JWT via Web Crypto API. | | verifyJWT | verifyJWT(token, secret) | Vérifie et décode un JWT. | | getSession | getSession(request, secret) | Extrait la session depuis les cookies. | | createSession | createSession(payload, secret) | Génère le header Set-Cookie. |

Browser & Client (core/browser.js & core/client.js)

| Fonction | Signature | Description | | :--- | :--- | :--- | | copyToClipboard | copyToClipboard(text) | Copie dans le presse-papier (avec fallback). | | emit | emit(name, detail) | Bus d'événements global (window.dispatchEvent). | | on | on(name, callback) | Écouteur d'événements global. | | standardGateView | standardGateView(view) | Ouvre une vue spécifique dans le Gate. | | standardGatePrompt | standardGatePrompt(text)| Ouvre le Gate avec un texte pré-rempli. |

Document Converter (core/document-converter.js)

| Fonction | Signature | Description | | :--- | :--- | :--- | | convertDocumentToMarkdown | convertDocumentToMarkdown(file) | Convertit DOCX, PDF, HTML ou RTF en Markdown. | | isSupportedDocument | isSupportedDocument(file) | Vérifie si le fichier est convertible. |

E-Ink Optimization (core/eink.js)

| Fonction | Signature | Description | | :--- | :--- | :--- | | initEInk | initEInk(options) | Initialise la détection et les styles E-Ink. | | toggleEInkMode | toggleEInkMode() | Bascule manuellement le mode E-Ink. |

Utils & Data (core/utils.js & core/slugify.js)

| Fonction | Signature | Description | | :--- | :--- | :--- | | slugify | slugify(text) | Slug robuste et universel. | | deepMerge | deepMerge(target, source) | Fusion profonde d'objets. | | getExcerpt | getExcerpt(content, opts) | Extrait un résumé (HTML/MD). | | formatDate | formatDate(date, format) | Formatage de dates multilingue. | | getReadingTime | getReadingTime(text) | Temps de lecture estimé. | | validateEmail | validateEmail(email) | Validation d'email simplifiée. |

Autres Helpers :

• core/cors.js : getCorsHeaders, handleCorsPreFlight.
• core/errors.js : Classes d'erreurs standardisées (StandardError, AuthError, etc.).
• core/filename.js : sanitizeFilename, makeUniqueFilename.
• core/logger.js : Système de log coloré (log.info, log.success, log.banner).
• core/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 (design/_standard-01-token.scss)

| Variable | Valeur par défaut | Description | | :--- | :--- | :--- | | --ratio-golden | 1.618 | Proportion d'or pour les mises en page. | | --ratio-silver | 1.414 | Proportion d'argent pour les échelles. | | --baseline | 1rlh | L'unité de base du rythme vertical. | | --space | var(--baseline) | Espacement de base. | | --space-[1-12] | var(--space) * n | Échelle d'espacement modulaire. | | --scale-[2-8] | modular scale | Échelle typographique exponentielle. | | --line-width | ~42rem | Largeur de lecture optimale (mesure). | | --radius | --leading | Rayon de bordure cohérent avec le rythme. |

🎨 Couleurs (design/_standard-02-color.scss)

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

| Token Sémantique | Description | | :--- | :--- | | --color-background | Fond de page (papier en clair, noir retro en sombre). | | --color-foreground | Couleur de texte principale. | | --color-accent | Couleur de marque/action (génère tout le reste). | | --color-surface | Couleur pour les cartes/conteneurs. | | --color-border | Bordures subtiles. | | --color-[green\|red\|yellow\|blue] | Couleurs pigmentaires dérivées de l'accent. | | --color-success\|error\|warning | États sémantiques. |

🛠 Breakpoints SCSS

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

💡 Notes pour l'IA

• Priorité Native : Utilisez toujours les fonctions natives d'Astro et les helpers Standard avant de recréer une logique.
• 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.