@qoretechnologies/qlip 0.1.3-beta.20260724071501 → 0.1.3-pr.28.g211f2a4

package/README.md

@@ -180,6 +180,10 @@ export const LoggedIn = {
 };
 ```
 
+Take as many as you like per story — each name is its own snapshot on the server. Give them distinct names: two captures of one story sharing a name (including `auto`, which the automatic capture uses) resolve to one snapshot, and the run warns which image it had to drop.
+
+**Known limitation:** qlip-server keys *baselines* by story, kind and viewport, without the screenshot name. A story's auto capture and its manual captures are therefore independent, but **two manual captures of one story at one viewport share a baseline** — accepting one sets the baseline for the other, which then shows a meaningless diff. The run warns when a build contains such captures. Fixing it needs a server-side change; until then, give such captures distinct viewports if you need independent baselines.
+
 ## Parameters
 
 Configure screenshots per story via `parameters.qlip`:
@@ -219,6 +223,7 @@ qlipVitestPlugin({
   waitForIdleMs: 300,
   maxWaitForIdleMs: 2000,
   ignoreElements: [],
+  diagnostics: false,
 });
 ```
 
@@ -226,6 +231,10 @@ qlipVitestPlugin({
 
 `ignoreElements` lets you provide CSS selectors to mask before capture. Qlip draws solid overlays on matching elements so layout stays intact while visual diffs ignore those regions.
 
+qlip also reports what it *failed* to capture: the run warns when Storybook stories executed without producing a capture, naming them and the files they came from. It is advisory — a story that sets `parameters.qlip.auto = false` shows up there too.
+
+`diagnostics` (or `QLIP_DEBUG=1`) logs one line per capture — story, kind, path, and which browser context wrote it. Turn it on when a CI build captured fewer stories than it ran; the always-written `capture-report.json` covers the same ground after the fact.
+
 ## Memory-safe config for large Storybooks
 
 If your Storybook has more than ~150 stories, or any stories that mount a heavy app shell (dashboards, multi-pane editors, etc.), the **default Vitest browser-mode** can OOM — it spawns one worker per CPU core, each with its own BrowserContext, and on a 12-core machine that's easily 20+ GB peak RAM.
@@ -265,11 +274,27 @@ Verified on a real consumer (qorus-ide, 90 story files / 643 tests, Vitest 2.1.9
       auto/<storyTitle>--<storyName>.png
       manual/<storyTitle>--<storyName>--<screenshotName>.png
       error/<storyTitle>--<storyName>--qlip-auto-error-capture.png
+    manifest-fragments/<contextId>-<seq>.json
     manifest.json
+    capture-report.json
 ```
 
 - `buildId` defaults to `YYYYMMDD-HHmmss`
 - `parameters.qlip.skip === true` disables all captures for that story
+- `manifest-fragments/` holds one append-only record per capture; they
+  merge into `manifest.json` at end-of-run. Safe to delete after a
+  build uploads — see [`design/MANIFEST_FRAGMENTS.md`](./design/MANIFEST_FRAGMENTS.md)
+- `capture-report.json` is the run's audit: captures per context and
+  per story file, plus any screenshot on disk that no manifest entry
+  references
+
+## Sharded CI runs
+
+Several `vitest run` invocations (or `test-storybook` shards) can capture into one build: pin `buildId` — e.g. `buildId: process.env.GITHUB_RUN_ID` — so every shard writes into the same `<outputDir>/<buildId>/`, then upload once at the end with `npx qlip-upload --build-dir ./qlip/screenshots/$GITHUB_RUN_ID`. Fragment names carry a per-process id, so shards cannot overwrite each other's captures.
+
+`isolate: false` is supported. Several story files then share one browser context and capture concurrently; fragments are append-only precisely so that is safe.
+
+Add `--fail-on-partial-build` to `qlip-upload` (or `upload.failOnPartialBuild` on the plugin) to turn "screenshots on disk that never reached the manifest" from a warning into a red build.
 
 ## Manifest
 

package/dist/fs/output.d.ts

@@ -14,6 +14,14 @@ export declare const DEFAULT_VIEWPORT: {
  * reference it without pulling node:fs/path into the browser bundle.
  */
 export declare const MANIFEST_FRAGMENT_DIR = "manifest-fragments";
+/**
+ * Fragment file name for one capture. `(fragmentId, seq)` is unique
+ * across browser contexts AND across processes sharing a build dir, so
+ * no two writers ever target the same path — that is what makes the
+ * fragment set append-only. Shared by both capture paths so they agree
+ * by construction. See `design/MANIFEST_FRAGMENTS.md`.
+ */
+export declare const fragmentFileName: (fragmentId: string, seq: number) => string;
 export declare const generateBuildId: (date?: Date) => string;
 export declare const sanitizeSegment: (value: string) => string;
 export declare const joinPath: (...parts: string[]) => string;

package/dist/fs/output.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"output.d.ts","sourceRoot":"","sources":["../../src/fs/output.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAEjE,eAAO,MAAM,SAAS,SAAS,CAAC;AAEhC,eAAO,MAAM,kBAAkB,uBAAuB,CAAC;AACvD,eAAO,MAAM,0BAA0B,4BAA4B,CAAC;AACpE,eAAO,MAAM,gBAAgB;;;CAA+B,CAAC;AAC7D;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB,uBAAuB,CAAC;AAE1D,eAAO,MAAM,eAAe,GAAI,OAAM,IAAiB,KAAG,MASzD,CAAC;AAEF,eAAO,MAAM,eAAe,GAAI,OAAO,MAAM,KAAG,MACD,CAAC;AAEhD,eAAO,MAAM,QAAQ,GAAI,GAAG,OAAO,MAAM,EAAE,KAAG,MAgB7C,CAAC;AA+BF,eAAO,MAAM,uBAAuB,GAAI,+CAKrC;IACD,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;;;CAOA,CAAC;AAEF,eAAO,MAAM,yBAAyB,GAAI,+DAMvC;IACD,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;CACxB;;;;CAYA,CAAC;AAKF,eAAO,MAAM,gBAAgB,GAAI,+CAK9B;IACD,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;;;CAOA,CAAC;AAEF,eAAO,MAAM,kBAAkB,GAAI,+DAMhC;IACD,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;CACxB;;;CAWA,CAAC;AAEF,eAAO,MAAM,cAAc,GAAI,oDAM5B;IACD,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,oBAAoB,CAAC;IAC/B,IAAI,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IACxC,SAAS,CAAC,EAAE,IAAI,CAAC;CAClB,KAAG,YAeF,CAAC"}
+{"version":3,"file":"output.d.ts","sourceRoot":"","sources":["../../src/fs/output.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAEjE,eAAO,MAAM,SAAS,SAAS,CAAC;AAEhC,eAAO,MAAM,kBAAkB,uBAAuB,CAAC;AACvD,eAAO,MAAM,0BAA0B,4BAA4B,CAAC;AACpE,eAAO,MAAM,gBAAgB;;;CAA+B,CAAC;AAC7D;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB,uBAAuB,CAAC;AAE1D;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,GAAI,YAAY,MAAM,EAAE,KAAK,MAAM,KAAG,MACb,CAAC;AAEvD,eAAO,MAAM,eAAe,GAAI,OAAM,IAAiB,KAAG,MASzD,CAAC;AAEF,eAAO,MAAM,eAAe,GAAI,OAAO,MAAM,KAAG,MACD,CAAC;AAEhD,eAAO,MAAM,QAAQ,GAAI,GAAG,OAAO,MAAM,EAAE,KAAG,MAgB7C,CAAC;AA+BF,eAAO,MAAM,uBAAuB,GAAI,+CAKrC;IACD,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;;;CAOA,CAAC;AAEF,eAAO,MAAM,yBAAyB,GAAI,+DAMvC;IACD,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;CACxB;;;;CAYA,CAAC;AAKF,eAAO,MAAM,gBAAgB,GAAI,+CAK9B;IACD,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;;;CAOA,CAAC;AAEF,eAAO,MAAM,kBAAkB,GAAI,+DAMhC;IACD,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;CACxB;;;CAWA,CAAC;AAEF,eAAO,MAAM,cAAc,GAAI,oDAM5B;IACD,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,oBAAoB,CAAC;IAC/B,IAAI,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IACxC,SAAS,CAAC,EAAE,IAAI,CAAC;CAClB,KAAG,YAeF,CAAC"}

package/dist/fs/output.js

@@ -10,6 +10,14 @@ export const DEFAULT_VIEWPORT = { width: 1280, height: 720 };
  * reference it without pulling node:fs/path into the browser bundle.
  */
 export const MANIFEST_FRAGMENT_DIR = 'manifest-fragments';
+/**
+ * Fragment file name for one capture. `(fragmentId, seq)` is unique
+ * across browser contexts AND across processes sharing a build dir, so
+ * no two writers ever target the same path — that is what makes the
+ * fragment set append-only. Shared by both capture paths so they agree
+ * by construction. See `design/MANIFEST_FRAGMENTS.md`.
+ */
+export const fragmentFileName = (fragmentId, seq) => `${fragmentId}-${String(seq).padStart(5, '0')}.json`;
 export const generateBuildId = (date = new Date()) => {
     const pad = (num) => String(num).padStart(2, '0');
     const year = date.getFullYear();

package/dist/plugin/vitestPlugin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"vitestPlugin.d.ts","sourceRoot":"","sources":["../../src/plugin/vitestPlugin.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAU5C,OAAO,EAAE,iBAAiB,EAAqB,MAAM,aAAa,CAAC;AAMnE,eAAO,MAAM,gBAAgB,GAAI,UAAS,iBAAsB,KAAG,MAiQlE,CAAC"}
+{"version":3,"file":"vitestPlugin.d.ts","sourceRoot":"","sources":["../../src/plugin/vitestPlugin.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAU5C,OAAO,EAAE,iBAAiB,EAAqB,MAAM,aAAa,CAAC;AAMnE,eAAO,MAAM,gBAAgB,GAAI,UAAS,iBAAsB,KAAG,MAmQlE,CAAC"}

package/dist/plugin/vitestPlugin.js

@@ -49,6 +49,8 @@ export const qlipVitestPlugin = (options = {}) => {
                     consoleLogExcludePatterns: options.consoleLogExcludePatterns ?? [],
                 },
                 tool: { name: TOOL_NAME, version },
+                // Read here, in Node, because the browser runtime has no env.
+                diagnostics: options.diagnostics ?? process.env['QLIP_DEBUG'] === '1',
             };
             const setupTs = fileURLToPath(new URL('../runtime/setup.ts', import.meta.url));
             const setupJs = fileURLToPath(new URL('../runtime/setup.js', import.meta.url));

package/dist/runtime/context.d.ts

@@ -7,20 +7,32 @@ export interface QlipRuntimeState {
     warnedMissingStorybook: boolean;
     consoleLogs: QlipConsoleMessage[];
     /**
-     * Unique-per-browser-context identifier used as the fragment
-     * filename when writing this context's manifest to
-     * `<buildDir>/manifest-fragments/`. Each `*.stories.tsx` runs in
-     * its own browser context with its own QlipRuntimeState (initialized
-     * here); without a per-context fragment, contexts would overwrite
-     * each other's writes to a shared `manifest.json`. See
-     * `src/upload/manifest.ts` for the Node-side merge.
+     * Identifies this browser context in the fragment file names it
+     * writes under `<buildDir>/manifest-fragments/`. Paired with
+     * `fragmentSeq` it makes every capture's file name unique, which is
+     * what lets fragments be append-only. See `src/upload/manifest.ts`
+     * for the Node-side merge.
      */
     fragmentId: string;
+    /**
+     * Captures written by this context so far. Incremented per fragment
+     * write; never reused, so no fragment file is ever written twice.
+     */
+    fragmentSeq: number;
 }
 export declare const getRuntimeState: () => QlipRuntimeState | null;
 export declare const initRuntimeState: () => QlipRuntimeState | null;
 export declare const nextStepName: (state: QlipRuntimeState, storyId: string) => string;
 export declare const pushEntry: (state: QlipRuntimeState, entry: QlipManifestEntry) => void;
+/**
+ * Claim the next fragment sequence number for this context.
+ *
+ * Synchronous and unshared, so two overlapping captures — the
+ * `afterEach` hooks of two test files in one context under
+ * `isolate: false` — can never claim the same number, and therefore
+ * never write the same fragment file.
+ */
+export declare const nextFragmentSeq: (state: QlipRuntimeState) => number;
 /**
  * Remove every `error`-kind entry for `storyId` from the in-memory
  * manifest. Returns the removed entries so the caller can delete their

package/dist/runtime/context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/runtime/context.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kBAAkB,EAClB,YAAY,EACZ,iBAAiB,EACjB,iBAAiB,EAClB,MAAM,aAAa,CAAC;AAIrB,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,iBAAiB,CAAC;IAC1B,QAAQ,EAAE,YAAY,CAAC;IACvB,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,sBAAsB,EAAE,OAAO,CAAC;IAChC,WAAW,EAAE,kBAAkB,EAAE,CAAC;IAClC;;;;;;;;OAQG;IACH,UAAU,EAAE,MAAM,CAAC;CACpB;AAyBD,eAAO,MAAM,eAAe,QAAO,gBAAgB,GAAG,IAKrD,CAAC;AAEF,eAAO,MAAM,gBAAgB,QAAO,gBAAgB,GAAG,IA0CtD,CAAC;AAEF,eAAO,MAAM,YAAY,GACvB,OAAO,gBAAgB,EACvB,SAAS,MAAM,KACd,MAKF,CAAC;AAEF,eAAO,MAAM,SAAS,GACpB,OAAO,gBAAgB,EACvB,OAAO,iBAAiB,SAGzB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,sBAAsB,GACjC,OAAO,gBAAgB,EACvB,SAAS,MAAM,KACd,iBAAiB,EAmBnB,CAAC;AAEF,eAAO,MAAM,WAAW,GAAI,OAAO,gBAAgB,EAAE,SAAS,OAAO,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC,SAM3F,CAAC;AAEF,eAAO,MAAM,oBAAoB,GAAI,OAAO,gBAAgB,SAE3D,CAAC;AAEF,eAAO,MAAM,cAAc,GACzB,OAAO,gBAAgB,EACvB,KAAK,kBAAkB,EACvB,SAAS,MAAM,SAKhB,CAAC;AAEF,eAAO,MAAM,gBAAgB,GAC3B,OAAO,gBAAgB,KACtB,kBAAkB,EAIpB,CAAC"}
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/runtime/context.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kBAAkB,EAClB,YAAY,EACZ,iBAAiB,EACjB,iBAAiB,EAClB,MAAM,aAAa,CAAC;AAIrB,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,iBAAiB,CAAC;IAC1B,QAAQ,EAAE,YAAY,CAAC;IACvB,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,sBAAsB,EAAE,OAAO,CAAC;IAChC,WAAW,EAAE,kBAAkB,EAAE,CAAC;IAClC;;;;;;OAMG;IACH,UAAU,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,WAAW,EAAE,MAAM,CAAC;CACrB;AAyBD,eAAO,MAAM,eAAe,QAAO,gBAAgB,GAAG,IAKrD,CAAC;AAEF,eAAO,MAAM,gBAAgB,QAAO,gBAAgB,GAAG,IA4CtD,CAAC;AAEF,eAAO,MAAM,YAAY,GACvB,OAAO,gBAAgB,EACvB,SAAS,MAAM,KACd,MAKF,CAAC;AAEF,eAAO,MAAM,SAAS,GACpB,OAAO,gBAAgB,EACvB,OAAO,iBAAiB,SAGzB,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe,GAAI,OAAO,gBAAgB,KAAG,MAGzD,CAAC;AAEF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,sBAAsB,GACjC,OAAO,gBAAgB,EACvB,SAAS,MAAM,KACd,iBAAiB,EAmBnB,CAAC;AAEF,eAAO,MAAM,WAAW,GAAI,OAAO,gBAAgB,EAAE,SAAS,OAAO,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC,SAM3F,CAAC;AAEF,eAAO,MAAM,oBAAoB,GAAI,OAAO,gBAAgB,SAE3D,CAAC;AAEF,eAAO,MAAM,cAAc,GACzB,OAAO,gBAAgB,EACvB,KAAK,kBAAkB,EACvB,SAAS,MAAM,SAKhB,CAAC;AAEF,eAAO,MAAM,gBAAgB,GAC3B,OAAO,gBAAgB,KACtB,kBAAkB,EAIpB,CAAC"}

package/dist/runtime/context.js

@@ -40,10 +40,11 @@ export const initRuntimeState = () => {
         tool: runtimeConfig.tool,
     });
     // Fragment ID needs to be unique per browser context, not unique per
-    // build. Stamp time + random suffix is plenty (each context is its
-    // own process / module graph, so two contexts can't race here).
-    // Math.random() alone would collide ~1 in 16M; with the millis
-    // prefix that risk is gone.
+    // build: under `isolate: false` several test files share one context
+    // (and one of these states), and several vitest processes can share
+    // one build dir. Stamp time + random suffix covers both — Math.random()
+    // alone would collide ~1 in 16M; with the millis prefix that risk is
+    // gone.
     const fragmentId = `${realDateNow().toString(36)}-${Math.random()
         .toString(36)
         .slice(2, 10)}`;
@@ -55,6 +56,7 @@ export const initRuntimeState = () => {
         warnedMissingStorybook: false,
         consoleLogs: [],
         fragmentId,
+        fragmentSeq: 0,
     };
     const globalState = globalThis;
     globalState[GLOBAL_KEY] = runtime;
@@ -69,6 +71,18 @@ export const nextStepName = (state, storyId) => {
 export const pushEntry = (state, entry) => {
     state.manifest.entries.push(entry);
 };
+/**
+ * Claim the next fragment sequence number for this context.
+ *
+ * Synchronous and unshared, so two overlapping captures — the
+ * `afterEach` hooks of two test files in one context under
+ * `isolate: false` — can never claim the same number, and therefore
+ * never write the same fragment file.
+ */
+export const nextFragmentSeq = (state) => {
+    state.fragmentSeq += 1;
+    return state.fragmentSeq;
+};
 /**
  * Remove every `error`-kind entry for `storyId` from the in-memory
  * manifest. Returns the removed entries so the caller can delete their

package/dist/runtime/screenshot.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"screenshot.d.ts","sourceRoot":"","sources":["../../src/runtime/screenshot.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,qBAAqB,EACrB,gBAAgB,EAEjB,MAAM,aAAa,CAAC;AA2BrB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAC;AAqJ1C;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,0BAA0B,GACrC,SAAS,MAAM;AACf;;;;;;;GAOG;AACH,gBAAgB,MAAM,KACrB;IAAE,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;IAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAA;CAiCvD,CAAC;AAwDF;;;;;;;GAOG;AACH,eAAO,MAAM,0BAA0B,GAAI,qEAIxC;IACD,iBAAiB,EAAE,OAAO,CAAC;IAC3B,oBAAoB,EAAE,OAAO,CAAC;IAC9B,qBAAqB,EAAE,OAAO,CAAC;CAChC,SA+DA,CAAC;AAyaF,eAAO,MAAM,UAAU,GACrB,KAAK,gBAAgB,EACrB,gBAAgB,MAAM,GAAG,qBAAqB,EAC9C,UAAU,qBAAqB,kBA0BhC,CAAC;AAEF,KAAK,eAAe,GAAG,WAAW,GAAG;IAAE,KAAK,CAAC,EAAE,gBAAgB,CAAA;CAAE,CAAC;AA8ClE,eAAO,MAAM,qBAAqB,GAAU,KAAK,eAAe,kBA0F/D,CAAC;AAEF,eAAO,MAAM,sBAAsB,GAAU,KAAK,eAAe,kBAkEhE,CAAC"}
+{"version":3,"file":"screenshot.d.ts","sourceRoot":"","sources":["../../src/runtime/screenshot.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,qBAAqB,EACrB,gBAAgB,EAEjB,MAAM,aAAa,CAAC;AA8BrB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAC;AA8L1C;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,0BAA0B,GACrC,SAAS,MAAM;AACf;;;;;;;GAOG;AACH,gBAAgB,MAAM,KACrB;IAAE,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;IAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAA;CAiCvD,CAAC;AAwDF;;;;;;;GAOG;AACH,eAAO,MAAM,0BAA0B,GAAI,qEAIxC;IACD,iBAAiB,EAAE,OAAO,CAAC;IAC3B,oBAAoB,EAAE,OAAO,CAAC;IAC9B,qBAAqB,EAAE,OAAO,CAAC;CAChC,SA+DA,CAAC;AA+ZF,eAAO,MAAM,UAAU,GACrB,KAAK,gBAAgB,EACrB,gBAAgB,MAAM,GAAG,qBAAqB,EAC9C,UAAU,qBAAqB,kBA0BhC,CAAC;AAEF,KAAK,eAAe,GAAG,WAAW,GAAG;IAAE,KAAK,CAAC,EAAE,gBAAgB,CAAA;CAAE,CAAC;AA8ClE,eAAO,MAAM,qBAAqB,GAAU,KAAK,eAAe,kBAiG/D,CAAC;AAEF,eAAO,MAAM,sBAAsB,GAAU,KAAK,eAAe,kBAkEhE,CAAC"}

package/dist/runtime/screenshot.js

@@ -1,9 +1,31 @@
 import { resolveQlipOptions } from '../config/parameters.js';
 import { monotonicNow, realClearInterval, realSetInterval, realSetTimeout, } from './clock.js';
-import { AUTO_ERROR_SCREENSHOT_BASE, MANIFEST_FRAGMENT_DIR, buildAutoLogPath, buildAutoScreenshotPath, buildManualLogPath, buildManualScreenshotPath, joinPath, sanitizeSegment, } from '../fs/output.js';
-import { flushConsoleLogs, initRuntimeState, markStorybookWarning, nextStepName, pruneStaleErrorEntries, pushEntry, updateStats, } from './context.js';
-const writeManifestFragment = async (commands, buildDir, fragmentId, manifest) => {
-    await commands.writeFile(joinPath(buildDir, MANIFEST_FRAGMENT_DIR, `${fragmentId}.json`), JSON.stringify(manifest, null, 2), 'utf-8');
+import { AUTO_ERROR_SCREENSHOT_BASE, MANIFEST_FRAGMENT_DIR, buildAutoLogPath, buildAutoScreenshotPath, buildManualLogPath, buildManualScreenshotPath, fragmentFileName, joinPath, sanitizeSegment, } from '../fs/output.js';
+import { flushConsoleLogs, initRuntimeState, markStorybookWarning, nextFragmentSeq, nextStepName, pruneStaleErrorEntries, pushEntry, updateStats, } from './context.js';
+const writeManifestFragment = async (commands, state, payload) => {
+    const seq = nextFragmentSeq(state);
+    const fragment = {
+        ...state.manifest,
+        entries: payload.entries ?? [],
+        fragmentId: state.fragmentId,
+        fragmentSeq: seq,
+        ...(payload.tombstones ? { tombstones: payload.tombstones } : {}),
+    };
+    // JSON.stringify runs to completion before the first await, so the
+    // payload is a consistent snapshot even while a concurrent capture
+    // mutates the shared manifest.
+    const data = JSON.stringify(fragment, null, 2);
+    await commands.writeFile(joinPath(state.config.buildDir, MANIFEST_FRAGMENT_DIR, fragmentFileName(state.fragmentId, seq)), data, 'utf-8');
+    if (state.config.diagnostics === true) {
+        for (const entry of payload.entries ?? []) {
+            // eslint-disable-next-line no-console
+            console.log(`[qlip] captured ${entry.storyId} ${entry.kind}/${entry.status} → ${entry.path} (ctx ${state.fragmentId} #${String(seq)})`);
+        }
+        for (const tombstone of payload.tombstones ?? []) {
+            // eslint-disable-next-line no-console
+            console.log(`[qlip] retracted ${tombstone.storyId} ${tombstone.kind} (ctx ${state.fragmentId} #${String(seq)})`);
+        }
+    }
 };
 /**
  * Best-effort file deletion for retry-mask pruning. Silent no-op when
@@ -398,7 +420,7 @@ const captureScreenshot = async ({ kind, story, screenshotName, options, testErr
     const usesNamedPath = kind === 'manual' || kind === 'error';
     if (resolved.skip) {
         flushConsoleLogs(runtime);
-        pushEntry(runtime, buildEntry({
+        const skippedEntry = buildEntry({
             kind,
             storyId: story.id,
             storyTitle: story.title,
@@ -425,14 +447,17 @@ const captureScreenshot = async ({ kind, story, screenshotName, options, testErr
             status: 'skipped',
             error: testError ?? null,
             timingsMs: monotonicNow() - captureStart,
-        }));
+        });
+        pushEntry(runtime, skippedEntry);
         updateStats(runtime, {
             storiesTotal: kind === 'auto'
                 ? runtime.manifest.stats.storiesTotal + 1
                 : runtime.manifest.stats.storiesTotal,
             skipped: runtime.manifest.stats.skipped + 1,
         });
-        await writeManifestFragment(commands, runtime.config.buildDir, runtime.fragmentId, runtime.manifest);
+        await writeManifestFragment(commands, runtime, {
+            entries: [skippedEntry],
+        });
         return;
     }
     let relativePath = '';
@@ -561,7 +586,7 @@ const captureScreenshot = async ({ kind, story, screenshotName, options, testErr
                 : runtime.manifest.stats.failed,
         });
     }
-    await writeManifestFragment(commands, runtime.config.buildDir, runtime.fragmentId, runtime.manifest);
+    await writeManifestFragment(commands, runtime, { entries: [entry] });
 };
 export const screenshot = async (ctx, nameOrOptions, options) => {
     const runtime = initRuntimeState();
@@ -688,6 +713,13 @@ export const captureAutoScreenshot = async (ctx) => {
         const pruned = pruneStaleErrorEntries(runtime, story.id);
         if (pruned.length) {
             const { commands } = await ensureBrowserContext();
+            // Fragments are append-only, so dropping the entries from the
+            // in-memory manifest no longer removes them from disk — the
+            // fragments that carried them were already written. Retract them
+            // with a tombstone the merger applies.
+            await writeManifestFragment(commands, runtime, {
+                tombstones: [{ storyId: story.id, kind: 'error' }],
+            });
             for (const entry of pruned) {
                 if (entry.path) {
                     await bestEffortRemoveFile(commands, joinPath(runtime.config.buildDir, entry.path));

package/dist/test-runner/cli/upload.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"upload.d.ts","sourceRoot":"","sources":["../../../src/test-runner/cli/upload.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AA0HH,MAAM,WAAW,gBAAgB;IAC/B,+CAA+C;IAC/C,QAAQ,EAAE,MAAM,CAAC;IACjB,uEAAuE;IACvE,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;GAIG;AACH,eAAO,MAAM,SAAS,GACpB,MAAM,MAAM,EAAE,EACd,MAAK,MAAM,CAAC,UAAwB,EACpC,SAAQ;IAAE,GAAG,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAAC,KAAK,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAA;CAAY,KAC7E,OAAO,CAAC,gBAAgB,CAoE1B,CAAC"}
+{"version":3,"file":"upload.d.ts","sourceRoot":"","sources":["../../../src/test-runner/cli/upload.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAoIH,MAAM,WAAW,gBAAgB;IAC/B,+CAA+C;IAC/C,QAAQ,EAAE,MAAM,CAAC;IACjB,uEAAuE;IACvE,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;GAIG;AACH,eAAO,MAAM,SAAS,GACpB,MAAM,MAAM,EAAE,EACd,MAAK,MAAM,CAAC,UAAwB,EACpC,SAAQ;IAAE,GAAG,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAAC,KAAK,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAA;CAAY,KAC7E,OAAO,CAAC,gBAAgB,CAsE1B,CAAC"}

package/dist/test-runner/cli/upload.js

@@ -54,12 +54,18 @@ Options:
   --commit <sha>              Override commit detection.
   --fail-on-upload-error      Exit non-zero on upload failure (default:
                               log error + exit 0).
+  --fail-on-partial-build     Exit non-zero when screenshots on disk are
+                              missing from the manifest (default: warn).
   -h, --help                  Show this help.
 
 Env vars override defaults; CLI flags override env vars.
 `;
 const parseArgs = (argv) => {
-    const args = { failOnUploadError: false, help: false };
+    const args = {
+        failOnUploadError: false,
+        failOnPartialBuild: false,
+        help: false,
+    };
     for (let i = 0; i < argv.length; i += 1) {
         const arg = argv[i];
         const next = () => argv[++i];
@@ -92,6 +98,9 @@ const parseArgs = (argv) => {
             case '--fail-on-upload-error':
                 args.failOnUploadError = true;
                 break;
+            case '--fail-on-partial-build':
+                args.failOnPartialBuild = true;
+                break;
             default:
                 if (arg.startsWith('-')) {
                     throw new Error(`Unknown option: ${arg}`);
@@ -172,6 +181,7 @@ export const runUpload = async (argv, env = process.env, logger = console) => {
         ...(parsed.branch !== undefined ? { branch: parsed.branch } : {}),
         ...(parsed.commit !== undefined ? { commit: parsed.commit } : {}),
         failOnUploadError: parsed.failOnUploadError,
+        failOnPartialBuild: parsed.failOnPartialBuild,
     };
     // finalizeBuild needs a runtime config but only reads `buildDir`
     // off it. We can synthesize a minimal one — the manifest itself
@@ -189,8 +199,9 @@ export const runUpload = async (argv, env = process.env, logger = console) => {
         await finalizeBuild({ runtime, upload });
     }
     catch (err) {
-        // finalizeBuild only throws if failOnUploadError is set AND
-        // upload failed. So if we get here, the CLI should exit non-zero.
+        // finalizeBuild only throws when the caller opted in: upload
+        // failed with --fail-on-upload-error, or the build came out
+        // partial with --fail-on-partial-build. Either way, exit non-zero.
         logger.error(`qlip-upload: ${err.message}`);
         return { exitCode: 2, buildDir };
     }

package/dist/test-runner/index.js

@@ -45,7 +45,7 @@ import { promises as fs } from 'node:fs';
 import path from 'node:path';
 import { resolveQlipOptions } from '../config/parameters.js';
 import { DEFAULT_OUTPUT_DIR, DEFAULT_VIEWPORT, MANIFEST_FRAGMENT_DIR, TOOL_NAME, buildAutoScreenshotPath, generateBuildId, } from '../fs/output.js';
-import { flushFragmentToDisk, getOrInitStore, nextStepName, peekStore, pushEntry, } from './manifest-store.js';
+import { writeEntryFragment, getOrInitStore, nextStepName, peekStore, pushEntry, } from './manifest-store.js';
 import { applyAnimationControlInPage, applyIgnoreMasksInPage, removeIgnoreMasksInPage, waitForDomIdleInPage, } from './prep-scripts.js';
 import { QLIP_TOOL_VERSION } from './version.js';
 /**
@@ -217,7 +217,7 @@ const qlipCaptureInner = async (page, context, options) => {
             timingsMs: Date.now() - captureStart,
         });
         pushEntry(store, entry);
-        await flushFragmentToDisk(store);
+        await writeEntryFragment(store, entry);
         return entry;
     }
     let status = 'captured';
@@ -276,7 +276,7 @@ const qlipCaptureInner = async (page, context, options) => {
     pushEntry(store, entry);
     // Persist after every capture so the separate qlip-upload process
     // sees the latest state even if the test run is interrupted.
-    await flushFragmentToDisk(store);
+    await writeEntryFragment(store, entry);
     return entry;
 };
 export { nextStepName }; // exposed for the manual-screenshot path (v1.5)

package/dist/test-runner/manifest-store.d.ts

@@ -39,16 +39,18 @@ export interface IQlipTestRunnerStore {
     /** ms-since-epoch at first capture, for `durationMs`. */
     startedAt: number;
     /**
-     * Per-process fragment ID. Each Jest worker / test-runner shard
-     * gets its own fragment file under `manifest-fragments/`. Lines
-     * up with the Vitest plugin path's fragment-per-browser-context
-     * model so `mergeManifestFragments()` (in `src/upload/manifest.ts`)
-     * works identically across both capture paths.
+     * Per-process fragment ID, prefixing every fragment file this
+     * process writes under `manifest-fragments/`. Lines up with the
+     * Vitest plugin path's model so `mergeManifestFragments()` (in
+     * `src/upload/manifest.ts`) works identically across both capture
+     * paths.
      *
      * Random + timestamp keeps it unique across parallel workers
      * without coordination.
      */
     fragmentId: string;
+    /** Captures written so far; see `QlipRuntimeState.fragmentSeq`. */
+    fragmentSeq: number;
 }
 /**
  * Get-or-initialise the per-process store. Idempotent; safe to
@@ -62,16 +64,16 @@ export declare const getOrInitStore: (init: {
     toolVersion: string;
 }) => IQlipTestRunnerStore;
 /**
- * Write the current store's full manifest to its fragment file on
- * disk. Called after every capture so the qlip-upload CLI (a
- * separate process) can read the latest state at end-of-run.
+ * Write one capture's fragment to disk. Called after every capture so
+ * the qlip-upload CLI (a separate process) sees it even if the run is
+ * interrupted.
  *
- * Cheap: ~5 KB JSON written per capture, well within macOS/Linux
- * filesystem cache. We overwrite each call rather than appending —
- * the file's contents always reflect THIS process's full
- * accumulated manifest.
+ * Append-only, matching the Vitest path: a fragment file is named for
+ * `(fragmentId, seq)` and therefore written exactly once, so no two
+ * captures — in this process or any other sharing the build dir — can
+ * clobber each other. See `design/MANIFEST_FRAGMENTS.md`.
  */
-export declare const flushFragmentToDisk: (store: IQlipTestRunnerStore) => Promise<void>;
+export declare const writeEntryFragment: (store: IQlipTestRunnerStore, entry: QlipManifestEntry) => Promise<void>;
 /**
  * Read the current store. Returns `undefined` if `qlipCapture` was
  * never invoked (e.g. globalSetup teardown firing on a run with no

package/dist/test-runner/manifest-store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"manifest-store.d.ts","sourceRoot":"","sources":["../../src/test-runner/manifest-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAIH,OAAO,KAAK,EACV,YAAY,EACZ,iBAAiB,EACjB,oBAAoB,EACrB,MAAM,aAAa,CAAC;AASrB,MAAM,WAAW,oBAAoB;IACnC,yDAAyD;IACzD,QAAQ,EAAE,MAAM,CAAC;IACjB,gEAAgE;IAChE,OAAO,EAAE,MAAM,CAAC;IAChB,qEAAqE;IACrE,SAAS,EAAE,MAAM,CAAC;IAClB,0DAA0D;IAC1D,QAAQ,EAAE,YAAY,CAAC;IACvB,4DAA4D;IAC5D,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9B,yDAAyD;IACzD,SAAS,EAAE,MAAM,CAAC;IAClB;;;;;;;;;OASG;IACH,UAAU,EAAE,MAAM,CAAC;CACpB;AAQD;;;GAGG;AACH,eAAO,MAAM,cAAc,GAAI,MAAM;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,oBAAoB,CAAC;IAC/B,WAAW,EAAE,MAAM,CAAC;CACrB,KAAG,oBA4BH,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,mBAAmB,GAC9B,OAAO,oBAAoB,KAC1B,OAAO,CAAC,IAAI,CAWd,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,SAAS,QAAO,oBAAoB,GAAG,SAEnD,CAAC;AAEF,sEAAsE;AACtE,eAAO,MAAM,UAAU,QAAO,IAE7B,CAAC;AAEF,yDAAyD;AACzD,eAAO,MAAM,SAAS,GACpB,OAAO,oBAAoB,EAC3B,OAAO,iBAAiB,KACvB,IAaF,CAAC;AAEF,gEAAgE;AAChE,eAAO,MAAM,YAAY,GACvB,OAAO,oBAAoB,EAC3B,SAAS,MAAM,KACd,MAKF,CAAC"}
+{"version":3,"file":"manifest-store.d.ts","sourceRoot":"","sources":["../../src/test-runner/manifest-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAIH,OAAO,KAAK,EACV,YAAY,EACZ,iBAAiB,EAEjB,oBAAoB,EACrB,MAAM,aAAa,CAAC;AAUrB,MAAM,WAAW,oBAAoB;IACnC,yDAAyD;IACzD,QAAQ,EAAE,MAAM,CAAC;IACjB,gEAAgE;IAChE,OAAO,EAAE,MAAM,CAAC;IAChB,qEAAqE;IACrE,SAAS,EAAE,MAAM,CAAC;IAClB,0DAA0D;IAC1D,QAAQ,EAAE,YAAY,CAAC;IACvB,4DAA4D;IAC5D,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9B,yDAAyD;IACzD,SAAS,EAAE,MAAM,CAAC;IAClB;;;;;;;;;OASG;IACH,UAAU,EAAE,MAAM,CAAC;IACnB,mEAAmE;IACnE,WAAW,EAAE,MAAM,CAAC;CACrB;AAQD;;;GAGG;AACH,eAAO,MAAM,cAAc,GAAI,MAAM;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,oBAAoB,CAAC;IAC/B,WAAW,EAAE,MAAM,CAAC;CACrB,KAAG,oBA6BH,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,kBAAkB,GAC7B,OAAO,oBAAoB,EAC3B,OAAO,iBAAiB,KACvB,OAAO,CAAC,IAAI,CAkBd,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,SAAS,QAAO,oBAAoB,GAAG,SAEnD,CAAC;AAEF,sEAAsE;AACtE,eAAO,MAAM,UAAU,QAAO,IAE7B,CAAC;AAEF,yDAAyD;AACzD,eAAO,MAAM,SAAS,GACpB,OAAO,oBAAoB,EAC3B,OAAO,iBAAiB,KACvB,IAaF,CAAC;AAEF,gEAAgE;AAChE,eAAO,MAAM,YAAY,GACvB,OAAO,oBAAoB,EAC3B,SAAS,MAAM,KACd,MAKF,CAAC"}

package/dist/test-runner/manifest-store.js

@@ -26,7 +26,7 @@
  */
 import { promises as fs } from 'node:fs';
 import path from 'node:path';
-import { MANIFEST_FRAGMENT_DIR, TOOL_NAME, createManifest, } from '../fs/output.js';
+import { MANIFEST_FRAGMENT_DIR, TOOL_NAME, createManifest, fragmentFileName, } from '../fs/output.js';
 const STORE_KEY = Symbol.for('@qoretechnologies/qlip/__test_runner_store__');
 const holder = () => globalThis;
 /**
@@ -57,23 +57,31 @@ export const getOrInitStore = (init) => {
         counters: new Map(),
         startedAt: Date.now(),
         fragmentId,
+        fragmentSeq: 0,
     };
     holder()[STORE_KEY] = store;
     return store;
 };
 /**
- * Write the current store's full manifest to its fragment file on
- * disk. Called after every capture so the qlip-upload CLI (a
- * separate process) can read the latest state at end-of-run.
+ * Write one capture's fragment to disk. Called after every capture so
+ * the qlip-upload CLI (a separate process) sees it even if the run is
+ * interrupted.
  *
- * Cheap: ~5 KB JSON written per capture, well within macOS/Linux
- * filesystem cache. We overwrite each call rather than appending —
- * the file's contents always reflect THIS process's full
- * accumulated manifest.
+ * Append-only, matching the Vitest path: a fragment file is named for
+ * `(fragmentId, seq)` and therefore written exactly once, so no two
+ * captures — in this process or any other sharing the build dir — can
+ * clobber each other. See `design/MANIFEST_FRAGMENTS.md`.
  */
-export const flushFragmentToDisk = async (store) => {
-    const fragmentPath = path.join(store.buildDir, MANIFEST_FRAGMENT_DIR, `${store.fragmentId}.json`);
-    await fs.writeFile(fragmentPath, JSON.stringify(store.manifest, null, 2), 'utf-8');
+export const writeEntryFragment = async (store, entry) => {
+    store.fragmentSeq += 1;
+    const seq = store.fragmentSeq;
+    const fragment = {
+        ...store.manifest,
+        entries: [entry],
+        fragmentId: store.fragmentId,
+        fragmentSeq: seq,
+    };
+    await fs.writeFile(path.join(store.buildDir, MANIFEST_FRAGMENT_DIR, fragmentFileName(store.fragmentId, seq)), JSON.stringify(fragment, null, 2), 'utf-8');
 };
 /**
  * Read the current store. Returns `undefined` if `qlipCapture` was

package/dist/types.d.ts

@@ -101,6 +101,13 @@ export interface QlipUploadOptions {
      * Set to `true` in CI when you want red builds on upload errors.
      */
     failOnUploadError?: boolean;
+    /**
+     * Whether a partial build should fail the run. A build is partial
+     * when PNGs exist on disk that no manifest entry references — i.e.
+     * captures whose manifest record was lost. Default: `false` (warn
+     * only). See `design/MANIFEST_FRAGMENTS.md`.
+     */
+    failOnPartialBuild?: boolean;
 }
 export interface QlipPluginOptions extends QlipCaptureOptions {
     outputDir?: string;
@@ -111,6 +118,13 @@ export interface QlipPluginOptions extends QlipCaptureOptions {
      * happens — the screenshots stay on local disk.
      */
     upload?: QlipUploadOptions;
+    /**
+     * Log one line per capture (story, kind, path, context + sequence)
+     * and keep it in the build's `capture-report.json`. Off by default;
+     * `$QLIP_DEBUG=1` turns it on without touching config. Use it when a
+     * CI build captured fewer stories than it ran.
+     */
+    diagnostics?: boolean;
 }
 export type QlipResolvedDefaults = Required<QlipCaptureOptions> & {
     outputDir: string;
@@ -125,6 +139,8 @@ export interface QlipRuntimeConfig {
         name: string;
         version: string;
     };
+    /** See `QlipPluginOptions.diagnostics`. */
+    diagnostics?: boolean;
 }
 export interface QlipScreenshotOptions extends QlipCaptureOptions {
     name?: string;
@@ -256,4 +272,35 @@ export interface QlipManifest {
     };
     entries: QlipManifestEntry[];
 }
+/**
+ * Marks every entry for `(storyId, kind)` as stale, whatever order the
+ * fragments merge in. Written by the retry-mask prune when a story
+ * passes on a later attempt: the error captures from the failed
+ * attempts are no longer real failures. Order-independent by design —
+ * "this story ultimately passed" is true regardless of when the
+ * tombstone lands relative to the entries it retracts.
+ */
+export interface QlipManifestTombstone {
+    storyId: string;
+    kind: QlipEntryKind;
+}
+/**
+ * One capture's on-disk record under `<buildDir>/manifest-fragments/`.
+ *
+ * Fragments are append-only: one file per capture, written exactly
+ * once and never rewritten, so concurrent captures — in one context,
+ * across contexts, or across processes sharing a `--build-dir` —
+ * cannot clobber each other. `entries` therefore holds a single entry
+ * (or none, for a tombstone-only fragment), but the merger accepts any
+ * count so fragments written by older qlip versions still merge.
+ *
+ * See `design/MANIFEST_FRAGMENTS.md`.
+ */
+export interface QlipManifestFragment extends QlipManifest {
+    /** Identifies the writing browser context / process. */
+    fragmentId?: string;
+    /** Per-context capture counter; orders entries within a context. */
+    fragmentSeq?: number;
+    tombstones?: QlipManifestTombstone[];
+}
 //# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}