@pyreon/head 0.24.4 → 0.24.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pyreon/head",
-  "version": "0.24.4",
+  "version": "0.24.6",
   "description": "Head tag management for Pyreon — works in SSR and CSR",
   "homepage": "https://github.com/pyreon/pyreon/tree/main/packages/head#readme",
   "bugs": {
@@ -15,7 +15,6 @@
   "files": [
     "lib",
     "!lib/**/*.map",
-    "src",
     "README.md",
     "LICENSE"
   ],
@@ -26,27 +25,22 @@
   "types": "./lib/types/index.d.ts",
   "exports": {
     ".": {
-      "bun": "./src/index.ts",
       "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",
       "types": "./lib/types/provider.d.ts"
     },
     "./use-head": {
-      "bun": "./src/use-head.ts",
       "import": "./lib/use-head.js",
       "types": "./lib/types/use-head.d.ts"
     },
     "./ssr": {
-      "bun": "./src/ssr.ts",
       "import": "./lib/ssr.js",
       "types": "./lib/types/ssr.d.ts"
     }
@@ -64,15 +58,15 @@
     "prepublishOnly": "bun run build"
   },
   "dependencies": {
-    "@pyreon/core": "^0.24.4",
-    "@pyreon/reactivity": "^0.24.4",
-    "@pyreon/runtime-server": "^0.24.4"
+    "@pyreon/core": "^0.24.6",
+    "@pyreon/reactivity": "^0.24.6",
+    "@pyreon/runtime-server": "^0.24.6"
   },
   "devDependencies": {
     "@happy-dom/global-registrator": "^20.8.9",
     "@pyreon/manifest": "0.13.1",
-    "@pyreon/runtime-dom": "^0.24.4",
-    "@pyreon/runtime-server": "^0.24.4",
+    "@pyreon/runtime-dom": "^0.24.6",
+    "@pyreon/runtime-server": "^0.24.6",
     "@pyreon/test-utils": "^0.13.11",
     "@vitest/browser-playwright": "^4.1.4"
   },

package/src/context.ts

@@ -1,282 +0,0 @@
-import { createContext } from '@pyreon/core'
-
-// ─── Types ────────────────────────────────────────────────────────────────────
-
-export interface HeadTag {
-  /** HTML tag name */
-  tag: 'title' | 'meta' | 'link' | 'script' | 'style' | 'base' | 'noscript'
-  /**
-   * Deduplication key. Tags with the same key replace each other;
-   * innermost component (last added) wins.
-   * Example: all components setting the page title use key "title".
-   */
-  key?: string
-  /** HTML attributes for the tag */
-  props?: Record<string, string>
-  /** Text content — for <title>, <script>, <style>, <noscript> */
-  children?: string
-}
-
-// ─── Strict tag types ────────────────────────────────────────────────────────
-
-/** Standard `<meta>` tag attributes. Catches typos like `{ naem: "description" }`. */
-export interface MetaTag {
-  /** Standard meta name (e.g. "description", "viewport", "robots") */
-  name?: string
-  /** Open Graph / social property (e.g. "og:title", "twitter:card") */
-  property?: string
-  /** HTTP equivalent header (e.g. "refresh", "content-type") */
-  'http-equiv'?: string
-  /** Value associated with name, property, or http-equiv */
-  content?: string
-  /** Document character encoding (e.g. "utf-8") */
-  charset?: string
-  /** Schema.org itemprop */
-  itemprop?: string
-  /** Media condition for applicability (e.g. "(prefers-color-scheme: dark)") */
-  media?: string
-}
-
-/** Standard `<link>` tag attributes. */
-export interface LinkTag {
-  /** Relationship to the current document (e.g. "stylesheet", "icon", "canonical") */
-  rel?: string
-  /** URL of the linked resource */
-  href?: string
-  /** Resource type hint for preloading (e.g. "style", "script", "font") */
-  as?: string
-  /** MIME type (e.g. "text/css", "image/png") */
-  type?: string
-  /** Media query for conditional loading */
-  media?: string
-  /** CORS mode */
-  crossorigin?: string
-  /** Subresource integrity hash */
-  integrity?: string
-  /** Icon sizes (e.g. "32x32", "any") */
-  sizes?: string
-  /** Language of the linked resource */
-  hreflang?: string
-  /** Title for the link (used for alternate stylesheets) */
-  title?: string
-  /** Fetch priority hint */
-  fetchpriority?: 'high' | 'low' | 'auto'
-  /** Referrer policy */
-  referrerpolicy?: string
-  /** Image source set for preloading responsive images */
-  imagesrcset?: string
-  /** Image sizes for preloading responsive images */
-  imagesizes?: string
-  /** Disable the resource (for stylesheets) */
-  disabled?: string
-  /** Color for mask-icon */
-  color?: string
-}
-
-/** Standard `<script>` tag attributes. */
-export interface ScriptTag {
-  /** External script URL */
-  src?: string
-  /** Script MIME type or module type (e.g. "module", "importmap") */
-  type?: string
-  /** Load asynchronously */
-  async?: string
-  /** Defer execution until document is parsed */
-  defer?: string
-  /** CORS mode */
-  crossorigin?: string
-  /** Subresource integrity hash */
-  integrity?: string
-  /** Exclude from module-supporting browsers */
-  nomodule?: string
-  /** Referrer policy */
-  referrerpolicy?: string
-  /** Fetch priority hint */
-  fetchpriority?: string
-  /** Inline script content */
-  children?: string
-}
-
-/** Standard `<style>` tag attributes. */
-export interface StyleTag {
-  /** Inline CSS content (required) */
-  children: string
-  /** Media query for conditional styles */
-  media?: string
-  /** Nonce for CSP */
-  nonce?: string
-  /** Title for alternate stylesheets */
-  title?: string
-  /** Render-blocking behavior */
-  blocking?: string
-}
-
-/**
- * How eagerly the browser should act on a speculation rule.
- * Per the W3C Speculation Rules spec.
- */
-export type SpeculationEagerness = 'immediate' | 'eager' | 'moderate' | 'conservative'
-
-/**
- * A single speculation rule (one entry in a `prefetch` / `prerender` list).
- *
- * - `source: 'list'` + `urls` — prefetch/prerender these explicit URLs.
- * - `source: 'document'` + `where` — let the browser pick links from the
- *   current document that match the predicate (e.g. a CSS selector via
- *   `{ selector_matches: '.router-link' }`).
- */
-export interface SpeculationRule {
-  /** `'list'` (explicit `urls`) or `'document'` (predicate-driven). */
-  source?: 'list' | 'document'
-  /** Same-origin URLs to prefetch/prerender (for `source: 'list'`). */
-  urls?: string[]
-  /** Document predicate (for `source: 'document'`) — e.g. `{ selector_matches: 'a.next' }`. */
-  where?: Record<string, unknown>
-  /** When the browser should fetch — defaults to the browser's per-source default. */
-  eagerness?: SpeculationEagerness
-  /** Capability requirements, e.g. `['anonymous-client-ip-when-cross-origin']`. */
-  requires?: string[]
-  /** Referrer policy for the speculative request. */
-  referrer_policy?: string
-}
-
-/**
- * Declarative Speculation Rules — emitted as a single
- * `<script type="speculationrules">` tag. Supported browsers prefetch or
- * fully prerender the next document(s) so navigation is instant. Inert in
- * non-supporting browsers (no polyfill needed). Opt-in: only emitted when
- * `useHead({ speculationRules })` is called.
- *
- * @see https://developer.mozilla.org/docs/Web/API/Speculation_Rules_API
- */
-export interface SpeculationRules {
-  /** Lightweight: fetch the response, no rendering. */
-  prefetch?: SpeculationRule[]
-  /** Heavy: fully render the next document in the background. */
-  prerender?: SpeculationRule[]
-}
-
-/** Standard `<base>` tag attributes. */
-export interface BaseTag {
-  /** Base URL for relative URLs in the document */
-  href?: string
-  /** Default target for links and forms */
-  target?: '_blank' | '_self' | '_parent' | '_top'
-}
-
-export interface UseHeadInput {
-  title?: string
-  /**
-   * Title template — use `%s` as a placeholder for the page title.
-   * Applied to the resolved title after deduplication.
-   * @example useHead({ titleTemplate: "%s | My App" })
-   */
-  titleTemplate?: string | ((title: string) => string)
-  meta?: MetaTag[]
-  link?: LinkTag[]
-  script?: ScriptTag[]
-  style?: StyleTag[]
-  noscript?: { children: string }[]
-  /** Convenience: emits a <script type="application/ld+json"> tag with JSON.stringify'd content */
-  jsonLd?: Record<string, unknown> | Record<string, unknown>[]
-  /**
-   * Convenience: emits a `<script type="speculationrules">` tag with the
-   * JSON.stringify'd rules. Supported browsers prefetch/prerender the next
-   * document(s) for near-instant navigation; inert elsewhere. Opt-in.
-   * @example useHead({ speculationRules: { prerender: [{ source: 'list', urls: ['/about'], eagerness: 'moderate' }] } })
-   */
-  speculationRules?: SpeculationRules
-  base?: BaseTag
-  /** Attributes to set on the <html> element (e.g. { lang: "en", dir: "ltr" }) */
-  htmlAttrs?: Record<string, string>
-  /** Attributes to set on the <body> element (e.g. { class: "dark" }) */
-  bodyAttrs?: Record<string, string>
-}
-
-// ─── Context ──────────────────────────────────────────────────────────────────
-
-export interface HeadEntry {
-  tags: HeadTag[]
-  titleTemplate?: string | ((title: string) => string) | undefined
-  htmlAttrs?: Record<string, string> | undefined
-  bodyAttrs?: Record<string, string> | undefined
-}
-
-export interface HeadContextValue {
-  add(id: symbol, entry: HeadEntry): void
-  remove(id: symbol): void
-  /** Returns deduplicated tags — last-added entry wins per key */
-  resolve(): HeadTag[]
-  /** Returns the merged titleTemplate (last-added wins) */
-  resolveTitleTemplate(): (string | ((title: string) => string)) | undefined
-  /** Returns merged htmlAttrs (later entries override earlier) */
-  resolveHtmlAttrs(): Record<string, string>
-  /** Returns merged bodyAttrs (later entries override earlier) */
-  resolveBodyAttrs(): Record<string, string>
-}
-
-export function createHeadContext(): HeadContextValue {
-  const map = new Map<symbol, HeadEntry>()
-
-  // ── Cached resolve ───────────────────────────────────────────────────────
-  let dirty = true
-  let cachedTags: HeadTag[] = []
-  let cachedTitleTemplate: (string | ((title: string) => string)) | undefined
-  let cachedHtmlAttrs: Record<string, string> = {}
-  let cachedBodyAttrs: Record<string, string> = {}
-
-  function rebuild(): void {
-    if (!dirty) return
-    dirty = false
-
-    const keyed = new Map<string, HeadTag>()
-    const unkeyed: HeadTag[] = []
-    let titleTemplate: (string | ((title: string) => string)) | undefined
-    const htmlAttrs: Record<string, string> = {}
-    const bodyAttrs: Record<string, string> = {}
-
-    for (const entry of map.values()) {
-      for (const tag of entry.tags) {
-        if (tag.key) keyed.set(tag.key, tag)
-        else unkeyed.push(tag)
-      }
-      if (entry.titleTemplate !== undefined) titleTemplate = entry.titleTemplate
-      if (entry.htmlAttrs) Object.assign(htmlAttrs, entry.htmlAttrs)
-      if (entry.bodyAttrs) Object.assign(bodyAttrs, entry.bodyAttrs)
-    }
-
-    cachedTags = [...keyed.values(), ...unkeyed]
-    cachedTitleTemplate = titleTemplate
-    cachedHtmlAttrs = htmlAttrs
-    cachedBodyAttrs = bodyAttrs
-  }
-
-  return {
-    add(id, entry) {
-      map.set(id, entry)
-      dirty = true
-    },
-    remove(id) {
-      map.delete(id)
-      dirty = true
-    },
-    resolve() {
-      rebuild()
-      return cachedTags
-    },
-    resolveTitleTemplate() {
-      rebuild()
-      return cachedTitleTemplate
-    },
-    resolveHtmlAttrs() {
-      rebuild()
-      return cachedHtmlAttrs
-    },
-    resolveBodyAttrs() {
-      rebuild()
-      return cachedBodyAttrs
-    },
-  }
-}
-
-export const HeadContext = createContext<HeadContextValue | null>(null)

package/src/dom.ts

@@ -1,147 +0,0 @@
-import type { HeadContextValue } from './context'
-
-const ATTR = 'data-pyreon-head'
-
-/** Tracks managed elements by key — avoids querySelectorAll on every sync */
-const managedElements = new Map<string, Element>()
-
-/**
- * Sync the resolved head tags to the real DOM <head>.
- * Uses incremental diffing: matches existing elements by key, patches attributes
- * in-place, adds new elements, and removes stale ones.
- * Also syncs htmlAttrs, bodyAttrs, and applies titleTemplate.
- * No-op on the server (typeof document === "undefined").
- */
-function patchExistingTag(
-  found: Element,
-  tag: { props: Record<string, unknown>; children: string },
-  kept: Set<string>,
-): void {
-  kept.add(found.getAttribute(ATTR) as string)
-  patchAttrs(found, tag.props as Record<string, string>)
-  const content = String(tag.children)
-  if (found.textContent !== content) found.textContent = content
-}
-
-function createNewTag(tag: {
-  tag: string
-  props: Record<string, unknown>
-  children: string
-  key: unknown
-}): void {
-  // SSR guard: only ever reached via the (also-guarded) `syncDom`, but
-  // keep the guard local so the contract is self-evident and SSR-safe
-  // even if a future caller invokes this directly.
-  if (typeof document === 'undefined') return
-  const el = document.createElement(tag.tag)
-  const key = tag.key as string
-  el.setAttribute(ATTR, key)
-  for (const [k, v] of Object.entries(tag.props as Record<string, string>)) {
-    el.setAttribute(k, v)
-  }
-  if (tag.children) el.textContent = tag.children
-  document.head.appendChild(el)
-  managedElements.set(key, el)
-}
-
-export function syncDom(ctx: HeadContextValue): void {
-  if (typeof document === 'undefined') return
-
-  const tags = ctx.resolve()
-  const titleTemplate = ctx.resolveTitleTemplate()
-
-  // Seed from DOM on first sync, or re-seed if DOM was reset (e.g. between tests)
-  let needsSeed = managedElements.size === 0
-  if (!needsSeed) {
-    // Check if a tracked element is still in the DOM
-    const sample = managedElements.values().next().value
-    if (sample && !sample.isConnected) {
-      managedElements.clear()
-      needsSeed = true
-    }
-  }
-  if (needsSeed) {
-    const existing = document.head.querySelectorAll(`[${ATTR}]`)
-    for (const el of existing) {
-      managedElements.set(el.getAttribute(ATTR) as string, el)
-    }
-  }
-
-  const kept = new Set<string>()
-
-  for (const tag of tags) {
-    if (tag.tag === 'title') {
-      document.title = applyTitleTemplate(String(tag.children), titleTemplate)
-      continue
-    }
-
-    const key = tag.key as string
-    const found = managedElements.get(key)
-
-    if (found && found.tagName.toLowerCase() === tag.tag) {
-      patchExistingTag(found, tag as { props: Record<string, unknown>; children: string }, kept)
-    } else {
-      if (found) {
-        found.remove()
-        managedElements.delete(key)
-      }
-      createNewTag(
-        tag as { tag: string; props: Record<string, unknown>; children: string; key: unknown },
-      )
-      kept.add(key)
-    }
-  }
-
-  // Remove stale elements
-  for (const [key, el] of managedElements) {
-    if (!kept.has(key)) {
-      el.remove()
-      managedElements.delete(key)
-    }
-  }
-
-  syncElementAttrs(document.documentElement, ctx.resolveHtmlAttrs())
-  syncElementAttrs(document.body, ctx.resolveBodyAttrs())
-}
-
-/** Patch an element's attributes to match the desired props. */
-function patchAttrs(el: Element, props: Record<string, string>): void {
-  for (let i = el.attributes.length - 1; i >= 0; i--) {
-    const attr = el.attributes[i]
-    if (!attr || attr.name === ATTR) continue
-    if (!(attr.name in props)) el.removeAttribute(attr.name)
-  }
-  for (const [k, v] of Object.entries(props)) {
-    if (el.getAttribute(k) !== v) el.setAttribute(k, v)
-  }
-}
-
-function applyTitleTemplate(
-  title: string,
-  template: string | ((t: string) => string) | undefined,
-): string {
-  if (!template) return title
-  if (typeof template === 'function') return template(title)
-  return template.replace(/%s/g, title)
-}
-
-/** Sync pyreon-managed attributes on <html> or <body>. */
-function syncElementAttrs(el: Element, attrs: Record<string, string>): void {
-  // Remove previously managed attrs that are no longer present
-  const managed = el.getAttribute(`${ATTR}-attrs`)
-  if (managed) {
-    for (const name of managed.split(',')) {
-      if (name && !(name in attrs)) el.removeAttribute(name)
-    }
-  }
-  const keys: string[] = []
-  for (const [k, v] of Object.entries(attrs)) {
-    keys.push(k)
-    if (el.getAttribute(k) !== v) el.setAttribute(k, v)
-  }
-  if (keys.length > 0) {
-    el.setAttribute(`${ATTR}-attrs`, keys.join(','))
-  } else if (managed) {
-    el.removeAttribute(`${ATTR}-attrs`)
-  }
-}

package/src/index.ts

@@ -1,18 +0,0 @@
-export type {
-  BaseTag,
-  HeadContextValue,
-  HeadEntry,
-  HeadTag,
-  LinkTag,
-  MetaTag,
-  ScriptTag,
-  SpeculationEagerness,
-  SpeculationRule,
-  SpeculationRules,
-  StyleTag,
-  UseHeadInput,
-} from './context'
-export { createHeadContext, HeadContext } from './context'
-export type { HeadProviderProps } from './provider'
-export { HeadProvider } from './provider'
-export { useHead } from './use-head'

package/src/manifest.ts

@@ -1,153 +0,0 @@
-import { defineManifest } from '@pyreon/manifest'
-
-export default defineManifest({
-  name: '@pyreon/head',
-  title: 'Head Management',
-  tagline:
-    'Reactive `<head>` tag management — useHead(), HeadProvider, renderWithHead() for SSR',
-  description:
-    'Reactive head tag management for Pyreon — `useHead()` collects title, meta, link, script, style, noscript, base, jsonLd entries from any component in the tree (static or signal-driven). `HeadProvider` collects them on the client and syncs to the live `<head>` element; `renderWithHead()` collects them on the server and returns the serialized HTML alongside the rendered app.',
-  category: 'browser',
-  features: [
-    'useHead(input | () => input) — register head tags from any component',
-    'Reactive: pass a function to re-register on signal change',
-    'Title templates with %s placeholder or function form',
-    'HeadProvider for client-side DOM sync',
-    'renderWithHead() for SSR — returns html + head string',
-    'Keyed deduplication — innermost component wins per key',
-    'JSON-LD shorthand: `jsonLd: {...}` auto-wraps as `<script type="application/ld+json">`',
-    'Speculation Rules shorthand: `speculationRules: {...}` auto-wraps as `<script type="speculationrules">` — native browser prefetch/prerender, opt-in',
-  ],
-  longExample: `import { useHead, HeadProvider } from '@pyreon/head'
-import { renderWithHead } from '@pyreon/head'
-import { mount } from '@pyreon/runtime-dom'
-
-// Static head tags from any component
-function ProfilePage() {
-  useHead({
-    title: 'My Profile',
-    meta: [{ name: 'description', content: 'User profile page' }],
-    link: [{ rel: 'canonical', href: 'https://example.com/profile' }],
-  })
-  return <div>profile body</div>
-}
-
-// Reactive head — pass a function so signal reads re-register on change
-function ReactiveTitle() {
-  useHead(() => ({
-    title: \`\${username()} — Profile\`,
-    meta: [{ property: 'og:title', content: username() }],
-  }))
-  return null
-}
-
-// Client setup
-mount(
-  <HeadProvider>
-    <App />
-  </HeadProvider>,
-  document.getElementById('app')!,
-)
-
-// Server setup — collects every useHead() call and serializes the head
-const { html, head, htmlAttrs, bodyAttrs } = await renderWithHead(<App />)
-const document = \`<!doctype html><html\${htmlAttrs}><head>\${head}</head><body\${bodyAttrs}>\${html}</body></html>\``,
-  api: [
-    {
-      name: 'useHead',
-      kind: 'hook',
-      signature: 'useHead(input: UseHeadInput | (() => UseHeadInput)): void',
-      summary:
-        'Register head tags from any component in the tree. Pass a static `UseHeadInput` object for one-shot registration, or a `() => UseHeadInput` thunk for reactive re-registration when signal reads inside the thunk change. Calling `useHead()` outside a `HeadProvider` ancestor (CSR) or `renderWithHead()` invocation (SSR) is a silent no-op — it does not throw.',
-      example: `// Static:
-useHead({ title: "My Page", meta: [{ name: "description", content: "..." }] })
-
-// Reactive (updates when signals change):
-useHead(() => ({
-  title: \`\${username()} — Profile\`,
-  meta: [{ property: "og:title", content: username() }]
-}))`,
-      mistakes: [
-        'Using `${...}` in a `titleTemplate` string — the placeholder is `%s` (or pass a function form `(title) => …`)',
-        'Calling `useHead()` outside any `HeadProvider` / `renderWithHead()` boundary — silent no-op, the entries simply go nowhere',
-        'Wrapping the input in `computed()` instead of a thunk — pass a plain `() => ({...})` arrow; `useHead` registers its own effect',
-        'Expecting `</script>` inside an inline script body to render verbatim — the SSR escaper rewrites it as `<\\/script>` to prevent breaking out of the inline tag',
-        'Treating `speculationRules` as a guaranteed perf win — it is a declarative HINT (like `<link rel=prefetch>`); supported browsers prefetch/prerender at their own discretion, unsupported ones ignore it. It is opt-in and zero-runtime-JS; it does not replace `RouterLink prefetch` (which warms loader data for client-side nav)',
-      ],
-      seeAlso: ['HeadProvider', 'renderWithHead'],
-    },
-    {
-      name: 'HeadProvider',
-      kind: 'component',
-      signature: '(props: HeadProviderProps) => VNodeChild',
-      summary:
-        '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>
-
-// 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 (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'],
-    },
-    {
-      name: 'renderWithHead',
-      kind: 'function',
-      signature:
-        'renderWithHead(app: VNode): Promise<{ html: string; head: string; htmlAttrs: string; bodyAttrs: string }>',
-      summary:
-        'SSR companion to `HeadProvider`. Renders the app to HTML via `renderToString` while collecting every `useHead()` call from the tree, then serializes the resolved tags into a single `head` string plus separate `htmlAttrs` / `bodyAttrs` strings. Async components that call `useHead()` in their body work — the renderer awaits suspended subtrees before serialization.',
-      example: `import { renderWithHead } from '@pyreon/head'
-
-const { html, head, htmlAttrs, bodyAttrs } = await renderWithHead(<App />)
-const doc = \`<!doctype html><html\${htmlAttrs}><head>\${head}</head><body\${bodyAttrs}>\${html}</body></html>\``,
-      mistakes: [
-        'Awaiting `renderWithHead` and then NOT splicing `head` into the `<head>` element — every `useHead()` call quietly disappears',
-        'Forgetting to interpolate `htmlAttrs` / `bodyAttrs` (the leading space is included in each string) — `htmlAttrs.lang` and `bodyAttrs.class` set via `useHead` won\\\'t reach the DOM',
-      ],
-      seeAlso: ['useHead', 'HeadProvider'],
-    },
-    {
-      name: 'createHeadContext',
-      kind: 'function',
-      signature: '() => HeadContextValue',
-      summary:
-        'Manual factory for a `HeadContextValue` — only needed when wiring up a custom SSR pipeline that bypasses `renderWithHead`, or when running multiple isolated head contexts in the same process. The value exposes `add` / `remove` / `resolve` / `resolveTitleTemplate` / `resolveHtmlAttrs` / `resolveBodyAttrs` for full programmatic control.',
-      example: `import { createHeadContext, HeadContext } from '@pyreon/head'
-
-const ctx = createHeadContext()
-provide(HeadContext, ctx)
-// ... render tree that calls useHead() ...
-const { tags, htmlAttrs, bodyAttrs } = ctx.resolve()`,
-      seeAlso: ['HeadProvider', 'renderWithHead'],
-    },
-  ],
-  gotchas: [
-    {
-      label: 'Key deduplication',
-      note:
-        'Tags with the same key replace each other (innermost wins). Meta keys: `name` → `property` → index. Link keys: `href + rel` → `rel` → index. Script keys: `src` → index. Style and noscript are unkeyed and always accumulated.',
-    },
-    {
-      label: 'Inline script escaping',
-      note:
-        'Script / style / noscript bodies are not HTML-escaped, but the SSR serializer rewrites `</script>` / `</style>` / `</noscript>` and `<!--` to prevent breaking out of the wrapping tag. Inline JSON-LD via `jsonLd: {...}` auto-wraps in `<script type="application/ld+json">` and stringifies the value.',
-    },
-  ],
-})