@stnd/modules 0.5.1 → 0.5.2

package/README.md

@@ -2,21 +2,24 @@
 title: "@stnd/modules"
 aliases: []
 created: 2026-07-04 23:28
-modified: 2026-07-05 19:23
+modified: 2026-09-16T17:28:28.771Z
 last_audited: 2026-07-14
 audit_interval_days: 90
 next_audit: 2026-10-12
 audit_priority: 3
 maturity: tree
 mode: read
-publish: false
+publish: true
 status: active
 tags:
   - package
   - stnd
 theme: kernel
 type: package
-visibility: private
+visibility: public
+garden-url: https://standard.garden/@francis/readme
+garden-short: https://stnd.gd/wAgx4e
+permalink: readme
 ---
 
 # @[stnd](../README)/modules
@@ -58,11 +61,20 @@ environment?: string | string[]
 
 // Unified Hooks (Logic & Interface)
 // ---------------------------------------------------------------------------
-// Standard automatically routes hooks based on their file extension:
-// - .js, .ts             -> LOGIC  (Listeners / Handlers)
-// - .astro, .svelte, .md -> UI     (Components / Plugs)
+// A hook name resolves to one of two kinds — never both, for the same name:
+// - LOGIC (virtual:stnd/hooks, runHook/runPipeline): the name starts with
+//   "astro:" (Astro's own lifecycle), OR the entry is a .js/.ts path and the
+//   name doesn't start with "launcher:" or end in ":action".
+// - UI/action zone (virtual:stnd/components, <Hook zone="..."> + direct
+//   extensions[zone] reads): everything else — .astro/.svelte/.md paths,
+//   and any "launcher:"/":action" name regardless of file type.
 //
-// These can be a single string or an array of entries.
+// Two modules registering the same hook name as different kinds is a
+// build-time fatal error (hook-kind-mismatch), not a silent split.
+//
+// These can be a single string (shorthand for `{ ui: "path" }`) or an array
+// of entries (`{ ui: "..." }` / `{ action: "..." }`, or `component` for
+// backward-compat with `ui`).
 hooks?: {
   [hookName: string]: string | Array<string | HookEntry>
 }
@@ -110,34 +122,24 @@ dependencies?: string[]
 
 ## Unified Hooks Architecture
 
-The `hooks` object is the brain of your module. It handles both system events and UI injection.
-
-### 1. Integration Hooks (Logic)
-
-If the hook name starts with `astro:` or the entry ends in `.js`/`.ts`, it’s treated as logic.
+The `hooks` object is the brain of your module. It handles both system events and UI injection — see [Hooks & Extension Points](https://stnd.build/manual/modules/hooks) in the manual for the full walkthrough and the native hooks the framework ships with. Quick reference:
 
 ```javascript
 // index.module.js
 export default {
   id: "my-feature",
   hooks: {
-    "astro:config:setup": "./hooks/setup.js", // Astro native hook
-    "app:init": "./hooks/init.ts", // Custom app hook
-  },
-};
-```
-
-### 2. Interface Hooks (UI Plugs)
+    // UI into zones (use `ui` key, or a bare string as shorthand for it)
+    "stnd:base":   ["./components/Banner.astro"],
+    "stnd:client": [{ ui: "./Drawer.svelte", meta: { "client:load": true } }],
 
-If the entry ends in `.astro`, `.svelte`, `.md`, or any other format, it’s treated as a UI component.
+    // Lifecycle hooks and JS action handlers (use `action`)
+    "astro:build:done": [{ action: "./hooks/generate-feed.js" }],
+    "launcher:action":  [{ action: "./actions/nav.js" }],
 
-```javascript
-// index.module.js
-export default {
-  id: "my-feature",
-  hooks: {
-    "header:top": ["./components/Banner.astro"],
-    "footer:bottom": "./components/Copyright.astro",
+    // Launcher views — a `launcher:`-prefixed name is always UI/action,
+    // even though its entry is registered under `ui`
+    "launcher:view": [{ ui: "./views/ShareView.svelte", trigger: "::share", meta: { title: "Share" } }],
   },
 };
 ```
@@ -146,26 +148,25 @@ export default {
 
 **UI Rendering (Zones):**
 
-In your Layout or components, use the `<Hook />` component to render all registered components for a hook ID.
+In your Layout or components, use the `<Hook />` component to render every registered entry for a zone name — the prop is `zone`, not `id`.
 
 ```astro
 ---
 import Hook from "@stnd/core/Hook";
 ---
 
-<header>
-  <Hook id="header:top" props={{ theme: "dark" }} />
-</header>
+<Hook zone="stnd:base" />
+<Hook zone="stnd:client" hydrated props={{ theme: "dark" }} />
 ```
 
 **Logic Execution:**
 
-Trigger logic hooks via the virtual module.
+Trigger logic hooks via the virtual module — `runHook` fans out and collects every module's result; `runPipeline` threads one value through each handler in sequence.
 
 ```javascript
 import { runHook } from "virtual:stnd/hooks";
 
-await runHook("app:init", { some: "data" });
+const results = await runHook("astro:build:done", buildContext);
 ```
 
 ### Middleware
@@ -323,29 +324,53 @@ These built-in modules come with `@stnd/modules` and can be loaded via `moduleLo
 
 ### Gold Standard (loaded by default)
 
-Every `@stnd` site ships with these. Opt out via `moduleExclude`.
-
-| Module                   | ID              | Route               | What it does                                                       |
-| :----------------------- | :-------------- | :------------------ | :----------------------------------------------------------------- |
-| `@stnd/modules/styles`   | `stnd-styles`   | —                   | Injects the Standard design stylesheet                             |
-| `@stnd/modules/robots`   | `stnd-robots`   | `/robots.txt`       | Generates `robots.txt` from site config                            |
-| `@stnd/modules/headers`  | `stnd-headers`  | `/_headers`         | Emits security headers (HSTS, X-Frame-Options, Permissions-Policy) |
-| `@stnd/modules/manifest` | `stnd-manifest` | `/site.webmanifest` | Serves the web app manifest                                        |
-| `@stnd/modules/sitemap`  | `stnd-sitemap`  | —                   | Sitemap generation via `@astrojs/sitemap`                          |
+Every `@stnd` site ships with these — the definitive list lives in
+`GOLD_STANDARD_MODULES` in `packages/core/standard.js`. Opt out via
+`moduleExclude`. (Three more gold standard entries — `@stnd/fonts/inter`,
+`@stnd/fonts/source-serif-4`, `@stnd/fonts/ibm-plex` — and `@stnd/icon/module`
+ship from their own packages, not from here.)
+
+| Module                        | ID                     | Route         | What it does                                                       |
+| :----------------------------- | :--------------------- | :------------ | :------------------------------------------------------------------ |
+| `@stnd/modules/toast`          | `stnd-toast`           | —             | Zero-dependency global notification system                          |
+| `@stnd/modules/confetti`       | `stnd-confetti`        | —             | A fun confetti explosion on page load                                |
+| `@stnd/modules/lab`            | `stnd-lab`             | —             | Loads the StandardLab inspector/debug bundle (dev mode)              |
+| `@stnd/modules/launcher`       | `stnd::launcher`       | —             | Universal command palette engine                                     |
+| `@stnd/modules/styles`         | `stnd-styles`          | —             | Injects the Standard design stylesheet                               |
+| `@stnd/modules/copy-buttons`   | `stnd-copy-buttons`    | —             | Adds copy-to-clipboard buttons to code blocks                        |
+| `@stnd/modules/image-zoom`     | `stnd-image-zoom`      | —             | Click-to-zoom lightbox behavior for images                           |
+| `@stnd/modules/scroll-wrappers`| `stnd-scroll-wrappers` | —             | Scroll-linked wrapper behaviors for content                          |
+| `@stnd/modules/mermaid`        | `mermaid`              | —             | Diagram and flowchart rendering with Mermaid.js                      |
+| `@stnd/modules/math`           | `math`                 | —             | Mathematical notation rendering with KaTeX                           |
+| `@stnd/modules/prism`          | `stnd-prism`           | —             | Syntax highlighting via Prism.js, loaded from CDN                    |
+| `@stnd/modules/robots`         | `stnd-robots`          | `/robots.txt` | Generates `robots.txt` from site config                              |
+| `@stnd/modules/headers`        | `stnd-headers`         | `/_headers`   | Emits security headers (HSTS, X-Frame-Options, Permissions-Policy)   |
+| `@stnd/modules/manifest`       | `stnd-manifest`        | `/site.webmanifest` | Serves the web app manifest                                    |
+| `@stnd/modules/sitemap`        | `stnd-sitemap`         | —             | Sitemap generation via `@astrojs/sitemap`                             |
 
 ### Opt-In Modules
 
 Load these explicitly via `moduleLoad` when your site needs them.
 
-| Module                       | ID                  | Route                       | What it does                                           |
-| :--------------------------- | :------------------ | :-------------------------- | :----------------------------------------------------- |
-| `@stnd/modules/rss`          | `stnd-rss`          | `/rss.xml`                  | Generates an RSS 2.0 feed from site content and config |
-| `@stnd/modules/security-txt` | `stnd-security-txt` | `/.well-known/security.txt` | RFC 9116 security contact disclosure                   |
-| `@stnd/modules/humans`       | `stnd-humans`       | `/humans.txt`               | The people and tools behind the site                   |
-| `@stnd/modules/themes`       | `stnd-themes`       | —                           | Theme/temperament stylesheet injection                 |
-| `@stnd/modules/lab`          | `stnd-lab`          | —                           | StandardLab CSS inspector (dev tool)                   |
-| `@stnd/modules/content`      | `stnd-content`      | `/[…slug]`                | Content collection catch-all route                     |
-| `@stnd/modules/maintenance`  | `stnd-maintenance`  | `/maintenance`              | Maintenance mode with redirect middleware              |
+| Module                       | ID                  | Route                        | What it does                                                |
+| :--------------------------- | :------------------ | :--------------------------- | :----------------------------------------------------------- |
+| `@stnd/modules/rss`          | `stnd-rss`          | `/rss.xml`                   | Generates an RSS 2.0 feed from site content and config       |
+| `@stnd/modules/security-txt` | `stnd-security-txt` | `/.well-known/security.txt`  | RFC 9116 security contact disclosure                          |
+| `@stnd/modules/humans`       | `stnd-humans`       | `/humans.txt`                | The people and tools behind the site                          |
+| `@stnd/modules/themes`       | `stnd-themes`       | —                             | Theme/temperament stylesheet injection                        |
+| `@stnd/modules/content`      | `stnd-content`      | `/[…slug]`                   | Content collection catch-all route                             |
+| `@stnd/modules/maintenance`  | `stnd-maintenance`  | `/maintenance`                | Maintenance mode with redirect middleware                      |
+| `@stnd/modules/brand-manual` | `stnd-brand-manual` | `/brand`                      | A brand manual page showing the active theme's design tokens   |
+| `@stnd/modules/deep-link`    | `stnd-deep-link`    | —                             | Deep-linking client behavior                                    |
+| `@stnd/modules/eink`         | `stnd-eink`         | —                             | E-ink display detection and adaptation                          |
+| `@stnd/modules/fonts`        | `stnd-fonts`        | —                             | Loads every shipped font folio at once, instead of cherry-picking one |
+| `@stnd/modules/gestures`     | `stnd-gestures`     | —                             | Touch/gesture client behaviors                                   |
+| `@stnd/modules/gsap`         | `gsap`              | —                             | GSAP animation library with ScrollTrigger, loaded from CDN on demand |
+| `@stnd/modules/iconify`      | `stnd-iconify`      | —                             | Client-side icon resolution via Iconify                          |
+| `@stnd/modules/keyboard`     | `stnd-keyboard`     | —                             | Keyboard-shortcut client behaviors                                |
+| `@stnd/modules/p5`           | `p5`                | —                             | Creative coding with p5.js, preloaded from CDN as `window.p5`     |
+| `@stnd/modules/stripe`       | `stnd-stripe`       | `/api/stripe/mock-checkout`   | Commerce integration and mock checkout service                   |
+| `@stnd/modules/theme-utils`  | `stnd-theme-utils`  | —                             | Global theme switcher — apply themes via `data-theme` buttons    |
 
 ## Usage in an App
 

package/content/route.astro

@@ -8,8 +8,8 @@
  */
 
 import { getCollection, render } from "astro:content";
-import Base from "../../layouts/Base.astro";
-import { generatePermalink } from "../../core/permalink";
+import Base from "@stnd/layout/Base.astro";
+import { generatePermalink } from "@stnd/utils";
 
 export async function getStaticPaths() {
   const content = await getCollection("content");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stnd/modules",
-  "version": "0.5.1",
+  "version": "0.5.2",
   "type": "module",
   "svelte": "./stripe/views/CheckoutView.svelte",
   "author": "Francis Fontaine",
@@ -17,8 +17,10 @@
   },
   "dependencies": {
     "@astrojs/sitemap": "^3.7.3",
-    "wrangler": "^4.105.0",
+    "wrangler": "^4.129.0",
+    "@stnd/client": "0.5.0",
     "@stnd/icon": "0.2.0",
+    "@stnd/layout": "0.5.1",
     "@stnd/log": "0.5.0",
     "@stnd/styles": "0.5.2",
     "@stnd/utils": "0.5.0"

package/prism/README.md

@@ -1,3 +1,18 @@
+---
+title: "@stnd/modules/prism"
+type: package
+publish: true
+visibility: public
+tags:
+  - package
+  - stnd
+garden-url: https://standard.garden/@francis/readme
+permalink: readme
+garden-short: https://stnd.gd/wAgx4e
+created: 2026-09-06T00:41:06.667Z
+modified: 2026-09-16T17:28:25.903Z
+---
+
 # Prism Syntax Highlighting Module
 
 This module loads Prism.js and Prism.css from CDN and ensures syntax highlighting is applied to all code blocks on initial load and after every Astro navigation ("astro:after-swap").

package/theme-utils/README.md

@@ -1,3 +1,6 @@
+---
+publish: false
+---
 # Theme Utils Module
 
 Global theme switcher for managing themes across the entire site.