@pyreon/head 0.18.0 → 0.19.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":"198a0340-1","name":"context.ts"},{"uid":"198a0340-3","name":"provider.ts"},{"uid":"198a0340-5","name":"dom.ts"},{"uid":"198a0340-7","name":"use-head.ts"},{"uid":"198a0340-9","name":"index.ts"}]}]}],"isRoot":true},"nodeParts":{"198a0340-1":{"renderedLength":1373,"gzipLength":509,"brotliLength":0,"metaUid":"198a0340-0"},"198a0340-3":{"renderedLength":681,"gzipLength":408,"brotliLength":0,"metaUid":"198a0340-2"},"198a0340-5":{"renderedLength":3401,"gzipLength":1293,"brotliLength":0,"metaUid":"198a0340-4"},"198a0340-7":{"renderedLength":2462,"gzipLength":1063,"brotliLength":0,"metaUid":"198a0340-6"},"198a0340-9":{"renderedLength":0,"gzipLength":0,"brotliLength":0,"metaUid":"198a0340-8"}},"nodeMetas":{"198a0340-0":{"id":"/src/context.ts","moduleParts":{"index.js":"198a0340-1"},"imported":[{"uid":"198a0340-10"}],"importedBy":[{"uid":"198a0340-8"},{"uid":"198a0340-2"},{"uid":"198a0340-6"}]},"198a0340-2":{"id":"/src/provider.ts","moduleParts":{"index.js":"198a0340-3"},"imported":[{"uid":"198a0340-10"},{"uid":"198a0340-0"}],"importedBy":[{"uid":"198a0340-8"}]},"198a0340-4":{"id":"/src/dom.ts","moduleParts":{"index.js":"198a0340-5"},"imported":[],"importedBy":[{"uid":"198a0340-6"}]},"198a0340-6":{"id":"/src/use-head.ts","moduleParts":{"index.js":"198a0340-7"},"imported":[{"uid":"198a0340-10"},{"uid":"198a0340-11"},{"uid":"198a0340-0"},{"uid":"198a0340-4"}],"importedBy":[{"uid":"198a0340-8"}]},"198a0340-8":{"id":"/src/index.ts","moduleParts":{"index.js":"198a0340-9"},"imported":[{"uid":"198a0340-0"},{"uid":"198a0340-2"},{"uid":"198a0340-6"}],"importedBy":[],"isEntry":true},"198a0340-10":{"id":"@pyreon/core","moduleParts":{},"imported":[],"importedBy":[{"uid":"198a0340-0"},{"uid":"198a0340-2"},{"uid":"198a0340-6"}]},"198a0340-11":{"id":"@pyreon/reactivity","moduleParts":{},"imported":[],"importedBy":[{"uid":"198a0340-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":"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 run = () => {
       const width = window.innerWidth;

package/lib/analysis/use-head.js.html

@@ -5386,7 +5386,7 @@ var drawChart = (function (exports) {
   </script>
   <script>
     /*<!--*/
-    const data = {"version":2,"tree":{"name":"root","children":[{"name":"use-head.js","children":[{"name":"src","children":[{"uid":"2d2aa494-1","name":"context.ts"},{"uid":"2d2aa494-3","name":"dom.ts"},{"uid":"2d2aa494-5","name":"use-head.ts"}]}]}],"isRoot":true},"nodeParts":{"2d2aa494-1":{"renderedLength":79,"gzipLength":85,"brotliLength":0,"metaUid":"2d2aa494-0"},"2d2aa494-3":{"renderedLength":3401,"gzipLength":1293,"brotliLength":0,"metaUid":"2d2aa494-2"},"2d2aa494-5":{"renderedLength":2462,"gzipLength":1063,"brotliLength":0,"metaUid":"2d2aa494-4"}},"nodeMetas":{"2d2aa494-0":{"id":"/src/context.ts","moduleParts":{"use-head.js":"2d2aa494-1"},"imported":[{"uid":"2d2aa494-6"}],"importedBy":[{"uid":"2d2aa494-4"}]},"2d2aa494-2":{"id":"/src/dom.ts","moduleParts":{"use-head.js":"2d2aa494-3"},"imported":[],"importedBy":[{"uid":"2d2aa494-4"}]},"2d2aa494-4":{"id":"/src/use-head.ts","moduleParts":{"use-head.js":"2d2aa494-5"},"imported":[{"uid":"2d2aa494-6"},{"uid":"2d2aa494-7"},{"uid":"2d2aa494-0"},{"uid":"2d2aa494-2"}],"importedBy":[],"isEntry":true},"2d2aa494-6":{"id":"@pyreon/core","moduleParts":{},"imported":[],"importedBy":[{"uid":"2d2aa494-4"},{"uid":"2d2aa494-0"}]},"2d2aa494-7":{"id":"@pyreon/reactivity","moduleParts":{},"imported":[],"importedBy":[{"uid":"2d2aa494-4"}]}},"env":{"rollup":"4.23.0"},"options":{"gzip":true,"brotli":false,"sourcemap":false}};
+    const data = {"version":2,"tree":{"name":"root","children":[{"name":"use-head.js","children":[{"name":"src","children":[{"uid":"a2d4ff75-1","name":"context.ts"},{"uid":"a2d4ff75-3","name":"dom.ts"},{"uid":"a2d4ff75-5","name":"use-head.ts"}]}]}],"isRoot":true},"nodeParts":{"a2d4ff75-1":{"renderedLength":79,"gzipLength":85,"brotliLength":0,"metaUid":"a2d4ff75-0"},"a2d4ff75-3":{"renderedLength":3447,"gzipLength":1292,"brotliLength":0,"metaUid":"a2d4ff75-2"},"a2d4ff75-5":{"renderedLength":2634,"gzipLength":1093,"brotliLength":0,"metaUid":"a2d4ff75-4"}},"nodeMetas":{"a2d4ff75-0":{"id":"/src/context.ts","moduleParts":{"use-head.js":"a2d4ff75-1"},"imported":[{"uid":"a2d4ff75-6"}],"importedBy":[{"uid":"a2d4ff75-4"}]},"a2d4ff75-2":{"id":"/src/dom.ts","moduleParts":{"use-head.js":"a2d4ff75-3"},"imported":[],"importedBy":[{"uid":"a2d4ff75-4"}]},"a2d4ff75-4":{"id":"/src/use-head.ts","moduleParts":{"use-head.js":"a2d4ff75-5"},"imported":[{"uid":"a2d4ff75-6"},{"uid":"a2d4ff75-7"},{"uid":"a2d4ff75-0"},{"uid":"a2d4ff75-2"}],"importedBy":[],"isEntry":true},"a2d4ff75-6":{"id":"@pyreon/core","moduleParts":{},"imported":[],"importedBy":[{"uid":"a2d4ff75-4"},{"uid":"a2d4ff75-0"}]},"a2d4ff75-7":{"id":"@pyreon/reactivity","moduleParts":{},"imported":[],"importedBy":[{"uid":"a2d4ff75-4"}]}},"env":{"rollup":"4.23.0"},"options":{"gzip":true,"brotli":false,"sourcemap":false}};
 
     const run = () => {
       const width = window.innerWidth;

package/lib/index.js

@@ -100,6 +100,7 @@ function patchExistingTag(found, tag, kept) {
 	if (found.textContent !== content) found.textContent = content;
 }
 function createNewTag(tag) {
+	if (typeof document === "undefined") return;
 	const el = document.createElement(tag.tag);
 	const key = tag.key;
 	el.setAttribute(ATTR, key);
@@ -238,6 +239,12 @@ function buildEntry(o) {
 		props: { type: "application/ld+json" },
 		children: JSON.stringify(o.jsonLd)
 	});
+	if (o.speculationRules) tags.push({
+		tag: "script",
+		key: "speculationrules",
+		props: { type: "speculationrules" },
+		children: JSON.stringify(o.speculationRules)
+	});
 	if (o.base) tags.push({
 		tag: "base",
 		key: "base",

package/lib/types/index.d.ts

@@ -104,6 +104,48 @@ interface StyleTag {
   /** Render-blocking behavior */
   blocking?: string;
 }
+/**
+ * How eagerly the browser should act on a speculation rule.
+ * Per the W3C Speculation Rules spec.
+ */
+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' }`).
+ */
+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
+ */
+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. */
 interface BaseTag {
   /** Base URL for relative URLs in the document */
@@ -128,6 +170,13 @@ interface UseHeadInput {
   }[];
   /** 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>;
@@ -190,5 +239,5 @@ declare const HeadProvider: ComponentFn<HeadProviderProps>;
  */
 declare function useHead(input: UseHeadInput | (() => UseHeadInput)): void;
 //#endregion
-export { type BaseTag, HeadContext, type HeadContextValue, type HeadEntry, HeadProvider, type HeadProviderProps, type HeadTag, type LinkTag, type MetaTag, type ScriptTag, type StyleTag, type UseHeadInput, createHeadContext, useHead };
+export { type BaseTag, HeadContext, type HeadContextValue, type HeadEntry, HeadProvider, type HeadProviderProps, type HeadTag, type LinkTag, type MetaTag, type ScriptTag, type SpeculationEagerness, type SpeculationRule, type SpeculationRules, type StyleTag, type UseHeadInput, createHeadContext, useHead };
 //# sourceMappingURL=index2.d.ts.map

package/lib/types/use-head.d.ts

@@ -87,6 +87,48 @@ interface StyleTag {
   /** Render-blocking behavior */
   blocking?: string;
 }
+/**
+ * How eagerly the browser should act on a speculation rule.
+ * Per the W3C Speculation Rules spec.
+ */
+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' }`).
+ */
+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
+ */
+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. */
 interface BaseTag {
   /** Base URL for relative URLs in the document */
@@ -111,6 +153,13 @@ interface UseHeadInput {
   }[];
   /** 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>;

package/lib/use-head.js

@@ -23,6 +23,7 @@ function patchExistingTag(found, tag, kept) {
 	if (found.textContent !== content) found.textContent = content;
 }
 function createNewTag(tag) {
+	if (typeof document === "undefined") return;
 	const el = document.createElement(tag.tag);
 	const key = tag.key;
 	el.setAttribute(ATTR, key);
@@ -161,6 +162,12 @@ function buildEntry(o) {
 		props: { type: "application/ld+json" },
 		children: JSON.stringify(o.jsonLd)
 	});
+	if (o.speculationRules) tags.push({
+		tag: "script",
+		key: "speculationrules",
+		props: { type: "speculationrules" },
+		children: JSON.stringify(o.speculationRules)
+	});
 	if (o.base) tags.push({
 		tag: "base",
 		key: "base",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pyreon/head",
-  "version": "0.18.0",
+  "version": "0.19.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.18.0",
-    "@pyreon/reactivity": "^0.18.0",
-    "@pyreon/runtime-server": "^0.18.0"
+    "@pyreon/core": "^0.19.0",
+    "@pyreon/reactivity": "^0.19.0",
+    "@pyreon/runtime-server": "^0.19.0"
   },
   "devDependencies": {
     "@happy-dom/global-registrator": "^20.8.9",
     "@pyreon/manifest": "0.13.1",
-    "@pyreon/runtime-dom": "^0.18.0",
-    "@pyreon/runtime-server": "^0.18.0",
-    "@pyreon/test-utils": "^0.13.5",
+    "@pyreon/runtime-dom": "^0.19.0",
+    "@pyreon/runtime-server": "^0.19.0",
+    "@pyreon/test-utils": "^0.13.6",
     "@vitest/browser-playwright": "^4.1.4"
   },
   "peerDependenciesMeta": {

package/src/context.ts

@@ -111,6 +111,51 @@ export interface StyleTag {
   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 */
@@ -134,6 +179,13 @@ export interface UseHeadInput {
   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>

package/src/dom.ts

@@ -29,6 +29,10 @@ function createNewTag(tag: {
   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)

package/src/index.ts

@@ -6,6 +6,9 @@ export type {
   LinkTag,
   MetaTag,
   ScriptTag,
+  SpeculationEagerness,
+  SpeculationRule,
+  SpeculationRules,
   StyleTag,
   UseHeadInput,
 } from './context'

package/src/manifest.ts

@@ -16,6 +16,7 @@ export default defineManifest({
     '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'
@@ -71,6 +72,7 @@ useHead(() => ({
         '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'],
     },

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

@@ -191,4 +191,61 @@ describe('head in real browser', () => {
     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
+    }
+  })
 })

package/src/tests/head.test.ts

@@ -1187,3 +1187,127 @@ describe('useHead — SSR paths (document undefined)', () => {
     expect(typeof document).toBe('undefined')
   })
 })
+
+// ─── speculationRules (E12) ──────────────────────────────────────────────────
+
+describe('useHead — speculationRules', () => {
+  test('SSR: emits a single <script type="speculationrules"> with valid JSON body', async () => {
+    function Page() {
+      useHead({
+        speculationRules: {
+          prerender: [{ source: 'list', urls: ['/about', '/posts'], eagerness: 'moderate' }],
+        },
+      })
+      return h('div', null)
+    }
+    const { head } = await renderWithHead(h(Page, null))
+    expect(head).toContain('type="speculationrules"')
+    // Body must be valid JSON parseable back to the exact rules.
+    const m = head.match(/<script type="speculationrules">([\s\S]*?)<\/script>/)
+    expect(m).not.toBeNull()
+    const parsed = JSON.parse((m as RegExpMatchArray)[1] as string)
+    expect(parsed).toEqual({
+      prerender: [{ source: 'list', urls: ['/about', '/posts'], eagerness: 'moderate' }],
+    })
+    // Exactly one block — no accidental duplicate.
+    expect(head.match(/type="speculationrules"/g)).toHaveLength(1)
+  })
+
+  test('CSR: syncs the speculationrules script into document.head on mount', () => {
+    const ctx = createHeadContext()
+    const container = document.createElement('div')
+    function Page() {
+      useHead({ speculationRules: { prefetch: [{ source: 'list', urls: ['/next'] }] } })
+      return h('div', null)
+    }
+    mount(h(HeadProvider, { context: ctx, children: h(Page, null) }), container)
+    const script = document.head.querySelector('script[type="speculationrules"]')
+    expect(script).not.toBeNull()
+    expect(JSON.parse(script?.textContent ?? '{}')).toEqual({
+      prefetch: [{ source: 'list', urls: ['/next'] }],
+    })
+  })
+
+  test('deduped by key — innermost component wins, never two blocks', async () => {
+    function Inner() {
+      useHead({ speculationRules: { prerender: [{ source: 'list', urls: ['/inner'] }] } })
+      return h('div', null)
+    }
+    function Outer() {
+      useHead({ speculationRules: { prerender: [{ source: 'list', urls: ['/outer'] }] } })
+      return h('div', null, h(Inner, null))
+    }
+    const { head } = await renderWithHead(h(Outer, null))
+    expect(head.match(/type="speculationrules"/g)).toHaveLength(1)
+    expect(head).toContain('/inner')
+    expect(head).not.toContain('/outer')
+  })
+
+  test('reactive: regenerates when the source signal changes', () => {
+    const ctx = createHeadContext()
+    const container = document.createElement('div')
+    const target = signal('/a')
+    function Page() {
+      useHead(() => ({
+        speculationRules: { prerender: [{ source: 'list', urls: [target()] }] },
+      }))
+      return h('div', null)
+    }
+    mount(h(HeadProvider, { context: ctx, children: h(Page, null) }), container)
+    expect(document.head.querySelector('script[type="speculationrules"]')?.textContent).toContain(
+      '/a',
+    )
+    target.set('/b')
+    expect(document.head.querySelector('script[type="speculationrules"]')?.textContent).toContain(
+      '/b',
+    )
+  })
+
+  test('document-source predicate rules round-trip', async () => {
+    function Page() {
+      useHead({
+        speculationRules: {
+          prefetch: [
+            {
+              source: 'document',
+              where: { selector_matches: 'a.router-link' },
+              eagerness: 'conservative',
+            },
+          ],
+        },
+      })
+      return h('div', null)
+    }
+    const { head } = await renderWithHead(h(Page, null))
+    const m = head.match(/<script type="speculationrules">([\s\S]*?)<\/script>/)
+    expect(JSON.parse((m as RegExpMatchArray)[1] as string).prefetch[0].where).toEqual({
+      selector_matches: 'a.router-link',
+    })
+  })
+
+  test('opt-in: no script emitted when speculationRules is absent', async () => {
+    function Page() {
+      useHead({ title: 'No Rules' })
+      return h('div', null)
+    }
+    const { head } = await renderWithHead(h(Page, null))
+    expect(head).not.toContain('speculationrules')
+  })
+
+  test('XSS-safe: a URL containing </script> is escaped, body stays valid JSON', async () => {
+    function Page() {
+      useHead({
+        speculationRules: { prerender: [{ source: 'list', urls: ['/x</script><b>pwn'] }] },
+      })
+      return h('div', null)
+    }
+    const { head } = await renderWithHead(h(Page, null))
+    // The raw closing tag must NOT appear unescaped inside the block.
+    const block = head.match(/<script type="speculationrules">([\s\S]*?)<\/script>/)
+    expect(block).not.toBeNull()
+    expect((block as RegExpMatchArray)[1]).not.toContain('</script>')
+    // And the un-escaped JSON still parses back to the original URL.
+    const unescaped = (block as RegExpMatchArray)[1]!.replace(/<\\\//g, '</')
+    expect(JSON.parse(unescaped).prerender[0].urls[0]).toBe('/x</script><b>pwn')
+  })
+})

package/src/use-head.ts

@@ -59,6 +59,14 @@ function buildEntry(o: UseHeadInput): HeadEntry {
       children: JSON.stringify(o.jsonLd),
     })
   }
+  if (o.speculationRules) {
+    tags.push({
+      tag: 'script',
+      key: 'speculationrules',
+      props: { type: 'speculationrules' },
+      children: JSON.stringify(o.speculationRules),
+    })
+  }
   if (o.base)
     tags.push({
       tag: 'base',