@variance-authority/storybook-collector 0.1.0

package/dist/page-agent.d.ts

@@ -0,0 +1,96 @@
+import type { SuspenseSettlement } from '@variance-authority/react';
+import type { RawCapture, RenderDocument, Viewport } from '@variance-authority/core';
+/**
+ * The browser half, shipped rather than written by each adopter.
+ *
+ * This is the file the design said could not be generic, and most of it was
+ * right: mounting a project's components needs the project's bundle, its
+ * providers and its own idea of settled. What makes Storybook the exception is
+ * that it *already solved that* — the preview owns the mount, and the collector's
+ * remaining job is to read a subtree that is already on screen. Nothing here
+ * knows what a `Button` is.
+ *
+ * `acquire` returns both products of **one** mount. Two mounts would be two
+ * renders, and any disagreement between the image and the names attached to it
+ * would be a story about which of them was looking at what.
+ */
+export interface AcquireRequest {
+    readonly subjectId: string;
+    readonly viewport: Viewport;
+    readonly engine: string;
+    readonly fonts?: readonly string[];
+    /**
+     * Subtrees this run excludes, as `(rule id, selector)` pairs (spec 0024).
+     *
+     * Carried into the page because a selector needs a document, and the document
+     * is here. What comes back is a *mark* on the capture, never a deletion — the
+     * counts downstream must be able to say that a difference was absorbed rather
+     * than that it never happened.
+     */
+    readonly ignore?: readonly {
+        readonly id: string;
+        readonly select: string;
+    }[];
+    /**
+     * Stabilization tricks to hold the page still with, by id.
+     *
+     * Absent means `COLLECT_RECIPE` — the default is *on*, because a suite that
+     * has to ask for determinism is a suite that discovers it needed it from a
+     * red build. Ids rather than interventions because this value crosses a
+     * `page.evaluate`, and a trick with a `settle` step is a closure that does
+     * not survive the trip; the page holds the same registry and resolves them.
+     */
+    readonly stabilize?: readonly string[];
+    /**
+     * Every asset the *page* has been observed to fetch, by URL.
+     *
+     * Sent in whole and narrowed here, because neither side can do it alone: the
+     * driver is the only party that saw the bytes, and this is the only party that
+     * knows which of them the subject references. Narrowing matters most where the
+     * page is shared — a Storybook run reads three hundred stories out of one
+     * document, and a key built from the page's request history would depend on
+     * which stories ran first, so sharding the suite would change every baseline's
+     * identity.
+     */
+    readonly assets?: Readonly<Record<string, string>>;
+    /**
+     * How long to wait for the story's Suspense boundaries, in milliseconds.
+     *
+     * Storybook's own readiness cannot answer this. `storyRendered` fires when the
+     * story function returns, and a component that suspends has returned — it is
+     * the boundary above it that is showing something else. `0` waits for nothing
+     * and is what a story deliberately captured mid-arrival sends.
+     */
+    readonly suspense?: {
+        readonly timeoutMs?: number;
+    };
+    /** Story mount points, tightest first. */
+    readonly roots: readonly string[];
+}
+export interface Acquired {
+    readonly document: RenderDocument;
+    readonly capture: RawCapture;
+    /**
+     * Tricks actually applied before the subject was read, by id.
+     *
+     * Sent back rather than assumed, because what the driver asked for and what
+     * the page could do are different lists: the recipe is filtered by the tier
+     * the host can observe. A run that printed its *request* would be declaring
+     * something that may not have happened, which is the failure contract 2 exists
+     * to prevent — and this is the one alteration the tool makes to somebody
+     * else's page.
+     */
+    readonly stabilization: readonly string[];
+    /**
+     * Whether the story had finished arriving, and what was still waiting.
+     *
+     * Reported rather than acted on here, for the reason every other judgement
+     * leaves this file: the page can see the boundary and only the run knows
+     * whether this story is one somebody declared a loading capture. What comes
+     * back is the reading; `suspenseRefusal` on the driver turns it into a verdict.
+     */
+    readonly suspense: SuspenseSettlement;
+}
+export declare function acquire(request: AcquireRequest): Promise<string>;
+export declare const AGENT_VERSION = "storybook-collector@0";
+//# sourceMappingURL=page-agent.d.ts.map

package/dist/page-agent.js

@@ -0,0 +1,60 @@
+import { acquireDocument, assetsFor, collect, stabilizeForObservation, } from '@variance-authority/dom';
+import { awaitSuspense, portalContentOf, provenanceOf } from '@variance-authority/react';
+import { recipeOf } from '@variance-authority/core';
+/**
+ * The story's own mount point, never the preview body.
+ *
+ * Storybook's chrome — the preview reset, the addon layout, the error overlay —
+ * lives outside `#storybook-root`, so acquiring from the root element is what
+ * keeps it out of the subject. Nothing here holds a denylist for it, and that is
+ * ADR-0003 working: a rule that matches nothing inside the subtree is pruned
+ * because it matches nothing, not because somebody listed it.
+ */
+function rootOf(selectors) {
+    for (const selector of selectors) {
+        const found = window.document.querySelector(selector);
+        if (found !== null)
+            return found;
+    }
+    throw new Error(`no story root among ${selectors.join(', ')}`);
+}
+export async function acquire(request) {
+    const root = rootOf(request.roots);
+    // First of everything, because it decides what the rest of it is looking at.
+    // The story has rendered by Storybook's definition and may still be a
+    // skeleton: a component that suspends *has* returned, and what is on screen is
+    // the boundary above it. Ahead of stabilization deliberately — content that
+    // arrives late brings its own images and fonts, and a `waitForImages` that ran
+    // before them waited for the fallback's.
+    const suspense = await awaitSuspense(root, request.suspense ?? {});
+    // Before anything is read, and by default. An animation in flight moves
+    // `transform` and `opacity`, both of which the semantic representation
+    // carries — so an unstabilized collection reports a fade as a regression with
+    // a component and a file attached. See `docs/stabilization.md`.
+    const held = await stabilizeForObservation(root.ownerDocument, request.stabilize === undefined ? {} : { recipe: recipeOf(request.stabilize) });
+    // Narrowed to this story's own subtree before it reaches either key. See
+    // `AcquireRequest.assets`.
+    const assets = request.assets === undefined ? {} : assetsFor(root, request.assets);
+    const shared = {
+        subject: { id: request.subjectId, kind: 'story' },
+        viewport: request.viewport,
+        ...(request.fonts !== undefined ? { fonts: request.fonts } : {}),
+        ...(Object.keys(assets).length > 0 ? { assets } : {}),
+    };
+    // The style index is built once and handed to both, which is not only a
+    // saving: two indexes built either side of a lazily-inserted `<style>` would
+    // describe two different documents, and the run would compare an image of one
+    // against the names of the other.
+    const document = { ...acquireDocument(root, shared), baseUrl: root.ownerDocument.baseURI };
+    const capture = collect(root, {
+        ...shared,
+        engine: request.engine,
+        portalsOf: portalContentOf,
+        provenanceOf,
+        ...(held.digest !== undefined ? { stabilization: held.digest } : {}),
+        ...(request.ignore !== undefined ? { ignore: request.ignore } : {}),
+    });
+    return JSON.stringify({ document, capture, stabilization: held.ids, suspense });
+}
+export const AGENT_VERSION = 'storybook-collector@0';
+//# sourceMappingURL=page-agent.js.map

package/dist/page-agent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"page-agent.js","sourceRoot":"","sources":["../src/page-agent.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  acquireDocument,\n  assetsFor,\n  collect,\n  stabilizeForObservation,\n} from '@variance-authority/dom';\nimport { awaitSuspense, portalContentOf, provenanceOf } from '@variance-authority/react';\nimport type { SuspenseSettlement } from '@variance-authority/react';\nimport { recipeOf } from '@variance-authority/core';\nimport type { RawCapture, RenderDocument, Viewport } from '@variance-authority/core';\n\n/**\n * The browser half, shipped rather than written by each adopter.\n *\n * This is the file the design said could not be generic, and most of it was\n * right: mounting a project's components needs the project's bundle, its\n * providers and its own idea of settled. What makes Storybook the exception is\n * that it *already solved that* — the preview owns the mount, and the collector's\n * remaining job is to read a subtree that is already on screen. Nothing here\n * knows what a `Button` is.\n *\n * `acquire` returns both products of **one** mount. Two mounts would be two\n * renders, and any disagreement between the image and the names attached to it\n * would be a story about which of them was looking at what.\n */\n\nexport interface AcquireRequest {\n  readonly subjectId: string;\n  readonly viewport: Viewport;\n  readonly engine: string;\n  readonly fonts?: readonly string[];\n\n  /**\n   * Subtrees this run excludes, as `(rule id, selector)` pairs (spec 0024).\n   *\n   * Carried into the page because a selector needs a document, and the document\n   * is here. What comes back is a *mark* on the capture, never a deletion — the\n   * counts downstream must be able to say that a difference was absorbed rather\n   * than that it never happened.\n   */\n  readonly ignore?: readonly { readonly id: string; readonly select: string }[];\n  /**\n   * Stabilization tricks to hold the page still with, by id.\n   *\n   * Absent means `COLLECT_RECIPE` — the default is *on*, because a suite that\n   * has to ask for determinism is a suite that discovers it needed it from a\n   * red build. Ids rather than interventions because this value crosses a\n   * `page.evaluate`, and a trick with a `settle` step is a closure that does\n   * not survive the trip; the page holds the same registry and resolves them.\n   */\n  readonly stabilize?: readonly string[];\n\n  /**\n   * Every asset the *page* has been observed to fetch, by URL.\n   *\n   * Sent in whole and narrowed here, because neither side can do it alone: the\n   * driver is the only party that saw the bytes, and this is the only party that\n   * knows which of them the subject references. Narrowing matters most where the\n   * page is shared — a Storybook run reads three hundred stories out of one\n   * document, and a key built from the page's request history would depend on\n   * which stories ran first, so sharding the suite would change every baseline's\n   * identity.\n   */\n  readonly assets?: Readonly<Record<string, string>>;\n\n  /**\n   * How long to wait for the story's Suspense boundaries, in milliseconds.\n   *\n   * Storybook's own readiness cannot answer this. `storyRendered` fires when the\n   * story function returns, and a component that suspends has returned — it is\n   * the boundary above it that is showing something else. `0` waits for nothing\n   * and is what a story deliberately captured mid-arrival sends.\n   */\n  readonly suspense?: { readonly timeoutMs?: number };\n\n  /** Story mount points, tightest first. */\n  readonly roots: readonly string[];\n}\n\nexport interface Acquired {\n  readonly document: RenderDocument;\n  readonly capture: RawCapture;\n\n  /**\n   * Tricks actually applied before the subject was read, by id.\n   *\n   * Sent back rather than assumed, because what the driver asked for and what\n   * the page could do are different lists: the recipe is filtered by the tier\n   * the host can observe. A run that printed its *request* would be declaring\n   * something that may not have happened, which is the failure contract 2 exists\n   * to prevent — and this is the one alteration the tool makes to somebody\n   * else's page.\n   */\n  readonly stabilization: readonly string[];\n\n  /**\n   * Whether the story had finished arriving, and what was still waiting.\n   *\n   * Reported rather than acted on here, for the reason every other judgement\n   * leaves this file: the page can see the boundary and only the run knows\n   * whether this story is one somebody declared a loading capture. What comes\n   * back is the reading; `suspenseRefusal` on the driver turns it into a verdict.\n   */\n  readonly suspense: SuspenseSettlement;\n}\n\n/**\n * The story's own mount point, never the preview body.\n *\n * Storybook's chrome — the preview reset, the addon layout, the error overlay —\n * lives outside `#storybook-root`, so acquiring from the root element is what\n * keeps it out of the subject. Nothing here holds a denylist for it, and that is\n * ADR-0003 working: a rule that matches nothing inside the subtree is pruned\n * because it matches nothing, not because somebody listed it.\n */\nfunction rootOf(selectors: readonly string[]): Element {\n  for (const selector of selectors) {\n    const found = window.document.querySelector(selector);\n    if (found !== null) return found;\n  }\n  throw new Error(`no story root among ${selectors.join(', ')}`);\n}\n\nexport async function acquire(request: AcquireRequest): Promise<string> {\n  const root = rootOf(request.roots);\n\n  // First of everything, because it decides what the rest of it is looking at.\n  // The story has rendered by Storybook's definition and may still be a\n  // skeleton: a component that suspends *has* returned, and what is on screen is\n  // the boundary above it. Ahead of stabilization deliberately — content that\n  // arrives late brings its own images and fonts, and a `waitForImages` that ran\n  // before them waited for the fallback's.\n  const suspense = await awaitSuspense(root, request.suspense ?? {});\n\n  // Before anything is read, and by default. An animation in flight moves\n  // `transform` and `opacity`, both of which the semantic representation\n  // carries — so an unstabilized collection reports a fade as a regression with\n  // a component and a file attached. See `docs/stabilization.md`.\n  const held = await stabilizeForObservation(\n    root.ownerDocument,\n    request.stabilize === undefined ? {} : { recipe: recipeOf(request.stabilize) },\n  );\n\n  // Narrowed to this story's own subtree before it reaches either key. See\n  // `AcquireRequest.assets`.\n  const assets = request.assets === undefined ? {} : assetsFor(root, request.assets);\n\n  const shared = {\n    subject: { id: request.subjectId, kind: 'story' as const },\n    viewport: request.viewport,\n    ...(request.fonts !== undefined ? { fonts: request.fonts } : {}),\n    ...(Object.keys(assets).length > 0 ? { assets } : {}),\n  };\n\n  // The style index is built once and handed to both, which is not only a\n  // saving: two indexes built either side of a lazily-inserted `<style>` would\n  // describe two different documents, and the run would compare an image of one\n  // against the names of the other.\n  const document = { ...acquireDocument(root, shared), baseUrl: root.ownerDocument.baseURI };\n  const capture = collect(root, {\n    ...shared,\n    engine: request.engine,\n    portalsOf: portalContentOf,\n    provenanceOf,\n    ...(held.digest !== undefined ? { stabilization: held.digest } : {}),\n    ...(request.ignore !== undefined ? { ignore: request.ignore } : {}),\n  });\n\n  return JSON.stringify({ document, capture, stabilization: held.ids, suspense });\n}\n\nexport const AGENT_VERSION = 'storybook-collector@0';\n"]}

package/dist/serve.d.ts

@@ -0,0 +1,6 @@
+export interface StaticServer {
+    readonly baseUrl: string;
+    close(): Promise<void>;
+}
+export declare function serveStatic(root: string): Promise<StaticServer>;
+//# sourceMappingURL=serve.d.ts.map

package/dist/serve.js

@@ -0,0 +1,66 @@
+import { createServer } from 'node:http';
+import { existsSync, readFileSync } from 'node:fs';
+import { extname, join, normalize } from 'node:path';
+/**
+ * A static server for a built Storybook, because `file://` will not do.
+ *
+ * Not an accident of convenience and not something an adapter can skip: the
+ * preview fetches its own index and lazily imports story chunks, and both are
+ * blocked by `file://` origin rules. A Storybook that is *already served* needs
+ * none of this — see `baseUrl` — and that is the arrangement to prefer, because
+ * then nothing here has an opinion about how the build is hosted.
+ */
+const TYPES = {
+    '.html': 'text/html; charset=utf-8',
+    '.js': 'text/javascript; charset=utf-8',
+    '.mjs': 'text/javascript; charset=utf-8',
+    '.json': 'application/json; charset=utf-8',
+    '.css': 'text/css; charset=utf-8',
+    '.map': 'application/json; charset=utf-8',
+    '.woff': 'font/woff',
+    '.woff2': 'font/woff2',
+    '.ttf': 'font/ttf',
+    '.svg': 'image/svg+xml',
+    '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.gif': 'image/gif',
+    '.webp': 'image/webp',
+    '.avif': 'image/avif',
+    '.ico': 'image/x-icon',
+};
+export async function serveStatic(root) {
+    const server = createServer((request, response) => {
+        const path = decodeURIComponent((request.url ?? '/').split('?')[0] ?? '/');
+        const resolved = join(root, normalize(path === '/' ? '/index.html' : path));
+        // Containment before existence: a request that escapes the root must be
+        // refused rather than answered, and answering it 404 when it happens to miss
+        // would make the refusal depend on what is on disk.
+        if (!resolved.startsWith(root) || !existsSync(resolved)) {
+            response.writeHead(404).end('not found');
+            return;
+        }
+        response.writeHead(200, {
+            'content-type': TYPES[extname(resolved)] ?? 'application/octet-stream',
+        });
+        response.end(readFileSync(resolved));
+    });
+    const port = await new Promise((resolve) => {
+        server.listen(0, '127.0.0.1', () => {
+            const address = server.address();
+            resolve(address === null || typeof address === 'string' ? 0 : address.port);
+        });
+    });
+    return {
+        baseUrl: `http://127.0.0.1:${port}`,
+        async close() {
+            // `close` alone waits for open connections to drain, and a browser that has
+            // just been killed does not always get to send its FIN — so the callback
+            // never fires and a run that produced a correct report hangs on exit. The
+            // sockets are ours and the browser is gone; ending them races nothing.
+            server.closeAllConnections();
+            await new Promise((resolve) => server.close(() => resolve()));
+        },
+    };
+}
+//# sourceMappingURL=serve.js.map

package/dist/serve.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"serve.js","sourceRoot":"","sources":["../src/serve.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAe,MAAM,WAAW,CAAC;AACtD,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAErD;;;;;;;;GAQG;AAEH,MAAM,KAAK,GAAqC;IAC9C,OAAO,EAAE,0BAA0B;IACnC,KAAK,EAAE,gCAAgC;IACvC,MAAM,EAAE,gCAAgC;IACxC,OAAO,EAAE,iCAAiC;IAC1C,MAAM,EAAE,yBAAyB;IACjC,MAAM,EAAE,iCAAiC;IACzC,OAAO,EAAE,WAAW;IACpB,QAAQ,EAAE,YAAY;IACtB,MAAM,EAAE,UAAU;IAClB,MAAM,EAAE,eAAe;IACvB,MAAM,EAAE,WAAW;IACnB,MAAM,EAAE,YAAY;IACpB,OAAO,EAAE,YAAY;IACrB,MAAM,EAAE,WAAW;IACnB,OAAO,EAAE,YAAY;IACrB,OAAO,EAAE,YAAY;IACrB,MAAM,EAAE,cAAc;CACvB,CAAC;AAOF,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,IAAY;IAC5C,MAAM,MAAM,GAAW,YAAY,CAAC,CAAC,OAAO,EAAE,QAAQ,EAAE,EAAE;QACxD,MAAM,IAAI,GAAG,kBAAkB,CAAC,CAAC,OAAO,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC;QAC3E,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,EAAE,SAAS,CAAC,IAAI,KAAK,GAAG,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;QAE5E,wEAAwE;QACxE,6EAA6E;QAC7E,oDAAoD;QACpD,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;YACxD,QAAQ,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;YACzC,OAAO;QACT,CAAC;QAED,QAAQ,CAAC,SAAS,CAAC,GAAG,EAAE;YACtB,cAAc,EAAE,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,IAAI,0BAA0B;SACvE,CAAC,CAAC;QACH,QAAQ,CAAC,GAAG,CAAC,YAAY,CAAC,QAAQ,CAAC,CAAC,CAAC;IACvC,CAAC,CAAC,CAAC;IAEH,MAAM,IAAI,GAAG,MAAM,IAAI,OAAO,CAAS,CAAC,OAAO,EAAE,EAAE;QACjD,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,WAAW,EAAE,GAAG,EAAE;YACjC,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,EAAE,CAAC;YACjC,OAAO,CAAC,OAAO,KAAK,IAAI,IAAI,OAAO,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QAC9E,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,OAAO;QACL,OAAO,EAAE,oBAAoB,IAAI,EAAE;QACnC,KAAK,CAAC,KAAK;YACT,4EAA4E;YAC5E,yEAAyE;YACzE,0EAA0E;YAC1E,uEAAuE;YACvE,MAAM,CAAC,mBAAmB,EAAE,CAAC;YAC7B,MAAM,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;QACtE,CAAC;KACF,CAAC;AACJ,CAAC","sourcesContent":["import { createServer, type Server } from 'node:http';\nimport { existsSync, readFileSync } from 'node:fs';\nimport { extname, join, normalize } from 'node:path';\n\n/**\n * A static server for a built Storybook, because `file://` will not do.\n *\n * Not an accident of convenience and not something an adapter can skip: the\n * preview fetches its own index and lazily imports story chunks, and both are\n * blocked by `file://` origin rules. A Storybook that is *already served* needs\n * none of this — see `baseUrl` — and that is the arrangement to prefer, because\n * then nothing here has an opinion about how the build is hosted.\n */\n\nconst TYPES: Readonly<Record<string, string>> = {\n  '.html': 'text/html; charset=utf-8',\n  '.js': 'text/javascript; charset=utf-8',\n  '.mjs': 'text/javascript; charset=utf-8',\n  '.json': 'application/json; charset=utf-8',\n  '.css': 'text/css; charset=utf-8',\n  '.map': 'application/json; charset=utf-8',\n  '.woff': 'font/woff',\n  '.woff2': 'font/woff2',\n  '.ttf': 'font/ttf',\n  '.svg': 'image/svg+xml',\n  '.png': 'image/png',\n  '.jpg': 'image/jpeg',\n  '.jpeg': 'image/jpeg',\n  '.gif': 'image/gif',\n  '.webp': 'image/webp',\n  '.avif': 'image/avif',\n  '.ico': 'image/x-icon',\n};\n\nexport interface StaticServer {\n  readonly baseUrl: string;\n  close(): Promise<void>;\n}\n\nexport async function serveStatic(root: string): Promise<StaticServer> {\n  const server: Server = createServer((request, response) => {\n    const path = decodeURIComponent((request.url ?? '/').split('?')[0] ?? '/');\n    const resolved = join(root, normalize(path === '/' ? '/index.html' : path));\n\n    // Containment before existence: a request that escapes the root must be\n    // refused rather than answered, and answering it 404 when it happens to miss\n    // would make the refusal depend on what is on disk.\n    if (!resolved.startsWith(root) || !existsSync(resolved)) {\n      response.writeHead(404).end('not found');\n      return;\n    }\n\n    response.writeHead(200, {\n      'content-type': TYPES[extname(resolved)] ?? 'application/octet-stream',\n    });\n    response.end(readFileSync(resolved));\n  });\n\n  const port = await new Promise<number>((resolve) => {\n    server.listen(0, '127.0.0.1', () => {\n      const address = server.address();\n      resolve(address === null || typeof address === 'string' ? 0 : address.port);\n    });\n  });\n\n  return {\n    baseUrl: `http://127.0.0.1:${port}`,\n    async close() {\n      // `close` alone waits for open connections to drain, and a browser that has\n      // just been killed does not always get to send its FIN — so the callback\n      // never fires and a run that produced a correct report hangs on exit. The\n      // sockets are ours and the browser is gone; ending them races nothing.\n      server.closeAllConnections();\n      await new Promise<void>((resolve) => server.close(() => resolve()));\n    },\n  };\n}\n"]}

package/dist/source.d.ts

@@ -0,0 +1,25 @@
+import { type SourceIndex } from '@variance-authority/core';
+/**
+ * Component to `file:line`, by scanning the project's own source.
+ *
+ * A regex scan rather than a plugin, and the reason is the same one the whole
+ * project keeps arriving at: an index built from the source that shipped is a
+ * fact about the repository, while an index built by a build step is a fact
+ * about a build somebody has to keep configured. `resolveSource` is the last hop
+ * of attribution, so getting it from the cheapest possible place is what makes
+ * `file:line` free rather than a feature.
+ *
+ * **Directories, not globs.** A glob syntax is a small language with its own
+ * bugs, and the question here is only *which files hold components* — which a
+ * directory and a set of extensions answers. Nothing is installed to ask it.
+ */
+export interface SourceScan {
+    /** Directories to walk, relative to `root` or absolute. */
+    readonly dirs: readonly string[];
+    /** Defaults to `.tsx`, `.jsx`, `.ts`, `.js`. */
+    readonly extensions?: readonly string[];
+    /** Skipped anywhere in a path. Defaults to tests, stories and `node_modules`. */
+    readonly exclude?: readonly string[];
+}
+export declare function scanSource(root: string, scan: SourceScan): SourceIndex;
+//# sourceMappingURL=source.d.ts.map

package/dist/source.js

@@ -0,0 +1,43 @@
+import { readFileSync, readdirSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import { indexSource, mergeSourceIndexes } from '@variance-authority/core';
+import { operatorError } from './operator.js';
+const EXTENSIONS = ['.tsx', '.jsx', '.ts', '.js'];
+const EXCLUDE = ['node_modules', '.test.', '.spec.', '.stories.', 'dist/', 'storybook-static'];
+function walk(dir, into) {
+    let entries;
+    try {
+        entries = readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        // A directory that is not there is a configuration mistake worth reporting,
+        // and reporting it is `scanSource`'s job — it can say which of several was
+        // missing, and this one cannot.
+        return into;
+    }
+    for (const entry of entries) {
+        const path = join(dir, entry.name);
+        if (entry.isDirectory())
+            walk(path, into);
+        else
+            into.push(path);
+    }
+    return into;
+}
+export function scanSource(root, scan) {
+    const extensions = scan.extensions ?? EXTENSIONS;
+    const exclude = scan.exclude ?? EXCLUDE;
+    const files = scan.dirs
+        .flatMap((dir) => walk(join(root, dir), []))
+        .filter((file) => extensions.some((extension) => file.endsWith(extension)))
+        .filter((file) => !exclude.some((fragment) => file.includes(fragment)));
+    // Empty is reported rather than returned. An index with nothing in it produces
+    // a report whose every component resolves to no file — which reads exactly like
+    // a project whose components are anonymous, and is instead a mistyped path.
+    if (files.length === 0) {
+        throw operatorError(`no source files under ${scan.dirs.join(', ')} (from ${root}) matching ` +
+            `${extensions.join(', ')}; every component would resolve to no file`);
+    }
+    return mergeSourceIndexes(files.map((file) => indexSource(relative(root, file), readFileSync(file, 'utf8'))));
+}
+//# sourceMappingURL=source.js.map

package/dist/source.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"source.js","sourceRoot":"","sources":["../src/source.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AACpD,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,EAAE,WAAW,EAAE,kBAAkB,EAAoB,MAAM,0BAA0B,CAAC;AAE7F,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AA0B9C,MAAM,UAAU,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC;AAClD,MAAM,OAAO,GAAG,CAAC,cAAc,EAAE,QAAQ,EAAE,QAAQ,EAAE,WAAW,EAAE,OAAO,EAAE,kBAAkB,CAAC,CAAC;AAE/F,SAAS,IAAI,CAAC,GAAW,EAAE,IAAc;IACvC,IAAI,OAAmD,CAAC;IACxD,IAAI,CAAC;QACH,OAAO,GAAG,WAAW,CAAC,GAAG,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;IACtD,CAAC;IAAC,MAAM,CAAC;QACP,4EAA4E;QAC5E,2EAA2E;QAC3E,gCAAgC;QAChC,OAAO,IAAI,CAAC;IACd,CAAC;IAED,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;QACnC,IAAI,KAAK,CAAC,WAAW,EAAE;YAAE,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;;YACrC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACvB,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,IAAY,EAAE,IAAgB;IACvD,MAAM,UAAU,GAAG,IAAI,CAAC,UAAU,IAAI,UAAU,CAAC;IACjD,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,IAAI,OAAO,CAAC;IAExC,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI;SACpB,OAAO,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,GAAG,CAAC,EAAE,EAAE,CAAC,CAAC;SAC3C,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,CAAC;SAC1E,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;IAE1E,+EAA+E;IAC/E,gFAAgF;IAChF,4EAA4E;IAC5E,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvB,MAAM,aAAa,CACjB,yBAAyB,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,IAAI,aAAa;YACtE,GAAG,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,4CAA4C,CACvE,CAAC;IACJ,CAAC;IAED,OAAO,kBAAkB,CACvB,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,WAAW,CAAC,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,CACnF,CAAC;AACJ,CAAC","sourcesContent":["import { readFileSync, readdirSync } from 'node:fs';\nimport { join, relative } from 'node:path';\nimport { indexSource, mergeSourceIndexes, type SourceIndex } from '@variance-authority/core';\n\nimport { operatorError } from './operator.js';\n\n/**\n * Component to `file:line`, by scanning the project's own source.\n *\n * A regex scan rather than a plugin, and the reason is the same one the whole\n * project keeps arriving at: an index built from the source that shipped is a\n * fact about the repository, while an index built by a build step is a fact\n * about a build somebody has to keep configured. `resolveSource` is the last hop\n * of attribution, so getting it from the cheapest possible place is what makes\n * `file:line` free rather than a feature.\n *\n * **Directories, not globs.** A glob syntax is a small language with its own\n * bugs, and the question here is only *which files hold components* — which a\n * directory and a set of extensions answers. Nothing is installed to ask it.\n */\n\nexport interface SourceScan {\n  /** Directories to walk, relative to `root` or absolute. */\n  readonly dirs: readonly string[];\n  /** Defaults to `.tsx`, `.jsx`, `.ts`, `.js`. */\n  readonly extensions?: readonly string[];\n  /** Skipped anywhere in a path. Defaults to tests, stories and `node_modules`. */\n  readonly exclude?: readonly string[];\n}\n\nconst EXTENSIONS = ['.tsx', '.jsx', '.ts', '.js'];\nconst EXCLUDE = ['node_modules', '.test.', '.spec.', '.stories.', 'dist/', 'storybook-static'];\n\nfunction walk(dir: string, into: string[]): string[] {\n  let entries: { name: string; isDirectory(): boolean }[];\n  try {\n    entries = readdirSync(dir, { withFileTypes: true });\n  } catch {\n    // A directory that is not there is a configuration mistake worth reporting,\n    // and reporting it is `scanSource`'s job — it can say which of several was\n    // missing, and this one cannot.\n    return into;\n  }\n\n  for (const entry of entries) {\n    const path = join(dir, entry.name);\n    if (entry.isDirectory()) walk(path, into);\n    else into.push(path);\n  }\n  return into;\n}\n\nexport function scanSource(root: string, scan: SourceScan): SourceIndex {\n  const extensions = scan.extensions ?? EXTENSIONS;\n  const exclude = scan.exclude ?? EXCLUDE;\n\n  const files = scan.dirs\n    .flatMap((dir) => walk(join(root, dir), []))\n    .filter((file) => extensions.some((extension) => file.endsWith(extension)))\n    .filter((file) => !exclude.some((fragment) => file.includes(fragment)));\n\n  // Empty is reported rather than returned. An index with nothing in it produces\n  // a report whose every component resolves to no file — which reads exactly like\n  // a project whose components are anonymous, and is instead a mistyped path.\n  if (files.length === 0) {\n    throw operatorError(\n      `no source files under ${scan.dirs.join(', ')} (from ${root}) matching ` +\n        `${extensions.join(', ')}; every component would resolve to no file`,\n    );\n  }\n\n  return mergeSourceIndexes(\n    files.map((file) => indexSource(relative(root, file), readFileSync(file, 'utf8'))),\n  );\n}\n"]}

package/mark.svg

@@ -0,0 +1,30 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 320" role="img" aria-labelledby="title desc">
+  <title id="title">Variance Authority mark</title>
+  <desc id="desc">Folded ribbon VA mark in charcoal and orange.</desc>
+
+  <defs>
+    <style>
+      .ribbon-dark {
+        fill: #24282A;
+      }
+
+      @media (prefers-color-scheme: dark) {
+        .ribbon-dark {
+          fill: #F3F4F6;
+        }
+      }
+    </style>
+  </defs>
+
+  <!-- Left descending ribbon -->
+  <path class="ribbon-dark" d="M64 54H159L256 266H160Z"/>
+
+  <!-- Right descending ribbon -->
+  <path class="ribbon-dark" d="M331 28H419L494 266H397Z"/>
+
+  <!-- Chosen / variant ribbon -->
+  <path d="M256 266L202 152L283 28H376L301 165Z" fill="#FF4A19"/>
+
+  <!-- Fold shadow -->
+  <path d="M202 152L256 266L301 165L264 103Z" fill="#D83A13" opacity="0.72"/>
+</svg>

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@variance-authority/storybook-collector",
+  "version": "0.1.0",
+  "description": "Turn a built or already-served Storybook into Variance Authority subjects.",
+  "keywords": [
+    "variance-authority",
+    "visual-regression",
+    "visual-testing",
+    "storybook",
+    "component-testing",
+    "stories"
+  ],
+  "license": "MIT",
+  "author": "Machine Garden",
+  "homepage": "https://variance-authority.dev#packages",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Variance-Authority/variance-authority.git",
+    "directory": "packages/storybook-collector"
+  },
+  "bugs": "https://github.com/Variance-Authority/variance-authority/issues",
+  "engines": {
+    "node": ">=22"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "!dist/**/*.d.ts.map",
+    "mark.svg"
+  ],
+  "scripts": {
+    "build": "tsc --build"
+  },
+  "dependencies": {
+    "@variance-authority/core": "^0.1.0",
+    "@variance-authority/dom": "^0.1.0",
+    "@variance-authority/playwright": "^0.1.0",
+    "@variance-authority/react": "^0.1.0",
+    "@variance-authority/sense": "^0.1.0",
+    "@variance-authority/storybook": "^0.1.0"
+  }
+}