From febec37fd1eff3470fa9b0dff5b8fa6c10f7ce5c Mon Sep 17 00:00:00 2001
From: Oto Macenauer <oto.macenauer@absa.africa>
Date: Tue, 23 Jun 2026 20:50:10 +0200
Subject: [PATCH] feat: add web-fragments skill

Skill for building, embedding, debugging, and deploying micro-frontends with
the Web Fragments framework (web-fragments npm package).

- SKILL.md hub: mental model, exact v0.8.x API, workflow, gotchas (progressive
  disclosure, token-optimized)
- references/: api-reference, host-integration (per-framework middleware),
  fragment-authoring, troubleshooting, css-and-styling, csp-and-iframe,
  piercing-and-performance, frameworks-astro
- scripts/: scaffold-fragment.mjs (generate a Vite fragment + gateway snippet),
  doctor.mjs (static-check a host/fragment project for v0.8.x gotchas)
- scripts/experiments/: reproducible Playwright experiments backing the verified
  CSS-isolation and Astro findings

Knowledge verified against the library source and Playwright; includes the
head-style-accumulation bug filed upstream as web-fragments#297 and a verified
smooth-transition-without-ClientRouter workaround.
---
 skills/web-fragments/SKILL.md                 | 138 +++++++++++++
 skills/web-fragments/evals/evals.json         |  48 +++++
 .../web-fragments/references/api-reference.md | 186 ++++++++++++++++++
 .../references/csp-and-iframe.md              |  43 ++++
 .../references/css-and-styling.md             |  63 ++++++
 .../references/fragment-authoring.md          |  91 +++++++++
 .../references/frameworks-astro.md            | 165 ++++++++++++++++
 .../references/host-integration.md            | 167 ++++++++++++++++
 .../references/piercing-and-performance.md    |  60 ++++++
 .../references/troubleshooting.md             | 130 ++++++++++++
 skills/web-fragments/scripts/doctor.mjs       | 166 ++++++++++++++++
 .../scripts/experiments/README.md             |  12 ++
 .../astro-fragment/astro.config.mjs           |  12 ++
 .../experiments/astro-fragment/package.json   |  12 ++
 .../astro-fragment/public/css/a.css           |   2 +
 .../astro-fragment/public/css/b.css           |   2 +
 .../astro-fragment/public/css/c.css           |   2 +
 .../astro-fragment/src/layouts/Layout.astro   |  38 ++++
 .../src/layouts/SmoothLayout.astro            |  74 +++++++
 .../astro-fragment/src/pages/[...path].astro  |  55 ++++++
 .../astro-fragment/src/pages/index.astro      |  11 ++
 .../src/pages/smooth/[site].astro             |   8 +
 .../experiments/astro-host/package.json       |   9 +
 .../scripts/experiments/astro-host/server.mjs |  54 +++++
 .../css-vars-isolation/fragment.html          |  43 ++++
 .../experiments/css-vars-isolation/index.html |  56 ++++++
 .../scripts/experiments/measure-astro.cjs     |  84 ++++++++
 .../scripts/experiments/measure-css.cjs       |  61 ++++++
 .../scripts/experiments/measure-head.cjs      |  75 +++++++
 .../scripts/experiments/measure-optout.cjs    |  67 +++++++
 .../scripts/experiments/measure-smooth.cjs    |  54 +++++
 .../scripts/scaffold-fragment.mjs             | 123 ++++++++++++
 32 files changed, 2111 insertions(+)
 create mode 100644 skills/web-fragments/SKILL.md
 create mode 100644 skills/web-fragments/evals/evals.json
 create mode 100644 skills/web-fragments/references/api-reference.md
 create mode 100644 skills/web-fragments/references/csp-and-iframe.md
 create mode 100644 skills/web-fragments/references/css-and-styling.md
 create mode 100644 skills/web-fragments/references/fragment-authoring.md
 create mode 100644 skills/web-fragments/references/frameworks-astro.md
 create mode 100644 skills/web-fragments/references/host-integration.md
 create mode 100644 skills/web-fragments/references/piercing-and-performance.md
 create mode 100644 skills/web-fragments/references/troubleshooting.md
 create mode 100644 skills/web-fragments/scripts/doctor.mjs
 create mode 100644 skills/web-fragments/scripts/experiments/README.md
 create mode 100644 skills/web-fragments/scripts/experiments/astro-fragment/astro.config.mjs
 create mode 100644 skills/web-fragments/scripts/experiments/astro-fragment/package.json
 create mode 100644 skills/web-fragments/scripts/experiments/astro-fragment/public/css/a.css
 create mode 100644 skills/web-fragments/scripts/experiments/astro-fragment/public/css/b.css
 create mode 100644 skills/web-fragments/scripts/experiments/astro-fragment/public/css/c.css
 create mode 100644 skills/web-fragments/scripts/experiments/astro-fragment/src/layouts/Layout.astro
 create mode 100644 skills/web-fragments/scripts/experiments/astro-fragment/src/layouts/SmoothLayout.astro
 create mode 100644 skills/web-fragments/scripts/experiments/astro-fragment/src/pages/[...path].astro
 create mode 100644 skills/web-fragments/scripts/experiments/astro-fragment/src/pages/index.astro
 create mode 100644 skills/web-fragments/scripts/experiments/astro-fragment/src/pages/smooth/[site].astro
 create mode 100644 skills/web-fragments/scripts/experiments/astro-host/package.json
 create mode 100644 skills/web-fragments/scripts/experiments/astro-host/server.mjs
 create mode 100644 skills/web-fragments/scripts/experiments/css-vars-isolation/fragment.html
 create mode 100644 skills/web-fragments/scripts/experiments/css-vars-isolation/index.html
 create mode 100644 skills/web-fragments/scripts/experiments/measure-astro.cjs
 create mode 100644 skills/web-fragments/scripts/experiments/measure-css.cjs
 create mode 100644 skills/web-fragments/scripts/experiments/measure-head.cjs
 create mode 100644 skills/web-fragments/scripts/experiments/measure-optout.cjs
 create mode 100644 skills/web-fragments/scripts/experiments/measure-smooth.cjs
 create mode 100644 skills/web-fragments/scripts/scaffold-fragment.mjs

diff --git a/skills/web-fragments/SKILL.md b/skills/web-fragments/SKILL.md
new file mode 100644
index 0000000..b2ac312
--- /dev/null
+++ b/skills/web-fragments/SKILL.md
@@ -0,0 +1,138 @@
+---
+name: web-fragments
+description: >-
+  Build, embed, debug, and deploy micro-frontends with the Web Fragments framework
+  (the `web-fragments` npm package by web-fragments.dev / Cloudflare). Use whenever the user
+  works with web-fragments, the `<web-fragment>` element, `FragmentGateway`,
+  `registerFragment`, `getWebMiddleware` / `getNodeMiddleware`, fragment "piercing", or the
+  "reframed" iframe isolation — and more broadly when they want to incrementally migrate,
+  decompose, or compose a web frontend from independently deployed micro-frontends that
+  share one DOM, even if they don't name the library. Covers authoring a fragment, wiring it
+  into a host app, gateway/route-pattern config, styling across the shadow boundary, and
+  troubleshooting hydration/asset/type errors. Prefer this skill over guessing the API — the
+  framework is beta (v0.8.x) and several public docs are stale.
+---
+
+# Web Fragments
+
+Framework-/platform-agnostic micro-frontend architecture. Each micro-frontend's client JS
+runs in an isolated context (a hidden iframe = *reframed*) while all fragments **share one
+DOM, navigation, and history** — "containers for web frontends." Beta v0.8.x, in production
+at Cloudflare.
+
+**Don't read `node_modules/web-fragments/` source for the API — it's captured here and in
+`references/`.** web-fragments.dev docs are partly stale; when they disagree with this skill,
+trust the skill (verify via the package's `exports` map in `node_modules/web-fragments/package.json`).
+
+## Mental model: 3 pieces
+
+1. **Fragment app** — a *standalone* app (any stack) at an HTTP endpoint serving its own
+   HTML + assets; doesn't know it's a fragment. → `references/fragment-authoring.md`
+2. **Host (shell)** — the existing app that embeds fragments: calls `initializeWebFragments()`
+   once + places `<web-fragment fragment-id="…">`. → `references/host-integration.md`
+3. **Gateway** — **mandatory** middleware on the host server (issue #278): proxies fragment
+   requests onto the host's single origin and *pierces* SSR markup into the shell.
+
+Flow: browser → host origin → gateway matches `routePatterns` → proxies to fragment
+`endpoint` → response composed into the host page.
+
+## Public API (v0.8.x) — exactly three entry points
+
+There is **no** `web-fragments/middleware` entry point (a stale doc claims one).
+
+| Import | Exports |
+|---|---|
+| `web-fragments` | `initializeWebFragments()`, `WebFragment`, `WebFragmentHost` |
+| `web-fragments/gateway` | `FragmentGateway`, `getWebMiddleware`, types `FragmentConfig`, `FragmentMiddlewareOptions` |
+| `web-fragments/gateway/node` | `getNodeMiddleware` |
+
+**Client (host bootstrap):**
+```ts
+import { initializeWebFragments } from 'web-fragments';
+initializeWebFragments(); // defines the custom elements; call as early as possible
+```
+```html
+<web-fragment fragment-id="party-button"></web-fragment>
+```
+`fragment-id` is required (throws without it); `src` is optional. `<web-fragment-host>` is
+internal — you rarely author it.
+
+**Gateway (host server):**
+```ts
+import { FragmentGateway } from 'web-fragments/gateway';
+const gateway = new FragmentGateway(/* { piercingStyles?: string } */);
+gateway.registerFragment({                 // method is registerFragment, NOT register
+  fragmentId: 'party-button',              // required; must match the element's fragment-id
+  endpoint: 'https://party-button.example.dev', // required; URL string OR a fetch-compatible fn
+  routePatterns: ['/__wf/party-button/:_*', '/'], // required (path-to-regexp v6): assets + host route(s)
+  piercing: true,                          // optional, default true; false = client-only
+  // piercingClassNames, forwardFragmentHeaders, iframeHeaders, onSsrFetchError — see api-reference
+});
+```
+Full `FragmentConfig` + deprecated aliases (`upstream`→`endpoint`,
+`prePiercingClassNames`→`piercingClassNames`): `references/api-reference.md`.
+
+**Middleware (pick ONE per host runtime):**
+```ts
+import { getWebMiddleware } from 'web-fragments/gateway';        // Web/Fetch: CF, Vercel, Netlify, Hono, SW
+const mw = getWebMiddleware(gateway, { mode: 'development' });   // 'production' | 'development'
+
+import { getNodeMiddleware } from 'web-fragments/gateway/node';  // Node: Express / Connect
+app.use(getNodeMiddleware(gateway));
+```
+Per-framework wiring: `references/host-integration.md`.
+
+## Workflow (add a fragment to an app)
+
+1. **Fragment app** serves its own HTML+assets, emitting assets under a **unique** path
+   (e.g. Vite `build.assetsDir: "__wf/<id>/"`) that lines up with the asset `routePattern`.
+2. **Bootstrap** the host client: `initializeWebFragments()` at the earliest entry.
+3. **Place** `<web-fragment fragment-id="…">` at the chosen host route.
+4. **Register**: `new FragmentGateway()` + `registerFragment(...)` with two patterns (assets +
+   host route). The host-route pattern MUST match where the element lives (step 3).
+5. **Install** the middleware matching the runtime (Web vs Node).
+6. **Verify** (below), then deploy — fragment and host ship independently.
+
+## Verify
+
+Fragment renders as **nested shadow roots**: `<web-fragment>` ▸ shadowRoot ▸
+`<web-fragment-host>` ▸ shadowRoot ▸ `<wf-document>`, plus a hidden `<iframe name="wf:<id>">`
+running its scripts. In dev tools: fragment DOM is in the main document but inside a shadow
+root (style isolation); a `wf:<id>` context exists; removing the element tears it down;
+asset requests hit `/__wf/<id>/…` on the **host** origin (proxied).
+
+Automated: `node scripts/doctor.mjs <project-dir>` flags the common wiring mistakes (wrong
+import path, `register` vs `registerFragment`, asset/routePattern mismatch, missing
+middleware). Use it whenever a fragment "doesn't show up" or assets 404.
+
+## Bundled resources
+
+Load only the reference matching the task:
+- `references/api-reference.md` — every export, full `FragmentConfig`/options, deprecations. Writing/reviewing gateway/element code.
+- `references/host-integration.md` — middleware wiring per framework (Express, CF Pages/Workers, Vercel, Netlify, Hono, Angular, Next.js, Vite SPA).
+- `references/fragment-authoring.md` — build a fragment from scratch: structure, Vite `assetsDir`, route patterns, deploy.
+- `references/troubleshooting.md` — known issues/gotchas (hydration, asset truncation, nodenext types, Angular htmlrewriter, style accumulation). Read FIRST when broken.
+- `references/css-and-styling.md` — **verified** style behavior across the shadow boundary (`:root` vs `:host`, `@layer`, what inherits/leaks).
+- `references/csp-and-iframe.md` — CSP / `X-Frame-Options` / `frame-ancestors` so the gateway's hidden iframe isn't blocked. Read when a fragment silently fails to load or you're setting security headers.
+- `references/piercing-and-performance.md` — piercing internals (`sec-fetch-dest` hard-nav, `data-piercing` styling, HTMLRewriter), caching (`Vary`, stub TTL, `forwardFragmentHeaders`), `mode:production`, route specificity. Read for perf/piercing/CLS work.
+- `references/frameworks-astro.md` — **verified** Astro recipe: embedding, `<ClientRouter />`, the head-accumulation bug (#297), and smooth transitions without ClientRouter.
+
+Scripts (run, don't read): `scripts/scaffold-fragment.mjs` (generate a Vite fragment +
+gateway snippet); `scripts/doctor.mjs` (static-check a project).
+
+**Official slash commands** (PR #294, ship with the package under `.claude/commands/`):
+`/web-fragments:init-fragment | gateway-config | debug-fragment | fragment-test |
+migrate-to-fragments | fragment-csp | fragment-perf` — explicit task runners. They complement
+this skill: the skill auto-triggers and supplies verified knowledge; the commands run a
+specific job on request. Use them when the user invokes one or wants a guided scaffold/audit.
+
+## Top gotchas (full list: references/troubleshooting.md)
+
+- **Wrong middleware import.** No `web-fragments/middleware`. Web = `web-fragments/gateway`; Node = `web-fragments/gateway/node`.
+- **`registerFragment`, not `register`.**
+- **Asset path ↔ routePattern mismatch** — #1 cause of 404'd assets / blank fragments. Fragment asset dir and gateway asset `routePattern` must share the prefix.
+- **Gateway is mandatory** — no server-less mode yet (#278).
+- **`nodenext`** type resolution may fail (#284); **Angular host** needs `outputMode:"server"` + `externalDependencies` (#280).
+- **`:root` is dead inside a fragment; use `:host`.** Host `:root` vars + inherited props (font/color) flow in; selector rules don't. → `css-and-styling.md`.
+- **`X-Frame-Options: DENY` on the fragment endpoint silently kills it** — it blocks the gateway's hidden iframe. Allow framing (`frame-ancestors 'self' <gateway-origin>`). → `csp-and-iframe.md`.
+- **Piercing fires only on hard navigation** (`sec-fetch-dest: document`); set `mode:'production'` when deployed; register specific routePatterns before broad ones (first-match-wins). → `piercing-and-performance.md`.
diff --git a/skills/web-fragments/evals/evals.json b/skills/web-fragments/evals/evals.json
new file mode 100644
index 0000000..46221e3
--- /dev/null
+++ b/skills/web-fragments/evals/evals.json
@@ -0,0 +1,48 @@
+{
+  "skill_name": "web-fragments",
+  "evals": [
+    {
+      "id": 0,
+      "name": "embed-react-widget-into-express-host",
+      "prompt": "I run an existing Express app (Node) and I have a separately deployed React widget hosted at https://reviews.acme.dev. I want to embed that widget as a micro-frontend on my /products page using the web-fragments library. Show me everything I need: the gateway setup, the middleware, the client bootstrap, and where the element goes.",
+      "expected_output": "Uses FragmentGateway + registerFragment with fragmentId/endpoint/routePatterns (asset pattern + /products host route), getNodeMiddleware from web-fragments/gateway/node, initializeWebFragments() in client bootstrap, and a <web-fragment fragment-id> on the /products page. Must NOT import web-fragments/middleware and must use registerFragment not register.",
+      "assertions": [
+        {"text": "Imports getNodeMiddleware from 'web-fragments/gateway/node' (Node host)", "type": "code"},
+        {"text": "Calls gateway.registerFragment(...) and NOT gateway.register(...)", "type": "code"},
+        {"text": "registerFragment config includes fragmentId, endpoint, and routePatterns", "type": "code"},
+        {"text": "routePatterns include both an asset pattern (e.g. /__wf/...) and the /products host route", "type": "code"},
+        {"text": "Calls initializeWebFragments() in the client bootstrap", "type": "code"},
+        {"text": "Places a <web-fragment fragment-id=\"...\"> element on the /products page", "type": "code"},
+        {"text": "Does NOT import from 'web-fragments/middleware' (non-existent entry point)", "type": "code"}
+      ],
+      "files": []
+    },
+    {
+      "id": 1,
+      "name": "debug-blank-fragment-asset-404",
+      "prompt": "I'm using web-fragments. My fragment renders blank on the host page and the browser console shows the fragment's JS and CSS files returning 404 under /__wf/. The host page itself loads fine and the fragment app works when I open its own URL directly. The fragment is a Vite app. What's going wrong and how do I fix it?",
+      "expected_output": "Identifies the asset-path vs routePattern mismatch as the root cause: the fragment's Vite build.assetsDir must share the same /__wf/<unique>/ prefix as the gateway's asset routePattern. Gives a concrete fix aligning the two. Does not invent unrelated causes.",
+      "assertions": [
+        {"text": "Identifies asset path / routePattern prefix mismatch as the root cause", "type": "manual"},
+        {"text": "References Vite build.assetsDir alignment with the /__wf/ asset routePattern", "type": "code"},
+        {"text": "Gives a concrete corrective step (edit assetsDir or routePattern so prefixes match)", "type": "manual"},
+        {"text": "Does not hallucinate an unrelated root cause (e.g. CORS, missing fragment-id) as primary", "type": "manual"}
+      ],
+      "files": []
+    },
+    {
+      "id": 2,
+      "name": "author-fragment-and-register-on-cloudflare",
+      "prompt": "Create a brand-new web fragment from scratch: a small standalone 'newsletter-signup' app. Then show me how to register and serve it from my host app, which is deployed on Cloudflare Pages.",
+      "expected_output": "A standalone fragment app that does NOT import web-fragments, with a unique Vite build.assetsDir under __wf/. Host registration uses FragmentGateway + registerFragment with a matching asset routePattern, and Cloudflare Pages middleware uses getWebMiddleware from web-fragments/gateway (Web, not Node) in a functions/_middleware.ts onRequest handler.",
+      "assertions": [
+        {"text": "The fragment app does NOT import the web-fragments package (it's a plain standalone app)", "type": "manual"},
+        {"text": "Sets a unique Vite build.assetsDir under __wf/ for the fragment", "type": "code"},
+        {"text": "Uses getWebMiddleware from 'web-fragments/gateway' (Web runtime), NOT getNodeMiddleware", "type": "code"},
+        {"text": "Cloudflare Pages wiring uses functions/_middleware.ts with an onRequest handler", "type": "code"},
+        {"text": "registerFragment asset routePattern prefix matches the fragment's assetsDir", "type": "manual"}
+      ],
+      "files": []
+    }
+  ]
+}
diff --git a/skills/web-fragments/references/api-reference.md b/skills/web-fragments/references/api-reference.md
new file mode 100644
index 0000000..6f0d354
--- /dev/null
+++ b/skills/web-fragments/references/api-reference.md
@@ -0,0 +1,186 @@
+# Web Fragments API Reference (v0.8.x)
+
+Source of truth: the `web-fragments` package `exports` map and TypeScript sources.
+This file mirrors them so you never need to open `node_modules` source.
+
+## Contents
+- [Entry points](#entry-points)
+- [Client elements](#client-elements)
+- [`FragmentGateway`](#fragmentgateway)
+- [`FragmentConfig`](#fragmentconfig)
+- [`FragmentGatewayConfig`](#fragmentgatewayconfig)
+- [Middleware](#middleware)
+- [`FragmentMiddlewareOptions`](#fragmentmiddlewareoptions)
+- [Route patterns](#route-patterns)
+- [Deprecations](#deprecations)
+
+## Entry points
+
+```jsonc
+// node_modules/web-fragments/package.json -> exports
+{
+  ".":              "./dist/elements.js",        // client elements
+  "./gateway":      "./dist/gateway.js",         // gateway + web middleware
+  "./gateway/node": "./dist/gateway/node.js"     // node middleware
+}
+```
+
+| Specifier | Named exports |
+|---|---|
+| `web-fragments` | `initializeWebFragments`, `WebFragment`, `WebFragmentHost` |
+| `web-fragments/gateway` | `FragmentGateway`, `getWebMiddleware`, type `FragmentConfig`, type `FragmentMiddlewareOptions` |
+| `web-fragments/gateway/node` | `getNodeMiddleware` |
+
+There is intentionally **no** `web-fragments/middleware` and **no** `web-fragments/client`.
+If you see those in a doc or blog, they are stale.
+
+## Client elements
+
+```ts
+import { initializeWebFragments } from 'web-fragments';
+initializeWebFragments();
+```
+`initializeWebFragments()` calls `customElements.define('web-fragment', WebFragment)` and
+`customElements.define('web-fragment-host', WebFragmentHost)`. Call it once, as early as
+possible in the host's client bootstrap (before any `<web-fragment>` is parsed/connected).
+
+### `<web-fragment>`
+| Attribute | Required | Meaning |
+|---|---|---|
+| `fragment-id` | **yes** | Matches a registered `FragmentConfig.fragmentId`. Missing → throws `The <web-fragment> is missing fragment-id attribute!` |
+| `src` | no | Optional initial route/URL for this fragment instance. |
+
+On `connectedCallback` the element looks for an existing pierced `<web-fragment-host
+fragment-id="…">` (server-rendered) and adopts it; otherwise it creates one. A mismatched
+`fragment-id` between `<web-fragment>` and a contained `<web-fragment-host>` throws.
+
+### `<web-fragment-host>`
+Internal element that owns the fragment's shadow root + reframed iframe context. It is
+produced by piercing (server) or by `<web-fragment>` itself (client). You normally never
+author it directly. Exposed mainly so frameworks/tests can reference the class.
+
+## `FragmentGateway`
+
+```ts
+import { FragmentGateway } from 'web-fragments/gateway';
+
+class FragmentGateway {
+  constructor(config?: FragmentGatewayConfig);
+  registerFragment(fragmentConfig: FragmentConfig): void;
+  matchRequestToFragment(urlPath: string, requestFragmentId?: string): FragmentConfig | null;
+}
+```
+- `registerFragment` — register one fragment. Call once per fragment. **Not** `register`.
+- `matchRequestToFragment` — used internally by the middleware to route a request to a
+  fragment; useful in custom middleware / tests.
+
+## `FragmentConfig`
+
+```ts
+interface FragmentConfig {
+  /** Unique id; must equal the <web-fragment fragment-id>. */
+  fragmentId: string;                              // REQUIRED
+
+  /** path-to-regexp v6 patterns this fragment serves (assets + host routes). */
+  routePatterns: string[];                         // REQUIRED
+
+  /** Fragment app origin URL, or a fetch-compatible function. */
+  endpoint: string | typeof fetch;                 // REQUIRED
+
+  /** Server-side pierce the fragment into the shell. Default: true. */
+  piercing?: boolean;
+
+  /** Classes applied to the fragment before piercing for a seamless visual swap.
+   *  Recommended selector: :not(web-fragment) > web-fragment-host[fragment-id="<id>"] */
+  piercingClassNames?: string[];
+
+  /** Fragment response headers to forward into the combined gateway response. */
+  forwardFragmentHeaders?: string[];
+
+  /** Extra headers on the iframe STUB response (the init doc), NOT the fragment content.
+   *  Names normalized to HTTP-Header-Case. For CSP/X-Frame-Options on content, set them on
+   *  the fragment endpoint itself. See csp-and-iframe.md. */
+  iframeHeaders?: Record<string, string>;
+
+  /** Fallback when fetching the fragment's SSR markup fails (4xx/5xx/throw). Without it, a
+   *  failure falls back to a generic gateway error response. With overrideResponse:true the
+   *  returned response REPLACES the whole page (e.g. auth redirect). */
+  onSsrFetchError?: (
+    req: Request,
+    failedResOrError: Response | Error,
+  ) => SSRFetchErrorResponse | Promise<SSRFetchErrorResponse>;
+
+  // --- deprecated ---
+  /** @deprecated use endpoint */            upstream?: string;
+  /** @deprecated use piercingClassNames */  prePiercingClassNames?: string[];
+}
+
+interface SSRFetchErrorResponse {
+  response: Response;
+  overrideResponse?: boolean;
+}
+```
+
+### About `routePatterns`
+You almost always register **two kinds** of patterns:
+1. **Asset pattern** — a unique prefix the fragment serves its JS/CSS/static files under,
+   e.g. `'/__wf/<unique>/:_*'`. Must line up with the fragment build's asset output dir.
+2. **Host route pattern(s)** — the URL(s) in the *host* app where the fragment is mounted,
+   e.g. `'/'`, `'/dashboard/:_*'`. Must match where `<web-fragment>` is placed.
+
+`/x` does **not** match `/x/123` — use `/x/:_*` for sub-paths. Matching returns the **first**
+matching pattern (no specificity ordering yet — `matchRequestToFragment` TODO), so register
+**specific patterns before broad ones**. Details: `piercing-and-performance.md`.
+
+## `FragmentGatewayConfig`
+
+```ts
+interface FragmentGatewayConfig {
+  /** Global CSS injected to style fragments during piercing. */
+  piercingStyles?: string;
+  /** @deprecated use piercingStyles */
+  prePiercingStyles?: string;
+}
+```
+Passing `prePiercingStyles` logs a red deprecation warning at runtime. Use `piercingStyles`.
+
+## Middleware
+
+```ts
+// Web / Fetch runtimes:
+import { getWebMiddleware } from 'web-fragments/gateway';
+function getWebMiddleware(
+  gateway: FragmentGateway,
+  options?: FragmentMiddlewareOptions,
+): (request: Request, next: () => Promise<Response>) => Promise<Response>;
+
+// Node (Express/Connect) runtimes:
+import { getNodeMiddleware } from 'web-fragments/gateway/node';
+function getNodeMiddleware(
+  gateway: FragmentGateway,
+  options?: FragmentMiddlewareOptions,
+): (req, res, next) => void;
+```
+The node middleware internally adapts Node req/res to the Web `Request`/`Response` the
+gateway works with (`web-to-node-adapter`). Use the entry point that matches your runtime;
+do not import the node one into an edge/worker build.
+
+## `FragmentMiddlewareOptions`
+
+```ts
+interface FragmentMiddlewareOptions {
+  additionalHeaders?: HeadersInit;          // headers added to gateway responses
+  mode?: 'production' | 'development';       // default 'development'
+}
+```
+Set `mode: 'production'` for deployed builds; `development` enables dev-friendly behavior
+(e.g. a fallback reframed HTML document) and more verbose handling.
+
+## Deprecations (rewrite on sight)
+
+| Deprecated | Use instead |
+|---|---|
+| `FragmentConfig.upstream` | `FragmentConfig.endpoint` |
+| `FragmentConfig.prePiercingClassNames` | `FragmentConfig.piercingClassNames` |
+| `FragmentGatewayConfig.prePiercingStyles` | `FragmentGatewayConfig.piercingStyles` |
+| import `web-fragments/middleware` | `web-fragments/gateway` (web) / `web-fragments/gateway/node` (node) |
diff --git a/skills/web-fragments/references/csp-and-iframe.md b/skills/web-fragments/references/csp-and-iframe.md
new file mode 100644
index 0000000..2079028
--- /dev/null
+++ b/skills/web-fragments/references/csp-and-iframe.md
@@ -0,0 +1,43 @@
+# CSP & iframe framing
+
+The gateway runs each fragment's JS in a **hidden iframe** (the reframed context) whose `src`
+points at the fragment. So the fragment must be **framable** by the host/gateway origin. Get
+this wrong and the fragment **silently fails** — the iframe just never loads. (Source: the
+reframed loader explicitly warns when the iframe response carries `X-Frame-Options: deny`,
+`reframed.ts`.)
+
+## Rules
+
+**Fragment endpoint** (the thing being framed) must NOT block framing:
+- ❌ `X-Frame-Options: DENY` → change to `SAMEORIGIN` or remove.
+- ❌ `Content-Security-Policy: frame-ancestors 'none'`.
+- ✅ `Content-Security-Policy: frame-ancestors 'self' <gateway-origin>` (allow the host to frame it).
+- Cloudflare Pages fragment routes (`public/_headers`):
+  ```
+  /<fragment-route>/*
+    Content-Security-Policy: frame-ancestors 'self' <gateway-origin>
+    X-Frame-Options: ALLOWALL
+  ```
+
+**Host / app shell** CSP must allow the fragment to be embedded + run:
+```
+Content-Security-Policy:
+  default-src 'self';
+  frame-src 'self' <fragment-origin>;
+  script-src 'self' 'unsafe-inline';   /* SSR frameworks often inject inline scripts; use nonces if you can */
+```
+If a fragment loads assets from a CDN, add those origins to `script-src` / `style-src`.
+
+## `iframeHeaders` ≠ fragment-content headers
+
+`FragmentConfig.iframeHeaders` sets headers on the **iframe stub** response — the tiny
+document the gateway returns for the iframe init request (`sec-fetch-dest` is normalized to
+`empty` for that fetch) — **not** on the fragment's content response. Use it for auth/tracing
+headers on the stub only. Header names are normalized to HTTP-Header-Case
+(`fragment-gateway.ts`). For CSP/X-Frame-Options on the *content*, set them on the fragment
+endpoint itself (above).
+
+## Quick check
+- Fragment blank, no errors? Inspect the hidden `wf:<id>` iframe in dev tools and check the
+  fragment endpoint's response headers for `X-Frame-Options`/`frame-ancestors`.
+- `scripts/doctor.mjs` flags an `X-Frame-Options: DENY` set in project source.
diff --git a/skills/web-fragments/references/css-and-styling.md b/skills/web-fragments/references/css-and-styling.md
new file mode 100644
index 0000000..ea1f8d1
--- /dev/null
+++ b/skills/web-fragments/references/css-and-styling.md
@@ -0,0 +1,63 @@
+# CSS & Styling Across the Fragment Boundary
+
+How styles interact between a host page and an embedded fragment. **All claims are
+empirically verified** (`web-fragments@0.8.x`, Playwright computed-style reads on both
+sides), identical in **pierced and non-pierced** modes.
+
+## Structure (what renders)
+
+```
+<web-fragment>                     ← light DOM
+  #shadow-root
+    <web-fragment-host>
+      #shadow-root                 ← THE style boundary
+        <style>…fragment styles…</style>
+        <wf-document><html>…fragment body…</html></wf-document>
+  <iframe name="wf:<id>" hidden>   ← reframed JS context (scripts run here)
+```
+Fragment markup + styles live in the **`web-fragment-host` shadow root**, so scoping follows
+normal **Shadow DOM** rules → the behaviors below.
+
+## Verified behaviors
+
+1. **Selector rules don't cross the boundary, either direction.** Host `.card{…}` doesn't
+   style a fragment `.card`, and vice versa. Host and fragment can reuse class names with
+   zero collision. *(Host `.leak-class{magenta}` → fragment element stayed black.)*
+2. **Inherited properties flow host → fragment.** `font-family`, `color`, `line-height`,
+   etc. cascade down across the boundary. The host's typography/color baseline bleeds into
+   every fragment. *(Host `body{font-family:Georgia}` → fragment text = Georgia.)*
+3. **Custom properties (vars) inherit host → fragment.** They're inherited properties, so
+   host `:root{--brand:red}` is visible as `var(--brand)` inside the fragment. Great for
+   theming; risky if a fragment unknowingly reads a host token of the same name. *(`--brand`
+   resolved to red inside the fragment.)*
+4. **`:root` is DEAD inside a fragment.** It matches only the document root, which doesn't
+   exist in a shadow tree, so a fragment's `:root{--brand:purple}` is a **no-op**. *(Tried to
+   override `--brand` via `:root`; value stayed the inherited host red.)* → use `:host`.
+5. **`:host` works** — sets properties on the shadow host, inherited by descendants. *(`:host{
+   --accent:orange}` resolved to orange inside the fragment.)* Define fragment tokens here.
+6. **Vars do NOT leak fragment → host.** Inheritance is downward only. *(Host reading
+   `var(--host-accent)` defined in the fragment → unset/black.)*
+7. **`@layer` is tree-scoped.** Host and fragment layer orderings are independent; neither
+   reorders the other. *(Both had `base` then `theme`; each resolved to its own `theme`.)*
+
+## Practical guidance
+
+- **Expect host inheritance to reach the fragment.** To insulate, neutralize at the
+  boundary: `:host { all: initial }` (aggressive) or set the inherited props you care about
+  explicitly on `:host` (`font-family`, `color`, `line-height`).
+- **Never put fragment tokens on `:root`** — silently dead; use `:host` (or a wrapper class).
+- **Theme fragments via host `:root` tokens on purpose.** Define `--color-*`/`--space-*` on
+  the host `:root`; fragments consuming `var(--…)` inherit them. This is the supported theming
+  channel (Shadow DOM blocks reaching into a fragment's styles directly).
+- **No prefixing needed** for host↔fragment class collisions (behavior #1 isolates them).
+- **Host-side:** to keep a token out of fragments, scope it under a host-only wrapper class,
+  not `:root`/`html`. Inherited props (font/color) still flow down unless the fragment
+  overrides them at `:host`.
+
+## Reproduce
+`scripts/experiments/css-vars-isolation/` (host `index.html` + `fragment.html`) +
+`scripts/experiments/measure-css.cjs` — launches Chromium, traverses the nested shadow roots,
+prints computed `color`/`font-family`/var values for host and fragment probes. Run:
+`NODE_PATH=<playground>/node_modules node measure-css.cjs`. To test a new question, add a
+probe with a known expected color in `fragment.html` and read it through the path
+`web-fragment ▸ shadowRoot ▸ web-fragment-host ▸ shadowRoot ▸ #your-id`.
diff --git a/skills/web-fragments/references/fragment-authoring.md b/skills/web-fragments/references/fragment-authoring.md
new file mode 100644
index 0000000..053e4a8
--- /dev/null
+++ b/skills/web-fragments/references/fragment-authoring.md
@@ -0,0 +1,91 @@
+# Authoring a Fragment App
+
+A **fragment** is just a standalone web app served over HTTP. It does not import
+`web-fragments` itself — the host embeds it. The only fragment-side concern is making its
+**assets resolve under a unique, predictable path** so the gateway can route them on the
+host origin without colliding with the host's or other fragments' assets.
+
+The canonical example is `web-fragments/party-button-fragment` (a Vite + vanilla TS app
+that shoots confetti). Its shape:
+
+```
+party-button-fragment/
+├── index.html          # plain HTML, loads /src/main.ts
+├── src/main.ts         # the fragment's client code
+├── public/             # static assets
+├── package.json        # vite + wrangler (deployed to Cloudflare, but any host works)
+└── vite.config.ts      # <-- the important part: assetsDir
+```
+
+`index.html` is unremarkable:
+```html
+<!doctype html>
+<html lang="en">
+  <head><meta charset="UTF-8" /><title>Web Fragment Party Button!</title></head>
+  <body>
+    <button>🎉 Let's party! 🥳</button>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>
+```
+
+## The one rule that matters: unique asset path
+
+The fragment must emit its build assets under a unique directory so they can be addressed
+as `/__wf/<unique-id>/…` on the host origin. With Vite:
+
+```ts
+// vite.config.ts
+import { defineConfig } from 'vite';
+
+export default defineConfig({
+  build: {
+    assetsDir: '__wf/dev.web-fragments.demos.party-button/', // unique per fragment
+  },
+});
+```
+
+Then in the host gateway the **asset routePattern uses the same prefix**:
+```ts
+gateway.registerFragment({
+  fragmentId: 'party-button',
+  endpoint: 'https://party-button.example.dev',
+  routePatterns: [
+    '/__wf/dev.web-fragments.demos.party-button/:_*', // ← matches assetsDir above
+    '/',                                              // host route(s)
+  ],
+});
+```
+If these two prefixes drift apart, the host page loads but the fragment's JS/CSS 404 and
+the fragment appears blank. This is the single most common authoring mistake.
+
+**Naming the unique id:** use a reverse-DNS-ish slug you control, e.g.
+`__wf/<org>.<app>.<fragment>/`. It only needs to be globally unique across fragments
+embedded in the same host.
+
+## Tech stack & framework choice
+Any stack works — vanilla, React, Angular, Qwik, full-stack frameworks. The fragment can
+have its own nested routes, layouts, data fetching, and form handling. Constraints:
+- Serve real HTML on the fragment's routes (the gateway fetches SSR markup for piercing).
+- Keep asset URLs under the unique prefix (configure the bundler's asset/base path).
+- For frameworks with a configurable base/public path, set it to the same `__wf/<id>/`.
+
+## Deploying a fragment
+Deploy anywhere that serves the built HTML + assets over HTTP: Cloudflare
+(`wrangler deploy`), a Node server, static host + edge, etc. The party-button example uses:
+```jsonc
+// package.json scripts
+{
+  "dev": "vite",
+  "build": "tsc && vite build",
+  "preview": "vite build && vite preview",
+  "deploy": "pnpm build && wrangler deploy"
+}
+```
+The host references the deployed URL via `FragmentConfig.endpoint`. Fragment and host
+deploy and version **independently** — that is the whole point of the architecture.
+
+## Local dev
+Run the fragment on its own port (`vite` → e.g. `http://localhost:5173`) and point the
+host gateway's `endpoint` at it with `mode: 'development'`. Use `scripts/scaffold-fragment.mjs`
+to generate this skeleton instead of hand-writing it.
diff --git a/skills/web-fragments/references/frameworks-astro.md b/skills/web-fragments/references/frameworks-astro.md
new file mode 100644
index 0000000..6463519
--- /dev/null
+++ b/skills/web-fragments/references/frameworks-astro.md
@@ -0,0 +1,165 @@
+# Embedding an Astro Site as a Fragment (incl. Client Router)
+
+**Verified** (`web-fragments@0.8.2` + `astro@5`, Playwright). A static Astro build embeds
+cleanly, and `<ClientRouter />` performs real SPA navigation inside the fragment: link
+clicks swap content with no full reload, JS state (`sessionStorage`) persists, and all
+nav/asset fetches route through the gateway on the host's **single origin**.
+
+**Watch:** the top browser URL does **not** change on fragment-internal SPA nav (stays at the
+host route). Fragment-internal routes aren't address-bar deep-linkable in this setup — design
+host-level routing if you need that.
+
+## Working configuration
+
+One rule (as with any fragment): **namespace pages AND assets under one prefix**, route that
+whole prefix to the fragment.
+
+```js
+// 1. astro.config.mjs — namespace everything under base
+import { defineConfig } from 'astro/config';   // NB: astro/config, not 'astro' (Astro 5)
+export default defineConfig({
+  base: '/astro',           // pages -> /astro/, /astro/page2/ ; assets -> /astro/_astro/...
+  trailingSlash: 'always',
+  build: { format: 'directory' },
+});
+```
+```astro
+---
+// 2. layout — view transitions
+import { ClientRouter } from 'astro:transitions';
+---
+<html><head><ClientRouter /></head><body><slot /></body></html>
+```
+```js
+// 3. fragment endpoint — serve the static build mounted at the SAME base
+fragApp.use('/astro', express.static('astro-fragment/dist', { extensions: ['html'] }));
+
+// 4. host gateway — one routePattern covers pages + _astro assets + client-router fetches
+const gateway = new FragmentGateway();
+gateway.registerFragment({ fragmentId: 'astro', endpoint: 'http://localhost:5400',
+  piercing: false, routePatterns: ['/astro/:_*'] });
+app.use(getNodeMiddleware(gateway, { mode: 'development' }));
+```
+```html
+<!-- 5. host shell — plain HTML resolves the client via an import map; src = fragment entry -->
+<script type="importmap">{ "imports": { "web-fragments": "/_wf/elements.js" } }</script>
+<web-fragment fragment-id="astro" src="/astro/"></web-fragment>
+<script type="module">import { initializeWebFragments } from 'web-fragments'; initializeWebFragments();</script>
+```
+Serve the client bundle: `app.use('/_wf', express.static('node_modules/web-fragments/dist'))`.
+`src="/astro/"` sets the initial route (the element sits on host `/`, outside `/astro/:_*`).
+
+**Pitfalls:** `defineConfig` from `astro/config` (not `'astro'`); `base` must namespace pages
+*and* assets so one `/astro/:_*` pattern catches all (too-narrow → 404s mid-nav); mount the
+static build at the same base on the endpoint; give `<web-fragment>` a `src` when the host
+route differs from the entry route; don't expect the address bar to track internal nav.
+
+## ⚠️ Bug: head `<style>`/`<link>` accumulate across ClientRouter navigation
+
+> **Filed upstream: [#297](https://github.com/web-fragments/web-fragments/issues/297)**
+> (reproduced + verified locally; the bundled repro is what was reported). Tangential older
+> tickets: #119 (head/body support, closed), #78 (`@import` piercing, closed).
+
+When a fragment uses `<ClientRouter />` and each route injects its own CSS into `<head>`
+(e.g. a `[...path].astro` catch-all where each page does `<Fragment set:html={beforeHeadEnd}
+/><ClientRouter /><Fragment set:html={afterHeadEnd} />`), **the previous route's `<style>`
+and `<link>` are not removed on navigation — they accumulate unbounded, and earlier pages'
+rules keep applying.**
+
+Traversing sites a → b → c → a → b, nodes present in the fragment shadow tree after each nav:
+
+| Step | inline `<style>` left behind | total `<style>` | total `<link>` |
+|---|---|---|---|
+| a | a | 3 | 1 |
+| b | a, b | 5 | 2 |
+| c | a, b, c | 7 | 3 |
+| a (revisit) | a, b, c, a | 9 | 4 |
+| b (revisit) | a, b, c, a, b | 11 | 5 |
+
+Nothing is ever removed; revisits add duplicates. With distinct rules on a shared
+`#site-name`, leftovers visibly stack — by site C the element wears A's background + B's
+border + C's italic at once. (Identical selectors hide it: last-inserted wins so the current
+color looks right, but nodes still leak and unrelated rules still bleed.)
+
+**Root cause:** reframed renders the doc as `wf-html`/`wf-head`/`wf-body` and patches
+`document.head` → `wf-head`. To apply head `<style>`/`<link>` in the shadow tree it
+**relocates them out of `wf-head`** (probe: `wf-head` empty while nodes pile up elsewhere).
+Astro's swap cleans `document.head` (= `wf-head`), but the relocated nodes aren't there, so
+they're never removed. The two head strategies don't compose. (An `astro:after-swap` cleanup
+of `document.head` can't reach the relocated nodes either.)
+
+**Mitigations:** keep the fragment's `<head>` stable — load one shared stylesheet once,
+scope per-page rules under a body class/attribute instead of swapping `<link>`/`<style>` per
+route (stable head ⇒ no accumulation). Or drop `<ClientRouter />` and use the smooth-swap
+recipe below.
+
+## Smooth page transitions WITHOUT ClientRouter (avoids #297)
+
+**Verified working.** Keep `<head>` stable, intercept internal link clicks, `fetch` the
+target, and swap **only the content region** inside `document.startViewTransition()`.
+(`document.startViewTransition` is available in the reframed context — verified — so this is a
+real crossfade.)
+
+Why simpler options fail: native cross-document VT (`@view-transition`) and plain `<a>` links
+both trigger a real navigation, which **navigates the top window out of the embed**;
+CSS-entrance animation still needs a swap and gives no crossfade.
+
+**Link handling — you need not tag every link.** Opt-in (`a[data-swap]`) is explicit but
+verbose; **opt-out (recommended, verified)** intercepts all `<a>` and falls through for
+anything that shouldn't swap. Verified: untagged internal links (`/astro/*`) soft-swap; an
+out-of-namespace link falls through to a real navigation.
+
+```html
+<head>
+  <style>
+    #content { view-transition-name: wf-content; }      /* loaded ONCE, never swapped */
+    [data-site="a"] #site-name { color: red; }
+    [data-site="b"] #site-name { color: green; }
+    ::view-transition-old(wf-content), ::view-transition-new(wf-content) { animation-duration: 300ms; }
+  </style>
+</head>
+<body>
+  <nav><a href="/astro/smooth/a/">A</a> <a href="/astro/smooth/b/">B</a></nav>  <!-- no tagging -->
+  <main id="content" data-site="a"> … page content … </main>
+  <script is:inline>
+    async function navigate(url, push) {
+      const html = await (await fetch(url)).text();
+      const next = new DOMParser().parseFromString(html, 'text/html').querySelector('#content');
+      const cur = document.querySelector('#content');
+      if (!next || !cur) { location.href = url; return; }            // graceful fallback
+      const swap = () => cur.replaceWith(next);                       // reframed adopts the node;
+      if (typeof document.startViewTransition === 'function')         // use importNode if a browser balks
+        document.startViewTransition(swap); else swap();
+      if (push) history.pushState({}, '', url);
+    }
+    document.addEventListener('click', (e) => {                       // OPT-OUT filter
+      const a = e.target.closest && e.target.closest('a[href]');
+      if (!a || e.defaultPrevented) return;
+      if (e.button !== 0 || e.metaKey || e.ctrlKey || e.shiftKey || e.altKey) return; // new tab/window
+      if (a.target && a.target !== '_self') return;                  // target="_blank"
+      if (a.hasAttribute('download') || a.getAttribute('rel') === 'external') return;
+      const url = new URL(a.href, location.href);
+      if (url.origin !== location.origin) return;                    // external site
+      if (!url.pathname.startsWith('/astro/')) return;               // outside this fragment's routes
+      if (url.pathname === location.pathname && url.hash) return;     // same-page anchor
+      e.preventDefault();
+      navigate(url.pathname + url.search, true);
+    });
+    window.addEventListener('popstate', () => navigate(location.pathname, false));
+  </script>
+</body>
+```
+The two fragment-critical guards are `url.origin !== location.origin` and
+`!url.pathname.startsWith('/astro/')` — both must do a real navigation, not a swap.
+
+Verified across a → b → c → a → b: head `<style>` count stays **constant** (vs ClientRouter's
+3→5→7→9→11), content swaps, scoped colors correct, no stale styles, stays embedded. Top URL
+stays at the host route; `history.pushState` keeps back/forward working. Tradeoff: ~20 lines
+of swap logic and you forgo Astro's per-element `transition:name` beyond what you wire.
+
+## Reproduce
+Bundled under `scripts/experiments/` (run with `NODE_PATH=<playground>/node_modules node <probe>` after `npm i && astro build` in the fragment and `node server.mjs` in the host):
+- `astro-fragment/` + `astro-host/server.mjs` — minimal Astro app + express host/gateway.
+- `measure-astro.cjs` — basic ClientRouter embed (SPA-vs-reload + network).
+- `astro-fragment/src/pages/[...path].astro` + `measure-head.cjs` — the #297 accumulation/pollution repro.
+- `astro-fragment/src/{layouts/SmoothLayout.astro, pages/smooth/[site].astro}` + `measure-smooth.cjs` / `measure-optout.cjs` — smooth-swap (stable head) + opt-out link handling.
diff --git a/skills/web-fragments/references/host-integration.md b/skills/web-fragments/references/host-integration.md
new file mode 100644
index 0000000..8a7e940
--- /dev/null
+++ b/skills/web-fragments/references/host-integration.md
@@ -0,0 +1,167 @@
+# Host (Shell) Integration Recipes
+
+Wiring the gateway into the **host** per runtime. Every recipe assumes you bootstrapped the
+client once (`initializeWebFragments()` at the earliest entry), placed `<web-fragment
+fragment-id="…">`, and built a shared gateway module:
+
+```ts
+// gateway.ts
+import { FragmentGateway } from 'web-fragments/gateway';
+export const gateway = new FragmentGateway();
+gateway.registerFragment({
+  fragmentId: 'my-fragment',
+  endpoint: process.env.MY_FRAGMENT_ENDPOINT ?? 'http://localhost:5173',
+  routePatterns: ['/__wf/my-fragment/:_*', '/'],
+});
+```
+Pick **Web (Fetch)** middleware OR **Node** middleware per server — never both.
+
+## Express / Connect (Node)
+
+```ts
+import express from 'express';
+import { getNodeMiddleware } from 'web-fragments/gateway/node';
+import { gateway } from './gateway';
+
+const app = express();
+app.use(getNodeMiddleware(gateway, { mode: 'production' }));
+// ... your existing routes / static serving AFTER the fragment middleware
+app.listen(3000);
+```
+Register the fragment middleware **before** your catch-all/static handlers so fragment
+asset + proxy requests are intercepted first.
+
+## Cloudflare Pages
+
+`functions/_middleware.ts` (Pages Functions run the Web middleware):
+```ts
+import { getWebMiddleware } from 'web-fragments/gateway';
+import { gateway } from '../gateway';
+
+const fragmentMiddleware = getWebMiddleware(gateway, { mode: 'production' });
+
+export const onRequest: PagesFunction = async (context) => {
+  return fragmentMiddleware(context.request, () => context.next());
+};
+```
+Reference implementation: `web-fragments/web-fragments` repo →
+`e2e/pierced-react/functions/_middleware.ts`.
+
+## Cloudflare Workers
+
+```ts
+import { getWebMiddleware } from 'web-fragments/gateway';
+import { gateway } from './gateway';
+
+const fragmentMiddleware = getWebMiddleware(gateway, { mode: 'production' });
+
+export default {
+  async fetch(request, env, ctx) {
+    return fragmentMiddleware(request, async () => {
+      // your origin handler when no fragment route matches
+      return new Response('Not found', { status: 404 });
+    });
+  },
+};
+```
+
+## Vercel Edge Middleware
+
+`middleware.ts` at project root:
+```ts
+import { getWebMiddleware } from 'web-fragments/gateway';
+import { gateway } from './gateway';
+
+export const config = { matcher: '/:path*' };
+const fragmentMiddleware = getWebMiddleware(gateway, { mode: 'production' });
+
+export default async function middleware(request: Request) {
+  return fragmentMiddleware(request, () => fetch(request)); // fall through to origin
+}
+```
+
+## Netlify Edge Functions
+
+`netlify/edge-functions/web-fragments.ts`:
+```ts
+import { getWebMiddleware } from 'web-fragments/gateway';
+import { gateway } from '../../gateway.ts';
+
+const fragmentMiddleware = getWebMiddleware(gateway, { mode: 'production' });
+
+export default async (request: Request, context) =>
+  fragmentMiddleware(request, () => context.next());
+
+export const config = { path: '/*' };
+```
+
+## Hono
+
+```ts
+import { Hono } from 'hono';
+import { getWebMiddleware } from 'web-fragments/gateway';
+import { gateway } from './gateway';
+
+const app = new Hono();
+const fragmentMiddleware = getWebMiddleware(gateway, { mode: 'production' });
+
+app.use('*', async (c, next) => {
+  return fragmentMiddleware(c.req.raw, async () => {
+    await next();
+    return c.res;
+  });
+});
+```
+
+## Angular (host)
+
+Angular SSR hosts hit a known `htmlrewriter` resolution error during build (issue #280).
+Fix in `angular.json` for the host app's build target:
+```jsonc
+{
+  "outputMode": "server",
+  "externalDependencies": [
+    "web-fragments/gateway",
+    "web-fragments/gateway/node",
+    "htmlrewriter"
+  ]
+}
+```
+Then add the Node or Web middleware in your Angular SSR server entry depending on your
+deploy target (Express adapter → `getNodeMiddleware`; edge → `getWebMiddleware`).
+
+## Next.js (host)
+
+> ⚠️ **Open bug: Next.js does not hydrate fragments** (issue #290) — SSR piercing renders but
+> client hydration is unreliable. Try `piercing: false` to isolate; track #290 and confirm
+> against the latest release before committing to a Next.js host.
+
+Wiring (`middleware.ts`, Edge runtime) follows the Vercel pattern above with `getWebMiddleware`.
+
+## Vite SPA dev server
+
+For a pure SPA host in dev, run the gateway as a Vite plugin/connect middleware using the
+Node middleware (Vite's dev server is connect-based):
+```ts
+// vite.config.ts
+import { getNodeMiddleware } from 'web-fragments/gateway/node';
+import { gateway } from './gateway';
+
+export default {
+  plugins: [{
+    name: 'web-fragments-gateway',
+    configureServer(server) {
+      server.middlewares.use(getNodeMiddleware(gateway, { mode: 'development' }));
+    },
+  }],
+};
+```
+
+## Cross-cutting rules
+- The **host-route** `routePattern` must match the URL where `<web-fragment>` is placed,
+  or the gateway never serves that fragment.
+- The **asset** `routePattern` prefix must match the fragment build's asset output dir.
+- One `FragmentGateway` instance can hold many `registerFragment` calls — register every
+  fragment the host embeds.
+- Pick Web **or** Node middleware to match the runtime; importing `gateway/node` into an
+  edge/worker bundle will fail.
diff --git a/skills/web-fragments/references/piercing-and-performance.md b/skills/web-fragments/references/piercing-and-performance.md
new file mode 100644
index 0000000..c636f38
--- /dev/null
+++ b/skills/web-fragments/references/piercing-and-performance.md
@@ -0,0 +1,60 @@
+# Piercing & Performance
+
+All claims below are **confirmed in the gateway source** (`src/gateway/middleware/web.ts`,
+`fragment-gateway.ts`, `web-fragment-host.ts`) unless marked.
+
+## Piercing (SSR composition)
+
+Piercing server-side-renders the fragment's markup into the app-shell response, removing the
+client round-trip on first load. It's the primary perf feature; `piercing` defaults to `true`.
+
+- **Fires only on hard navigation:** the gateway pierces when `sec-fetch-dest: document`
+  (`fetchingToPierce` in web.ts). Soft navs (fetch/XHR) take the non-pierced path. So piercing
+  helps full-page loads, not in-app fetches.
+- **HTML rewrite:** the gateway rewrites the fragment's `<html>`/`<head>`/`<body>` to
+  `<wf-html>`/`<wf-head>`/`<wf-body>` (web.ts). The fragment must return **real HTML with
+  those tags** and `content-type: text/html`.
+- **Pre-pierce styling (avoid CLS):** the gateway emits
+  `<web-fragment-host … data-piercing="true">`. Position it via `piercingStyles` targeting
+  `web-fragment-host[data-piercing="true"]` (e.g. `position`, `z-index`) so it lands in the
+  right place before portaling; the attribute is removed after portaling (web-fragment-host.ts).
+- **Missing placeholder = layout shift:** if the app shell lacks a `<web-fragment
+  fragment-id="…">` on the matching route, the gateway appends the host at the end of
+  `<body>` as a fallback — piercing still works but the fragment appears out of place.
+- **HTMLRewriter engine** *(per PR #294 / maintainers):* native on Cloudflare Workers
+  (streams the combined response before the fragment fetch finishes); WASM on Node buffers the
+  whole fragment first — a latency limitation.
+
+## Caching & headers
+
+- **`Vary: sec-fetch-dest`** is appended to gateway responses to prevent BFCache serving the
+  wrong (pierced vs not) variant (web.ts). Don't let a proxy strip it.
+- **iframe stub** is cached `max-age=3600, public, stale-while-revalidate=31536000` by default
+  (web.ts). Only override via `iframeHeaders` if you need a shorter TTL.
+- **Forward fragment cache headers:** `forwardFragmentHeaders: ['cache-control']` so the
+  fragment's `Cache-Control` reaches the combined response (else the host's is used). Same
+  mechanism for other fragment response headers the host needs (`Set-Cookie`, custom).
+
+## `mode: 'production'` vs `'development'`
+
+Set `mode: 'production'` when deployed. Development mode disables compression passthrough to
+work around a miniflare bug that mangles `content-length` on compressed/chunked responses
+(cloudflare/workers-sdk#6577, web.ts) and is otherwise dev-oriented (verbose errors). Wrong
+`mode` in prod = avoidable overhead / leaked error detail.
+
+## Route-pattern specificity
+
+`matchRequestToFragment` returns the **first** matching pattern — there is **no specificity
+ordering yet** (explicit `// TODO: path matching needs to take pattern specificity into
+account` in fragment-gateway.ts). Consequences:
+- **List more specific patterns first**; an overly broad `/:_*` earlier will shadow them and
+  also try to serve routes that should fall through to the app shell.
+- `/products` does **not** match `/products/123` (path-to-regexp v6) — use `/products/:_*`.
+
+## onSsrFetchError
+
+- Without an `onSsrFetchError` handler, a failed fragment fetch falls back to the gateway's
+  default (`defaultOnSsrFetchError`, `overrideResponse: false`) — a generic error response to
+  the user. Provide one to serve a friendly fallback.
+- `overrideResponse: true` makes the returned `response` **replace the entire page** (the
+  middleware `throw`s it) — useful for auth redirects. Return `content-type: text/html`.
diff --git a/skills/web-fragments/references/troubleshooting.md b/skills/web-fragments/references/troubleshooting.md
new file mode 100644
index 0000000..d799151
--- /dev/null
+++ b/skills/web-fragments/references/troubleshooting.md
@@ -0,0 +1,130 @@
+# Troubleshooting & Known Issues (v0.8.x)
+
+Read this FIRST when a fragment is broken. Each entry: symptom → cause → fix. The
+issue numbers reference github.com/web-fragments/web-fragments/issues — check there for
+the current status, since this is a fast-moving beta.
+
+## Module / import errors
+
+### `Cannot find module 'web-fragments/middleware'`
+**Cause:** stale docs. That entry point never existed. **Fix:** import web middleware from
+`web-fragments/gateway` (`getWebMiddleware`), node middleware from
+`web-fragments/gateway/node` (`getNodeMiddleware`).
+
+### `gateway.register is not a function`
+**Cause:** the method is `registerFragment`, not `register`. **Fix:** rename the call.
+
+### Types don't resolve under `moduleResolution: "nodenext"` (issue #284)
+**Symptom:** TS can't find the library's type declarations when the consumer uses
+`nodenext`/`node16` resolution. **Fix options:** set the host tsconfig to
+`"moduleResolution": "bundler"` if your toolchain allows; or add a local module
+declaration shim; or pin/upgrade to a release where the `exports` `types` conditions are
+fixed. Verify the installed version's `package.json` `exports` includes `types` for each
+entry. Track issue #284.
+
+## Build / bundler errors
+
+### `htmlrewriter` error when host is Angular (issue #280, resolved via config)
+**Fix** in the host app's `angular.json` build target:
+```jsonc
+"outputMode": "server",
+"externalDependencies": ["web-fragments/gateway", "web-fragments/gateway/node", "htmlrewriter"]
+```
+Marking those as external stops the Angular bundler from trying to bundle the
+WASM-backed `htmlrewriter` dependency.
+
+### Edge/worker build fails importing node middleware
+**Cause:** `web-fragments/gateway/node` pulls in Node APIs. **Fix:** in edge/worker
+runtimes import `getWebMiddleware` from `web-fragments/gateway` instead.
+
+## Runtime: fragment doesn't appear
+
+### Blank fragment / asset 404s
+**Cause #1 (most common):** the fragment build's asset directory and the gateway's asset
+`routePattern` prefix don't match. **Fix:** align Vite `build.assetsDir` (or the
+framework's base/public path) with the `/__wf/<id>/:_*` pattern. See
+`fragment-authoring.md`.
+**Cause #2:** the **host-route** `routePattern` doesn't match the URL where
+`<web-fragment>` is placed. **Fix:** add/adjust a pattern for that route.
+
+### `The <web-fragment> is missing fragment-id attribute!`
+**Fix:** add `fragment-id` to the element; it must equal a registered `fragmentId` —
+**case-sensitive exact match** (`UserProfile` ≠ `user-profile`).
+
+### Element does nothing / not upgraded
+**Cause:** `initializeWebFragments()` not called, or called after the element connected.
+**Fix:** call it once, as early as possible in the host client bootstrap.
+
+### Fragment silently fails to load (no error), hidden iframe never loads
+**Cause:** the fragment endpoint responds with `X-Frame-Options: DENY` (or
+`frame-ancestors 'none'`), blocking the hidden iframe the gateway uses as the JS context.
+**Fix:** remove it / use `SAMEORIGIN`, and allow framing via
+`frame-ancestors 'self' <gateway-origin>`. Full model: `csp-and-iframe.md`.
+
+### Route matches too much / wrong fragment served / sub-paths 404
+**Cause:** path-to-regexp v6 — `/products` does **not** match `/products/123` (use
+`/products/:_*`). Also the gateway returns the **first** matching pattern (no specificity
+ordering yet), so a broad pattern can shadow a specific one. **Fix:** use `:_*` for
+sub-paths; register **specific patterns before broad ones**. See `piercing-and-performance.md`.
+
+### Fragment renders but in the wrong place / layout shift on first paint
+**Cause:** the app shell lacks a `<web-fragment fragment-id="…">` on the pierced route, so the
+gateway appends the host at the end of `<body>` as a fallback; or `piercingStyles` doesn't
+position `web-fragment-host[data-piercing="true"]`. **Fix:** add the placeholder on the route
+and style the pre-pierce host. See `piercing-and-performance.md`.
+
+### Gateway not detected / no error surfaced (issue #288)
+There is currently no built-in custom error handling when the gateway middleware isn't
+present in the request path. **Mitigation:** verify the middleware is installed and ordered
+before catch-all routes; add your own guard/logging until first-class handling lands.
+
+## Runtime: SSR / hydration / streaming
+
+### Next.js fragments don't hydrate (issue #290, OPEN bug)
+Server piercing may render but client hydration is unreliable on Next.js hosts. **Mitigate:**
+try `piercing: false` to isolate piercing vs hydration; track issue #290; don't promise full
+Next.js support without testing the current release.
+
+### JS assets truncated mid-stream via `getNodeMiddleware` (issue #293, OPEN bug)
+**Symptom:** fragment JS cut off / parse errors when proxied through the Node middleware,
+caused by a `Content-Length`/`Content-Encoding` mismatch after undici transparently
+decompresses the upstream response. **Mitigations:** prefer the Web middleware where the
+runtime allows; ensure the fragment origin's compression headers are consistent; track
+issue #293. Suspect this when assets load fine directly from the fragment origin but break
+when proxied through a Node host.
+
+### Fragment styles accumulate / old pages' CSS bleeds into new ones during SPA nav
+**Symptom:** a fragment that does client-side routing (e.g. Astro `<ClientRouter />`) and
+injects per-route `<style>`/`<link>` into `<head>` leaves the previous route's styles
+behind. They pile up node-by-node on every navigation and earlier rules keep applying.
+**Cause:** reframed relocates head `<style>`/`<link>` out of `wf-head` to apply them inside
+the shadow tree, so the framework's head-swap (which cleans `document.head` = `wf-head`)
+never removes them. **Fix:** keep the fragment's `<head>` CSS stable across navigations
+(one shared stylesheet loaded once; scope per-page rules under a body class), or drop
+client-side routing for that fragment. Tracked upstream as
+[#297](https://github.com/web-fragments/web-fragments/issues/297). Full verified analysis +
+repro: `references/frameworks-astro.md` → "Bug: head styles accumulate".
+
+### Styles bleed between fragment and host
+Should not happen — fragments live in a shadow root. If it does, confirm
+`initializeWebFragments()` ran and the fragment is actually inside `<web-fragment-host>`
+(inspect the shadow root in dev tools). Pre-pierce flashes can be smoothed with
+`piercingClassNames` / `FragmentGatewayConfig.piercingStyles`.
+
+## Architecture constraints (not bugs)
+
+- **The gateway is mandatory** (issue #278). There is no server-less mode yet; a
+  service-worker gateway is in progress. Fragments cannot federate without it.
+- **Each fragment gets its own JS context** (`wf:<fragment-id>`, a hidden iframe). This is
+  by design — it's how isolation works. Removing the `<web-fragment>` element tears the
+  context down and frees its memory.
+- **Passing synchronous host→fragment inputs** is not yet supported (feature request
+  #289). Communicate via shared DOM, navigation, URL, or `postMessage`-style channels.
+
+## Fast diagnosis checklist
+1. Run `scripts/doctor.mjs <project>` — catches import path, `register` vs
+   `registerFragment`, asset/routePattern mismatch, missing middleware.
+2. Dev tools: is there a `wf:<id>` iframe context? Is the DOM inside a shadow root?
+3. Network tab: do `/__wf/<id>/…` asset requests 200 on the **host** origin?
+4. Confirm the installed version (`node_modules/web-fragments/package.json`) and its
+   `exports` map before trusting any external doc.
diff --git a/skills/web-fragments/scripts/doctor.mjs b/skills/web-fragments/scripts/doctor.mjs
new file mode 100644
index 0000000..f381d36
--- /dev/null
+++ b/skills/web-fragments/scripts/doctor.mjs
@@ -0,0 +1,166 @@
+#!/usr/bin/env node
+// doctor.mjs — static-analyze a Web Fragments host/fragment project for the common
+// v0.8.x wiring mistakes, without deploying or reading library source.
+//
+// Usage:  node doctor.mjs [projectDir]   (defaults to cwd)
+// Exit code: 0 = no errors, 1 = at least one ERROR-level finding.
+//
+// Heuristic, not a compiler. It greps source files and reports likely problems with a
+// fix for each. False positives are possible — treat findings as leads, not verdicts.
+
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { join, relative, extname } from 'node:path';
+
+const root = process.argv[2] || process.cwd();
+const SKIP_DIRS = new Set(['node_modules', '.git', 'dist', 'build', '.next', '.astro', 'out', 'coverage']);
+const TEXT_EXT = new Set(['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs', '.html', '.vue', '.svelte', '.astro', '.json', '.jsonc']);
+
+const findings = []; // { level: 'error'|'warn'|'info', msg, fix, file? }
+const add = (level, msg, fix, file) => findings.push({ level, msg, fix, file });
+
+/** Collect candidate source files. */
+function walk(dir, acc = []) {
+  let entries;
+  try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return acc; }
+  for (const e of entries) {
+    if (e.name.startsWith('.') && e.name !== '.') continue;
+    const full = join(dir, e.name);
+    if (e.isDirectory()) {
+      if (!SKIP_DIRS.has(e.name)) walk(full, acc);
+    } else if (TEXT_EXT.has(extname(e.name))) {
+      acc.push(full);
+    }
+  }
+  return acc;
+}
+
+const files = walk(root);
+const sources = files.map((f) => {
+  try { return { f, text: readFileSync(f, 'utf8') }; } catch { return { f, text: '' }; }
+});
+const rel = (f) => relative(root, f) || f;
+const any = (re) => sources.filter((s) => re.test(s.text));
+
+// --- 1. Wrong middleware import (stale doc) ---
+for (const s of any(/from\s+['"]web-fragments\/middleware['"]/)) {
+  add('error',
+    `Imports from the non-existent 'web-fragments/middleware' entry point.`,
+    `Use 'web-fragments/gateway' (getWebMiddleware) or 'web-fragments/gateway/node' (getNodeMiddleware).`,
+    rel(s.f));
+}
+
+// --- 2. register vs registerFragment ---
+for (const s of sources) {
+  // a gateway-ish variable calling .register( but not .registerFragment(
+  if (/\.register\s*\(/.test(s.text) && !/\.registerFragment\s*\(/.test(s.text) && /FragmentGateway|web-fragments\/gateway/.test(s.text)) {
+    add('error',
+      `Calls .register(...) on what looks like a FragmentGateway.`,
+      `The method is registerFragment(config), not register.`,
+      rel(s.f));
+  }
+}
+
+// --- 3. Detect project role ---
+const usesGateway = any(/web-fragments\/gateway/).length > 0;
+const usesElements = any(/from\s+['"]web-fragments['"]/).length > 0 || any(/<web-fragment[\s>]/).length > 0;
+const isHost = usesGateway || usesElements;
+
+// --- 4. Host: initializeWebFragments present if elements used ---
+if (any(/<web-fragment[\s>]/).length > 0 && any(/initializeWebFragments\s*\(/).length === 0) {
+  add('error',
+    `Uses <web-fragment> but never calls initializeWebFragments().`,
+    `Import { initializeWebFragments } from 'web-fragments' and call it once, early in the host client bootstrap.`);
+}
+
+// --- 5. Host: middleware installed if gateway registered ---
+if (any(/registerFragment\s*\(/).length > 0 &&
+    any(/getWebMiddleware|getNodeMiddleware/).length === 0) {
+  add('error',
+    `Registers fragments but never installs gateway middleware.`,
+    `Add getWebMiddleware(gateway) (Web runtimes) or getNodeMiddleware(gateway) (Express/Connect) to the host server.`);
+}
+
+// --- 6. Required FragmentConfig fields present near registerFragment ---
+for (const s of any(/registerFragment\s*\(/)) {
+  const blockHasId = /fragmentId\s*:/.test(s.text);
+  const blockHasEndpoint = /endpoint\s*:/.test(s.text) || /upstream\s*:/.test(s.text);
+  const blockHasRoutes = /routePatterns\s*:/.test(s.text);
+  if (!blockHasId) add('error', `registerFragment without a fragmentId.`, `fragmentId is required and must match the <web-fragment fragment-id>.`, rel(s.f));
+  if (!blockHasEndpoint) add('error', `registerFragment without an endpoint.`, `endpoint (URL string or fetch fn) is required.`, rel(s.f));
+  if (!blockHasRoutes) add('error', `registerFragment without routePatterns.`, `routePatterns (path-to-regexp v6) is required: asset prefix + host route(s).`, rel(s.f));
+}
+
+// --- 7. Deprecated fields ---
+const deprecated = [
+  [/\bupstream\s*:/, 'upstream', 'endpoint'],
+  [/\bprePiercingClassNames\s*:/, 'prePiercingClassNames', 'piercingClassNames'],
+  [/\bprePiercingStyles\s*:/, 'prePiercingStyles', 'piercingStyles'],
+];
+for (const [re, oldName, newName] of deprecated) {
+  for (const s of any(re)) add('warn', `Uses deprecated '${oldName}'.`, `Rename to '${newName}'.`, rel(s.f));
+}
+
+// --- 8. Asset path vs routePattern coherence ---
+const assetDirRe = /assetsDir\s*:\s*['"]([^'"]+)['"]/;
+const assetDirs = [];
+for (const s of sources) { const m = s.text.match(assetDirRe); if (m) assetDirs.push(m[1].replace(/^\/+|\/+$/g, '')); }
+const routePatternPrefixes = [];
+for (const s of sources) {
+  for (const m of s.text.matchAll(/['"](\/__wf\/[^'":*]+)/g)) routePatternPrefixes.push(m[1].replace(/^\/+|\/+$/g, ''));
+}
+if (assetDirs.length && routePatternPrefixes.length) {
+  for (const a of assetDirs) {
+    const norm = a.replace(/^__wf\//, '__wf/');
+    const matched = routePatternPrefixes.some((p) => p.includes(norm) || norm.includes(p.replace(/^__wf\//, '__wf/')));
+    if (!matched) add('warn',
+      `Vite assetsDir '${a}' does not appear to match any '/__wf/...' routePattern prefix.`,
+      `Align the fragment build asset dir with the gateway asset routePattern, or assets will 404.`);
+  }
+}
+
+// --- 9. Suspicious __wf routePattern without an asset-dir anywhere (host-only project: fine) ---
+// (info only; host projects legitimately have no assetsDir)
+
+// --- 10. X-Frame-Options: DENY blocks the gateway's hidden iframe ---
+for (const s of any(/x-frame-options['"\s:=,()]+\s*['"]?\s*deny/i)) {
+  add('error',
+    `Sets X-Frame-Options: DENY — blocks the hidden iframe the gateway uses as the JS context (fragment silently fails).`,
+    `Use SAMEORIGIN / remove it on fragment endpoints; allow framing via 'frame-ancestors self <gateway-origin>'. See references/csp-and-iframe.md.`,
+    rel(s.f));
+}
+
+// --- 11. Unscoped static serving registered BEFORE the fragment middleware ---
+// Only flag catch-all static (`.use(express.static(...))` with no path prefix); a path-scoped
+// `.use('/assets', express.static(...))` doesn't shadow fragment routes.
+for (const s of sources) {
+  const mw = s.text.search(/get(Node|Web)Middleware\s*\(/);
+  const stat = s.text.search(/\.use\(\s*(express\.static|serveStatic)\s*\(/);
+  if (mw !== -1 && stat !== -1 && stat < mw) {
+    add('warn',
+      `Unscoped static serving appears before the fragment middleware in this file.`,
+      `Register get(Node|Web)Middleware BEFORE catch-all static serving, or static answers fragment requests first.`,
+      rel(s.f));
+  }
+}
+
+// --- Report ---
+const order = { error: 0, warn: 1, info: 2 };
+findings.sort((a, b) => order[a.level] - order[b.level]);
+const icon = { error: '✖ ERROR', warn: '▲ WARN ', info: 'ℹ INFO ' };
+
+console.log(`\nWeb Fragments doctor — scanned ${sources.length} files under ${root}`);
+console.log(`Project role: ${isHost ? (usesGateway && usesElements ? 'host (elements + gateway)' : usesGateway ? 'host server / gateway' : 'host client') : 'no web-fragments usage detected (fragment app or unrelated)'}\n`);
+
+if (findings.length === 0) {
+  console.log('✓ No issues found by the heuristics. Still verify in a browser (wf:<id> context + asset 200s).');
+} else {
+  for (const f of findings) {
+    console.log(`${icon[f.level]}  ${f.msg}${f.file ? `  [${f.file}]` : ''}`);
+    console.log(`         ↳ ${f.fix}\n`);
+  }
+}
+
+const errors = findings.filter((f) => f.level === 'error').length;
+const warns = findings.filter((f) => f.level === 'warn').length;
+console.log(`Summary: ${errors} error(s), ${warns} warning(s).`);
+process.exit(errors > 0 ? 1 : 0);
diff --git a/skills/web-fragments/scripts/experiments/README.md b/skills/web-fragments/scripts/experiments/README.md
new file mode 100644
index 0000000..11a2307
--- /dev/null
+++ b/skills/web-fragments/scripts/experiments/README.md
@@ -0,0 +1,12 @@
+# Web Fragments skill — experiments
+
+Verified mini-apps backing the references. Each is runnable; see the matching reference doc.
+
+- css-vars-isolation/ + measure-css.cjs  -> references/css-and-styling.md
+- astro-fragment/ + astro-host/ + measure-astro.cjs -> references/frameworks-astro.md (basic ClientRouter embed)
+- astro-fragment/src/pages/[...path].astro + measure-head.cjs -> the #297 head-accumulation repro
+- astro-fragment/src/{layouts/SmoothLayout.astro, pages/smooth/[site].astro} + measure-smooth.cjs
+  -> smooth transitions WITHOUT ClientRouter (stable head + View Transition API), avoids #297
+
+These are reference experiments, not part of the skill runtime. Node + a chromium from
+`@playwright/test` are required to re-run them.
diff --git a/skills/web-fragments/scripts/experiments/astro-fragment/astro.config.mjs b/skills/web-fragments/scripts/experiments/astro-fragment/astro.config.mjs
new file mode 100644
index 0000000..373f2ef
--- /dev/null
+++ b/skills/web-fragments/scripts/experiments/astro-fragment/astro.config.mjs
@@ -0,0 +1,12 @@
+import { defineConfig } from 'astro/config';
+
+// Namespace everything (pages + assets) under /astro so the fragment gateway can route
+// all fragment requests with a single pattern: /astro/:_*
+export default defineConfig({
+  base: '/astro',
+  trailingSlash: 'always',
+  build: {
+    // default assets dir is _astro; under base it becomes /astro/_astro/...
+    format: 'directory',
+  },
+});
diff --git a/skills/web-fragments/scripts/experiments/astro-fragment/package.json b/skills/web-fragments/scripts/experiments/astro-fragment/package.json
new file mode 100644
index 0000000..f315753
--- /dev/null
+++ b/skills/web-fragments/scripts/experiments/astro-fragment/package.json
@@ -0,0 +1,12 @@
+{
+  "name": "astro-fragment-demo",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "build": "astro build",
+    "preview": "astro preview"
+  },
+  "dependencies": {
+    "astro": "^5.0.0"
+  }
+}
diff --git a/skills/web-fragments/scripts/experiments/astro-fragment/public/css/a.css b/skills/web-fragments/scripts/experiments/astro-fragment/public/css/a.css
new file mode 100644
index 0000000..cbf8705
--- /dev/null
+++ b/skills/web-fragments/scripts/experiments/astro-fragment/public/css/a.css
@@ -0,0 +1,2 @@
+.link-mark { color: rgb(255,0,0); }
+.site-a-only { outline: 2px solid rgb(255,0,0); }
diff --git a/skills/web-fragments/scripts/experiments/astro-fragment/public/css/b.css b/skills/web-fragments/scripts/experiments/astro-fragment/public/css/b.css
new file mode 100644
index 0000000..cb50225
--- /dev/null
+++ b/skills/web-fragments/scripts/experiments/astro-fragment/public/css/b.css
@@ -0,0 +1,2 @@
+.link-mark { color: rgb(0,128,0); }
+.site-b-only { outline: 2px solid rgb(0,128,0); }
diff --git a/skills/web-fragments/scripts/experiments/astro-fragment/public/css/c.css b/skills/web-fragments/scripts/experiments/astro-fragment/public/css/c.css
new file mode 100644
index 0000000..be6a505
--- /dev/null
+++ b/skills/web-fragments/scripts/experiments/astro-fragment/public/css/c.css
@@ -0,0 +1,2 @@
+.link-mark { color: rgb(0,0,255); }
+.site-c-only { outline: 2px solid rgb(0,0,255); }
diff --git a/skills/web-fragments/scripts/experiments/astro-fragment/src/layouts/Layout.astro b/skills/web-fragments/scripts/experiments/astro-fragment/src/layouts/Layout.astro
new file mode 100644
index 0000000..0749fbe
--- /dev/null
+++ b/skills/web-fragments/scripts/experiments/astro-fragment/src/layouts/Layout.astro
@@ -0,0 +1,38 @@
+---
+import { ClientRouter } from 'astro:transitions';
+const { title } = Astro.props;
+---
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <title>{title}</title>
+    <ClientRouter />
+    <style>
+      body { font-family: system-ui, sans-serif; padding: 1rem; }
+      nav a { margin-right: 1rem; }
+      .marker { color: rebeccapurple; font-weight: bold; }
+    </style>
+  </head>
+  <body>
+    <h2>Astro fragment — <span transition:name="page-title">{title}</span></h2>
+    <nav>
+      <a href="/astro/">Home</a>
+      <a href="/astro/page2/">Page 2</a>
+    </nav>
+    <slot />
+    <p class="marker" id="nav-count">navigations: <span id="count">0</span></p>
+    <script>
+      // Count client-router page swaps. A full reload resets this to 0;
+      // a successful SPA navigation increments it (state survives the swap via sessionStorage).
+      const n = Number(sessionStorage.getItem('wf-astro-nav') || '0');
+      const el = document.getElementById('count');
+      if (el) el.textContent = String(n);
+      document.addEventListener('astro:after-swap', () => {
+        const next = Number(sessionStorage.getItem('wf-astro-nav') || '0') + 1;
+        sessionStorage.setItem('wf-astro-nav', String(next));
+        const e2 = document.getElementById('count');
+        if (e2) e2.textContent = String(next);
+      });
+    </script>
+  </body>
+</html>
diff --git a/skills/web-fragments/scripts/experiments/astro-fragment/src/layouts/SmoothLayout.astro b/skills/web-fragments/scripts/experiments/astro-fragment/src/layouts/SmoothLayout.astro
new file mode 100644
index 0000000..3bdb969
--- /dev/null
+++ b/skills/web-fragments/scripts/experiments/astro-fragment/src/layouts/SmoothLayout.astro
@@ -0,0 +1,74 @@
+---
+const { site } = Astro.props;
+---
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <title>smooth {site}</title>
+    <!-- ALL styles loaded ONCE here, identical on every page, never swapped.
+         Per-site rules are scoped by [data-site]; only #content (with its data-site) is
+         swapped on navigation, so <head> never changes => no #297 accumulation. -->
+    <style>
+      body { font-family: system-ui, sans-serif; padding: 1rem; }
+      nav a { margin-right: 1rem; }
+      #content { view-transition-name: wf-content; }
+      [data-site="a"] #site-name { color: rgb(255,0,0); background: rgb(255,230,230); }
+      [data-site="b"] #site-name { color: rgb(0,128,0); border-bottom: 4px solid rgb(0,128,0); }
+      [data-site="c"] #site-name { color: rgb(0,0,255); font-style: italic; }
+      ::view-transition-old(wf-content),
+      ::view-transition-new(wf-content) { animation-duration: 300ms; }
+    </style>
+  </head>
+  <body>
+    <nav>
+      <a href="/astro/smooth/a/">A</a>
+      <a href="/astro/smooth/b/">B</a>
+      <a href="/astro/smooth/c/">C</a>
+      <a href="/not-a-fragment/page" id="ext-link">OutOfNamespace</a>
+    </nav>
+    <span id="vt-flag" hidden></span>
+    <main id="content" data-site={site}>
+      <h2><span id="site-name">Site {site}</span></h2>
+      <p class="body-copy">Content for site {site}.</p>
+    </main>
+
+    <script is:inline>
+      // Minimal in-fragment content swap. Stays inside the fragment (preventDefault on
+      // links), never mutates <head>, and animates via the same-document View Transition
+      // API when available (graceful fallback to an instant swap otherwise).
+      async function navigate(url, push) {
+        let html;
+        try { html = await (await fetch(url)).text(); }
+        catch { location.href = url; return; }
+        const doc = new DOMParser().parseFromString(html, 'text/html');
+        const next = doc.querySelector('#content');
+        const cur = document.querySelector('#content');
+        if (!next || !cur) { location.href = url; return; }
+        const swap = () => cur.replaceWith(next);
+        if (typeof document.startViewTransition === 'function') document.startViewTransition(swap);
+        else swap();
+        if (push) history.pushState({}, '', url);
+      }
+      // OPT-OUT: intercept ALL internal links, fall through for everything that shouldn't soft-swap.
+      document.addEventListener('click', (e) => {
+        const a = e.target.closest && e.target.closest('a[href]');
+        if (!a) return;
+        if (e.defaultPrevented) return;
+        if (e.button !== 0 || e.metaKey || e.ctrlKey || e.shiftKey || e.altKey) return; // new tab/window
+        if (a.target && a.target !== '_self') return;          // target="_blank" etc.
+        if (a.hasAttribute('download')) return;
+        if (a.getAttribute('rel') === 'external') return;
+        const url = new URL(a.href, location.href);
+        if (url.origin !== location.origin) return;            // external site
+        if (!url.pathname.startsWith('/astro/')) return;       // outside THIS fragment's routes
+        if (url.pathname === location.pathname && url.hash) return; // same-page anchor
+        e.preventDefault();
+        navigate(url.pathname + url.search, true);
+      });
+      window.addEventListener('popstate', () => navigate(location.pathname, false));
+      // expose VT availability into the DOM (readable across the shadow boundary)
+      var vf = document.getElementById('vt-flag');
+      if (vf) vf.textContent = String(typeof document.startViewTransition === 'function');
+    </script>
+  </body>
+</html>
diff --git a/skills/web-fragments/scripts/experiments/astro-fragment/src/pages/[...path].astro b/skills/web-fragments/scripts/experiments/astro-fragment/src/pages/[...path].astro
new file mode 100644
index 0000000..f94fefb
--- /dev/null
+++ b/skills/web-fragments/scripts/experiments/astro-fragment/src/pages/[...path].astro
@@ -0,0 +1,55 @@
+---
+import { ClientRouter } from 'astro:transitions';
+
+// Mimic "embedding multiple static sites, each referencing different CSS", served from a
+// catch-all route. Each site injects its OWN inline <style> and external <link> into the
+// head via set:html, exactly around <ClientRouter />.
+const SITES = {
+  a: { color: 'rgb(255, 0, 0)', name: 'Site A (red)' },
+  b: { color: 'rgb(0, 128, 0)', name: 'Site B (green)' },
+  c: { color: 'rgb(0, 0, 255)', name: 'Site C (blue)' },
+};
+
+export function getStaticPaths() {
+  return ['a', 'b', 'c'].map((p) => ({ params: { path: p } }));
+}
+
+const { path } = Astro.params;
+const site = SITES[path] ?? SITES.a;
+
+// Distinct, NON-overlapping rule per site targeting the shared #site-name element.
+// If old head styles are not removed on nav, these stack and visibly pollute later pages.
+const distinct = {
+  a: '#site-name{ background-color: rgb(255,0,0); }',
+  b: '#site-name{ border-bottom: 4px solid rgb(0,128,0); }',
+  c: '#site-name{ font-style: italic; }',
+}[path] ?? '';
+
+// raw HTML injected before and after <ClientRouter /> — the reported pattern
+const beforeHeadEnd = `<style class="wf-probe-inline" data-site="${path}">.inline-mark{color:${site.color}} ${distinct}</style>`;
+const afterHeadEnd = `<link class="wf-probe-link" data-site="${path}" rel="stylesheet" href="/astro/css/${path}.css" />`;
+---
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <title>{site.name}</title>
+    <Fragment set:html={beforeHeadEnd} />
+    <ClientRouter />
+    <Fragment set:html={afterHeadEnd} />
+    <style>
+      body { font-family: system-ui, sans-serif; padding: 1rem; }
+      nav a { margin-right: 1rem; }
+    </style>
+  </head>
+  <body>
+    <h2>Embedded static site: <span id="site-name">{site.name}</span></h2>
+    <nav>
+      <a href="/astro/">Home</a>
+      <a href="/astro/a/">A</a>
+      <a href="/astro/b/">B</a>
+      <a href="/astro/c/">C</a>
+    </nav>
+    <p class="inline-mark" id="inline-mark" data-site={path}>inline-mark (expect {site.color} from this site's inline &lt;style&gt;)</p>
+    <p class="link-mark" id="link-mark" data-site={path}>link-mark (expect {site.color} from this site's &lt;link&gt; css)</p>
+  </body>
+</html>
diff --git a/skills/web-fragments/scripts/experiments/astro-fragment/src/pages/index.astro b/skills/web-fragments/scripts/experiments/astro-fragment/src/pages/index.astro
new file mode 100644
index 0000000..0fca3be
--- /dev/null
+++ b/skills/web-fragments/scripts/experiments/astro-fragment/src/pages/index.astro
@@ -0,0 +1,11 @@
+---
+import Layout from '../layouts/Layout.astro';
+---
+<Layout title="Home">
+  <p id="page-marker" data-page="home">Hub. Each link below is a separate static site with its own CSS.</p>
+  <nav>
+    <a href="/astro/a/">Site A</a>
+    <a href="/astro/b/">Site B</a>
+    <a href="/astro/c/">Site C</a>
+  </nav>
+</Layout>
diff --git a/skills/web-fragments/scripts/experiments/astro-fragment/src/pages/smooth/[site].astro b/skills/web-fragments/scripts/experiments/astro-fragment/src/pages/smooth/[site].astro
new file mode 100644
index 0000000..6f63e82
--- /dev/null
+++ b/skills/web-fragments/scripts/experiments/astro-fragment/src/pages/smooth/[site].astro
@@ -0,0 +1,8 @@
+---
+import SmoothLayout from '../../layouts/SmoothLayout.astro';
+export function getStaticPaths() {
+  return ['a', 'b', 'c'].map((site) => ({ params: { site } }));
+}
+const { site } = Astro.params;
+---
+<SmoothLayout site={site} />
diff --git a/skills/web-fragments/scripts/experiments/astro-host/package.json b/skills/web-fragments/scripts/experiments/astro-host/package.json
new file mode 100644
index 0000000..2fbf69f
--- /dev/null
+++ b/skills/web-fragments/scripts/experiments/astro-host/package.json
@@ -0,0 +1,9 @@
+{
+  "name": "astro-fragment-host",
+  "private": true,
+  "type": "module",
+  "dependencies": {
+    "express": "^4.21.0",
+    "web-fragments": "0.8.2"
+  }
+}
diff --git a/skills/web-fragments/scripts/experiments/astro-host/server.mjs b/skills/web-fragments/scripts/experiments/astro-host/server.mjs
new file mode 100644
index 0000000..f4b0414
--- /dev/null
+++ b/skills/web-fragments/scripts/experiments/astro-host/server.mjs
@@ -0,0 +1,54 @@
+import express from 'express';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { FragmentGateway } from 'web-fragments/gateway';
+import { getNodeMiddleware } from 'web-fragments/gateway/node';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const ASTRO_DIST = path.resolve(__dirname, '../astro-fragment/dist');
+const FRAGMENT_PORT = 5400;
+const HOST_PORT = 5402;
+
+// --- Fragment endpoint: static Astro build, mounted at /astro (matches Astro `base`) ---
+const fragApp = express();
+fragApp.use('/astro', express.static(ASTRO_DIST, { extensions: ['html'] }));
+fragApp.listen(FRAGMENT_PORT, () => console.log(`fragment (astro) on http://localhost:${FRAGMENT_PORT}/astro/`));
+
+// --- Host shell + fragment gateway ---
+const gateway = new FragmentGateway();
+gateway.registerFragment({
+  fragmentId: 'astro',
+  endpoint: `http://localhost:${FRAGMENT_PORT}`,
+  piercing: false,
+  routePatterns: ['/astro/:_*'],
+});
+
+const SHELL = `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <title>Astro-in-fragment host</title>
+    <style>
+      body { font-family: Georgia, serif; padding: 1rem; }
+      web-fragment { display:block; border:2px dashed #6c2bd9; padding:.5rem; margin-top:1rem; }
+    </style>
+    <script type="importmap">
+      { "imports": { "web-fragments": "/_wf/elements.js" } }
+    </script>
+  </head>
+  <body>
+    <h1 id="host-h1">HOST shell (plain HTML)</h1>
+    <p>The box below is an Astro site embedded as a web fragment.</p>
+    <web-fragment fragment-id="astro" src="/astro/"></web-fragment>
+    <script type="module">
+      import { initializeWebFragments } from 'web-fragments';
+      initializeWebFragments();
+    </script>
+  </body>
+</html>`;
+
+const app = express();
+app.use('/_wf', express.static(path.join(__dirname, 'node_modules/web-fragments/dist')));
+app.use(getNodeMiddleware(gateway, { mode: 'development' }));
+app.get('/', (_req, res) => res.type('html').send(SHELL));
+app.listen(HOST_PORT, () => console.log(`host on http://localhost:${HOST_PORT}/`));
diff --git a/skills/web-fragments/scripts/experiments/css-vars-isolation/fragment.html b/skills/web-fragments/scripts/experiments/css-vars-isolation/fragment.html
new file mode 100644
index 0000000..971ad07
--- /dev/null
+++ b/skills/web-fragments/scripts/experiments/css-vars-isolation/fragment.html
@@ -0,0 +1,43 @@
+<!doctype html>
+<html>
+	<head>
+		<meta charset="UTF-8" />
+		<title>css-vars-isolation fragment</title>
+		<style>
+			/* Does :root match anything inside a shadow tree? (hypothesis: no) */
+			:root {
+				--brand: rgb(128, 0, 128); /* purple — attempt to override the host brand */
+			}
+			/* :host targets the shadow host; vars defined here inherit to fragment descendants */
+			:host {
+				--host-accent: rgb(255, 165, 0); /* orange */
+			}
+			/* Fragment's own cascade layers — independent ordering from the host */
+			@layer base, theme;
+			@layer base {
+				.flayered {
+					color: rgb(0, 0, 255);
+				} /* blue */
+			}
+			@layer theme {
+				.flayered {
+					color: rgb(0, 128, 0);
+				} /* green wins if layers are tree-scoped */
+			}
+			.fbrand {
+				color: var(--brand); /* host red (inherited) or fragment purple (:root)? */
+			}
+			.faccent {
+				color: var(--host-accent, rgb(0, 0, 0)); /* orange if :host vars apply */
+			}
+		</style>
+	</head>
+	<body>
+		<h2>css-vars-isolation fragment</h2>
+		<p id="frag-brand" class="fbrand">FRAG brand var (red=inherited, purple=:root won)</p>
+		<p id="frag-accent" class="faccent">FRAG :host accent (expect orange)</p>
+		<p id="frag-layered" class="flayered">FRAG layered (expect green)</p>
+		<p id="frag-font">FRAG font (Georgia if host body font leaks in)</p>
+		<p id="frag-leak" class="leak-class">FRAG host-class leak (expect black, NOT magenta)</p>
+	</body>
+</html>
diff --git a/skills/web-fragments/scripts/experiments/css-vars-isolation/index.html b/skills/web-fragments/scripts/experiments/css-vars-isolation/index.html
new file mode 100644
index 0000000..3a76dd5
--- /dev/null
+++ b/skills/web-fragments/scripts/experiments/css-vars-isolation/index.html
@@ -0,0 +1,56 @@
+<!doctype html>
+<html>
+	<head>
+		<meta charset="UTF-8" />
+		<title>WF Playground: css-vars-isolation</title>
+		<style>
+			/* Host custom properties on :root */
+			:root {
+				--brand: rgb(255, 0, 0); /* red */
+				--pad: 24px;
+			}
+			/* Host cascade layers: theme declared after base => theme wins */
+			@layer base, theme;
+			@layer base {
+				.layered {
+					color: rgb(0, 0, 255);
+				} /* blue */
+			}
+			@layer theme {
+				.layered {
+					color: rgb(0, 128, 0);
+				} /* green wins */
+			}
+			/* Inherited property set on body */
+			body {
+				font-family: Georgia, serif;
+			}
+			/* Non-inherited, host-only class selector. Should NOT cross into the fragment shadow tree. */
+			.leak-class {
+				color: rgb(255, 0, 255); /* magenta */
+			}
+			.brand {
+				color: var(--brand);
+			}
+			web-fragment-host {
+				display: block;
+				border: 1px dashed #999;
+			}
+		</style>
+	</head>
+	<body>
+		<h1>WF Playground: css-vars-isolation</h1>
+
+		<p id="host-brand" class="brand">HOST brand (expect red)</p>
+		<p id="host-layered" class="layered">HOST layered (expect green)</p>
+		<!-- host probe for a var only defined inside the fragment: should be unset (black) -->
+		<p id="host-accent-probe" style="color: var(--host-accent, rgb(0, 0, 0))">HOST accent probe (expect black)</p>
+
+		<web-fragment fragment-id="css-vars-isolation"></web-fragment>
+
+		<script type="module">
+			import { initializeWebFragments } from 'web-fragments';
+			initializeWebFragments();
+		</script>
+	</body>
+</html>
diff --git a/skills/web-fragments/scripts/experiments/measure-astro.cjs b/skills/web-fragments/scripts/experiments/measure-astro.cjs
new file mode 100644
index 0000000..8784ff5
--- /dev/null
+++ b/skills/web-fragments/scripts/experiments/measure-astro.cjs
@@ -0,0 +1,84 @@
+const { chromium } = require('@playwright/test');
+
+const HOST = 'http://localhost:5402/';
+
+// Traverse host light DOM -> web-fragment shadow -> web-fragment-host shadow -> fragment content
+const FIND = `(() => {
+  const wf = document.querySelector('web-fragment');
+  const wfh = wf && wf.shadowRoot && wf.shadowRoot.querySelector('web-fragment-host');
+  const sr = wfh && wfh.shadowRoot;
+  return sr;
+})()`;
+
+(async () => {
+  const browser = await chromium.launch();
+  const page = await browser.newPage();
+  const logs = [];
+  page.on('console', (m) => logs.push(`[${m.type()}] ${m.text()}`.slice(0, 200)));
+  page.on('pageerror', (e) => logs.push('pageerror: ' + e.message));
+  const requests = [];
+  page.on('request', (r) => requests.push(r.method() + ' ' + r.url()));
+
+  await page.goto(HOST, { waitUntil: 'networkidle' });
+
+  // wait for fragment astro content
+  await page.waitForFunction(`(${FIND}) && (${FIND}).querySelector('#page-marker')`, { timeout: 15000 }).catch(() => {});
+
+  const snap = async (label) =>
+    page.evaluate(({ FIND, label }) => {
+      const sr = eval(FIND);
+      const marker = sr && sr.querySelector('#page-marker');
+      const count = sr && sr.querySelector('#count');
+      return {
+        label,
+        url: location.href,
+        page: marker ? marker.getAttribute('data-page') : '(none)',
+        markerText: marker ? marker.textContent.trim() : '(none)',
+        navCount: count ? count.textContent : '(none)',
+        reloadFlagPresent: !!window.__wfNoReload,
+      };
+    }, { FIND, label });
+
+  const before = await snap('before-click');
+
+  // plant a window flag that a full page reload would wipe out
+  await page.evaluate(() => { window.__wfNoReload = true; });
+
+  // click the "Page 2" link inside the fragment (Playwright pierces open shadow roots)
+  let clickMethod = 'locator';
+  let clicked = false;
+  try {
+    await page.getByRole('link', { name: 'Page 2' }).click({ timeout: 4000 });
+    clicked = true;
+  } catch (e) {
+    clickMethod = 'evaluate-dispatch';
+    clicked = await page.evaluate((FIND) => {
+      const sr = eval(FIND);
+      const link = [...sr.querySelectorAll('a')].find((a) => /page 2/i.test(a.textContent));
+      if (!link) return false;
+      link.click();
+      return true;
+    }, FIND);
+  }
+
+  // wait for the fragment content to become page2 (SPA) — or detect a reload
+  await page.waitForFunction(`(${FIND}) && (${FIND}).querySelector('#page-marker') && (${FIND}).querySelector('#page-marker').getAttribute('data-page') === 'page2'`, { timeout: 8000 }).catch(() => {});
+  await page.waitForTimeout(500);
+
+  const after = await snap('after-click');
+
+  const verdict =
+    after.page === 'page2'
+      ? after.reloadFlagPresent
+        ? 'SPA navigation (client router swapped content, NO full reload)'
+        : 'navigated to page2 but via FULL reload (window flag was wiped)'
+      : 'navigation did NOT reach page2 inside the fragment';
+
+  console.log(JSON.stringify({ clicked, clickMethod, before, after, verdict }, null, 2));
+  console.log('--- fragment-scoped requests after click ---');
+  console.log(requests.filter((r) => r.includes('/astro/')).slice(-8).join('\n'));
+  console.log('--- console (last 12) ---');
+  console.log(logs.slice(-12).join('\n'));
+  await page.screenshot({ path: 'C:/Users/oto/AppData/Local/Temp/claude/C--Projects-agentic-toolkit/f9921fa9-5fde-47de-8514-261887da6a8d/scratchpad/astro-after.png', fullPage: true });
+  await browser.close();
+})();
diff --git a/skills/web-fragments/scripts/experiments/measure-css.cjs b/skills/web-fragments/scripts/experiments/measure-css.cjs
new file mode 100644
index 0000000..1622890
--- /dev/null
+++ b/skills/web-fragments/scripts/experiments/measure-css.cjs
@@ -0,0 +1,61 @@
+const { chromium } = require('@playwright/test');
+
+(async () => {
+  const browser = await chromium.launch();
+  const page = await browser.newPage();
+  const errors = [];
+  page.on('console', (m) => { if (m.type() === 'error') errors.push(m.text()); });
+  page.on('pageerror', (e) => errors.push('pageerror: ' + e.message));
+
+  await page.goto('http://localhost:5300/css-vars-isolation/', { waitUntil: 'networkidle' });
+
+  // Wait for the nested fragment shadow content to mount
+  await page.waitForFunction(() => {
+    const wf = document.querySelector('web-fragment');
+    const wfh = wf && wf.shadowRoot && wf.shadowRoot.querySelector('web-fragment-host');
+    const sr = wfh && wfh.shadowRoot;
+    return sr && sr.querySelector('#frag-brand');
+  }, { timeout: 15000 }).catch(() => {});
+
+  const result = await page.evaluate(() => {
+    const color = (el) => (el ? getComputedStyle(el).color : '(no element)');
+    const font = (el) => (el ? getComputedStyle(el).fontFamily : '(no element)');
+    const varOf = (el, name) => (el ? getComputedStyle(el).getPropertyValue(name).trim() : '(no element)');
+    const get = (id) => document.getElementById(id);
+    const wf = document.querySelector('web-fragment');
+    const wfh = wf && wf.shadowRoot && wf.shadowRoot.querySelector('web-fragment-host');
+    const sr = wfh && wfh.shadowRoot;
+    const fget = (id) => (sr ? sr.querySelector('#' + id) : null);
+
+    let shadowDump = null;
+    if (sr && !fget('frag-brand')) {
+      shadowDump = sr.innerHTML.slice(0, 600);
+    }
+
+    return {
+      shadowRootPresent: !!sr,
+      shadowDump,
+      host: {
+        brand_expectRed: color(get('host-brand')),
+        layered_expectGreen: color(get('host-layered')),
+        accentProbe_expectBlack: color(get('host-accent-probe')),
+        font: font(get('host-brand')),
+      },
+      fragment: sr
+        ? {
+            brand_red_or_purple: color(fget('frag-brand')),
+            brandVarValue: varOf(fget('frag-brand'), '--brand'),
+            accent_expectOrange: color(fget('frag-accent')),
+            hostAccentVarValue: varOf(fget('frag-accent'), '--host-accent'),
+            layered_expectGreen: color(fget('frag-layered')),
+            font_Georgia_means_leak: font(fget('frag-font')),
+            leak_expectBlack_notMagenta: color(fget('frag-leak')),
+          }
+        : null,
+    };
+  });
+
+  console.log(JSON.stringify({ result, consoleErrors: errors }, null, 2));
+  await page.screenshot({ path: 'C:/Users/oto/AppData/Local/Temp/claude/C--Projects-agentic-toolkit/f9921fa9-5fde-47de-8514-261887da6a8d/scratchpad/css-shot.png', fullPage: true });
+  await browser.close();
+})();
diff --git a/skills/web-fragments/scripts/experiments/measure-head.cjs b/skills/web-fragments/scripts/experiments/measure-head.cjs
new file mode 100644
index 0000000..0dea1fe
--- /dev/null
+++ b/skills/web-fragments/scripts/experiments/measure-head.cjs
@@ -0,0 +1,75 @@
+const { chromium } = require('@playwright/test');
+const HOST = 'http://localhost:5402/';
+const INNER = `(() => {
+  const wf = document.querySelector('web-fragment');
+  const wfh = wf && wf.shadowRoot && wf.shadowRoot.querySelector('web-fragment-host');
+  return wfh && wfh.shadowRoot;
+})()`;
+
+(async () => {
+  const browser = await chromium.launch();
+  const page = await browser.newPage();
+  await page.goto(HOST, { waitUntil: 'networkidle' });
+  await page.waitForFunction(`(${INNER}) && (${INNER}).querySelector('#page-marker')`, { timeout: 15000 }).catch(() => {});
+
+  const probe = (label) =>
+    page.evaluate(({ INNER, label }) => {
+      const sr = eval(INNER);
+      const all = (root, sel) => [...root.querySelectorAll(sel)];
+      // probe styles/links ANYWHERE in the inner shadow tree
+      const inAnywhere = all(sr, 'style.wf-probe-inline').map((s) => s.getAttribute('data-site'));
+      const linkAnywhere = all(sr, 'link.wf-probe-link').map((l) => l.getAttribute('data-site'));
+      // adopted stylesheets on the inner shadow root (constructable)
+      const adopted = (sr.adoptedStyleSheets || []).map((ss) => {
+        try { return [...ss.cssRules].map((r) => r.cssText).join(' ').slice(0, 80); } catch { return '(opaque)'; }
+      });
+      // also check the outer light-DOM document head (in case styles hoist to the top doc)
+      const outerProbe = all(document.head, 'style.wf-probe-inline, link.wf-probe-link').map(
+        (e) => e.getAttribute('data-site'),
+      );
+      const cur = sr.querySelector('#inline-mark') || sr.querySelector('#page-marker');
+      const col = (id) => {
+        const el = sr.querySelector('#' + id);
+        return el ? getComputedStyle(el).color : '(no el)';
+      };
+      return {
+        label,
+        site: cur ? cur.getAttribute('data-site') || cur.getAttribute('data-page') : '(none)',
+        inlineProbeSites_inShadow: inAnywhere,
+        linkProbeSites_inShadow: linkAnywhere,
+        totalStyleEls_inShadow: all(sr, 'style').length,
+        totalLinkEls_inShadow: all(sr, 'link').length,
+        adoptedSheetsCount: (sr.adoptedStyleSheets || []).length,
+        adoptedProbeRules: adopted.filter((t) => /inline-mark|link-mark/.test(t)),
+        outerHeadProbeSites: outerProbe,
+        inlineMarkColor: col('inline-mark'),
+        linkMarkColor: col('link-mark'),
+        // pollution check on shared #site-name: only the CURRENT site's distinct rule should apply
+        siteName: (() => {
+          const el = sr.querySelector('#site-name');
+          if (!el) return '(no el)';
+          const c = getComputedStyle(el);
+          return { bg: c.backgroundColor, borderBottom: c.borderBottomWidth, fontStyle: c.fontStyle };
+        })(),
+      };
+    }, { INNER, label });
+
+  const steps = [await probe('0:home')];
+  const visit = async (slug) => {
+    await page.evaluate(({ INNER, slug }) => {
+      const sr = eval(INNER);
+      const link = [...sr.querySelectorAll('a')].find((a) => a.getAttribute('href') === `/astro/${slug}/`);
+      if (link) link.click();
+    }, { INNER, slug });
+    await page.waitForFunction(
+      `(${INNER}) && (${INNER}).querySelector('#inline-mark') && (${INNER}).querySelector('#inline-mark').getAttribute('data-site') === '${slug}'`,
+      { timeout: 8000 },
+    ).catch(() => {});
+    await page.waitForTimeout(500);
+    steps.push(await probe(`visit:${slug}`));
+  };
+  for (const n of ['a', 'b', 'c', 'a', 'b']) await visit(n);
+
+  console.log(JSON.stringify(steps, null, 2));
+  await browser.close();
+})();
diff --git a/skills/web-fragments/scripts/experiments/measure-optout.cjs b/skills/web-fragments/scripts/experiments/measure-optout.cjs
new file mode 100644
index 0000000..5b7aef8
--- /dev/null
+++ b/skills/web-fragments/scripts/experiments/measure-optout.cjs
@@ -0,0 +1,67 @@
+const { chromium } = require('@playwright/test');
+const HOST = 'http://localhost:5402/';
+const INNER = `(() => {
+  const wf = document.querySelector('web-fragment');
+  const wfh = wf && wf.shadowRoot && wf.shadowRoot.querySelector('web-fragment-host');
+  return wfh && wfh.shadowRoot;
+})()`;
+
+(async () => {
+  const browser = await chromium.launch();
+  const page = await browser.newPage();
+  await page.goto(HOST, { waitUntil: 'networkidle' });
+  await page.waitForFunction(`(${INNER}) && (${INNER}).querySelector('#content')`, { timeout: 15000 }).catch(() => {});
+
+  const probe = (label) =>
+    page.evaluate(({ INNER, label }) => {
+      const sr = eval(INNER);
+      const content = sr && sr.querySelector('#content');
+      const siteName = sr && sr.querySelector('#site-name');
+      return {
+        label,
+        contentSite: content ? content.getAttribute('data-site') : '(none)',
+        siteNameColor: siteName ? getComputedStyle(siteName).color : '(none)',
+        stylesInShadow: sr ? sr.querySelectorAll('style').length : -1,
+        stillEmbedded: !!document.querySelector('web-fragment'),
+        topURL: location.href,
+      };
+    }, { INNER, label });
+
+  const out = { internal: [], external: null };
+  out.internal.push(await probe('0:initial(a)'));
+
+  // INTERNAL links — now UNtagged (no data-swap); opt-out filter should still intercept+swap
+  const clickInternal = async (slug) => {
+    await page.evaluate(({ INNER, slug }) => {
+      const sr = eval(INNER);
+      const link = [...sr.querySelectorAll('a')].find((a) => a.getAttribute('href') === `/astro/smooth/${slug}/`);
+      if (link) link.click();
+    }, { INNER, slug });
+    await page.waitForFunction(
+      `(${INNER}) && (${INNER}).querySelector('#content') && (${INNER}).querySelector('#content').getAttribute('data-site') === '${slug}'`,
+      { timeout: 8000 },
+    ).catch(() => {});
+    await page.waitForTimeout(400);
+    out.internal.push(await probe(`internal:${slug}`));
+  };
+  await clickInternal('b');
+  await clickInternal('c');
+
+  // OUT-OF-NAMESPACE link — opt-out filter should FALL THROUGH to a real top navigation
+  const beforeURL = page.url();
+  await page.evaluate((INNER) => {
+    const sr = eval(INNER);
+    const link = sr.querySelector('#ext-link');
+    if (link) link.click();
+  }, INNER);
+  await page.waitForTimeout(1500); // allow a real navigation to occur
+  out.external = {
+    beforeURL,
+    afterURL: page.url(),
+    navigatedAway: page.url() !== beforeURL,
+    webFragmentStillPresent: await page.evaluate(() => !!document.querySelector('web-fragment')),
+  };
+
+  console.log(JSON.stringify(out, null, 2));
+  await browser.close();
+})();
diff --git a/skills/web-fragments/scripts/experiments/measure-smooth.cjs b/skills/web-fragments/scripts/experiments/measure-smooth.cjs
new file mode 100644
index 0000000..4c08c78
--- /dev/null
+++ b/skills/web-fragments/scripts/experiments/measure-smooth.cjs
@@ -0,0 +1,54 @@
+const { chromium } = require('@playwright/test');
+const HOST = 'http://localhost:5402/';
+const INNER = `(() => {
+  const wf = document.querySelector('web-fragment');
+  const wfh = wf && wf.shadowRoot && wf.shadowRoot.querySelector('web-fragment-host');
+  return wfh && wfh.shadowRoot;
+})()`;
+
+(async () => {
+  const browser = await chromium.launch();
+  const page = await browser.newPage();
+  const logs = [];
+  page.on('console', (m) => logs.push(`[${m.type()}] ${m.text()}`.slice(0, 160)));
+  page.on('pageerror', (e) => logs.push('pageerror: ' + e.message));
+  await page.goto(HOST, { waitUntil: 'networkidle' });
+  await page.waitForFunction(`(${INNER}) && (${INNER}).querySelector('#content')`, { timeout: 15000 }).catch(() => {});
+
+  const probe = (label) =>
+    page.evaluate(({ INNER, label }) => {
+      const sr = eval(INNER);
+      const content = sr && sr.querySelector('#content');
+      const siteName = sr && sr.querySelector('#site-name');
+      return {
+        label,
+        contentSite: content ? content.getAttribute('data-site') : '(none)',
+        siteNameColor: siteName ? getComputedStyle(siteName).color : '(none)',
+        stylesInShadow: sr ? sr.querySelectorAll('style').length : -1,
+        linksInShadow: sr ? sr.querySelectorAll('link').length : -1,
+        stillEmbedded: !!document.querySelector('web-fragment'),
+        topURL: location.href,
+      };
+    }, { INNER, label });
+
+  const steps = [await probe('0:initial(a)')];
+
+  const visit = async (slug) => {
+    await page.evaluate(({ INNER, slug }) => {
+      const sr = eval(INNER);
+      const link = [...sr.querySelectorAll('a[data-swap]')].find((a) => a.getAttribute('href') === `/astro/smooth/${slug}/`);
+      if (link) link.click();
+    }, { INNER, slug });
+    await page.waitForFunction(
+      `(${INNER}) && (${INNER}).querySelector('#content') && (${INNER}).querySelector('#content').getAttribute('data-site') === '${slug}'`,
+      { timeout: 8000 },
+    ).catch(() => {});
+    await page.waitForTimeout(500);
+    steps.push(await probe(`visit:${slug}`));
+  };
+  for (const n of ['b', 'c', 'a', 'b']) await visit(n);
+
+  console.log(JSON.stringify(steps, null, 2));
+  console.log('--- console (last 6) ---\n' + logs.slice(-6).join('\n'));
+  await browser.close();
+})();
diff --git a/skills/web-fragments/scripts/scaffold-fragment.mjs b/skills/web-fragments/scripts/scaffold-fragment.mjs
new file mode 100644
index 0000000..6a3abfe
--- /dev/null
+++ b/skills/web-fragments/scripts/scaffold-fragment.mjs
@@ -0,0 +1,123 @@
+#!/usr/bin/env node
+// scaffold-fragment.mjs — generate a minimal Vite fragment app skeleton + the matching
+// gateway registration snippet for the host. Mirrors the party-button-fragment layout.
+//
+// Usage:
+//   node scaffold-fragment.mjs <fragment-id> [targetDir] [--org <slug>]
+//
+// Example:
+//   node scaffold-fragment.mjs party-button ./party-button --org acme.shop
+//
+// Creates: index.html, src/main.ts, vite.config.ts, package.json, tsconfig.json
+// Prints:  the FragmentGateway.registerFragment(...) snippet to paste into the host,
+//          with the asset routePattern already aligned to the fragment's assetsDir.
+
+import { mkdirSync, writeFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+const args = process.argv.slice(2);
+const positional = args.filter((a) => !a.startsWith('--'));
+const orgIdx = args.indexOf('--org');
+const org = orgIdx !== -1 ? args[orgIdx + 1] : 'dev.web-fragments.demos';
+
+const fragmentId = positional[0];
+if (!fragmentId || !/^[a-z0-9][a-z0-9-]*$/.test(fragmentId)) {
+  console.error('Usage: node scaffold-fragment.mjs <fragment-id> [targetDir] [--org <slug>]');
+  console.error('  <fragment-id> must be lowercase kebab-case, e.g. party-button');
+  process.exit(1);
+}
+const targetDir = positional[1] || `./${fragmentId}`;
+const assetsDir = `__wf/${org}.${fragmentId}/`;
+const assetRoutePattern = `/${assetsDir}:_*`;
+
+if (existsSync(targetDir)) {
+  console.error(`Refusing to overwrite existing directory: ${targetDir}`);
+  process.exit(1);
+}
+
+const files = {
+  'index.html': `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>${fragmentId} fragment</title>
+  </head>
+  <body>
+    <div id="app">${fragmentId} fragment</div>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>
+`,
+  'src/main.ts': `// The fragment's client code. A fragment is a normal standalone app — it does NOT
+// import 'web-fragments'. The host embeds it through a web-fragment element whose
+// fragment-id is "${fragmentId}".
+const app = document.getElementById('app');
+if (app) {
+  app.addEventListener('click', () => {
+    app.textContent = 'Hello from the ${fragmentId} fragment! ' + new Date().toLocaleTimeString();
+  });
+}
+`,
+  'vite.config.ts': `import { defineConfig } from 'vite';
+
+// The ONE rule that matters for a fragment: emit assets under a unique path so the host
+// gateway can proxy them on its own origin without colliding with other fragments.
+// This must stay in sync with the asset routePattern registered in the host gateway.
+export default defineConfig({
+  build: {
+    assetsDir: '${assetsDir}',
+  },
+});
+`,
+  'package.json': JSON.stringify({
+    name: `${fragmentId}-fragment`,
+    private: true,
+    type: 'module',
+    license: 'MIT',
+    scripts: {
+      dev: 'vite',
+      build: 'tsc && vite build',
+      preview: 'vite build && vite preview',
+    },
+    devDependencies: {
+      typescript: '~5.7.2',
+      vite: '^6.2.0',
+    },
+  }, null, 2) + '\n',
+  'tsconfig.json': JSON.stringify({
+    compilerOptions: {
+      target: 'ES2022',
+      module: 'ESNext',
+      moduleResolution: 'bundler',
+      strict: true,
+      skipLibCheck: true,
+      noEmit: true,
+    },
+    include: ['src'],
+  }, null, 2) + '\n',
+};
+
+for (const [relPath, content] of Object.entries(files)) {
+  const full = join(targetDir, relPath);
+  mkdirSync(join(full, '..'), { recursive: true });
+  writeFileSync(full, content);
+}
+
+console.log(`✓ Scaffolded fragment '${fragmentId}' at ${targetDir}`);
+console.log(`  Run:  cd ${targetDir} && npm install && npm run dev   (serves on http://localhost:5173)\n`);
+console.log('Paste this into the HOST app gateway (asset pattern is already aligned):\n');
+console.log(`  import { FragmentGateway } from 'web-fragments/gateway';
+
+  export const gateway = new FragmentGateway();
+  gateway.registerFragment({
+    fragmentId: '${fragmentId}',
+    endpoint: process.env.${fragmentId.toUpperCase().replace(/-/g, '_')}_ENDPOINT ?? 'http://localhost:5173',
+    routePatterns: [
+      '${assetRoutePattern}', // fragment assets (matches vite assetsDir)
+      '/',                    // TODO: host route(s) where <web-fragment fragment-id="${fragmentId}"> is placed
+    ],
+  });
+`);
+console.log('And in the host markup:');
+console.log(`  <web-fragment fragment-id="${fragmentId}"></web-fragment>\n`);