@stnd/core 0.24.38 → 0.24.40

package/README.md

@@ -61,11 +61,11 @@ The concept relies on a strict separation between the **Core** (static, tested)
 
 ---
 
-## 🔌 Module System (Spores)
+## 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`):
+### Anatomy of a Module (`index.module.js`)
 
 ```javascript
 export default {
@@ -87,21 +87,40 @@ export default {
 };
 ```
 
-### Virtual Modules & Rendering:
+### 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.
+The module loader compiles `hooks:` registrations into two dedicated virtual modules based on entry classification:
 
-**UI Consumption:**
+| Virtual Module | Entry Classification | Primary Consumers |
+| :--- | :--- | :--- |
+| `virtual:stnd/hooks` | **Logic hooks** — `.js` / `.ts` entries (excluding `launcher:*` and `*:action`) | `runHook()` and `runPipeline()` |
+| `virtual:stnd/components` | **UI & action zones** — `.astro` / `.svelte` / `.md` components, plus all `launcher:*` and `*:action` entries | `<Hook zone="..." />` and `extensions[zone]` |
+
+#### Calling Conventions (`virtual:stnd/hooks`)
+
+- **Fan-out (`runHook(name, ...args)`)**: Calls every registered handler for `name` and collects their return values into an array (e.g. `astro:build:done`, `stnd:rss:register`).
+- **Sequential Pipeline (`runPipeline(name, initialValue, ...args)`)**: Threads a single value through every registered handler in sequence. Each handler must explicitly return the (optionally transformed) value — ideal when modules inspect and override a shared descriptor (e.g. `note:render` in `apps/stnd.gd`).
+
+#### Isolation & Bundling Guarantees
+
+- **Failure Isolation**: Both `runHook` and `runPipeline` isolate handler exceptions — a throwing handler is logged and skipped so it cannot abort sibling handlers.
+- **Server-Only Filtering (`server: true`)**: Handlers marked with `server: true` are stripped from the client bundle of `virtual:stnd/hooks`. Use this for any handler touching databases or secrets when client modules (like `@stnd/launcher`) also import from `virtual:stnd/hooks`.
+- **Build-Time Classification Guards**:
+  - Registering the same hook name as both a logic hook and a UI/action zone across modules throws a build-time fatal error ([`hook-kind-mismatch`](https://stnd.build/manual/diagnostic/hook-kind-mismatch)).
+  - Setting `server: true` on a `launcher:*` or `*:action` entry throws a build-time fatal error ([`hook-server-flag-ignored`](https://stnd.build/manual/diagnostic/hook-server-flag-ignored)), since `virtual:stnd/components` has no SSR/client split.
+
+#### UI Consumption
 
 ```astro
+---
 import Hook from "@stnd/core/Hook.astro";
-<Hook id="header:top" />
+---
+<Hook zone="header:top" />
 ```
 
 ---
 
-## 🛠 Helpers Reference (Core & Server)
+## Helpers Reference (Core & Server)
 
 Importable via `@stnd/server/[filename]` or `@stnd/utils/[filename]`.
 
@@ -140,7 +159,7 @@ Importable via `@stnd/server/[filename]` or `@stnd/utils/[filename]`.
 | `getReadingTime` | `getReadingTime(text)` | Estimated reading time. |
 | `validateEmail` | `validateEmail(email)` | Simplified email validation. |
 
-### Other Helpers:
+### Other Helpers
 
 - `@stnd/server/cors.js`: `getCorsHeaders`, `handleCorsPreflight`.
 - `@stnd/server/errors.js`: Standardized error classes (`StandardError`, `AuthError`, etc.).
@@ -150,11 +169,11 @@ Importable via `@stnd/server/[filename]` or `@stnd/utils/[filename]`.
 
 ---
 
-## 🎨 Design Tokens (CSS Variables)
+## Design Tokens (CSS Variables)
 
 The system uses CSS variables (`--stnd-*` or root variables `:root`) for consistency.
 
-### 📐 Geometry & Rhythm (`packages/styles/_standard-01-token.scss`)
+### Geometry & Rhythm (`packages/styles/_standard-01-token.scss`)
 
 | Variable | Default Value | Description |
 | :--- | :--- | :--- |
@@ -170,7 +189,7 @@ The system uses CSS variables (`--stnd-*` or root variables `:root`) for consist
 | `--rhythm-block-scale` | `2` | Multiplier for non-text block elements. |
 | `--radius` | `--leading` | Border radius consistent with rhythm. |
 
-### 🎨 Colors (`packages/styles/_standard-02-color.scss`)
+### Colors (`packages/styles/_standard-02-color.scss`)
 
 OKLCH-based system generating harmony from `--color-accent`.
 
@@ -184,7 +203,7 @@ OKLCH-based system generating harmony from `--color-accent`.
 | `--color-[green\|red\|yellow\|blue]` | Pigment colors derived from accent. |
 | `--color-success\|error\|warning` | Semantic states. |
 
-### 🛠 SCSS Breakpoints
+### SCSS Breakpoints
 
 - `$mobile`: 600px
 - `$small`: 768px
@@ -193,7 +212,7 @@ OKLCH-based system generating harmony from `--color-accent`.
 
 ---
 
-## 💡 Notes for AI
+## 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`.
@@ -223,11 +242,10 @@ Part of the [Road to Public Release](../README.md#-road-to-public-release) (Phas
 - [ ] **`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
+## Links & Standards
 
-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)
+This package implements the core architectural principles of the Standard ecosystem. For further details on how the framework operates globally, see:
+- **System Architecture**: [Framework Guide & Invariants](../../apps/stnd.build/modules/manual/content/system/framework-guide.md)
+- **Engineering Philosophy**: [Engineering Philosophy](../../apps/stnd.build/modules/manual/content/philosophy/engineering-philosophy.md)
+- **Package Ecosystem**: [packages/README.md](../README.md)
+- **Monorepo Root**: [README.md](../../README.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stnd/core",
-  "version": "0.24.38",
+  "version": "0.24.40",
   "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",
@@ -63,16 +63,16 @@
     "@stnd/fonts": "0.8.1",
     "@stnd/icon": "0.10.0",
     "@stnd/lab": "1.6.1",
-    "@stnd/launcher": "1.10.2",
+    "@stnd/launcher": "1.10.3",
     "@stnd/layout": "0.10.1",
-    "@stnd/modules": "0.14.0",
+    "@stnd/log": "0.6.0",
+    "@stnd/modules": "0.14.2",
     "@stnd/press": "0.13.2",
-    "@stnd/styles": "0.27.2",
     "@stnd/store": "0.6.0",
+    "@stnd/styles": "0.28.0",
+    "@stnd/themes": "0.26.5",
     "@stnd/ui": "0.16.1",
-    "@stnd/utils": "0.10.0",
-    "@stnd/log": "0.6.0",
-    "@stnd/themes": "0.26.4"
+    "@stnd/utils": "0.10.0"
   },
   "devDependencies": {
     "@playwright/test": "^1.61.1",

package/src/loader.js

@@ -129,19 +129,33 @@ export async function loadModules({
   log.success("Initializing module engine...");
 
   const modulePatterns = buildModulePatterns(finalConfig);
-  const require = createRequire(import.meta.url);
+  const coreRequire = createRequire(import.meta.url);
+  let appRequire = coreRequire;
+  try {
+    appRequire = createRequire(path.join(appRoot, "package.json"));
+  } catch {
+    // Fallback to coreRequire when appRoot has no package.json
+  }
 
   const discoveredFiles = discoverModuleFiles(appRoot, modulePatterns);
 
-  const resolveModulePath = (idOrPath) => {
+  const resolveModulePath = (idOrPath, fromFile = null) => {
     if (path.isAbsolute(idOrPath)) return idOrPath;
 
     const tryResolve = (id) => {
-      try {
-        return require.resolve(id);
-      } catch {
-        return null;
+      for (const req of [
+        appRequire,
+        fromFile ? createRequire(fromFile) : null,
+        coreRequire,
+      ]) {
+        if (!req) continue;
+        try {
+          return req.resolve(id);
+        } catch {
+          // try next resolver
+        }
       }
+      return null;
     };
 
     const isBare =
@@ -175,8 +189,8 @@ export async function loadModules({
   while (loadQueue.length > 0) {
     const batch = loadQueue.splice(0, loadQueue.length);
     const tasks = batch
-      .map(({ rawId, origin, sourceModule }) => {
-        const resolvedPath = resolveModulePath(rawId);
+      .map(({ rawId, origin, sourceModule, sourceFile }) => {
+        const resolvedPath = resolveModulePath(rawId, sourceFile);
         if (!resolvedPath || processedPaths.has(resolvedPath)) return null;
         processedPaths.add(resolvedPath);
         return { rawId, origin, sourceModule, resolvedPath };
@@ -254,6 +268,7 @@ export async function loadModules({
               rawId: depId,
               origin: "dependency",
               sourceModule: def.id,
+              sourceFile: resolvedPath,
             });
           }
         }
@@ -281,7 +296,7 @@ export async function loadModules({
     for (const rawDep of def.dependencies) {
       let depId = rawDep;
       if (!idToPath.has(depId)) {
-        const resolvedDepPath = resolveModulePath(rawDep);
+        const resolvedDepPath = resolveModulePath(rawDep, pathStr);
         if (resolvedDepPath && moduleMap.has(resolvedDepPath)) {
           depId = moduleMap.get(resolvedDepPath).def.id;
         }