diff --git a/packages/overlay/.storybook/main.ts b/packages/overlay/.storybook/main.ts
new file mode 100644
index 0000000..4178902
--- /dev/null
+++ b/packages/overlay/.storybook/main.ts
@@ -0,0 +1,68 @@
+import type { StorybookConfig } from "@storybook/html-vite";
+
+/*
+ * Storybook for the overlay.
+ *
+ * The HTML renderer, and not as a fallback — it is the exact shape this code
+ * already has. Every seam in the overlay hands back an `HTMLElement`
+ * (`ControlHandle.element`, `renderFill(ctx, node)`, `DesignPanel.element`,
+ * `toolRow(item)`), which is precisely what an HTML story returns. A React
+ * renderer would mean a wrapper around each one and React in the dependency
+ * graph of a package that has deliberately never had it.
+ *
+ * What this buys that the test suite cannot: `vitest.config.ts` runs on
+ * happy-dom, and its own docstring — plus `inspector/test-support.ts`'s — lists
+ * what that costs. No layout, no native CSS nesting, `@layer` dropped entirely,
+ * no `CSSStyleDeclaration` iterator. Those are the four things the inspector
+ * reads. Here they are real, because this is a real browser.
+ */
+const config: StorybookConfig = {
+ addons: [
+ // axe on every story. The overlay hand-wires its ARIA — `role="group"` plus
+ // a label on segmented groups, `aria-pressed` per cell, `aria-haspopup`
+ // /`aria-expanded` on selects — and `inspector/a11y.test.ts` asserts a
+ // sample of it. This checks the rest, on every story, for free.
+ "@storybook/addon-a11y",
+ /*
+ * Opt-in since Storybook 9, and not optional here.
+ *
+ * The editor is dark-only chrome, and three of its border tokens are
+ * `rgba(255,255,255,0.06…0.12)` — on Storybook's default white canvas they
+ * are invisible, so a hairline that is missing looks exactly like a hairline
+ * that is there. `preview.ts` defines the two grounds this repo has: the
+ * editor surface, and the white page the docks float over.
+ */
+ "storybook/backgrounds",
+ /*
+ * The browser test tier — see `vitest.browser.config.ts`.
+ *
+ * Registered here so the runner and the UI agree on what a story is, but
+ * deliberately *not* wired into `pnpm test`: that runs from
+ * `.husky/pre-commit`, and a commit hook that launches Chromium fails on any
+ * machine that has not downloaded it. `make test-browser` opts in.
+ */
+ "@storybook/addon-vitest",
+ ],
+
+ framework: { name: "@storybook/html-vite", options: {} },
+
+ /*
+ * The fonts, which the overlay cannot render honestly without.
+ *
+ * `styles/index.ts` declares `@font-face` against `/__airship/fonts/*.woff2`,
+ * and in production only the proxy serves that path
+ * (`packages/server/src/proxy.ts`). The files themselves are emitted by
+ * `@airship/editor-tokens`' postbuild, so this mapping is why the `storybook`
+ * turbo task depends on that package's `build` — Storybook errors at startup
+ * on a missing `from`, rather than starting up and rendering everything in
+ * fallback fonts. Failing loudly is the right trade: the dock is 11px type in
+ * a 360px column, and it is a different piece of design in Helvetica.
+ */
+ staticDirs: [
+ { from: "../../editor-tokens/dist/fonts", to: "/__airship/fonts" },
+ ],
+
+ stories: ["../src/**/*.stories.ts"],
+};
+
+export default config;
diff --git a/packages/overlay/.storybook/preview.ts b/packages/overlay/.storybook/preview.ts
new file mode 100644
index 0000000..c525b85
--- /dev/null
+++ b/packages/overlay/.storybook/preview.ts
@@ -0,0 +1,247 @@
+import type { Preview } from "@storybook/html-vite";
+import { PREFIX } from "../src/dom";
+import { closeOpenPopover, mountPopoverHost } from "../src/popover-host";
+import { setCaptionsEnabled } from "../src/stories/captions";
+import { runStoryTeardown } from "../src/stories/lifecycle";
+import { overlayCss } from "../src/styles";
+import { setRuntimeTokens, setStaticTokens } from "../src/tokens/registry";
+
+/*
+ * What every story needs around it before it can be looked at honestly.
+ *
+ * Each of the four things below is a *silent* failure if skipped: nothing
+ * throws, the story renders, and what you are looking at is wrong. That is the
+ * whole reason they are here rather than in each story.
+ */
+
+/**
+ * The overlay stylesheet, as one tag, re-written in place.
+ *
+ * Deliberately not `injectStyles()`. That function guards on a module-level
+ * `injected` flag, and Vite resets module state on HMR — so editing any
+ * `styles/*.css.ts` clears the flag and appends a *second*
+ * `` +
+ (wrap === "none" ? body : `
${body}
`);
+
+ const node = page.querySelector("[data-subject]");
+ if (!node) {
+ throw new Error(
+ `Specimen "${name}" declares no [data-subject] node — the marker is how a ` +
+ "story says which element it is about. See stories/subjects.ts."
+ );
+ }
+ return { node, page };
+}
+
+/** One specimen in the story's own document. */
+export function subject(name: SubjectName): Subject {
+ return buildSpecimenIn(document, name);
+}
+
+// ---------------------------------------------------------------------------
+// The cross-realm case
+// ---------------------------------------------------------------------------
+
+/** A subject in its own document, plus the `Surface` that describes it. */
+export interface FrameSubject extends Subject {
+ surface: Surface;
+}
+
+/**
+ * An empty frame, and the function that fills it once it has been mounted.
+ *
+ * Two steps rather than one, and the reason is a browser rule with teeth:
+ * **moving an iframe in the DOM reloads it.** A frame written to while it is
+ * still detached — or while it sits somewhere other than where the story will
+ * finally put it — is wiped the moment Storybook appends the story to the
+ * canvas, and what is left is a blank white pane and a `Surface` pointing at a
+ * document that no longer exists. Nothing throws; the panel simply reads an
+ * empty page and reports it accurately.
+ *
+ * So `frame` goes into the story's DOM first, and `fill` runs after Storybook
+ * has mounted it.
+ */
+export interface PendingFrame {
+ fill: (name: SubjectName) => FrameSubject;
+ frame: HTMLIFrameElement;
+}
+
+/**
+ * The same specimens, in their own document, with a `Surface` pointed at them.
+ *
+ * This exists for one specific and non-obvious reason. `stubSurface()` in
+ * `test-support.ts` returns `doc: document` — which under happy-dom is a clean
+ * empty document, and in Storybook is the *preview iframe*, carrying Storybook's
+ * own stylesheets. `matchedRules` walks `doc.styleSheets`, and `isOwnSheet` skips
+ * the overlay's sheet but knows nothing about Storybook's. So a CSS-pane story on
+ * a same-document subject would list Storybook's reset as the element's
+ * provenance, which is worse than useless: it is a plausible wrong answer.
+ *
+ * Putting the subject in its own document fixes it exactly, and does so by being
+ * more faithful rather than less — this is the production topology. In canvas
+ * mode the app runs in frame iframes while the overlay runs in the shell, which
+ * is why `realm.ts` exists at all. The panel resolves `getComputedStyle` against
+ * the node's own window and duck-types its `instanceof` checks, so it handles
+ * this natively.
+ */
+export function pendingFrame(): PendingFrame {
+ const frame = document.createElement("iframe");
+ // Named, because the a11y pass checks `frame-title` and an unnamed frame is a
+ // real finding rather than a harness artefact — the canvas frames want one too.
+ frame.title = "The page being inspected";
+ frame.style.cssText =
+ "width: 100%; height: 100%; min-height: 420px; border: 0; background: #fff;";
+
+ const fill = (name: SubjectName): FrameSubject => {
+ const doc = frame.contentDocument;
+ const win = frame.contentWindow;
+ if (!(doc && win)) {
+ throw new Error("iframe has no document — was it mounted first?");
+ }
+ // `document.write` rather than `srcdoc`: srcdoc loads asynchronously, and
+ // the caller needs the subject measurable in the same tick it is handed
+ // back so the panel can seed from a real box.
+ doc.open();
+ doc.write("");
+ doc.close();
+
+ const built = buildSpecimenIn(doc, name);
+ doc.body.style.margin = "0";
+ doc.body.style.padding = "24px";
+ doc.body.append(built.page);
+
+ return { ...built, surface: frameSurface(frame, doc, win) };
+ };
+
+ return { fill, frame };
+}
+
+/**
+ * A `Surface` over one frame.
+ *
+ * Only the members the panel actually reaches for are real; the rest answer
+ * honestly for a static, unzoomed frame. This mirrors `stubSurface()`'s approach
+ * and its rationale — implement what is used, and let the type document the
+ * rest — but differs in the one member that matters here, `doc`.
+ */
+function frameSurface(
+ frame: HTMLIFrameElement,
+ doc: Document,
+ win: Window
+): Surface {
+ const offset = () => frame.getBoundingClientRect();
+ return {
+ bounds: () => {
+ const r = offset();
+ return { height: r.height, left: r.left, top: r.top, width: r.width };
+ },
+ doc,
+ elementAtScreen: (point) => {
+ const r = offset();
+ return doc.elementFromPoint(point.x - r.left, point.y - r.top);
+ },
+ extract: (target: Element) =>
+ Promise.resolve({
+ context: contextOf(target) as ElementContext,
+ source: null,
+ }),
+ id: "story-frame",
+ isLive: true,
+ // 1:1 — the canvas zoom is a separate concern and none of these stories
+ // exercise it. A scaled frame would need `toScreen`/`toLocal` to multiply.
+ scale: 1,
+ scanTokens: () => ({ framework: "unknown", tokens: [] }),
+ toLocal: (point) => {
+ const r = offset();
+ return { x: point.x - r.left, y: point.y - r.top };
+ },
+ toScreen: (rect) => {
+ const r = offset();
+ return { ...rect, left: rect.left + r.left, top: rect.top + r.top };
+ },
+ win,
+ };
+}
diff --git a/packages/overlay/vitest.browser.config.ts b/packages/overlay/vitest.browser.config.ts
new file mode 100644
index 0000000..9170190
--- /dev/null
+++ b/packages/overlay/vitest.browser.config.ts
@@ -0,0 +1,57 @@
+import { storybookTest } from "@storybook/addon-vitest/vitest-plugin";
+import { playwright } from "@vitest/browser-playwright";
+import { defineConfig } from "vitest/config";
+
+/*
+ * The browser tier: every story, run as a test, in real Chromium.
+ *
+ * ## Why this is a second file rather than a `projects` array
+ *
+ * The obvious shape is one `vitest.config.ts` with two projects — happy-dom for
+ * the unit tests, a browser project for the stories. It is the wrong shape here
+ * for a reason outside vitest entirely: `.husky/pre-commit` runs `pnpm test`,
+ * which reaches `vitest run` with no project filter, which would run *both*.
+ * Every commit would launch Chromium, and on a machine that has not downloaded
+ * it the hook would fail and block the commit. This repo has no CI — `make
+ * check` is documented in the Makefile as "what CI should run" — so that hook is
+ * the only gate there is, and making it depend on a browser download is a bad
+ * trade for a catalogue.
+ *
+ * Separate file, separate script, separate turbo task, not wired into `test`.
+ * `make test-browser` opts in; `make browsers` fetches the browser.
+ *
+ * ## What it adds that the unit suite cannot
+ *
+ * `vitest.config.ts`'s own docstring, and `inspector/test-support.ts`'s, both
+ * list what happy-dom cannot do: no layout, no native CSS nesting, `@layer`
+ * dropped entirely, no `CSSStyleDeclaration` iterator. Those are the four things
+ * the inspector reads. Here they are real — which makes this the complement to
+ * the unit suite rather than a second copy of it.
+ *
+ * Every story becomes a smoke test that it renders without throwing, every
+ * `play` function becomes an interaction test, and the `a11y` parameter in
+ * `preview.ts` makes an axe violation fail the run rather than merely appear in
+ * a panel.
+ *
+ * ## What is deliberately absent
+ *
+ * No `test.include`: `main.ts`'s `stories` glob is the single index, and passing
+ * one here is ignored with a warning. No `setupFiles` either — since Storybook
+ * 10.3 the plugin applies `preview.ts`'s annotations itself, and a hand-rolled
+ * `setProjectAnnotations` now conflicts with that rather than enabling it. The
+ * risk that setup file was guarding against — stories running *without* the
+ * decorator, rendering unstyled, and passing anyway — is covered instead by the
+ * `play` assertions on `Foundations/Tokens`, which check the token scope and the
+ * fonts from inside the run.
+ */
+export default defineConfig({
+ plugins: [storybookTest({ configDir: ".storybook" })],
+ test: {
+ browser: {
+ enabled: true,
+ headless: true,
+ instances: [{ browser: "chromium" }],
+ provider: playwright(),
+ },
+ },
+});