@variance-authority/storybook-collector 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,101 @@
 # @variance-authority/storybook-collector
 
+## 0.2.0
+
+### Minor Changes
+
+- 8efba76: A run that changed ten files stops rewriting the whole selection index
+  
+  Every run after the first reads the selection index, lays its own recording over
+  it, and writes it back. At a repository's scale almost all of that was spent
+  making objects nobody reads: a run that re-records ten modules of twenty thousand
+  decoded six hundred thousand regions into a model, merged ten of them, and
+  encoded the model back — the other 99.95% of the index materialized and
+  re-serialized to arrive at the bytes it was read from.
+  
+  `layerTestCoverage` does the merge and the encode as one pass over the columns
+  the previous snapshot is already stored in. A module the run did not touch is
+  never made an object: its rows are copied column to column as integers, its
+  strings blob to blob as bytes, and the only thing that happens to either is the
+  renumbering the new dictionary implies. Objects are made for what the merge has
+  to reason about — the tests, the modules this run re-recorded, and the carried
+  modules whose text moved on disk. Over twenty thousand modules that is 1855 ms to
+  616, and it is byte for byte the same file, which a gate asserts across every
+  case the merge distinguishes.
+  
+  The columns are now zstd rather than brotli, at two levels, because the runs are
+  two kinds of data. A varint run is a dense stream of small integers and answers
+  to a long search; a run of the string blob is file paths and hex digests, which
+  zstd finds most of at level 1 and nothing more of above it. Against the brotli
+  quality 4 it replaces, over the same snapshot: 319 ms to compress became 120, and
+  the file got 86 KB smaller.
+  
+  `zlib.zstdCompressSync` arrived in Node 22.15, so that is the floor these
+  packages declare. The snapshot's layout version moved with the codec, which means
+  an index written by an earlier build is refused at its header and rebuilt — one
+  full run, and nothing a reader has to think about.
+
+### Patch Changes
+
+- e546e21: Where the JSX settings live under Vite 8
+  
+  Vite 8 transforms with oxc, so `esbuild: { jsx, jsxDev, jsxImportSource }` becomes
+  `oxc: { jsx: { runtime, development, importSource } }`, and `esbuild.keepNames`
+  becomes `build.rolldownOptions.output.keepNames`. A config keeps whichever keys it
+  is given and reads only the ones its own major knows, so the wrong block is not an
+  error, not a warning and not a log line: the plugin installs, the bundle runs,
+  every subject renders, and every report names the line a component is declared on
+  instead of the line that wrote the element. It fails in the direction that looks
+  like it worked.
+  
+  The `jsx-source` README carries a table of where the two settings live per
+  transform, both spellings on every copyable snippet, and the reminder to read
+  `provenanceOf`'s result rather than the config — the config cannot tell you.
+  `storybook-collector` gets the same for `keepNames`, on the symptom it produces: a
+  confident report naming a component that appears nowhere in your source.
+- Updated dependencies [e546e21]
+- Updated dependencies [8efba76]
+- Updated dependencies [e546e21]
+- Updated dependencies [d50e020]
+- Updated dependencies [f4b328b]
+- Updated dependencies [e546e21]
+- Updated dependencies [e546e21]
+- Updated dependencies [f4b328b]
+- Updated dependencies [0718464]
+- Updated dependencies [0718464]
+- Updated dependencies [0718464]
+- Updated dependencies [e546e21]
+- Updated dependencies [e546e21]
+- Updated dependencies [0718464]
+  - @variance-authority/core@0.2.0
+  - @variance-authority/sense@0.2.0
+  - @variance-authority/playwright@0.2.0
+  - @variance-authority/dom@0.2.0
+  - @variance-authority/react@0.2.0
+  - @variance-authority/storybook@0.2.0
+
+## 0.1.1
+
+### Patch Changes
+
+- db08866: Keep the run when the execution journal cannot be recorded.
+  
+  `close()` already held the position that a journal is not the artefact under
+  review: a recorder that declines to record is written to stderr and the run
+  continues, because failing the run over it would cost every subject in it the
+  baselines it just captured. Only the declining half was handled. A throw out of
+  the same call — `duplicate test coverage observation` was the one reached in
+  practice — went straight up through `close()` and took the run down with it.
+  Both outcomes now end the same way, in a sentence on stderr and a run that keeps
+  its images.
+- Updated dependencies [fe578c8]
+  - @variance-authority/sense@0.1.1
+  - @variance-authority/core@0.1.1
+  - @variance-authority/dom@0.1.1
+  - @variance-authority/playwright@0.1.1
+  - @variance-authority/react@0.1.1
+  - @variance-authority/storybook@0.1.1
+
 ## 0.1.0
 
 ### Patch Changes

package/README.md

@@ -56,26 +56,24 @@ 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.
+remembers otherwise. Preserve component names when the report must use them.
+
+That scan 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, a **development**
+Storybook needs no instrumentation. A **built** Storybook can opt into that
+extra precision with `@variance-authority/jsx-source`; collection, comparison
+and declaration-level attribution work without it. The build must emit
+automatic development JSX, and the plugin belongs in `viteFinal`:
 
 ```bash
 npm install --save-dev @variance-authority/jsx-source
 ```
 
+See [`@variance-authority/jsx-source`](../jsx-source) for the Vite configuration
+and for builds that already use Emotion, theme-ui or another custom JSX runtime.
+
 ### 3. Point the CLI at the Storybook index and collector
 
 In `variance.config.json`, the index is the built file and `collector` is the
@@ -107,20 +105,19 @@ 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
+.variance/report.html` and open the result in a browser to see the before, diff and
+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.
+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
+baseline — the stored snapshot a subject is compared against — that 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.
+and run again. The next unchanged run exits `0` without repainting the subjects
+whose stored document digest already proves they did not change.
 
-The executable `storybook-case` demonstrates the
-complete cycle against a Storybook-built artifact: new → accept → unchanged → a
+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
@@ -135,6 +132,9 @@ complete cycle against a Storybook-built artifact: new → accept → unchanged
 | `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. |
+| `hashAssets` | Your asset URLs already carry their own content hash. | `true`. Read only while `network` is on, so GIF freezing and blanking survive it — this, not `network: false`, is the setting for a content-addressed build. |
+| `wiring` | Your preview's renderer is not React, so the fiber walk buys an absent band. | `true`. A band of its own; turning it off changes no stored digest. |
+| `holdings` | Application values behind the nodes are evidence you want carried. | `false`. Changes `structureHash` — an inert wrapper survives the collapse — so both sides of a comparison must be read the same way. |
 | `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. |
 
@@ -146,8 +146,8 @@ 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
+`testSelectionProbes()` was given, and `cacheRoot` and `coverageFile` override
+the repository-keyed cache paths for the block records 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.
@@ -171,9 +171,8 @@ 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.
+difference no one authored, and every band — the severity category a change is filed
+under, from accessibility down to sub-pixel noise — agrees with both.
 
 Declare the exception when the fallback is the subject:
 
@@ -199,16 +198,19 @@ the other side.
   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.
+  Production minification must also preserve component function names. Vite 8
+  spells that `build.rolldownOptions.output.keepNames: true`; Vite 7 and below,
+  including the worked case, spell it `esbuild.keepNames: true`. A config
+  carrying the other major's key is read by nothing and warns about nothing, so
+  the symptom is a confident report naming a component that appears nowhere in
+  your source.
 - **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.
+  this is the expected fallback for an uninstrumented built Storybook. Install
+  `jsx-source` only when the report must distinguish the exact element instance,
+  and make that build emit automatic development JSX. Against a development
+  Storybook nothing normally needs installing; missing lines there mean React
+  is not its development build, the dev server emits no source maps, or React 18
+  is still compiled to classic `createElement` calls.
 - **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.

package/dist/contract.d.ts

@@ -1,4 +1,5 @@
-import type { CallSiteResolver, RenderDocument, SemanticSnapshot, SourceIndex, SubjectRef, Viewport } from '@variance-authority/core';
+import type { CallSiteResolver, SourceIndex } from '@variance-authority/core/attribute';
+import type { RenderDocument, SemanticSnapshot, SubjectRef, Viewport } from '@variance-authority/core/format';
 /**
  * The contract a collector satisfies, restated here rather than imported.
  *
@@ -130,6 +131,27 @@ export interface Collector {
      * this bounded, and a suite's subjects share their modules.
      */
     readonly callSites?: CallSiteResolver;
+    /**
+     * Collect this subject again, in a world nothing else has touched.
+     *
+     * The saving this whole tool is built on is that the world is *not* rebuilt
+     * between subjects (ADR-0009): one browser, one page, one Storybook, for the
+     * length of a run. What it buys is the possibility that story B renders
+     * differently because story A ran first — and a comparison cannot tell that
+     * apart from a regression, because both arrive as "the pixels moved".
+     *
+     * One clean collection settles it. If the difference is gone with nothing else
+     * in the world, the baseline was right and the session moved this subject, and
+     * the run reports `order-dependent` rather than asking anybody to accept it.
+     *
+     * Optional in the contract the CLI declares, because a collector holding a
+     * single page open has no clean world to offer and the run says so rather than
+     * reading silence as "nothing leaked". This collector implements it: a
+     * Storybook preview can be opened twice, and the second one costs a browser
+     * launch — which is why the run only spends it on subjects it already called
+     * `changed`, up to `alone.limit`.
+     */
+    collectAlone?(subject: PlannedSubject): Promise<Collected>;
     close(): Promise<void>;
 }
 //# sourceMappingURL=contract.d.ts.map

package/dist/contract.js.map

@@ -1 +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"]}
+{"version":3,"file":"contract.js","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"","sourcesContent":["import type { CallSiteResolver, SourceIndex } from '@variance-authority/core/attribute';\nimport type {\n  RenderDocument,\n  SemanticSnapshot,\n  SubjectRef,\n  Viewport,\n} from '@variance-authority/core/format';\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\n  /**\n   * Collect this subject again, in a world nothing else has touched.\n   *\n   * The saving this whole tool is built on is that the world is *not* rebuilt\n   * between subjects (ADR-0009): one browser, one page, one Storybook, for the\n   * length of a run. What it buys is the possibility that story B renders\n   * differently because story A ran first — and a comparison cannot tell that\n   * apart from a regression, because both arrive as \"the pixels moved\".\n   *\n   * One clean collection settles it. If the difference is gone with nothing else\n   * in the world, the baseline was right and the session moved this subject, and\n   * the run reports `order-dependent` rather than asking anybody to accept it.\n   *\n   * Optional in the contract the CLI declares, because a collector holding a\n   * single page open has no clean world to offer and the run says so rather than\n   * reading silence as \"nothing leaked\". This collector implements it: a\n   * Storybook preview can be opened twice, and the second one costs a browser\n   * launch — which is why the run only spends it on subjects it already called\n   * `changed`, up to `alone.limit`.\n   */\n  collectAlone?(subject: PlannedSubject): Promise<Collected>;\n\n  close(): Promise<void>;\n}\n"]}

package/dist/execution.d.ts

@@ -19,8 +19,8 @@ export interface StoryExecutionOptions {
     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;
+    /** Where the build wrote its block records. Defaults to the user cache. */
+    readonly cacheRoot?: string;
     /** Coverage index. Defaults to the repository-keyed cache the runner seams share. */
     readonly coverageFile?: string;
 }

package/dist/execution.js

@@ -49,13 +49,30 @@ export async function createStoryRecorder(index, options) {
             // 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 }),
-            });
+            //
+            // That holds for a throw as much as for a refusal. The recorder reports
+            // what it declined in `because`, but it is a file format, a lock and a
+            // filesystem underneath, and any of them can raise something it has no
+            // sentence for. Letting that escape ends the run *after* every subject
+            // has been rendered and compared — the most expensive possible moment to
+            // lose a set of baselines, and over the half of the work that was only
+            // ever an addition.
+            let record;
+            try {
+                record = await recordExecution({
+                    root,
+                    subjects: observed,
+                    ...(options.label === undefined ? {} : { label: options.label }),
+                    ...(options.cacheRoot === undefined ? {} : { cacheRoot: options.cacheRoot }),
+                    ...(options.coverageFile === undefined ? {} : { coverageFile: options.coverageFile }),
+                });
+            }
+            catch (error) {
+                process.stderr.write('variance-authority: recorded no story execution — the recorder failed with ' +
+                    `${error instanceof Error ? error.message : String(error)}; this run is ` +
+                    'unaffected and the next `--since` will run everything\n');
+                return;
+            }
             if (!record.recorded) {
                 process.stderr.write(`variance-authority: recorded no story execution — ${record.because}\n`);
             }

package/dist/execution.js.map

@@ -1 +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"]}
+{"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  /** Where the build wrote its block records. Defaults to the user cache. */\n  readonly cacheRoot?: 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      //\n      // That holds for a throw as much as for a refusal. The recorder reports\n      // what it declined in `because`, but it is a file format, a lock and a\n      // filesystem underneath, and any of them can raise something it has no\n      // sentence for. Letting that escape ends the run *after* every subject\n      // has been rendered and compared — the most expensive possible moment to\n      // lose a set of baselines, and over the half of the work that was only\n      // ever an addition.\n      let record: Awaited<ReturnType<typeof recordExecution>>;\n      try {\n        record = await recordExecution({\n          root,\n          subjects: observed,\n          ...(options.label === undefined ? {} : { label: options.label }),\n          ...(options.cacheRoot === undefined ? {} : { cacheRoot: options.cacheRoot }),\n          ...(options.coverageFile === undefined ? {} : { coverageFile: options.coverageFile }),\n        });\n      } catch (error) {\n        process.stderr.write(\n          'variance-authority: recorded no story execution — the recorder failed with ' +\n            `${error instanceof Error ? error.message : String(error)}; this run is ` +\n            'unaffected and the next `--since` will run everything\\n',\n        );\n        return;\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"]}

package/dist/index.d.ts

@@ -1,137 +1,6 @@
-import { type StoryExecutionOptions } from './execution.js';
+import type { StorybookCollectorOptions } from './options.js';
 export type { Collected, Collector, CollectorConfig, CollectorContext, Plan, PlannedSubject, } from './contract.js';
 import type { Collector, CollectorContext } from './contract.js';
-import { type SourceScan } from './source.js';
-/**
- * The Storybook collector, shipped.
- *
- * ## Why this package exists, stated as the thing it retracts
- *
- * This repository's position was that mounting is the adopter's, once, per
- * project — and it measured the cost honestly at 341 lines rather than the
- * "about thirty" the source had guessed. That position is right about React
- * applications and wrong about Storybook, for a reason the measurement itself
- * shows: of those 341 lines, the parts that were genuinely *this project's* were
- * a map of three ready selectors, a directory to scan for components, and a
- * static server. Everything else was Storybook's own contract being re-typed.
- *
- * A story index is a documented artifact. A preview owns its own mount and
- * exposes a channel for switching stories. So for this one subject source the
- * mounting problem is already solved by somebody else, and asking every adopter
- * to re-solve it was charging them for our boundary rather than for their
- * project.
- *
- * **What stays theirs.** Readiness per story, because Storybook's `storyRendered`
- * fires when the story function returns — which for a component that defers work
- * is *before the component exists*. That is knowledge about a component, and a
- * project-wide default would be a guess about all of them.
- *
- * ## What it does not make generic
- *
- * Nothing outside Storybook. A Playwright suite, a route table or a bespoke
- * mount is still a collector somebody writes — see
- * [`@variance-authority/playwright-test`](../playwright-test) for the surface
- * where the adopter's own test body plays that part instead.
- */
-export interface StorybookCollectorOptions {
-    /**
-     * Story id to the selector that says it is ready.
-     *
-     * Per story, not per project, and that is the design rather than an
-     * ergonomics gap. A button needs no marker and demanding one from it would
-     * time out every story to solve a problem one of them has. A story that
-     * declares a marker and never attaches it times out saying which selector it
-     * waited for — there is no fallback, because falling back is how you
-     * photograph a spinner and call it a component.
-     */
-    readonly ready?: Readonly<Record<string, string>>;
-    /**
-     * Where the components live, for `file:line` attribution.
-     *
-     * Omitted, the report names components and no files — which is still ahead of
-     * every product in the category and is not what this is for.
-     */
-    readonly source?: SourceScan;
-    /**
-     * A Storybook that is already served, e.g. `http://localhost:6006`.
-     *
-     * Preferred when it exists: then nothing here has an opinion about how the
-     * build is hosted. Omitted, the directory holding `subjects.index` is served
-     * on a loopback port for the life of the run.
-     */
-    readonly baseUrl?: string;
-    /** Defaults to `true`. Set false to watch a run by hand. */
-    readonly headless?: boolean;
-    /**
-     * Watch the wire: hash asset bodies into the environment key, and serve
-     * animated GIFs as their first frame. Defaults to `true`.
-     *
-     * On, this is what closes a false `unchanged` that a page cannot see about
-     * itself. A logo re-exported at the same URL is the same markup, the same CSS
-     * and the same document — so every tier settles, and the run reports that
-     * nothing moved while the image on the page is different bytes. Only the party
-     * that saw the response knows otherwise.
-     *
-     * The assets are narrowed **per story** before they reach a key, from the URLs
-     * that story's own subtree references (`assetsFor`). Without that, a run that
-     * reads three hundred stories out of one page would give story 200 a key that
-     * depends on which stories ran before it, and sharding the suite would change
-     * every baseline's identity.
-     *
-     * Off is a position for a build whose asset URLs already contain their own
-     * content hash: the URL is then the identity, and hashing the bytes again buys
-     * a read and nothing else.
-     */
-    readonly network?: boolean;
-    /** Overrides the roots the story is read from. Tightest first. */
-    readonly roots?: readonly string[];
-    /** Milliseconds for Storybook or a declared marker to report readiness. Defaults to 15000. */
-    readonly readyTimeoutMs?: number;
-    /**
-     * Milliseconds to wait for a story's Suspense boundaries. Defaults to 5000.
-     *
-     * Paid only by stories that are actually waiting: a subtree with no boundary
-     * in it returns on the first read. `0` turns the wait off and keeps the
-     * reading, which is a position for a project whose readiness markers already
-     * cover its data — the refusal below still fires, so the boundary is reported
-     * rather than photographed.
-     */
-    readonly suspenseTimeoutMs?: number;
-    /**
-     * Record what each story executed, into the shared test-selection index.
-     *
-     * Off unless asked for, and it asks something of the build rather than of this
-     * package: the Storybook preview has to have been built with
-     * `testSelectionProbes()` from `@variance-authority/sense/journal`, which is
-     * what puts probes in the source and writes down what their ordinals mean.
-     * Without it a run records nothing and says so on stderr — the next selection
-     * then runs everything, which is the direction every uncertainty here
-     * resolves.
-     *
-     * A story is its own owner in that index. 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.
-     */
-    readonly tests?: boolean | StoryExecutionOptions;
-    /**
-     * Stories whose *loading* state is the subject, as id globs.
-     *
-     * The escape hatch, and the only one. A story left showing its fallback is
-     * otherwise refused, because a subject that records a skeleton on a slow
-     * machine and a component on a fast one is a flake nobody wrote — so a
-     * skeleton somebody *does* want a baseline over has to be said out loud.
-     *
-     * Declared here rather than sensed, and checked in both directions: a story
-     * named by this that turns out to settle is refused too. A declaration that
-     * outlived its subject is the same nondeterminism arriving from the other side.
-     *
-     * Matched against the story id and the subject id both, so
-     * `case-surface--feed` and `story:case-surface--feed` name the same story —
-     * `ready` above is keyed by the first.
-     */
-    readonly loading?: readonly string[];
-}
 /**
  * Build the module a `subjects.collector` path should default-export.
  *
@@ -149,6 +18,7 @@ export interface StorybookCollectorOptions {
  * ```
  */
 export declare function storybookCollector(options?: StorybookCollectorOptions): (context: CollectorContext) => Promise<Collector>;
+export type { StorybookCollectorOptions } from './options.js';
 export type { StoryExecutionOptions } from './execution.js';
 export type { SourceScan } from './source.js';
 export type { AcquireRequest, Acquired } from './page-agent.js';