first commit

docs/foundation/data/packer-browser/src/preload/preload.md

@@ -0,0 +1,88 @@
+# `preload` — `<link rel="preload">` hint generation
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+`generatePreloadHints` derives an ordered list of `<link rel="preload">`
+hints from a packed manifest, and `injectPreloadHints` appends those
+hints to a document's `<head>`. Together they let the Service Worker
+(or a one-off bootstrap script) preload critical packed entries before
+the browser's HTML parser would have requested them.
+
+These helpers are PACKER-BROWSER-18's production surface. They are pure
+and feature-detected — `injectPreloadHints` is safe to call from a
+Service Worker context (`document` is `undefined`) and will simply
+return an empty array.
+
+## Features
+
+- `preload: true` selection (default) or descending-priority top-N
+- Stable tiebreak for ties: lexicographic ordering on `url`
+- `as` defaults to `"fetch"` when absent — preserves correct dispatch
+- `crossOrigin` pass-through to the emitted `<link>`
+- OTel `fetchTotal` increments when an observability bundle is supplied
+
+## Usage: Basic
+
+```ts
+import {
+    generatePreloadHints,
+    injectPreloadHints,
+} from "@suaveplan/packer-browser/preload";
+
+const hints = generatePreloadHints({
+    entries: [
+        { url: "/hero.image.packed", preload: true, as: "image" },
+        { url: "/font.woff2", preload: true, as: "font" },
+    ],
+});
+injectPreloadHints(document, hints);
+```
+
+## Usage: Advanced
+
+```ts
+import { createPackerBrowserObservability } from "@suaveplan/packer-browser";
+
+const observability = createPackerBrowserObservability({ meter });
+
+const topThree = generatePreloadHints(
+    {
+        entries: [
+            { url: "/a.packed", priority: 1 },
+            { url: "/b.packed", priority: 5 },
+            { url: "/c.packed", priority: 3 },
+        ],
+    },
+    { topN: 3, observability }
+);
+// emits 3 fetchTotal increments
+```
+
+## API Reference
+
+- `generatePreloadHints(manifest, opts?): readonly PreloadHintLink[]`
+  - `manifest.entries: ReadonlyArray<PreloadManifestEntry>`
+  - `opts.topN?: number` — override the default `preload: true` filter
+  - `opts.observability?: PackerBrowserObservability` — emit counters
+
+- `injectPreloadHints(doc, hints): readonly HTMLLinkElement[]`
+  - Returns `[]` when `doc` is `undefined` or has no `<head>`.
+  - Each created element carries `rel="preload"`, the configured
+    `href`, `as`, and optional `crossorigin` attributes.
+
+## Implementation Notes
+
+- The OTel emission is intentionally one counter per emitted hint —
+  not one per manifest entry — so the count tracks bytes that actually
+  get preload-requested by the browser.
+- `topN` is clamped to `[0, manifest.entries.length]` so a negative
+  value yields an empty array without throwing.
+- The helper does not de-duplicate URLs — manifests are the source of
+  truth for ordering and duplicates.
+- `injectPreloadHints` does not handle the non-DOM environment by
+  feature-flag; it relies on `doc === undefined` or `doc.head === null`
+  so a hand-rolled adapter can drop a fake document in tests.