npm package: @stnd/astro
Description: A fine-art typography framework implementing classical design principles, mathematical precision with the golden ratio, and micro-typography rules inspired by the masters of print design.
Author: Francis Fontaine
Latest version: 0.19.0

# @stnd/astro 🌿

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`) :
```javascript
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 `@stnd/utils/[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
- **Plugin Integration**: Standardized on "Plugin" terminology (formerly Spores).
- **Actions**: Core actions are now fully decanted into their respective plugins 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.