@pyreon/head 0.20.0 → 0.21.0

package/lib/analysis/index.js.html

@@ -5386,7 +5386,7 @@ var drawChart = (function (exports) {
   </script>
   <script>
     /*<!--*/
-    const data = {"version":2,"tree":{"name":"root","children":[{"name":"index.js","children":[{"name":"src","children":[{"uid":"c3ae39c2-1","name":"context.ts"},{"uid":"c3ae39c2-3","name":"provider.ts"},{"uid":"c3ae39c2-5","name":"dom.ts"},{"uid":"c3ae39c2-7","name":"use-head.ts"},{"uid":"c3ae39c2-9","name":"index.ts"}]}]}],"isRoot":true},"nodeParts":{"c3ae39c2-1":{"renderedLength":1373,"gzipLength":509,"brotliLength":0,"metaUid":"c3ae39c2-0"},"c3ae39c2-3":{"renderedLength":681,"gzipLength":408,"brotliLength":0,"metaUid":"c3ae39c2-2"},"c3ae39c2-5":{"renderedLength":3447,"gzipLength":1292,"brotliLength":0,"metaUid":"c3ae39c2-4"},"c3ae39c2-7":{"renderedLength":2634,"gzipLength":1093,"brotliLength":0,"metaUid":"c3ae39c2-6"},"c3ae39c2-9":{"renderedLength":0,"gzipLength":0,"brotliLength":0,"metaUid":"c3ae39c2-8"}},"nodeMetas":{"c3ae39c2-0":{"id":"/src/context.ts","moduleParts":{"index.js":"c3ae39c2-1"},"imported":[{"uid":"c3ae39c2-10"}],"importedBy":[{"uid":"c3ae39c2-8"},{"uid":"c3ae39c2-2"},{"uid":"c3ae39c2-6"}]},"c3ae39c2-2":{"id":"/src/provider.ts","moduleParts":{"index.js":"c3ae39c2-3"},"imported":[{"uid":"c3ae39c2-10"},{"uid":"c3ae39c2-0"}],"importedBy":[{"uid":"c3ae39c2-8"}]},"c3ae39c2-4":{"id":"/src/dom.ts","moduleParts":{"index.js":"c3ae39c2-5"},"imported":[],"importedBy":[{"uid":"c3ae39c2-6"}]},"c3ae39c2-6":{"id":"/src/use-head.ts","moduleParts":{"index.js":"c3ae39c2-7"},"imported":[{"uid":"c3ae39c2-10"},{"uid":"c3ae39c2-11"},{"uid":"c3ae39c2-0"},{"uid":"c3ae39c2-4"}],"importedBy":[{"uid":"c3ae39c2-8"}]},"c3ae39c2-8":{"id":"/src/index.ts","moduleParts":{"index.js":"c3ae39c2-9"},"imported":[{"uid":"c3ae39c2-0"},{"uid":"c3ae39c2-2"},{"uid":"c3ae39c2-6"}],"importedBy":[],"isEntry":true},"c3ae39c2-10":{"id":"@pyreon/core","moduleParts":{},"imported":[],"importedBy":[{"uid":"c3ae39c2-0"},{"uid":"c3ae39c2-2"},{"uid":"c3ae39c2-6"}]},"c3ae39c2-11":{"id":"@pyreon/reactivity","moduleParts":{},"imported":[],"importedBy":[{"uid":"c3ae39c2-6"}]}},"env":{"rollup":"4.23.0"},"options":{"gzip":true,"brotli":false,"sourcemap":false}};
+    const data = {"version":2,"tree":{"name":"root","children":[{"name":"index.js","children":[{"name":"src","children":[{"uid":"4825d939-1","name":"context.ts"},{"uid":"4825d939-3","name":"provider.ts"},{"uid":"4825d939-5","name":"dom.ts"},{"uid":"4825d939-7","name":"use-head.ts"},{"uid":"4825d939-9","name":"index.ts"}]}]}],"isRoot":true},"nodeParts":{"4825d939-1":{"renderedLength":1373,"gzipLength":509,"brotliLength":0,"metaUid":"4825d939-0"},"4825d939-3":{"renderedLength":2121,"gzipLength":1074,"brotliLength":0,"metaUid":"4825d939-2"},"4825d939-5":{"renderedLength":3447,"gzipLength":1292,"brotliLength":0,"metaUid":"4825d939-4"},"4825d939-7":{"renderedLength":2634,"gzipLength":1093,"brotliLength":0,"metaUid":"4825d939-6"},"4825d939-9":{"renderedLength":0,"gzipLength":0,"brotliLength":0,"metaUid":"4825d939-8"}},"nodeMetas":{"4825d939-0":{"id":"/src/context.ts","moduleParts":{"index.js":"4825d939-1"},"imported":[{"uid":"4825d939-10"}],"importedBy":[{"uid":"4825d939-8"},{"uid":"4825d939-2"},{"uid":"4825d939-6"}]},"4825d939-2":{"id":"/src/provider.ts","moduleParts":{"index.js":"4825d939-3"},"imported":[{"uid":"4825d939-10"},{"uid":"4825d939-0"}],"importedBy":[{"uid":"4825d939-8"}]},"4825d939-4":{"id":"/src/dom.ts","moduleParts":{"index.js":"4825d939-5"},"imported":[],"importedBy":[{"uid":"4825d939-6"}]},"4825d939-6":{"id":"/src/use-head.ts","moduleParts":{"index.js":"4825d939-7"},"imported":[{"uid":"4825d939-10"},{"uid":"4825d939-11"},{"uid":"4825d939-0"},{"uid":"4825d939-4"}],"importedBy":[{"uid":"4825d939-8"}]},"4825d939-8":{"id":"/src/index.ts","moduleParts":{"index.js":"4825d939-9"},"imported":[{"uid":"4825d939-0"},{"uid":"4825d939-2"},{"uid":"4825d939-6"}],"importedBy":[],"isEntry":true},"4825d939-10":{"id":"@pyreon/core","moduleParts":{},"imported":[],"importedBy":[{"uid":"4825d939-0"},{"uid":"4825d939-2"},{"uid":"4825d939-6"}]},"4825d939-11":{"id":"@pyreon/reactivity","moduleParts":{},"imported":[],"importedBy":[{"uid":"4825d939-6"}]}},"env":{"rollup":"4.23.0"},"options":{"gzip":true,"brotli":false,"sourcemap":false}};
 
     const run = () => {
       const width = window.innerWidth;

package/lib/analysis/provider.js.html

@@ -5386,7 +5386,7 @@ var drawChart = (function (exports) {
   </script>
   <script>
     /*<!--*/
-    const data = {"version":2,"tree":{"name":"root","children":[{"name":"provider.js","children":[{"name":"src","children":[{"uid":"65ae058d-1","name":"context.ts"},{"uid":"65ae058d-3","name":"provider.ts"}]}]}],"isRoot":true},"nodeParts":{"65ae058d-1":{"renderedLength":1373,"gzipLength":509,"brotliLength":0,"metaUid":"65ae058d-0"},"65ae058d-3":{"renderedLength":681,"gzipLength":408,"brotliLength":0,"metaUid":"65ae058d-2"}},"nodeMetas":{"65ae058d-0":{"id":"/src/context.ts","moduleParts":{"provider.js":"65ae058d-1"},"imported":[{"uid":"65ae058d-4"}],"importedBy":[{"uid":"65ae058d-2"}]},"65ae058d-2":{"id":"/src/provider.ts","moduleParts":{"provider.js":"65ae058d-3"},"imported":[{"uid":"65ae058d-4"},{"uid":"65ae058d-0"}],"importedBy":[],"isEntry":true},"65ae058d-4":{"id":"@pyreon/core","moduleParts":{},"imported":[],"importedBy":[{"uid":"65ae058d-2"},{"uid":"65ae058d-0"}]}},"env":{"rollup":"4.23.0"},"options":{"gzip":true,"brotli":false,"sourcemap":false}};
+    const data = {"version":2,"tree":{"name":"root","children":[{"name":"provider.js","children":[{"name":"src","children":[{"uid":"11781eb7-1","name":"context.ts"},{"uid":"11781eb7-3","name":"provider.ts"}]}]}],"isRoot":true},"nodeParts":{"11781eb7-1":{"renderedLength":1373,"gzipLength":509,"brotliLength":0,"metaUid":"11781eb7-0"},"11781eb7-3":{"renderedLength":2121,"gzipLength":1074,"brotliLength":0,"metaUid":"11781eb7-2"}},"nodeMetas":{"11781eb7-0":{"id":"/src/context.ts","moduleParts":{"provider.js":"11781eb7-1"},"imported":[{"uid":"11781eb7-4"}],"importedBy":[{"uid":"11781eb7-2"}]},"11781eb7-2":{"id":"/src/provider.ts","moduleParts":{"provider.js":"11781eb7-3"},"imported":[{"uid":"11781eb7-4"},{"uid":"11781eb7-0"}],"importedBy":[],"isEntry":true},"11781eb7-4":{"id":"@pyreon/core","moduleParts":{},"imported":[],"importedBy":[{"uid":"11781eb7-2"},{"uid":"11781eb7-0"}]}},"env":{"rollup":"4.23.0"},"options":{"gzip":true,"brotli":false,"sourcemap":false}};
 
     const run = () => {
       const width = window.innerWidth;

package/lib/index.js

@@ -64,18 +64,42 @@ const HeadContext = createContext(null);
 * 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)))
 */
 const HeadProvider = (props) => {
-	provide(HeadContext, props.context ?? createHeadContext());
+	provide(HeadContext, props.context ?? useContext(HeadContext) ?? createHeadContext());
 	const ch = props.children;
 	return typeof ch === "function" ? ch() : ch;
 };

package/lib/provider.js

@@ -1,4 +1,4 @@
-import { createContext, nativeCompat, provide } from "@pyreon/core";
+import { createContext, nativeCompat, provide, useContext } from "@pyreon/core";
 
 //#region src/context.ts
 function createHeadContext() {
@@ -63,18 +63,42 @@ const HeadContext = createContext(null);
 * 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)))
 */
 const HeadProvider = (props) => {
-	provide(HeadContext, props.context ?? createHeadContext());
+	provide(HeadContext, props.context ?? useContext(HeadContext) ?? createHeadContext());
 	const ch = props.children;
 	return typeof ch === "function" ? ch() : ch;
 };

package/lib/types/index.d.ts

@@ -212,15 +212,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

@@ -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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pyreon/head",
-  "version": "0.20.0",
+  "version": "0.21.0",
   "description": "Head tag management for Pyreon — works in SSR and CSR",
   "homepage": "https://github.com/pyreon/pyreon/tree/main/packages/head#readme",
   "bugs": {
@@ -59,16 +59,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.21.0",
+    "@pyreon/reactivity": "^0.21.0",
+    "@pyreon/runtime-server": "^0.21.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.21.0",
+    "@pyreon/runtime-server": "^0.21.0",
+    "@pyreon/test-utils": "^0.13.8",
     "@vitest/browser-playwright": "^4.1.4"
   },
   "peerDependenciesMeta": {

package/src/manifest.ts

@@ -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

@@ -1,5 +1,5 @@
 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'
 
@@ -12,18 +12,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/tests/provider-inherits-context.test.tsx

@@ -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')
+    })
+  })
+})