npm - @pyreon/head - Versions diffs - 0.24.4 → 0.24.6 - Mend

@pyreon/head 0.24.4 → 0.24.6

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 (16) hide show

package/package.json +6 -12
package/src/context.ts +0 -282
package/src/dom.ts +0 -147
package/src/index.ts +0 -18
package/src/manifest.ts +0 -153
package/src/provider.ts +0 -65
package/src/ssr.ts +0 -89
package/src/tests/context-identity.test.ts +0 -126
package/src/tests/head.browser.test.tsx +0 -251
package/src/tests/head.test.ts +0 -1313
package/src/tests/integration.test.tsx +0 -83
package/src/tests/manifest-snapshot.test.ts +0 -34
package/src/tests/native-marker.test.ts +0 -9
package/src/tests/provider-inherits-context.test.tsx +0 -131
package/src/tests/setup.ts +0 -3
package/src/use-head.ts +0 -123

package/src/provider.ts DELETED Viewed

@@ -1,65 +0,0 @@
-import type { ComponentFn, Props, VNodeChild } from '@pyreon/core'
-import { nativeCompat, provide, useContext } from '@pyreon/core'
-import type { HeadContextValue } from './context'
-import { createHeadContext, HeadContext } from './context'
-export interface HeadProviderProps extends Props {
-  context?: HeadContextValue | undefined
-  children?: VNodeChild
-}
-/**
- * Provides a HeadContextValue to all descendant components.
- * Wrap your app root with this to enable useHead() throughout the tree.
- *
- * 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 (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) => {
-  // `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
-  return typeof ch === 'function' ? (ch as () => VNodeChild)() : ch
-}
-// Mark as native — compat-mode jsx() runtimes skip wrapCompatComponent so
-// HeadProvider's provide(HeadContext, ...) call runs inside Pyreon's setup
-// frame, not the compat wrapper's runUntracked accessor.
-nativeCompat(HeadProvider)

package/src/ssr.ts DELETED Viewed

@@ -1,89 +0,0 @@
-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'
-const VOID_TAGS = new Set(['meta', 'link', 'base'])
-/**
- * Render a Pyreon app to an HTML fragment + a serialized <head> string.
- *
- * The returned `head` string can be injected directly into your HTML template:
- *
- * @example
- * const { html, head } = await renderWithHead(h(App, null))
- * const page = `<!DOCTYPE html>
- * <html>
- *   <head>
- *     <meta charset="UTF-8" />
- *     ${head}
- *   </head>
- *   <body><div id="app">${html}</div></body>
- * </html>`
- */
-export interface RenderWithHeadResult {
-  html: string
-  head: string
-  /** Attributes to set on the <html> element */
-  htmlAttrs: Record<string, string>
-  /** Attributes to set on the <body> element */
-  bodyAttrs: Record<string, string>
-}
-export async function renderWithHead(app: VNode): Promise<RenderWithHeadResult> {
-  const ctx = createHeadContext()
-  // HeadInjector runs inside renderToString's ALS scope, so pushContext reaches
-  // the per-request context stack rather than the module-level fallback stack.
-  function HeadInjector(): VNode {
-    pushContext(new Map([[HeadContext.id, ctx]]))
-    return app
-  }
-  const html = await renderToString(h(HeadInjector as ComponentFn, null))
-  const titleTemplate = ctx.resolveTitleTemplate()
-  const head = ctx
-    .resolve()
-    .map((tag) => serializeTag(tag, titleTemplate))
-    .join('\n  ')
-  return {
-    html,
-    head,
-    htmlAttrs: ctx.resolveHtmlAttrs(),
-    bodyAttrs: ctx.resolveBodyAttrs(),
-  }
-}
-function serializeTag(tag: HeadTag, titleTemplate?: string | ((title: string) => string)): string {
-  if (tag.tag === 'title') {
-    const raw = tag.children || ''
-    const title = titleTemplate
-      ? typeof titleTemplate === 'function'
-        ? titleTemplate(raw)
-        : titleTemplate.replace(/%s/g, raw)
-      : raw
-    return `<title>${esc(title)}</title>`
-  }
-  const props = tag.props as Record<string, string> | undefined
-  const attrs = props
-    ? Object.entries(props)
-        .map(([k, v]) => `${k}="${esc(v)}"`)
-        .join(' ')
-    : ''
-  const open = attrs ? `<${tag.tag} ${attrs}` : `<${tag.tag}`
-  if (VOID_TAGS.has(tag.tag)) return `${open} />`
-  const content = tag.children || ''
-  // Escape sequences that could break out of script/style/noscript blocks:
-  // 1. Closing tags like </script> — use Unicode escape in the slash
-  // 2. HTML comment openers <!-- that could confuse parsers
-  const body = content.replace(/<\/(script|style|noscript)/gi, '<\\/$1').replace(/<!--/g, '<\\!--')
-  return `${open}>${body}</${tag.tag}>`
-}
-const ESC_RE = /[&<>"]/g
-const ESC_MAP: Record<string, string> = { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' }
-function esc(s: string): string {
-  return ESC_RE.test(s) ? s.replace(ESC_RE, (ch) => ESC_MAP[ch] as string) : s
-}

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

@@ -1,126 +0,0 @@
-/**
- * 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,provider,use-head,ssr}.js`) and the shared
- * `@vitus-labs/tools-rolldown` (< 2.4.0) invoked 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 durable fix lives upstream in `@vitus-labs/tools-rolldown >= 2.4.0`:
- * the build tool now creates SHARED CHUNKS across sub-entries, so the
- * shared `context.ts` gets hoisted into a single chunk (`lib/context.js`)
- * that every other sub-entry imports via relative-path `./context.js`.
- * `createContext(null)` runs exactly once at runtime; `HeadContext` is
- * one Symbol across every sub-entry's bundle. No per-package
- * externalization / self-package-import workaround needed.
- *
- * Structural assertions (the BUG-CLASS-LOCK — same intent, cleaner shape):
- *   1. `lib/context.js` is the ONLY bundle that calls `createContext(`.
- *   2. EVERY other published JS file under `lib/` (including
- *      `lib/_chunks/*.js` shared chunks the tool emits) has ZERO
- *      `createContext` references — they all import `HeadContext` from
- *      `./context.js`, sharing the single Symbol identity.
- *
- * Together these invariants make the bug class structurally impossible
- * to re-introduce silently — any future regression (e.g. downgrade of
- * the build tool below 2.4.0, or a build-config change that re-enables
- * per-entry inlining) flips one of the per-bundle counters and trips
- * the assertion. Bisect-verified by reverting the
- * `@vitus-labs/tools-rolldown` bump: every non-context sub-bundle gets
- * its own inlined `createContext(null)` call (2 occurrences each), and
- * the second assertion fails on the first non-context bundle.
- */
-import { existsSync, readdirSync, 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 = (rel: string) => readFileSync(resolve(LIB_DIR, rel), 'utf8')
-/** Every published JS file under lib/ (incl. _chunks/), excluding source maps. */
-function publishedJsFiles(): string[] {
-  const out: string[] = []
-  for (const entry of readdirSync(LIB_DIR, { withFileTypes: true })) {
-    if (entry.isFile() && entry.name.endsWith('.js')) out.push(entry.name)
-    else if (entry.isDirectory() && entry.name === '_chunks') {
-      for (const sub of readdirSync(resolve(LIB_DIR, entry.name))) {
-        if (sub.endsWith('.js')) out.push(`_chunks/${sub}`)
-      }
-    }
-  }
-  return out
-}
-/**
- * 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. Every other
-    // sub-bundle / shared chunk should import `HeadContext` from it,
-    // 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)')
-    })
-    // ── Invariant 2: ZERO createContext references in EVERY other JS ──
-    //
-    // Covers both the top-level sub-entries AND the `_chunks/*.js` files
-    // the build tool now emits — any file that contains `createContext`
-    // would be running it at module-init and minting its own Symbol.
-    it('NO other lib/*.js (or lib/_chunks/*.js) calls createContext()', () => {
-      const offenders: Array<{ file: string; count: number }> = []
-      for (const rel of publishedJsFiles()) {
-        if (rel === 'context.js') continue
-        const count = read(rel).match(/createContext/g)?.length ?? 0
-        if (count > 0) offenders.push({ file: rel, count })
-      }
-      expect(offenders).toEqual([])
-    })
-    // ── Invariant 3: the package.json wiring that enables it ─────────
-    //
-    // The `./context` sub-export gives `HeadContext` a stable public
-    // address. Locking it here means a future revert 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')
-    })
-  },
-)

package/src/tests/head.browser.test.tsx DELETED Viewed

@@ -1,251 +0,0 @@
-import { h } from '@pyreon/core'
-import { signal } from '@pyreon/reactivity'
-import { flush, mountInBrowser } from '@pyreon/test-utils/browser'
-import { afterEach, describe, expect, it } from 'vitest'
-import { HeadProvider } from '../provider'
-import { useHead } from '../use-head'
-// Real-Chromium smoke suite for @pyreon/head.
-//
-// happy-dom mutates a fake `document.head`, but its serialization,
-// attribute order, and `querySelector` semantics differ subtly from
-// real browsers — and several head consumers care about exactly those
-// things (favicon swap on color scheme, dedup by `name`/`property`,
-// `<script type="application/ld+json">` content). This suite exercises
-// the wiring under a real DOM.
-const Page = (props: { setup: () => void; children?: unknown }) => {
-  props.setup()
-  return h('div', { id: 'page' }, 'page mounted')
-}
-describe('head in real browser', () => {
-  afterEach(() => {
-    // Clean up any tags this run added — head mutations are global.
-    for (const el of document.head.querySelectorAll('[data-pyreon-head]')) {
-      el.remove()
-    }
-    document.title = ''
-  })
-  it('useHead({ title }) writes document.title', () => {
-    const { unmount } = mountInBrowser(
-      h(
-        HeadProvider,
-        null,
-        h(Page, { setup: () => useHead({ title: 'Hello Browser' }) }),
-      ),
-    )
-    expect(document.title).toBe('Hello Browser')
-    unmount()
-  })
-  it('useHead({ meta }) inserts a real <meta> element with attribute correctness', () => {
-    const { unmount } = mountInBrowser(
-      h(
-        HeadProvider,
-        null,
-        h(Page, {
-          setup: () =>
-            useHead({
-              meta: [
-                { name: 'description', content: 'Pyreon framework' },
-                { property: 'og:type', content: 'website' },
-              ],
-            }),
-        }),
-      ),
-    )
-    const desc = document.head.querySelector<HTMLMetaElement>('meta[name="description"]')
-    const og = document.head.querySelector<HTMLMetaElement>('meta[property="og:type"]')
-    expect(desc?.getAttribute('content')).toBe('Pyreon framework')
-    expect(og?.getAttribute('content')).toBe('website')
-    unmount()
-  })
-  it('reactive useHead getter updates the title when the signal changes', async () => {
-    const counter = signal(0)
-    const { unmount } = mountInBrowser(
-      h(
-        HeadProvider,
-        null,
-        h(Page, { setup: () => useHead(() => ({ title: `Items: ${counter()}` })) }),
-      ),
-    )
-    expect(document.title).toBe('Items: 0')
-    counter.set(7)
-    await flush()
-    expect(document.title).toBe('Items: 7')
-    counter.set(42)
-    await flush()
-    expect(document.title).toBe('Items: 42')
-    unmount()
-  })
-  it('removes head tags when the providing component unmounts', () => {
-    const { unmount } = mountInBrowser(
-      h(
-        HeadProvider,
-        null,
-        h(Page, {
-          setup: () => useHead({ link: [{ rel: 'canonical', href: 'https://example.com/x' }] }),
-        }),
-      ),
-    )
-    expect(document.head.querySelector('link[rel="canonical"]')).not.toBeNull()
-    unmount()
-    expect(document.head.querySelector('link[rel="canonical"]')).toBeNull()
-  })
-  it('htmlAttrs / bodyAttrs are written to <html> and <body>', () => {
-    const { unmount } = mountInBrowser(
-      h(
-        HeadProvider,
-        null,
-        h(Page, {
-          setup: () =>
-            useHead({
-              htmlAttrs: { lang: 'en', dir: 'ltr' },
-              bodyAttrs: { class: 'theme-dark' },
-            }),
-        }),
-      ),
-    )
-    expect(document.documentElement.getAttribute('lang')).toBe('en')
-    expect(document.documentElement.getAttribute('dir')).toBe('ltr')
-    expect(document.body.getAttribute('class')).toBe('theme-dark')
-    unmount()
-    // After unmount the helpers remove the contributed attrs.
-    expect(document.documentElement.getAttribute('lang')).toBeNull()
-  })
-  it('titleTemplate wraps the resolved title', () => {
-    const { unmount } = mountInBrowser(
-      h(
-        HeadProvider,
-        null,
-        h(Page, {
-          setup: () => useHead({ title: 'Dashboard', titleTemplate: '%s | MyApp' }),
-        }),
-      ),
-    )
-    expect(document.title).toBe('Dashboard | MyApp')
-    unmount()
-  })
-  it('jsonLd convenience emits a <script type="application/ld+json"> with stringified content', () => {
-    const ld = { '@context': 'https://schema.org', '@type': 'Organization', name: 'Pyreon' }
-    const { unmount } = mountInBrowser(
-      h(
-        HeadProvider,
-        null,
-        h(Page, { setup: () => useHead({ jsonLd: ld }) }),
-      ),
-    )
-    const script = document.head.querySelector<HTMLScriptElement>(
-      'script[type="application/ld+json"]',
-    )
-    expect(script).not.toBeNull()
-    expect(JSON.parse(script!.textContent ?? '{}')).toEqual(ld)
-    unmount()
-  })
-  it('innermost useHead wins when multiple components contribute the same key', async () => {
-    const Inner = () => {
-      useHead({ title: 'Inner Wins' })
-      return h('div', { id: 'inner' }, 'inner')
-    }
-    const Outer = () => {
-      useHead({ title: 'Outer Loses' })
-      return h('div', { id: 'outer' }, h(Inner, {}))
-    }
-    const { unmount } = mountInBrowser(h(HeadProvider, null, h(Outer, {})))
-    await flush()
-    // Innermost component's title takes precedence.
-    expect(document.title).toBe('Inner Wins')
-    unmount()
-  })
-  it('script tags inserted with src + async + defer attributes', () => {
-    const { unmount } = mountInBrowser(
-      h(
-        HeadProvider,
-        null,
-        h(Page, {
-          setup: () =>
-            useHead({
-              script: [{ src: 'https://example.com/analytics.js', async: '', defer: '' }],
-            }),
-        }),
-      ),
-    )
-    const s = document.head.querySelector<HTMLScriptElement>(
-      'script[src="https://example.com/analytics.js"]',
-    )
-    expect(s).not.toBeNull()
-    expect(s?.async).toBe(true)
-    expect(s?.defer).toBe(true)
-    unmount()
-  })
-  // E12 — Speculation Rules. Kill-criterion #2: real Chromium must PARSE
-  // and ACCEPT the emitted block. happy-dom can't validate this — only a
-  // real browser runs the Speculation Rules parser and emits a console
-  // error on a malformed block. We assert: (a) the script lands in <head>
-  // with the exact type, (b) its body is valid JSON, (c) the browser
-  // raises NO "speculation rules" parse error, (d) HTMLScriptElement
-  // recognises the type. Whether Chromium then prefetches/prerenders is
-  // browser-discretionary (heuristic + headless-flag dependent) and is
-  // intentionally NOT asserted — the framework's contract is "emit a
-  // correct, valid declarative hint", same as `<link rel=prefetch>`.
-  it('emits a real <script type="speculationrules"> Chromium parses without error', () => {
-    const specErrors: string[] = []
-    const origErr = console.error
-    console.error = (...a: unknown[]) => {
-      const msg = a.map(String).join(' ')
-      if (/speculation\s*rules/i.test(msg)) specErrors.push(msg)
-    }
-    try {
-      const { unmount } = mountInBrowser(
-        h(
-          HeadProvider,
-          null,
-          h(Page, {
-            setup: () =>
-              useHead({
-                speculationRules: {
-                  prefetch: [
-                    {
-                      source: 'document',
-                      where: { selector_matches: 'a[data-spec]' },
-                      eagerness: 'moderate',
-                    },
-                  ],
-                  prerender: [{ source: 'list', urls: ['/about'], eagerness: 'conservative' }],
-                },
-              }),
-          }),
-        ),
-      )
-      const el = document.head.querySelector<HTMLScriptElement>(
-        'script[type="speculationrules"]',
-      )
-      expect(el).not.toBeNull()
-      // (b) body is valid JSON and round-trips.
-      const parsed = JSON.parse(el?.textContent ?? '')
-      expect(parsed.prerender[0].urls).toEqual(['/about'])
-      expect(parsed.prefetch[0].where).toEqual({ selector_matches: 'a[data-spec]' })
-      // (d) real HTMLScriptElement carries the exact type the spec requires.
-      expect(el?.type).toBe('speculationrules')
-      // (c) Chromium parsed it WITHOUT raising a speculation-rules error.
-      expect(specErrors).toEqual([])
-      unmount()
-    } finally {
-      console.error = origErr
-    }
-  })
-})