@stnd/core 0.1.0 → 0.22.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Francis Fontaine
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,236 @@
+---
+title: "@stnd/core"
+aliases: []
+created: 2026-06-20 13:56
+modified: 2026-07-15 10:20
+last_audited: 2026-07-14
+audit_interval_days: 90
+next_audit: 2026-10-12
+audit_priority: 3
+maturity: tree
+mode: read
+publish: false
+status: active
+tags:
+  - package
+  - stnd
+theme: kernel
+type: package
+visibility: private
+---
+
+# @[stnd](../README)/core
+
+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:**
+
+```javascript
+// 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 on `markdown-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`):
+
+```javascript
+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:
+
+- `virtual:stnd/hooks`: To execute **logic hooks** — `.js`/`.ts` entries not prefixed `launcher:` and not suffixed `:action` (those two patterns always classify as UI/action zone contributions instead — see `virtual:stnd/components` below — mismatched classification of the same hook name across registrations is a build-time fatal error). Two calling conventions over the same `hooks:` registrations: `runHook(name, ...args)` fans a call out to every registered handler and collects their results into an array (e.g. `astro:build:done`, `stnd:rss:register`); `runPipeline(name, initialValue, ...args)` threads one value through every registered handler in sequence, each required to explicitly return the (possibly transformed) value — for "let each interested module inspect and optionally override the same thing" (e.g. `apps/stnd.gd`'s `note:render`, where password-gate overrides how a locked note renders without the route naming it). Both isolate handler failures — a throwing handler is logged and skipped, not left to abort the rest. Handlers registered with `server: true` are excluded from the client build of this virtual module — required for any handler touching server-only data (DB calls, secrets), since client-bundled consumers like `packages/launcher/launcher.ts` import from the same module; setting `server: true` on a `launcher:`/`:action`-classified entry is a fatal error rather than a silent no-op, since that pool has no SSR/client split.
+- `virtual:stnd/components`: Used by the `<Hook />` component for UI rendering, and read directly (`extensions[zone]`) by client code that needs callable functions, not just components — e.g. `launcher:action`/`graft:action` entries.
+
+**UI Consumption:**
+
+```astro
+import Hook from "@stnd/core/Hook.astro";
+<Hook id="header:top" />
+```
+
+---
+
+## 🛠 Helpers Reference (Core & Server)
+
+Importable via `@stnd/server/[filename]` or `@stnd/utils/[filename]`.
+
+### Authentication (`@stnd/server/auth.js`)
+
+| Function | Signature | Description |
+| :--- | :--- | :--- |
+| `signJWT` | `signJWT(payload, secret)` | Signs a JWT token via the Web Crypto API. |
+| `verifyJWT` | `verifyJWT(token, secret)` | Verifies and decodes a JWT. |
+| `getSession` | `getSession(request, secret)` | Extracts the session from cookies. |
+| `createSession` | `createSession(payload, secret)` | Generates the `Set-Cookie` header. |
+
+### 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. |
+| `--line-width` | `~42rem` | Optimal reading width (measure). |
+| `--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/`) or `core/` helpers. Astro components are reserved for rendering.
+- **Typography**: Respect vertical rhythm by using `var(--space-*)` for margins and `var(--scale-*)` for font sizes.
+
+## Notes / Observations
+
+*(jot down anything noticed here — quirks, gotchas, ideas)*
+
+---
+
+## Todo <!-- was "What's next — open" -->
+
+Part of the [Road to Public Release](../README.md#-road-to-public-release) (Phases 1–2). These roll up into [the project board](../../README.md#the-project-board).
+
+- [ ] **Purge dead dependencies** — `astro-icon`, `pdfjs-dist`, `html-to-md`, [priority:: 3] [token_scale:: 3] [created:: 2026-07-14] [area:: framework]
+      `dotenv`, `unist-util-visit`, `toposort`, `modern-normalize`, `dompurify`,       `linkedom`, `markdown-it*` are declared in `package.json` but not referenced       by core’s own code (press owns its own copies). Run `pnpm audit:depedencies`.
+- [ ] **`wrangler` is declared here, in press, and in bin** — one owner. [priority:: 3] [token_scale:: 3] [created:: 2026-07-14] [area:: framework]
+- [ ] **Silent no-op** — `prefetch` and `experimental.clientPrerender` set on the [priority:: 3] [token_scale:: 3] [created:: 2026-07-14] [area:: framework]
+      integration object at [standard.js:63](standard.js:63) do nothing (Astro       only reads `name` + `hooks` on an integration). Route through `updateConfig`       or remove.
+- [x] **Alias list is now dynamic** — derived from core’s declared `@stnd/*`
+      deps in `standard.js`, so it can never drift. `@stnd/icon` added to deps.
+- [x] **Delete `src/___collections.___js`** — done (disabled dead file removed).
+- [x] **Layering paradox resolved** — core is documented as the sanctioned
+      meta-package (its code imports only log + utils; it declares the rest). See       the Import Hierarchy note in [packages/README](../README.md#-import-hierarchy-strict).
+- [ ] **`adeSsrDeps` → `@stnd/cloudflare`** (not core) — decided during Phase 2: [priority:: 3] [token_scale:: 3] [created:: 2026-07-14] [area:: framework]
+      the SSR/workerd optimizeDeps fix belongs with the Cloudflare package, split       from the app-specific deps that stay in the app.
+
+## 🔗 Liens & Normes
+
+Ce paquet implémente les principes directeurs de l’écosystème Standard. Pour plus de détails sur le fonctionnement global, consultez les documents suivants :
+- **Architecture Système** : [4.1 Architecture](../../apps/stnd.build/modules/manual/content/4-system/4.1-architecture.md)
+- **Principes de Code** : [4.2 Code Standards](../../apps/stnd.build/modules/manual/content/4-system/4.2-code-standards.md)
+- **Normes de Documentation** : [4.9 Normes README](../../apps/stnd.build/modules/manual/content/4-system/4.9-readme-standard.md)
+- **Le Standard** : [packages/README.md](../README.md)
+- **Entrée Monorepo** : [README.md](../../README.md)

package/package.json

@@ -1,24 +1,101 @@
 {
   "name": "@stnd/core",
-  "version": "0.1.0",
+  "version": "0.22.1",
+  "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",
+  "license": "MIT",
+  "homepage": "https://github.com/ZeFish/Standard#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ZeFish/Standard.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ZeFish/Standard/issues"
+  },
+  "keywords": [
+    "standard",
+    "astro-integration"
+  ],
+  "main": "standard.js",
   "type": "module",
-  "main": "./src/index.ts",
-  "types": "./src/index.ts",
+  "svelte": "./Hook.svelte",
   "exports": {
-    ".": "./src/index.ts"
+    ".": "./standard.js",
+    "./Hook": {
+      "astro": "./Hook.astro",
+      "svelte": "./Hook.svelte",
+      "default": "./Hook.astro"
+    },
+    "./loader": "./src/loader.js",
+    "./virtual": "./src/virtual.js",
+    "./src/dev-toolbar/*": "./src/dev-toolbar/*",
+    "./types/*": "./types/*"
   },
-  "dependencies": {
-    "@stnd/log": "0.2.0",
-    "@stnd/utils": "0.2.0"
-  },
-  "devDependencies": {
-    "astro": "^5.0.0",
-    "@types/node": "^20.0.0"
+  "files": [
+    "standard.js",
+    "types",
+    "src"
+  ],
+  "browserslist": [
+    "> 1%",
+    "last 2 versions",
+    "not dead"
+  ],
+  "engines": {
+    "node": ">=14.0.0"
   },
   "publishConfig": {
     "access": "public"
   },
+  "directories": {
+    "example": "example"
+  },
+  "dependencies": {
+    "@astrojs/sitemap": "^3.7.3",
+    "@astrojs/svelte": "9.0.1",
+    "astro": "7.1.3",
+    "glob": "^13.0.6",
+    "svelte": "5.56.4",
+    "zod": "^4.4.3",
+    "@stnd/client": "0.5.0",
+    "@stnd/cloudflare": "0.5.0",
+    "@stnd/fonts": "0.5.0",
+    "@stnd/icon": "0.2.0",
+    "@stnd/lab": "1.0.0",
+    "@stnd/launcher": "1.0.0",
+    "@stnd/layout": "0.5.0",
+    "@stnd/log": "0.5.0",
+    "@stnd/modules": "0.5.1",
+    "@stnd/press": "0.7.0",
+    "@stnd/store": "0.5.0",
+    "@stnd/styles": "0.5.2",
+    "@stnd/themes": "0.5.1",
+    "@stnd/ui": "0.5.0",
+    "@stnd/utils": "0.5.0"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.61.1",
+    "@types/node": "^26.0.1",
+    "auto-changelog": "^2.6.0",
+    "happy-dom": "^20.10.6",
+    "knip": "^6.23.0",
+    "prettier": "^3.9.1",
+    "prettier-plugin-astro": "^0.14.1",
+    "prettier-plugin-svelte": "^4.1.1",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.9"
+  },
+  "types": "./types/standard.d.ts",
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "build": "echo 'No build step required for core integration library'",
+    "dev": "pnpm run clean:ports && astro dev",
+    "start": "astro dev",
+    "kill-node": "killall node || taskkill /F /IM node.exe",
+    "commit": "git add . && git commit",
+    "test": "pnpm run test:lib",
+    "test:lib": "vitest run",
+    "audit:depedencies": "knip && ncu",
+    "clean:depedencies": "knip --fix --include dependencies,devDependencies",
+    "clean:ports": "lsof -ti:8083 | xargs kill -9 2>/dev/null || true"
   }
 }

package/src/dev-toolbar/debug-toggle.js

@@ -0,0 +1,21 @@
+import { defineToolbarApp } from "astro/toolbar";
+
+export default defineToolbarApp({
+  init(canvas, app) {
+    // Restore previous debug state
+    const wasActive = sessionStorage.getItem("stnd-debug-mode") === "true";
+    if (wasActive) {
+      document.documentElement.classList.add("stnd-debug");
+    }
+
+    app.onToggled(({ state }) => {
+      if (state) {
+        document.documentElement.classList.add("stnd-debug");
+        sessionStorage.setItem("stnd-debug-mode", "true");
+      } else {
+        document.documentElement.classList.remove("stnd-debug");
+        sessionStorage.setItem("stnd-debug-mode", "false");
+      }
+    });
+  },
+});

package/src/dev-toolbar/lab-toggle.js

@@ -0,0 +1,153 @@
+import { defineToolbarApp } from "astro/toolbar";
+
+/**
+ * Resilient Lab toggle
+ *
+ * Behavior:
+ * - If `window.StandardLab` is present, open the quick panel immediately.
+ * - Otherwise, attempt a dynamic import of the lab client (best-effort),
+ *   and wait briefly for the global to become available before opening.
+ * - Always toggle the toolbar state back off (momentary action).
+ */
+function waitForStandardLab(timeout = 3000, interval = 100) {
+  return new Promise((resolve, reject) => {
+    const start = Date.now();
+    const check = () => {
+      if (window.StandardLab) return resolve(window.StandardLab);
+      if (Date.now() - start >= timeout)
+        return reject(new Error("StandardLab not available within timeout"));
+      setTimeout(check, interval);
+    };
+    check();
+  });
+}
+
+export default defineToolbarApp({
+  init(canvas, app) {
+    // Poller handle (fallback if StandardLab doesn't emit events)
+    let stateWatcher = null;
+    // When toggles are triggered programmatically we should suppress
+    // the onToggled handler to avoid re-entrancy loops.
+    let suppressToggleHandler = false;
+
+    function startPoller() {
+      if (stateWatcher) return;
+      // Skip the first sample to avoid a race with initialization events
+      let grace = true;
+      stateWatcher = setInterval(() => {
+        if (!window.StandardLab) return;
+        if (grace) {
+          // Give the client a moment to initialize and emit its state event
+          grace = false;
+          return;
+        }
+        if (window.StandardLab.state === "dormant") {
+          clearInterval(stateWatcher);
+          stateWatcher = null;
+          // Ensure programmatic toggle doesn't re-enter the handler
+          suppressToggleHandler = true;
+          app.toggleState({ state: false });
+          setTimeout(() => (suppressToggleHandler = false), 0);
+        } else {
+          // Keep toolbar toggled while lab is open
+          suppressToggleHandler = true;
+          app.toggleState({ state: true });
+          setTimeout(() => (suppressToggleHandler = false), 0);
+        }
+      }, 250);
+    }
+
+    function clearPoller() {
+      if (stateWatcher) {
+        clearInterval(stateWatcher);
+        stateWatcher = null;
+      }
+    }
+
+    // Listen for StandardLab state events (if the client emits them)
+    const globalStateListener = (e) => {
+      const s = e?.detail?.state;
+      if (s === "dormant") {
+        clearPoller();
+        // Suppress the onToggled handler while we programmatically toggle the button
+        suppressToggleHandler = true;
+        app.toggleState({ state: false });
+        setTimeout(() => (suppressToggleHandler = false), 0);
+      } else if (s === "quick" || s === "full") {
+        // Suppress the onToggled handler while we programmatically toggle the button
+        suppressToggleHandler = true;
+        app.toggleState({ state: true });
+        setTimeout(() => (suppressToggleHandler = false), 0);
+        startPoller();
+      }
+    };
+    window.addEventListener("standardlab:state", globalStateListener);
+
+    // Initial sync: if the lab is already open, reflect that in the toolbar
+    if (
+      window.StandardLab &&
+      window.StandardLab.state &&
+      window.StandardLab.state !== "dormant"
+    ) {
+      app.toggleState({ state: true });
+      startPoller();
+    }
+
+    app.onToggled(({ state }) => {
+      // If this toggle came from our own programmatic updates, ignore it
+      if (suppressToggleHandler) return;
+      if (state) {
+        (async () => {
+          try {
+            // The Svelte Lab island (<Lab client:load />) provides
+            // window.StandardLab automatically. If it hasn't hydrated
+            // yet, wait briefly for it.
+            if (
+              !window.StandardLab ||
+              typeof window.StandardLab.openQuick !== "function"
+            ) {
+              await waitForStandardLab(3000, 100);
+            }
+
+            if (
+              window.StandardLab &&
+              typeof window.StandardLab.openQuick === "function"
+            ) {
+              window.StandardLab.openQuick();
+            } else {
+              console.warn(
+                "[Standard Lab] Instance not available. Ensure <Lab client:load /> is mounted.",
+              );
+              suppressToggleHandler = true;
+              app.toggleState({ state: false });
+              setTimeout(() => (suppressToggleHandler = false), 0);
+              return;
+            }
+
+            // Ensure we keep the toolbar toggled while the lab is open
+            startPoller();
+          } catch (err) {
+            console.warn("[Standard Lab] Error while trying to open:", err);
+            suppressToggleHandler = true;
+            app.toggleState({ state: false });
+            setTimeout(() => (suppressToggleHandler = false), 0);
+          }
+        })();
+      } else {
+        // User toggled the toolbar off -> close the lab (if open) and stop syncing
+        if (
+          window.StandardLab &&
+          typeof window.StandardLab.close === "function" &&
+          window.StandardLab.state !== "dormant"
+        ) {
+          try {
+            window.StandardLab.close();
+          } catch (err) {
+            console.warn("[Standard Lab] Error while trying to close:", err);
+          }
+        }
+        clearPoller();
+      }
+    });
+  },
+});