@variance-authority/storybook-collector 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,20 @@
+# @variance-authority/storybook-collector
+
+## 0.1.0
+
+### Patch Changes
+
+- Updated dependencies [9587133]
+- Updated dependencies [f800342]
+- Updated dependencies [26ae9ed]
+- Updated dependencies [f09528d]
+- Updated dependencies [cfb333d]
+- Updated dependencies [e8fee66]
+- Updated dependencies [48d32eb]
+- Updated dependencies [5c34e6d]
+  - @variance-authority/sense@0.1.0
+  - @variance-authority/dom@0.1.0
+  - @variance-authority/react@0.1.0
+  - @variance-authority/core@0.1.0
+  - @variance-authority/playwright@0.1.0
+  - @variance-authority/storybook@0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Machine Garden
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,224 @@
+<p align="center"><img src="./mark.svg" alt="Variance Authority mark" width="72"></p>
+
+# @variance-authority/storybook-collector
+
+> Turn a built or already-served Storybook into Variance Authority subjects.
+
+Turn a built or already-served Storybook into subjects that `variance run` can
+observe — one subject per story, the unit a comparison runs against. Use this
+package when Storybook already owns component mounting and you want
+source-attributed visual, semantic, accessibility, and localization findings
+without writing a browser harness.
+
+This is the Storybook adapter, not the `variance` binary. Pair it with
+`@variance-authority/cli`.
+
+```bash
+npm install --save-dev @variance-authority/cli @variance-authority/storybook-collector
+npx playwright install chromium
+```
+
+The second command is there because Playwright's browser binaries do not arrive
+with an `npm install`. The built `index.json` is the input, whether you build the
+Storybook or already serve it; `.storybook` configuration is not read.
+
+## Integrate a Storybook
+
+### 1. Build the artifact you want to observe
+
+The collector — the module you create in step 2 below — reads the artifact
+Storybook produced, so run your ordinary Storybook build first. A development
+server also works when you pass `baseUrl` below.
+
+### 2. Add a collector module
+
+Create a module in your project and default-export the collector factory. The
+only project-specific facts in the common path are where components live and
+which stories need an explicit readiness marker.
+
+```js
+// variance/storybook.mjs
+import { storybookCollector } from '@variance-authority/storybook-collector';
+
+export default storybookCollector({
+  ready: { 'checkout--deferred': '[data-testid="checkout-ready"]' },
+  source: { dirs: ['src'] },
+});
+```
+
+Omit `ready` for stories that are complete when Storybook emits
+`storyRendered`. Add an entry only when a story continues mounting or fetching
+after that signal. If the selector never appears, collection fails with the
+story id and selector instead of silently capturing a spinner.
+
+`source` enables component-to-`file:line` attribution. Without it the report can
+still name components, but it cannot point to their declarations.
+
+Against a built Storybook those names arrive minified — a run reports the cause
+as `Ce`, not `Button`, because the bundler renamed it and nothing in the browser
+remembers otherwise. `file:line` is the identifier that survives minification,
+which is what makes the plugin below load-bearing there rather than an
+enhancement.
+
+It names where a component is *declared* — one line however many times that
+component is rendered.
+
+For the line the changed element is actually written on: against a
+**development** Storybook, source locations work automatically — nothing to
+configure. Against a **built, minified** Storybook it needs the
+`@variance-authority/jsx-source` plugin in your `viteFinal` with
+`esbuild.jsxDev` on; a report prefers the exact location wherever it comes
+from, and this collector makes it repository-relative. The plugin does not
+take `jsxImportSource`, so a Storybook already compiling against Emotion or
+theme-ui keeps doing exactly that.
+
+```bash
+npm install --save-dev @variance-authority/jsx-source
+```
+
+### 3. Point the CLI at the Storybook index and collector
+
+In `variance.config.json`, the index is the built file and `collector` is the
+module you created:
+
+```json
+{
+  "project": "checkout-ui",
+  "profile": "chromium",
+  "viewport": { "width": 1280, "height": 800 },
+  "retention": "durable",
+  "subjects": {
+    "kind": "storybook",
+    "index": "storybook-static/index.json",
+    "collector": "variance/storybook.mjs"
+  },
+  "baselines": { "kind": "directory", "root": ".variance/baselines" },
+  "fonts": [],
+  "report": ".variance/report.json"
+}
+```
+
+### 4. Check the machine, then run
+
+```bash
+npx variance doctor --config variance.config.json
+npx variance run --config variance.config.json
+```
+
+Each run writes `.variance/report.json`, the artifact everything else reads.
+Run `npx variance report --config variance.config.json --format html >
+.variance/report.html` and open the result in a browser to see before/diff/after
+images per changed story, grouped by cause rather than by story. The page
+references its images relatively, so it belongs beside the `report` path this
+config declares; written anywhere else it shows broken images.
+
+The first successful run exits `1` and reports each story as `new`; a
+baseline — the stored snapshot a subject is compared against — nobody
+approved is not a pass. Review the candidates, accept the intended subjects,
+and run again. The next unchanged run exits `0` without re-rendering
+(*painting*) subjects whose stored document digest already proves they did
+not move.
+
+The executable `storybook-case` demonstrates the
+complete cycle against a Storybook-built artifact: new → accept → unchanged → a
+`Button` edit changing exactly the five stories that render it.
+
+## Options
+
+| Option | Use it when | Default and boundary |
+| --- | --- | --- |
+| `ready` | A particular story finishes after Storybook's render signal. | No additional wait. Keys are Storybook story ids. |
+| `readyTimeoutMs` | Storybook or a declared readiness marker legitimately needs longer to answer. | `15000`. A timeout is reported, never replaced by a fallback capture. |
+| `loading` | A story's *fallback* is the state you intend to review. | Omitted. Id globs, matched against the story id and the subject id. |
+| `suspenseTimeoutMs` | A story legitimately needs longer than five seconds to arrive. | `5000`. `0` skips the wait and keeps the reading. |
+| `source` | Reports should resolve component names to `file:line`. | Omitted; component names remain available. An empty or mistyped scan is refused. |
+| `baseUrl` | Storybook is already running. | Omitted; the directory containing `subjects.index` is served on loopback for the run. |
+| `headless` | You need to watch collection while debugging. | `true`; set `false` locally. |
+| `network` | Asset bytes at stable URLs must participate in render identity. | `true`; set `false` only when asset URLs are already content-addressed. |
+| `roots` | Your preview mounts somewhere other than the standard roots. | `['#storybook-root', '#root']`, tightest match first. |
+| `tests` | The next run should be able to skip stories whose code nothing touched. | `false`. Requires a preview built with `testSelectionProbes()` from `@variance-authority/sense/journal`; without a collector in the page the run says so on stderr and records nothing. |
+
+The package exports `StorybookCollectorOptions` plus the collector contract
+types (`Collector`, `CollectorContext`, `Plan`, `PlannedSubject`, and
+`Collected`) for callers that need to wrap the factory without re-declaring its
+boundary. `SourceScan`, `AcquireRequest`, and `Acquired` expose the corresponding
+source and page-agent shapes.
+
+`tests` accepts `true` or `StoryExecutionOptions`: `root` is the repository root
+the recorded paths are relative to, `label` must match the one the preview's
+`testSelectionProbes()` was given, and `modulesFile` and `coverageFile` override
+the repository-keyed cache paths for the block inventory and the coverage index. A
+story is its own owner in the recorded index — Storybook is an execution surface
+this tool drives one subject at a time — and a story that did not render still
+contributes its crossings while never justifying a later skip.
+
+The collector reads a built Storybook index and switches stories over
+Storybook's own preview channel, so a suite pays for one navigation rather than
+one navigation per story. Addon chrome remains outside the selected story root
+and does not enter the subject document.
+
+## Readiness and loading
+
+Before each story is read, the collector waits for every React Suspense boundary
+under the story root to settle. This runs first, ahead of stabilization — the
+step that pins in-flight CSS animations and transitions to a settled frame
+before anything is read — because content that arrives late brings its own
+images and fonts.
+
+`ready` cannot cover this case and no marker can: a component that suspends
+renders no markup for a selector to attach to, and Storybook's `storyRendered`
+has already fired — the story function returned. A story still showing a
+fallback when the wait runs out is reported as **not collected**, naming the open
+boundaries and the components that wrote them, rather than recorded as a
+baseline. A skeleton on a slow machine and the component on a fast one is a
+difference no one authored, and every band — the severity category, from
+accessibility down to sub-pixel noise, a change is filed under — agrees with
+both.
+
+Declare the exception when the fallback is the subject:
+
+```js
+export default storybookCollector({
+  loading: ['inbox--empty-state'],
+  source: { dirs: ['src'] },
+});
+```
+
+A declared story waits for nothing, and is refused if it turns out to have
+settled — a declaration that outlived its subject is the same nondeterminism from
+the other side.
+
+## When integration fails
+
+- **The index cannot be read:** build Storybook first and check
+  `subjects.index`. The collector reads `index.json`; it does not discover a
+  `.storybook` directory.
+- **A story times out:** verify the `ready` key is the Storybook story id and
+  that the selector is attached only after the intended UI is complete.
+- **A story is refused as still waiting:** the named Suspense boundary never
+  resolved. Fix what it awaits, or add the story to `loading` if the fallback is
+  what you intend to review.
+- **Components have names but no source lines:** add or correct `source.dirs`.
+  Production minification must also preserve component function names; the
+  worked case uses `esbuild.keepNames: true` for this reason.
+- **Elements report their component's declaration rather than their own line:**
+  against a built Storybook, the `jsx-source` plugin is not installed or
+  `esbuild.jsxDev` is off in the build that produced this artifact. Locations
+  survive minification, so it is worth turning on. Against a development
+  Storybook nothing needs installing — if lines are missing there, React is not
+  its development build, the dev server is emitting no source maps, or this is
+  React 18 compiled with the classic transform, which records no location for
+  either mechanism to read.
+- **Images change without a document change:** leave `network` enabled so asset
+  response bodies participate in the environment key. Disable it only when the
+  URL already identifies the bytes.
+- **The browser is missing:** run `npx playwright install chromium`, then
+  `variance doctor` again.
+
+## Boundaries
+
+This package handles Storybook only. For pages your application already serves,
+use `@variance-authority/route-collector`. For an existing
+Playwright test, use
+`@variance-authority/playwright-test`, where the test body
+already performs navigation, mounting, and readiness.

package/dist/contract.d.ts

@@ -0,0 +1,135 @@
+import type { CallSiteResolver, RenderDocument, SemanticSnapshot, SourceIndex, SubjectRef, Viewport } from '@variance-authority/core';
+/**
+ * The contract a collector satisfies, restated here rather than imported.
+ *
+ * The CLI declares the same shapes and this package does not depend on it — a
+ * surface package pulling in the binary would put a config parser, a docket and
+ * six commands into an adopter's dependency tree to describe four values
+ * (ADR-0024). What keeps the two copies honest is that the CLI imports *this*
+ * collector in its own tests, so a drift between them fails a build rather than
+ * a run.
+ */
+/** The subset of a run's configuration this collector reads. */
+export interface CollectorConfig {
+    readonly viewport: Viewport;
+    readonly fonts?: readonly string[];
+    /**
+     * Subtrees this project excludes, from `config.ignore` (spec 0024).
+     *
+     * Only the two fields a page needs: a rule id to record the mark under, and a
+     * selector to find it with. Everything else about a rule — its reason, its
+     * expiry, the bands it narrows to — is decided after collection, where a clock
+     * and the whole run's diffs are available and a browser is not.
+     */
+    readonly ignore?: readonly {
+        readonly id: string;
+        readonly select?: string;
+        /**
+         * Subjects the rule names. Read here to decide what to send, and never sent.
+         *
+         * A page can resolve a selector and cannot know which subject it is one of,
+         * so scoping has to happen on this side of the boundary. Without it a rule
+         * written for one route marks its element in every subject that renders the
+         * same shared layout, and a real regression inside that element is absorbed
+         * everywhere — an ignore silencing more than it says, which is the one thing
+         * the mechanism must not do.
+         */
+        readonly subjects?: readonly string[];
+        /** Tags the subject must carry. Read here to decide what to send, never sent. */
+        readonly tags?: readonly string[];
+    }[];
+    /**
+     * Images to serve as nothing, from `config.blank`.
+     *
+     * Handed to the driver rather than to the page, because it is enforced on the
+     * wire — before a byte is decoded, and therefore before the layout it would
+     * have participated in exists. Not scoped by subject, and it cannot be: a
+     * request carries no idea which subject will end up using it, which is the
+     * same reason the asset map is per page rather than per subject.
+     */
+    readonly blank?: readonly {
+        readonly id: string;
+        readonly url?: string;
+        readonly minPixels?: number;
+        readonly maxPixels?: number;
+    }[];
+    /**
+     * The subjects section of the config, as the operator wrote it.
+     *
+     * `index` is optional because it belongs to `subjects.kind: "storybook"`, and
+     * a config naming any other kind still reaches this collector — the kind is
+     * chosen in the config and the collector is chosen in the config, and nothing
+     * makes the operator pick a matching pair. Typed as always present, the first
+     * thing to read it hands `undefined` to `node:path` and the adopter gets a
+     * TypeError about an argument instead of a sentence naming the wrong word.
+     */
+    readonly subjects: {
+        readonly index?: string;
+    };
+}
+export interface PlannedSubject {
+    readonly subject: SubjectRef;
+    readonly viewport?: Viewport;
+    /**
+     * What the subject declares itself to be, from the artifact that produced it.
+     *
+     * Storybook's built index carries `tags` and does not carry a story's
+     * `parameters`, so a tag is the only per-story declaration that survives a
+     * build — and it is the right one anyway: what a subject *is* belongs in its
+     * own name, next to it, rather than in a central file repeating every id.
+     *
+     * Selection lives here; definition lives in the config. A tag is a word a
+     * story wears, and what that word *means* is the operator's to write down
+     * once, where a typo can be refused by name.
+     */
+    readonly tags?: readonly string[];
+}
+export interface Plan {
+    readonly subjects: readonly PlannedSubject[];
+    readonly notObserved: readonly unknown[];
+    readonly warnings: readonly string[];
+}
+export type Collected = {
+    readonly ok: true;
+    readonly document: RenderDocument;
+    readonly snapshot?: SemanticSnapshot;
+    readonly source?: SourceIndex;
+    /**
+     * Stabilization tricks applied to the page before this subject was read.
+     *
+     * Reported so a run can say what it did to somebody else's page. The
+     * digest of the same list is in the environment key, which is what makes a
+     * differently-stabilized baseline `incomparable`; this is the half a
+     * person reads.
+     */
+    readonly stabilization?: readonly string[];
+} | {
+    readonly ok: false;
+    readonly because: string;
+};
+export interface CollectorContext {
+    readonly config: CollectorConfig;
+    /** Computed by the run from the story index. Returned unchanged. */
+    readonly plan?: Plan;
+}
+export interface Collector {
+    plan(): Promise<Plan>;
+    collect(subject: PlannedSubject): Promise<Collected>;
+    /**
+     * The frames a snapshot carries, spent on demand.
+     *
+     * Present when the collector drives a browser, because resolving a frame means
+     * fetching the module it names and the page is the only place that request is
+     * already correct. Absent otherwise, and absence is not a degradation: it means
+     * either that nothing captured frames, or that the run has no live page to
+     * fetch through — and both are a report without call sites rather than a
+     * report that is wrong.
+     *
+     * Handed to `locateSites` with the few nodes a region or a finding names. The
+     * resolver is per collector rather than per subject: the cache is what makes
+     * this bounded, and a suite's subjects share their modules.
+     */
+    readonly callSites?: CallSiteResolver;
+    close(): Promise<void>;
+}
+//# sourceMappingURL=contract.d.ts.map

package/dist/contract.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=contract.js.map

package/dist/contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.js","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"","sourcesContent":["import type {\n  CallSiteResolver,\n  RenderDocument,\n  SemanticSnapshot,\n  SourceIndex,\n  SubjectRef,\n  Viewport,\n} from '@variance-authority/core';\n\n/**\n * The contract a collector satisfies, restated here rather than imported.\n *\n * The CLI declares the same shapes and this package does not depend on it — a\n * surface package pulling in the binary would put a config parser, a docket and\n * six commands into an adopter's dependency tree to describe four values\n * (ADR-0024). What keeps the two copies honest is that the CLI imports *this*\n * collector in its own tests, so a drift between them fails a build rather than\n * a run.\n */\n\n/** The subset of a run's configuration this collector reads. */\nexport interface CollectorConfig {\n  readonly viewport: Viewport;\n  readonly fonts?: readonly string[];\n  /**\n   * Subtrees this project excludes, from `config.ignore` (spec 0024).\n   *\n   * Only the two fields a page needs: a rule id to record the mark under, and a\n   * selector to find it with. Everything else about a rule — its reason, its\n   * expiry, the bands it narrows to — is decided after collection, where a clock\n   * and the whole run's diffs are available and a browser is not.\n   */\n  readonly ignore?: readonly {\n    readonly id: string;\n    readonly select?: string;\n    /**\n     * Subjects the rule names. Read here to decide what to send, and never sent.\n     *\n     * A page can resolve a selector and cannot know which subject it is one of,\n     * so scoping has to happen on this side of the boundary. Without it a rule\n     * written for one route marks its element in every subject that renders the\n     * same shared layout, and a real regression inside that element is absorbed\n     * everywhere — an ignore silencing more than it says, which is the one thing\n     * the mechanism must not do.\n     */\n    readonly subjects?: readonly string[];\n\n    /** Tags the subject must carry. Read here to decide what to send, never sent. */\n    readonly tags?: readonly string[];\n  }[];\n\n  /**\n   * Images to serve as nothing, from `config.blank`.\n   *\n   * Handed to the driver rather than to the page, because it is enforced on the\n   * wire — before a byte is decoded, and therefore before the layout it would\n   * have participated in exists. Not scoped by subject, and it cannot be: a\n   * request carries no idea which subject will end up using it, which is the\n   * same reason the asset map is per page rather than per subject.\n   */\n  readonly blank?: readonly {\n    readonly id: string;\n    readonly url?: string;\n    readonly minPixels?: number;\n    readonly maxPixels?: number;\n  }[];\n\n  /**\n   * The subjects section of the config, as the operator wrote it.\n   *\n   * `index` is optional because it belongs to `subjects.kind: \"storybook\"`, and\n   * a config naming any other kind still reaches this collector — the kind is\n   * chosen in the config and the collector is chosen in the config, and nothing\n   * makes the operator pick a matching pair. Typed as always present, the first\n   * thing to read it hands `undefined` to `node:path` and the adopter gets a\n   * TypeError about an argument instead of a sentence naming the wrong word.\n   */\n  readonly subjects: { readonly index?: string };\n}\n\nexport interface PlannedSubject {\n  readonly subject: SubjectRef;\n  readonly viewport?: Viewport;\n\n  /**\n   * What the subject declares itself to be, from the artifact that produced it.\n   *\n   * Storybook's built index carries `tags` and does not carry a story's\n   * `parameters`, so a tag is the only per-story declaration that survives a\n   * build — and it is the right one anyway: what a subject *is* belongs in its\n   * own name, next to it, rather than in a central file repeating every id.\n   *\n   * Selection lives here; definition lives in the config. A tag is a word a\n   * story wears, and what that word *means* is the operator's to write down\n   * once, where a typo can be refused by name.\n   */\n  readonly tags?: readonly string[];\n}\n\nexport interface Plan {\n  readonly subjects: readonly PlannedSubject[];\n  readonly notObserved: readonly unknown[];\n  readonly warnings: readonly string[];\n}\n\nexport type Collected =\n  | {\n      readonly ok: true;\n      readonly document: RenderDocument;\n      readonly snapshot?: SemanticSnapshot;\n      readonly source?: SourceIndex;\n\n      /**\n       * Stabilization tricks applied to the page before this subject was read.\n       *\n       * Reported so a run can say what it did to somebody else's page. The\n       * digest of the same list is in the environment key, which is what makes a\n       * differently-stabilized baseline `incomparable`; this is the half a\n       * person reads.\n       */\n      readonly stabilization?: readonly string[];\n    }\n  | { readonly ok: false; readonly because: string };\n\nexport interface CollectorContext {\n  readonly config: CollectorConfig;\n  /** Computed by the run from the story index. Returned unchanged. */\n  readonly plan?: Plan;\n}\n\nexport interface Collector {\n  plan(): Promise<Plan>;\n  collect(subject: PlannedSubject): Promise<Collected>;\n\n  /**\n   * The frames a snapshot carries, spent on demand.\n   *\n   * Present when the collector drives a browser, because resolving a frame means\n   * fetching the module it names and the page is the only place that request is\n   * already correct. Absent otherwise, and absence is not a degradation: it means\n   * either that nothing captured frames, or that the run has no live page to\n   * fetch through — and both are a report without call sites rather than a\n   * report that is wrong.\n   *\n   * Handed to `locateSites` with the few nodes a region or a finding names. The\n   * resolver is per collector rather than per subject: the cache is what makes\n   * this bounded, and a suite's subjects share their modules.\n   */\n  readonly callSites?: CallSiteResolver;\n  close(): Promise<void>;\n}\n"]}

package/dist/execution.d.ts

@@ -0,0 +1,41 @@
+/**
+ * What each story executed, recorded for the next run's selection.
+ *
+ * The instrument is the one `@variance-authority/sense` already uses; only the
+ * transport differs, which is the rule
+ * [spec 0028](../../../docs/specs/0028-the-instrument.md) states. The preview is
+ * built with `testSelectionProbes()`, the page counts block crossings, and this
+ * closes one window per story and joins them at the end of the run.
+ *
+ * A story is its own owner. Storybook is an execution surface this tool drives
+ * one subject at a time, so — unlike a test runner, where the file is the
+ * smallest thing a runner can be asked to execute — the crossings of one story
+ * belong to that story and to nothing else.
+ */
+import { type EvaluatingPage } from '@variance-authority/sense/journal';
+/** Where a story run's execution evidence is joined, read and kept. */
+export interface StoryExecutionOptions {
+    /** Repository root the recorded paths are relative to. Defaults to the cwd. */
+    readonly root?: string;
+    /** Matches the `label` the build's `testSelectionProbes()` used. Defaults to `build`. */
+    readonly label?: string;
+    /** Block inventory the build wrote. Defaults to the label's repository-keyed cache. */
+    readonly modulesFile?: string;
+    /** Coverage index. Defaults to the repository-keyed cache the runner seams share. */
+    readonly coverageFile?: string;
+}
+/** One run's accumulation: a window per story, written once at the end. */
+export interface StoryRecorder {
+    /**
+     * Close one story's window.
+     *
+     * `complete` is false for a story this run refused. A refused story still
+     * executed code, so its crossings are kept — what it may never do is justify
+     * excluding itself from a later run.
+     */
+    readonly note: (page: EvaluatingPage, subjectId: string, complete: boolean) => Promise<void>;
+    /** Merge the run into the index, or say on stderr why it could not. */
+    readonly close: () => Promise<void>;
+}
+export declare function createStoryRecorder(index: string, options: StoryExecutionOptions): Promise<StoryRecorder>;
+//# sourceMappingURL=execution.d.ts.map

package/dist/execution.js

@@ -0,0 +1,76 @@
+/**
+ * What each story executed, recorded for the next run's selection.
+ *
+ * The instrument is the one `@variance-authority/sense` already uses; only the
+ * transport differs, which is the rule
+ * [spec 0028](../../../docs/specs/0028-the-instrument.md) states. The preview is
+ * built with `testSelectionProbes()`, the page counts block crossings, and this
+ * closes one window per story and joins them at the end of the run.
+ *
+ * A story is its own owner. Storybook is an execution surface this tool drives
+ * one subject at a time, so — unlike a test runner, where the file is the
+ * smallest thing a runner can be asked to execute — the crossings of one story
+ * belong to that story and to nothing else.
+ */
+import { readFile } from 'node:fs/promises';
+import { drainExecution, preconditionOf, recordExecution, } from '@variance-authority/sense/journal';
+import { parseStoryIndex } from '@variance-authority/storybook';
+import { resolve } from 'node:path';
+export async function createStoryRecorder(index, options) {
+    const root = resolve(options.root ?? process.cwd());
+    const storyFiles = await storyFilesFrom(index);
+    const observed = [];
+    let seen = false;
+    return {
+        note: async (page, subjectId, complete) => {
+            const journal = await drainExecution(page);
+            if (journal === undefined)
+                return;
+            seen = true;
+            const storyId = subjectId.replace(/^story:/, '');
+            const file = storyFiles.get(storyId);
+            const precondition = file === undefined ? undefined : await preconditionOf(root, file);
+            observed.push({
+                owner: subjectId,
+                journal,
+                complete,
+                ...(precondition === undefined ? {} : { preconditions: [precondition] }),
+            });
+        },
+        close: async () => {
+            if (!seen) {
+                process.stderr.write('variance-authority: `tests` is on and the Storybook preview has no execution ' +
+                    'collector in it — build it with `testSelectionProbes()` from ' +
+                    '`@variance-authority/sense/journal`, or the next `--since` will run ' +
+                    'everything\n');
+                return;
+            }
+            // A refusal is written and the run continues. Recording is an addition to
+            // a visual run: losing it costs the *next* selection its narrowing, which
+            // is a full suite — the safe direction — while failing the run over it
+            // would cost this one its baselines, which is not.
+            const record = await recordExecution({
+                root,
+                subjects: observed,
+                ...(options.label === undefined ? {} : { label: options.label }),
+                ...(options.modulesFile === undefined ? {} : { modulesFile: options.modulesFile }),
+                ...(options.coverageFile === undefined ? {} : { coverageFile: options.coverageFile }),
+            });
+            if (!record.recorded) {
+                process.stderr.write(`variance-authority: recorded no story execution — ${record.because}\n`);
+            }
+        },
+    };
+}
+/**
+ * Story id to the file that declares it, from the index the run is driving.
+ *
+ * The one route from a subject back to a file, and the reason a story's own
+ * `.stories` file can select it: nothing *enters* a story file the way execution
+ * enters a module, so without this a commit that edits one selects nothing.
+ */
+async function storyFilesFrom(index) {
+    const parsed = parseStoryIndex(JSON.parse(await readFile(index, 'utf8')), index);
+    return new Map(parsed.stories.map((story) => [story.id, story.importPath]));
+}
+//# sourceMappingURL=execution.js.map

package/dist/execution.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"execution.js","sourceRoot":"","sources":["../src/execution.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * What each story executed, recorded for the next run's selection.\n *\n * The instrument is the one `@variance-authority/sense` already uses; only the\n * transport differs, which is the rule\n * [spec 0028](../../../docs/specs/0028-the-instrument.md) states. The preview is\n * built with `testSelectionProbes()`, the page counts block crossings, and this\n * closes one window per story and joins them at the end of the run.\n *\n * A story is its own owner. Storybook is an execution surface this tool drives\n * one subject at a time, so — unlike a test runner, where the file is the\n * smallest thing a runner can be asked to execute — the crossings of one story\n * belong to that story and to nothing else.\n */\n\nimport { readFile } from 'node:fs/promises';\nimport {\n  drainExecution,\n  preconditionOf,\n  recordExecution,\n  type EvaluatingPage,\n  type ObservedSubject,\n} from '@variance-authority/sense/journal';\nimport { parseStoryIndex } from '@variance-authority/storybook';\nimport { resolve } from 'node:path';\n\n/** Where a story run's execution evidence is joined, read and kept. */\nexport interface StoryExecutionOptions {\n  /** Repository root the recorded paths are relative to. Defaults to the cwd. */\n  readonly root?: string;\n  /** Matches the `label` the build's `testSelectionProbes()` used. Defaults to `build`. */\n  readonly label?: string;\n  /** Block inventory the build wrote. Defaults to the label's repository-keyed cache. */\n  readonly modulesFile?: string;\n  /** Coverage index. Defaults to the repository-keyed cache the runner seams share. */\n  readonly coverageFile?: string;\n}\n\n/** One run's accumulation: a window per story, written once at the end. */\nexport interface StoryRecorder {\n  /**\n   * Close one story's window.\n   *\n   * `complete` is false for a story this run refused. A refused story still\n   * executed code, so its crossings are kept — what it may never do is justify\n   * excluding itself from a later run.\n   */\n  readonly note: (page: EvaluatingPage, subjectId: string, complete: boolean) => Promise<void>;\n  /** Merge the run into the index, or say on stderr why it could not. */\n  readonly close: () => Promise<void>;\n}\n\nexport async function createStoryRecorder(\n  index: string,\n  options: StoryExecutionOptions,\n): Promise<StoryRecorder> {\n  const root = resolve(options.root ?? process.cwd());\n  const storyFiles = await storyFilesFrom(index);\n  const observed: ObservedSubject[] = [];\n  let seen = false;\n\n  return {\n    note: async (page, subjectId, complete) => {\n      const journal = await drainExecution(page);\n      if (journal === undefined) return;\n      seen = true;\n      const storyId = subjectId.replace(/^story:/, '');\n      const file = storyFiles.get(storyId);\n      const precondition = file === undefined ? undefined : await preconditionOf(root, file);\n      observed.push({\n        owner: subjectId,\n        journal,\n        complete,\n        ...(precondition === undefined ? {} : { preconditions: [precondition] }),\n      });\n    },\n\n    close: async () => {\n      if (!seen) {\n        process.stderr.write(\n          'variance-authority: `tests` is on and the Storybook preview has no execution ' +\n            'collector in it — build it with `testSelectionProbes()` from ' +\n            '`@variance-authority/sense/journal`, or the next `--since` will run ' +\n            'everything\\n',\n        );\n        return;\n      }\n      // A refusal is written and the run continues. Recording is an addition to\n      // a visual run: losing it costs the *next* selection its narrowing, which\n      // is a full suite — the safe direction — while failing the run over it\n      // would cost this one its baselines, which is not.\n      const record = await recordExecution({\n        root,\n        subjects: observed,\n        ...(options.label === undefined ? {} : { label: options.label }),\n        ...(options.modulesFile === undefined ? {} : { modulesFile: options.modulesFile }),\n        ...(options.coverageFile === undefined ? {} : { coverageFile: options.coverageFile }),\n      });\n      if (!record.recorded) {\n        process.stderr.write(\n          `variance-authority: recorded no story execution — ${record.because}\\n`,\n        );\n      }\n    },\n  };\n}\n\n/**\n * Story id to the file that declares it, from the index the run is driving.\n *\n * The one route from a subject back to a file, and the reason a story's own\n * `.stories` file can select it: nothing *enters* a story file the way execution\n * enters a module, so without this a commit that edits one selects nothing.\n */\nasync function storyFilesFrom(index: string): Promise<Map<string, string>> {\n  const parsed = parseStoryIndex(JSON.parse(await readFile(index, 'utf8')), index);\n  return new Map(parsed.stories.map((story) => [story.id, story.importPath]));\n}\n"]}