npm - @pyreon/head - Versions diffs - 0.20.0 → 0.22.0 - Mend

@pyreon/head 0.20.0 → 0.22.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (21) hide show

package/lib/analysis/context.js.html +5406 -0
package/lib/analysis/index.js.html +1 -1
package/lib/analysis/provider.js.html +1 -1
package/lib/analysis/ssr.js.html +1 -1
package/lib/analysis/use-head.js.html +1 -1
package/lib/context.js +62 -0
package/lib/index.js +30 -63
package/lib/provider.js +29 -62
package/lib/ssr.js +2 -59
package/lib/types/context.d.ts +205 -0
package/lib/types/index.d.ts +27 -4
package/lib/types/provider.d.ts +26 -2
package/lib/use-head.js +2 -5
package/package.json +12 -7
package/src/index.ts +6 -1
package/src/manifest.ts +14 -5
package/src/provider.ts +37 -5
package/src/ssr.ts +10 -1
package/src/tests/context-identity.test.ts +150 -0
package/src/tests/provider-inherits-context.test.tsx +131 -0
package/src/use-head.ts +4 -1

package/lib/types/index.d.ts CHANGED Viewed

@@ -1,3 +1,4 @@
+import { HeadContext, createHeadContext } from "@pyreon/head/context";
 import { ComponentFn, Props, VNodeChild } from "@pyreon/core";
 //#region src/context.d.ts
@@ -200,8 +201,6 @@ interface HeadContextValue {
   /** Returns merged bodyAttrs (later entries override earlier) */
   resolveBodyAttrs(): Record<string, string>;
 }
-declare function createHeadContext(): HeadContextValue;
-declare const HeadContext: import("@pyreon/core").Context<HeadContextValue | null>;
 //#endregion
 //#region src/provider.d.ts
 interface HeadProviderProps extends Props {
@@ -212,15 +211,39 @@ interface HeadProviderProps extends Props {
  * Provides a HeadContextValue to all descendant components.
  * Wrap your app root with this to enable useHead() throughout the tree.
  *
- * If no `context` prop is passed, a new HeadContext is created automatically.
+ * Resolution order (first non-null wins):
+ * 1. `props.context` — explicit context (documented SSR pattern).
+ * 2. An outer `HeadContext` already in scope — inherited transparently.
+ *    This is what makes `renderWithHead(h(HeadProvider, null, h(App)))`
+ *    work without manual context plumbing: `renderWithHead` pushes its
+ *    own `HeadContext` onto the per-request stack, and a nested
+ *    `HeadProvider` (e.g. one zero's `App` renders unconditionally)
+ *    inherits it instead of silently shadowing it with a fresh,
+ *    write-only registry.
+ * 3. A freshly-created `HeadContext` — root-level fallback (pure CSR).
+ *
+ * The inheritance step is load-bearing for any consumer wrapping
+ * `<HeadProvider>` inside `renderWithHead()` (the documented JSDoc
+ * pattern below) AND for the SSG / runtime-SSR pipeline in `@pyreon/zero`,
+ * whose `createApp` always mounts `h(HeadProvider, null, …)` with no
+ * `context` prop. Without inheritance, all `useHead()` calls in the
+ * subtree wrote tags into the inner ctx while `renderWithHead` resolved
+ * the outer ctx — producing an empty `<head>` for the whole app.
+ *
+ * Apps that genuinely need an isolated registry (e.g. iframe / micro-
+ * frontend boundaries) can still opt out by passing
+ * `context={createHeadContext()}` explicitly — `props.context` always wins.
  *
  * @example
- * // Auto-create context:
+ * // Auto-create context (root of a CSR app):
  * <HeadProvider><App /></HeadProvider>
  *
  * // Explicit context (e.g. for SSR):
  * const headCtx = createHeadContext()
  * mount(h(HeadProvider, { context: headCtx }, h(App, null)), root)
+ *
+ * // Composes with `renderWithHead` out of the box — no plumbing needed:
+ * const { html, head } = await renderWithHead(h(HeadProvider, null, h(App, null)))
  */
 declare const HeadProvider: ComponentFn<HeadProviderProps>;
 //#endregion

package/lib/types/provider.d.ts CHANGED Viewed

@@ -43,15 +43,39 @@ interface HeadProviderProps extends Props {
  * Provides a HeadContextValue to all descendant components.
  * Wrap your app root with this to enable useHead() throughout the tree.
  *
- * If no `context` prop is passed, a new HeadContext is created automatically.
+ * Resolution order (first non-null wins):
+ * 1. `props.context` — explicit context (documented SSR pattern).
+ * 2. An outer `HeadContext` already in scope — inherited transparently.
+ *    This is what makes `renderWithHead(h(HeadProvider, null, h(App)))`
+ *    work without manual context plumbing: `renderWithHead` pushes its
+ *    own `HeadContext` onto the per-request stack, and a nested
+ *    `HeadProvider` (e.g. one zero's `App` renders unconditionally)
+ *    inherits it instead of silently shadowing it with a fresh,
+ *    write-only registry.
+ * 3. A freshly-created `HeadContext` — root-level fallback (pure CSR).
+ *
+ * The inheritance step is load-bearing for any consumer wrapping
+ * `<HeadProvider>` inside `renderWithHead()` (the documented JSDoc
+ * pattern below) AND for the SSG / runtime-SSR pipeline in `@pyreon/zero`,
+ * whose `createApp` always mounts `h(HeadProvider, null, …)` with no
+ * `context` prop. Without inheritance, all `useHead()` calls in the
+ * subtree wrote tags into the inner ctx while `renderWithHead` resolved
+ * the outer ctx — producing an empty `<head>` for the whole app.
+ *
+ * Apps that genuinely need an isolated registry (e.g. iframe / micro-
+ * frontend boundaries) can still opt out by passing
+ * `context={createHeadContext()}` explicitly — `props.context` always wins.
  *
  * @example
- * // Auto-create context:
+ * // Auto-create context (root of a CSR app):
  * <HeadProvider><App /></HeadProvider>
  *
  * // Explicit context (e.g. for SSR):
  * const headCtx = createHeadContext()
  * mount(h(HeadProvider, { context: headCtx }, h(App, null)), root)
+ *
+ * // Composes with `renderWithHead` out of the box — no plumbing needed:
+ * const { html, head } = await renderWithHead(h(HeadProvider, null, h(App, null)))
  */
 declare const HeadProvider: ComponentFn<HeadProviderProps>;
 //#endregion

package/lib/use-head.js CHANGED Viewed

@@ -1,10 +1,7 @@
-import { createContext, onMount, onUnmount, useContext } from "@pyreon/core";
+import { onMount, onUnmount, useContext } from "@pyreon/core";
 import { effect } from "@pyreon/reactivity";
+import { HeadContext } from "@pyreon/head/context";
-//#region src/context.ts
-const HeadContext = createContext(null);
-//#endregion
 //#region src/dom.ts
 const ATTR = "data-pyreon-head";
 /** Tracks managed elements by key — avoids querySelectorAll on every sync */

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@pyreon/head",
-  "version": "0.20.0",
+  "version": "0.22.0",
   "description": "Head tag management for Pyreon — works in SSR and CSR",
   "homepage": "https://github.com/pyreon/pyreon/tree/main/packages/head#readme",
   "bugs": {
@@ -30,6 +30,11 @@
       "import": "./lib/index.js",
       "types": "./lib/types/index.d.ts"
     },
+    "./context": {
+      "bun": "./src/context.ts",
+      "import": "./lib/context.js",
+      "types": "./lib/types/context.d.ts"
+    },
     "./provider": {
       "bun": "./src/provider.ts",
       "import": "./lib/provider.js",
@@ -59,16 +64,16 @@
     "prepublishOnly": "bun run build"
   },
   "dependencies": {
-    "@pyreon/core": "^0.20.0",
-    "@pyreon/reactivity": "^0.20.0",
-    "@pyreon/runtime-server": "^0.20.0"
+    "@pyreon/core": "^0.22.0",
+    "@pyreon/reactivity": "^0.22.0",
+    "@pyreon/runtime-server": "^0.22.0"
   },
   "devDependencies": {
     "@happy-dom/global-registrator": "^20.8.9",
     "@pyreon/manifest": "0.13.1",
-    "@pyreon/runtime-dom": "^0.20.0",
-    "@pyreon/runtime-server": "^0.20.0",
-    "@pyreon/test-utils": "^0.13.7",
+    "@pyreon/runtime-dom": "^0.22.0",
+    "@pyreon/runtime-server": "^0.22.0",
+    "@pyreon/test-utils": "^0.13.9",
     "@vitest/browser-playwright": "^4.1.4"
   },
   "peerDependenciesMeta": {

package/src/index.ts CHANGED Viewed

@@ -12,7 +12,12 @@ export type {
   StyleTag,
   UseHeadInput,
 } from './context'
-export { createHeadContext, HeadContext } from './context'
+// Runtime VALUE re-export via self-package path so the build externalizes
+// the symbol — main entry + every sub-entry resolves to the same
+// `lib/context.js` at runtime. The type re-exports above stay as `./context`
+// (types erase, externalization doesn't apply). See `ssr.ts` for the full
+// rationale + `tests/context-identity.test.ts` for the post-build contract.
+export { createHeadContext, HeadContext } from '@pyreon/head/context'
 export type { HeadProviderProps } from './provider'
 export { HeadProvider } from './provider'
 export { useHead } from './use-head'

package/src/manifest.ts CHANGED Viewed

@@ -81,19 +81,28 @@ useHead(() => ({
       kind: 'component',
       signature: '(props: HeadProviderProps) => VNodeChild',
       summary:
-        'Client-side context provider that collects every `useHead()` call from descendants and syncs the resolved tags into the live `document.head` element. Mount once near the application root. Auto-creates a `HeadContextValue` when no `context` prop is passed; nested providers each own an independent context.',
+        'Context provider that collects every `useHead()` call from descendants. Resolves its context as `props.context ?? outer HeadContext in scope ?? a fresh one`, so a `HeadProvider` mounted INSIDE `renderWithHead()` (or inside another `HeadProvider`) transparently inherits the outer registry instead of shadowing it with a write-only one. On the client it also syncs the resolved tags into the live `document.head`. Mount once near the application root for the canonical CSR shape; the inheritance step makes nested mounts and the SSR-wrapped shape work without manual context plumbing.',
       example: `<HeadProvider>{children}</HeadProvider>
-// Client-side setup:
+// CSR root — auto-creates a fresh context:
 mount(
   <HeadProvider>
     <App />
   </HeadProvider>,
   document.getElementById("app")!
-)`,
+)
+// SSR — composes with renderWithHead out of the box (no context prop needed):
+const { html, head } = await renderWithHead(
+  <HeadProvider><App /></HeadProvider>
+)
+// Explicit isolation (iframe / micro-frontend boundary):
+<HeadProvider context={createHeadContext()}><App /></HeadProvider>`,
       mistakes: [
-        'Mounting two `HeadProvider` instances at sibling roots — each owns an independent context, so a `useHead()` deeper in tree A is invisible to tree B',
-        'Forgetting to mount `HeadProvider` and expecting `useHead()` to still update `document.head` — silent no-op outside a provider',
+        'Mounting two `HeadProvider` instances at SIBLING roots — each owns an independent context, so a `useHead()` deeper in tree A is invisible to tree B (use a shared `context` prop or merge under a common parent provider)',
+        'Forgetting to mount `HeadProvider` (or `renderWithHead`) and expecting `useHead()` to still update `document.head` — silent no-op outside any provider',
+        'Assuming a NESTED `HeadProvider` isolates its subtree by default — it does the opposite, inheriting the outer context. Pass `context={createHeadContext()}` explicitly when you genuinely want isolation',
       ],
       seeAlso: ['useHead', 'renderWithHead', 'createHeadContext'],
     },

package/src/provider.ts CHANGED Viewed

@@ -1,7 +1,10 @@
 import type { ComponentFn, Props, VNodeChild } from '@pyreon/core'
-import { nativeCompat, provide } from '@pyreon/core'
+import { nativeCompat, provide, useContext } from '@pyreon/core'
 import type { HeadContextValue } from './context'
-import { createHeadContext, HeadContext } from './context'
+// Runtime VALUE import via self-package path so the build externalizes
+// the symbol — every sub-entry resolves to the same `lib/context.js` at
+// runtime. See `ssr.ts` for the full rationale + `tests/context-identity.test.ts`.
+import { createHeadContext, HeadContext } from '@pyreon/head/context'
 export interface HeadProviderProps extends Props {
   context?: HeadContextValue | undefined
@@ -12,18 +15,47 @@ export interface HeadProviderProps extends Props {
  * Provides a HeadContextValue to all descendant components.
  * Wrap your app root with this to enable useHead() throughout the tree.
  *
- * If no `context` prop is passed, a new HeadContext is created automatically.
+ * Resolution order (first non-null wins):
+ * 1. `props.context` — explicit context (documented SSR pattern).
+ * 2. An outer `HeadContext` already in scope — inherited transparently.
+ *    This is what makes `renderWithHead(h(HeadProvider, null, h(App)))`
+ *    work without manual context plumbing: `renderWithHead` pushes its
+ *    own `HeadContext` onto the per-request stack, and a nested
+ *    `HeadProvider` (e.g. one zero's `App` renders unconditionally)
+ *    inherits it instead of silently shadowing it with a fresh,
+ *    write-only registry.
+ * 3. A freshly-created `HeadContext` — root-level fallback (pure CSR).
+ *
+ * The inheritance step is load-bearing for any consumer wrapping
+ * `<HeadProvider>` inside `renderWithHead()` (the documented JSDoc
+ * pattern below) AND for the SSG / runtime-SSR pipeline in `@pyreon/zero`,
+ * whose `createApp` always mounts `h(HeadProvider, null, …)` with no
+ * `context` prop. Without inheritance, all `useHead()` calls in the
+ * subtree wrote tags into the inner ctx while `renderWithHead` resolved
+ * the outer ctx — producing an empty `<head>` for the whole app.
+ *
+ * Apps that genuinely need an isolated registry (e.g. iframe / micro-
+ * frontend boundaries) can still opt out by passing
+ * `context={createHeadContext()}` explicitly — `props.context` always wins.
  *
  * @example
- * // Auto-create context:
+ * // Auto-create context (root of a CSR app):
  * <HeadProvider><App /></HeadProvider>
  *
  * // Explicit context (e.g. for SSR):
  * const headCtx = createHeadContext()
  * mount(h(HeadProvider, { context: headCtx }, h(App, null)), root)
+ *
+ * // Composes with `renderWithHead` out of the box — no plumbing needed:
+ * const { html, head } = await renderWithHead(h(HeadProvider, null, h(App, null)))
  */
 export const HeadProvider: ComponentFn<HeadProviderProps> = (props) => {
-  const ctx = props.context ?? createHeadContext()
+  // `useContext(HeadContext)` returns `null` when no outer provider exists
+  // (the context's defaultValue). The `??` chain therefore resolves to:
+  //   explicit prop  →  inherited outer ctx  →  fresh ctx
+  // and `provide()` re-pushes the same ctx for the subtree (harmless: the
+  // descendant `useContext` walk finds it identically via either frame).
+  const ctx = props.context ?? useContext(HeadContext) ?? createHeadContext()
   provide(HeadContext, ctx)
   const ch = props.children

package/src/ssr.ts CHANGED Viewed

@@ -2,7 +2,16 @@ import type { ComponentFn, VNode } from '@pyreon/core'
 import { h, pushContext } from '@pyreon/core'
 import { renderToString } from '@pyreon/runtime-server'
 import type { HeadTag } from './context'
-import { createHeadContext, HeadContext } from './context'
+// Runtime VALUE imports go through the self-package path so the build
+// emits an external `import` instead of inlining `createContext(null)`
+// into this sub-bundle. The bundler externalizes `@pyreon/head/context`
+// per the package's `build.external` config — every sub-entry resolves to
+// the SAME `lib/context.js` at runtime, so `HeadContext` is one Symbol
+// across `lib/index.js` / `lib/ssr.js` / `lib/use-head.js` / `lib/provider.js`.
+// See `tests/context-identity.test.ts` for the post-build identity contract.
+// Type-only imports (`HeadTag` above) keep the relative path — types erase
+// at build, no externalization needed.
+import { createHeadContext, HeadContext } from '@pyreon/head/context'
 const VOID_TAGS = new Set(['meta', 'link', 'base'])

package/src/tests/context-identity.test.ts ADDED Viewed

@@ -0,0 +1,150 @@
+/**
+ * Bundle-level regression: `HeadContext` is constructed in EXACTLY ONE
+ * place across the published `lib/` artifacts.
+ *
+ * The bug this test exists to catch: `@pyreon/head@0.21.0` shipped four
+ * sub-entries (`lib/index.js`, `lib/provider.js`, `lib/use-head.js`,
+ * `lib/ssr.js`) AND the shared `@vitus-labs/tools-rolldown` build invokes
+ * rolldown ONCE PER SUB-ENTRY (no cross-entry shared chunks). Result:
+ * every sub-bundle independently inlined `context.ts` and ran its own
+ * `createContext(null)` at module init — each call minted a unique
+ * `Symbol.for(...).id`, so a `useContext(HeadContext)` lookup in one
+ * bundle (e.g. the app's `useHead` from `lib/use-head.js`) silently
+ * MISSED a `provide(HeadContext)` from another (e.g. `renderWithHead`
+ * from `lib/ssr.js`). The bug was invisible in dev / source-mode tests
+ * because Vite's `bun` condition resolves to a single shared
+ * `src/context.ts` (ESM single-evaluation guarantee), but SSG output
+ * silently dropped every `useHead()`-registered tag — bad for SEO,
+ * social scrapers, accessibility, no-JS.
+ *
+ * The fix (`vl-tools.config.mjs` + self-package imports + the new
+ * `./context` sub-export): source uses `@pyreon/head/context` for the
+ * runtime VALUE; the build externalizes that specifier; every sub-bundle
+ * resolves to the SAME `lib/context.js` at runtime — one Symbol, one
+ * shared context.
+ *
+ * Structural assertions:
+ *   1. `lib/context.js` is the ONLY bundle that calls `createContext(`.
+ *   2. Every other published sub-bundle (`index`, `ssr`, `use-head`,
+ *      `provider`) imports `HeadContext` from `@pyreon/head/context`
+ *      (the external — the bundler's signal that the symbol comes from
+ *      a shared runtime chunk, not from inlined source).
+ *
+ * Together these two invariants make the bug class structurally
+ * impossible to re-introduce silently — any future regression (e.g.
+ * removing the `vl-tools.config.mjs` external, or reverting a source
+ * file to a relative `./context` import for the runtime VALUE) flips
+ * one of the per-bundle counters and trips the assertion.
+ *
+ * Bisect-verified at the build artifact:
+ * - With the fix: lib/context.js has 1 createContext call site (+ 1
+ *   import line = 2 occurrences); every other sub-bundle has 0.
+ * - Without the fix (revert `vl-tools.config.mjs`): every sub-bundle
+ *   gets its own inlined `createContext(null)` (2 occurrences each) —
+ *   this test fails on the first non-context bundle.
+ */
+import { existsSync, readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { describe, expect, it } from 'vitest'
+const PKG_ROOT = resolve(__dirname, '..', '..')
+const LIB_DIR = resolve(PKG_ROOT, 'lib')
+const libExists = existsSync(resolve(LIB_DIR, 'index.js'))
+const read = (name: string) => readFileSync(resolve(LIB_DIR, name), 'utf8')
+/**
+ * The bundle gate runs only when `lib/` has been built — `bun install`'s
+ * postinstall bootstrap rebuilds whenever sources are newer than lib, so
+ * in a normal dev session lib is always present. CI installs run the
+ * same bootstrap. The `skip` is a defensive escape so the suite doesn't
+ * false-fail in a partial worktree state where the user manually
+ * deleted lib/.
+ */
+describe.skipIf(!libExists)(
+  '@pyreon/head bundle-level HeadContext identity (regression for the SSG-Meta-dropped bug)',
+  () => {
+    // ── Invariant 1: ONE createContext call across all bundles ───────
+    //
+    // `lib/context.js` is the canonical single chunk. Each other
+    // sub-bundle (`index`, `ssr`, `use-head`, `provider`) should
+    // import `HeadContext` from it externally, NOT inline a fresh
+    // `createContext(null)` call.
+    it('lib/context.js is the SINGLE bundle that calls createContext()', () => {
+      const src = read('context.js')
+      // 2 occurrences = the `import { createContext }` line + the actual
+      // `createContext(null)` call at module init. This is the SOURCE OF
+      // TRUTH for HeadContext's Symbol identity.
+      expect(src.match(/createContext/g)?.length ?? 0).toBe(2)
+      expect(src).toContain('createContext(null)')
+    })
+    it.each([
+      ['index.js'],
+      ['provider.js'],
+      ['use-head.js'],
+      ['ssr.js'],
+    ])('lib/%s does NOT inline createContext (must import HeadContext from @pyreon/head/context)', (name) => {
+      const src = read(name)
+      // Zero `createContext` references — anything > 0 means the bundle
+      // either imports `createContext` (= would call it at init) or
+      // declares its own `HeadContext = createContext(...)`. Both are
+      // the bug. With the fix, the sub-bundle's HeadContext arrives via
+      // an external `import { HeadContext } from "@pyreon/head/context"`.
+      expect(src.match(/createContext/g)?.length ?? 0).toBe(0)
+    })
+    // ── Invariant 2: external import to @pyreon/head/context ─────────
+    //
+    // Every non-`context` sub-bundle that USES HeadContext must import
+    // it from the externalized `@pyreon/head/context` specifier (the
+    // bundler's signal the symbol is shared with `lib/context.js`).
+    it.each([
+      ['index.js'],
+      ['provider.js'],
+      ['use-head.js'],
+      ['ssr.js'],
+    ])('lib/%s imports HeadContext via the externalized @pyreon/head/context specifier', (name) => {
+      const src = read(name)
+      // The bundler emits the import verbatim for externalized specifiers.
+      // Both ESM string literal styles (`"…"` and `'…'`) are matched
+      // because rolldown's output quoting is deterministic but not
+      // version-pinned by this test.
+      const hasExternalImport =
+        /from\s+["']@pyreon\/head\/context["']/.test(src)
+      expect(hasExternalImport).toBe(true)
+    })
+    // ── Invariant 3: the package.json wiring that enables it ─────────
+    //
+    // Two things must coexist for the externalization to be honored —
+    // the `./context` sub-export (so the import has a runtime target),
+    // and the `vl-tools.config.mjs` external rule (so the bundler keeps
+    // the specifier instead of inlining). Locking these here means a
+    // future revert of either side immediately fails the test.
+    it('package.json declares the ./context sub-export', () => {
+      const pkg = JSON.parse(read('../package.json')) as {
+        exports: Record<string, { bun?: string; import?: string; types?: string }>
+      }
+      expect(pkg.exports['./context']).toBeDefined()
+      expect(pkg.exports['./context']?.import).toBe('./lib/context.js')
+      expect(pkg.exports['./context']?.bun).toBe('./src/context.ts')
+    })
+    it('vl-tools.config.mjs externalizes @pyreon/head/context for every sub-entry build', () => {
+      // Plain text read instead of dynamic import — vitest serves test
+      // files via http:// URLs, and Node's default ESM loader rejects
+      // anything outside `file:` / `data:`. Text-grep is enough: this
+      // assertion is structural, not behavioural — the build pipeline
+      // already proved the contract by emitting external imports in
+      // every sub-bundle (invariants 1 and 2 above).
+      const cfg = readFileSync(resolve(PKG_ROOT, 'vl-tools.config.mjs'), 'utf8')
+      expect(cfg).toContain("'@pyreon/head/context'")
+      expect(cfg).toMatch(/external\s*:/)
+    })
+  },
+)

package/src/tests/provider-inherits-context.test.tsx ADDED Viewed

@@ -0,0 +1,131 @@
+import type { ComponentFn } from '@pyreon/core'
+import { h } from '@pyreon/core'
+import { mount } from '@pyreon/runtime-dom'
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import { createHeadContext, HeadProvider, useHead } from '../index'
+import { renderWithHead } from '../ssr'
+/**
+ * `HeadProvider` resolves its HeadContext as `props.context ?? outer ?? fresh`.
+ * That inheritance step is load-bearing for the documented composition
+ * `renderWithHead(h(HeadProvider, null, h(App)))` AND for the
+ * `@pyreon/zero` SSR/SSG pipeline (whose `createApp` mounts
+ * `h(HeadProvider, null, …)` unconditionally with no `context` prop).
+ *
+ * Pre-fix `HeadProvider` ALWAYS auto-created a fresh ctx and `provide()`d
+ * it — silently SHADOWING the ctx that `renderWithHead` had pushed onto
+ * the per-request context stack. Every `useHead({...})` call in the
+ * subtree wrote tags to the inner ctx (HeadProvider's), but
+ * `renderWithHead` resolved the outer ctx (its own, still empty) and
+ * produced an empty `<head>` string. Static SSG / SSR output shipped
+ * with NO `<title>` / `<meta>` / JSON-LD / OG tags — social scrapers and
+ * non-JS crawlers saw nothing. Fixed by adding `useContext(HeadContext)`
+ * to the resolution chain so an outer ctx is inherited transparently.
+ */
+describe('HeadProvider — inherits an outer HeadContext (composability contract)', () => {
+  it('REGRESSION: `renderWithHead(h(HeadProvider, null, h(App)))` carries useHead tags into <head>', async () => {
+    // This is the EXACT shape `@pyreon/zero`'s `createApp` mounts:
+    //   h(App, null) → h(HeadProvider, null, h(RouterProvider, …, h(RouterView, null)))
+    // — i.e. the inner `HeadProvider` has no `context` prop. Pre-fix this
+    // produced an empty `head` string; the rendered HTML was perfectly fine.
+    const App: ComponentFn = () => {
+      useHead({
+        title: 'Page Title',
+        meta: [{ name: 'description', content: 'page desc' }],
+      })
+      return h('div', null, 'app body')
+    }
+    const wrapped = h(HeadProvider as ComponentFn, null, h(App, null))
+    const { html, head } = await renderWithHead(wrapped)
+    expect(html).toContain('app body')
+    expect(head).toContain('<title>Page Title</title>')
+    expect(head).toContain('name="description"')
+    expect(head).toContain('content="page desc"')
+  })
+  it('direct `h(App)` (no inner HeadProvider) still works — baseline parity', async () => {
+    const App: ComponentFn = () => {
+      useHead({ title: 'Baseline' })
+      return h('div', null)
+    }
+    const { head } = await renderWithHead(h(App, null))
+    expect(head).toContain('<title>Baseline</title>')
+  })
+  it('explicit `context` prop on the inner HeadProvider still wins (opt-out for isolation)', async () => {
+    // Apps that genuinely want an isolated head registry (iframe / micro-
+    // frontend) can pass their own ctx; the explicit prop overrides
+    // inheritance. The outer ctx that `renderWithHead` resolves remains
+    // empty in this case BY DESIGN — verifying the opt-out works.
+    const isolatedCtx = createHeadContext()
+    const App: ComponentFn = () => {
+      useHead({ title: 'Isolated' })
+      return h('div', null)
+    }
+    const wrapped = h(
+      HeadProvider as ComponentFn,
+      { context: isolatedCtx },
+      h(App, null),
+    )
+    const { head } = await renderWithHead(wrapped)
+    // Tags landed in the isolated ctx, NOT in renderWithHead's outer ctx
+    expect(head).toBe('')
+    // Confirm the tags really did go into the isolated ctx
+    const isolatedTags = isolatedCtx.resolve()
+    expect(isolatedTags.find((t) => t.tag === 'title')?.children).toBe('Isolated')
+  })
+  it('nested HeadProvider — inner inherits outer ctx, no shadow (registry stays single)', async () => {
+    // Two HeadProviders in the same tree should write into ONE registry,
+    // not two disjoint ones. Pre-fix the inner one created a fresh ctx,
+    // so the outer registry (which renderWithHead resolves) lost the
+    // inner subtree's tags. Post-fix the inner inherits the outer ctx
+    // and tags from both subtrees land in the same resolved <head>.
+    const Inner: ComponentFn = () => {
+      useHead({ meta: [{ name: 'inner', content: 'inner-value' }] })
+      return h('span', null, 'inner')
+    }
+    const Outer: ComponentFn = () => {
+      useHead({ title: 'Outer Title' })
+      return h(
+        'div',
+        null,
+        h(HeadProvider as ComponentFn, null, h(Inner, null)),
+      )
+    }
+    const { head } = await renderWithHead(h(Outer, null))
+    expect(head).toContain('<title>Outer Title</title>')
+    expect(head).toContain('name="inner"')
+    expect(head).toContain('content="inner-value"')
+  })
+  describe('CSR root — fresh-ctx fallback preserved (regression guard for the fix)', () => {
+    let container: HTMLElement
+    beforeEach(() => {
+      container = document.createElement('div')
+      document.body.appendChild(container)
+      for (const el of document.head.querySelectorAll('[data-pyreon-head]'))
+        el.remove()
+      document.title = ''
+    })
+    afterEach(() => {
+      container.remove()
+    })
+    it('mounts at CSR root with NO `context` prop + NO outer provider → auto-creates fresh ctx, useHead works', () => {
+      // When neither `props.context` nor an outer `HeadContext` is in
+      // scope, HeadProvider must STILL auto-create a fresh ctx so pure
+      // CSR roots work. If the fix accidentally regressed this path
+      // (e.g. requiring an outer ctx), `useHead` would no-op silently
+      // and `document.title` would stay empty.
+      const App: ComponentFn = () => {
+        useHead({ title: 'CSR Root' })
+        return h('div', null)
+      }
+      mount(h(HeadProvider as ComponentFn, null, h(App, null)), container)
+      expect(document.title).toBe('CSR Root')
+    })
+  })
+})

package/src/use-head.ts CHANGED Viewed

@@ -1,7 +1,10 @@
 import { onMount, onUnmount, useContext } from '@pyreon/core'
 import { effect } from '@pyreon/reactivity'
 import type { HeadEntry, HeadTag, UseHeadInput } from './context'
-import { HeadContext } from './context'
+// Runtime VALUE import via self-package path so the build externalizes
+// the symbol — every sub-entry resolves to the same `lib/context.js` at
+// runtime. See `ssr.ts` for the full rationale + `tests/context-identity.test.ts`.
+import { HeadContext } from '@pyreon/head/context'
 import { syncDom } from './dom'
 /** Cast a strict tag interface to the internal props format, stripping undefined values */