@testivai/witness 1.11.1 → 1.13.0

package/README.md

@@ -12,14 +12,13 @@ The TestivAI Witness SDK allows you to integrate visual regression testing into
 npm install -D @testivai/witness
 ```
 
-## Quick Start (Local Mode — Free)
+## Quick Start
 
-TestivAI works in **local mode** without any API key or cloud account:
+TestivAI runs entirely on your machine — no account, no server, nothing uploaded:
 
 1. **Initialize your project**
    ```bash
    npx testivai init
-   # Select "Local Mode" when prompted
    ```
 
 2. **Add visual captures to your tests**
@@ -45,17 +44,12 @@ TestivAI works in **local mode** without any API key or cloud account:
    npx testivai approve --all
    ```
 
-## Quick Start (Cloud Mode)
+## Sharing results with your team
 
-For team collaboration and hosted dashboards:
+Everything stays on your machine. To get a diff in front of a teammate:
 
-1. **Get an API key** at [testiv.ai](https://testiv.ai)
-2. **Set your API key**
-   ```bash
-   export TESTIVAI_API_KEY=your-api-key
-   ```
-3. Follow steps 1–3 from local mode above
-4. Results will upload to the cloud dashboard automatically
+- **In a PR** — the [`mcbuddy/testivai-oss` action](https://github.com/mcbuddy/testivai-oss) posts the summary as a PR comment and uploads the report as a build artifact. Approve from the PR with a `/testivai approve` comment.
+- **As a single file** — `npx testivai report --share` writes `visual-report/share.html` with every image inlined, so it works over chat or email with no server. Set `shareUploadCommand` in `.testivai/config.json` to pipe it to your own storage (S3, GCS, or anything with a CLI).
 
 ## Framework Integration
 
@@ -159,7 +153,7 @@ testivai run "npx wdio"
    - Page structure extraction
    - Layout analysis
    - Performance metrics
-5. **Batch Upload**: All captures are batched and uploaded to TestivAI for analysis
+5. **Compare & report**: Captures are diffed against `.testivai/baselines/` and written to `visual-report/` (HTML + `results.json`)
 
 ## Configuration
 
@@ -169,12 +163,6 @@ Create a `testivai.config.ts` file in your project root:
 import type { WitnessConfig } from '@testivai/witness';
 
 const config: WitnessConfig = {
-  // API key (set via TESTIVAI_API_KEY environment variable)
-  // apiKey: 'your-api-key-here',
-  
-  // Project ID from TestivAI dashboard
-  // projectId: 'your-project-id-here',
-  
   // Chrome remote debugging port
   browserPort: 9222,
   
@@ -204,8 +192,9 @@ export default config;
 ### `npx testivai init`
 Initialize TestivAI in your project. Detects your framework and provides setup instructions.
 
-### `npx testivai auth <api-key>`
-Authenticate with your TestivAI API key. Get your key from the [dashboard](https://dashboard.testiv.ai).
+### `npx testivai auth`
+Deprecated. TestivAI runs fully locally — there is no account or API key. The command
+now only prints a notice and exits.
 
 ### `npx testivai run <command>`
 Run your test command with automatic visual capture.
@@ -306,12 +295,12 @@ jobs:
             --disable-dev-shm-usage \
             --headless \
             --disable-gpu &
-            
-      - name: Authenticate
-        run: testivai auth ${{ secrets.TESTIVAI_API_KEY }}
-        
+
       - name: Run visual tests
         run: testivai run "npm test"
+
+      - name: Visual diff gate
+        run: npx testivai report --fail-on-diff
 ```
 
 ### Jenkins
@@ -342,10 +331,8 @@ pipeline {
     
     stage('Visual Tests') {
       steps {
-        withCredentials([string(credentialsId: 'testivai-api-key', variable: 'API_KEY')]) {
-          sh 'testivai auth $API_KEY'
-          sh 'testivai run "npm test"'
-        }
+        sh 'testivai run "npm test"'
+        sh 'npx testivai report --fail-on-diff'
       }
     }
   }
@@ -388,7 +375,7 @@ chrome --remote-debugging-port=9222
 - **Package size**: ~270KB (no browser binaries included)
 - **Memory usage**: ~50MB additional overhead
 - **Capture time**: ~100-500ms per snapshot
-- **Upload time**: Depends on network and snapshot size
+- **Compare time**: ~50-200ms per snapshot (pixel + DOM diff)
 
 ## API Reference
 

package/dist/bin/testivai.js

@@ -11,6 +11,7 @@ const init_1 = require("../commands/init");
 const run_1 = require("../commands/run");
 const capture_1 = require("../commands/capture");
 const approve_1 = require("../commands/approve");
+const merge_captures_1 = require("../commands/merge-captures");
 const report_1 = require("../commands/report");
 const packageJson = require('../../package.json');
 const program = new commander_1.Command();
@@ -46,6 +47,7 @@ program.addCommand(init_1.initCommand);
 program.addCommand(run_1.runCommand);
 program.addCommand(capture_1.witnessCommand);
 program.addCommand(approve_1.approveCommand);
+program.addCommand(merge_captures_1.mergeCapturesCommand);
 program.addCommand(report_1.reportCommand);
 // Parse arguments
 program.parse();

package/dist/bin/testivai.js.map

@@ -1 +1 @@
-{"version":3,"file":"testivai.js","sourceRoot":"","sources":["../../src/bin/testivai.ts"],"names":[],"mappings":";;;;;;AAEA,yCAAoC;AACpC,kDAA0B;AAC1B,2CAA+C;AAC/C,2CAA+C;AAC/C,yCAA6C;AAC7C,iDAAqD;AACrD,iDAAqD;AACrD,+CAAmD;AAEnD,MAAM,WAAW,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAAC;AAElD,MAAM,OAAO,GAAG,IAAI,mBAAO,EAAE,CAAC;AAE9B,iBAAiB;AACjB,MAAM,UAAU,GAAG,GAAG,EAAE;IACtB,OAAO,CAAC,GAAG,EAAE,CAAC;IACd,OAAO,CAAC,GAAG,CAAC,eAAK,CAAC,IAAI,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC,CAAC;IAC3C,OAAO,CAAC,GAAG,CAAC,eAAK,CAAC,IAAI,CAAC,yCAAyC,CAAC,CAAC,CAAC;IACnE,OAAO,CAAC,GAAG,EAAE,CAAC;AAChB,CAAC,CAAC;AAEF,OAAO;KACJ,IAAI,CAAC,UAAU,CAAC;KAChB,WAAW,CAAC,qEAAqE,CAAC;KAClF,OAAO,CAAC,WAAW,CAAC,OAAO,EAAE,eAAe,EAAE,wBAAwB,CAAC;KACvE,IAAI,CAAC,WAAW,EAAE,GAAG,EAAE;IACtB,wEAAwE;IACxE,kEAAkE;IAClE,MAAM,KAAK,GACT,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC;QAChC,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC;QAC3B,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;IAClC,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,UAAU,EAAE,CAAC;IACf,CAAC;AACH,CAAC,CAAC,CAAC;AAEL,iBAAiB;AACjB,OAAO;KACJ,MAAM,CAAC,eAAe,EAAE,uBAAuB,CAAC;KAChD,MAAM,CAAC,aAAa,EAAE,gCAAgC,CAAC;KACvD,MAAM,CAAC,SAAS,EAAE,mBAAmB,CAAC,CAAC;AAE1C,eAAe;AACf,OAAO,CAAC,UAAU,CAAC,kBAAW,CAAC,CAAC;AAChC,OAAO,CAAC,UAAU,CAAC,kBAAW,CAAC,CAAC;AAChC,OAAO,CAAC,UAAU,CAAC,gBAAU,CAAC,CAAC;AAC/B,OAAO,CAAC,UAAU,CAAC,wBAAc,CAAC,CAAC;AACnC,OAAO,CAAC,UAAU,CAAC,wBAAc,CAAC,CAAC;AACnC,OAAO,CAAC,UAAU,CAAC,sBAAa,CAAC,CAAC;AAElC,kBAAkB;AAClB,OAAO,CAAC,KAAK,EAAE,CAAC;AAEhB,mCAAmC;AACnC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;IAClC,OAAO,CAAC,UAAU,EAAE,CAAC;AACvB,CAAC"}
+{"version":3,"file":"testivai.js","sourceRoot":"","sources":["../../src/bin/testivai.ts"],"names":[],"mappings":";;;;;;AAEA,yCAAoC;AACpC,kDAA0B;AAC1B,2CAA+C;AAC/C,2CAA+C;AAC/C,yCAA6C;AAC7C,iDAAqD;AACrD,iDAAqD;AACrD,+DAAkE;AAClE,+CAAmD;AAEnD,MAAM,WAAW,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAAC;AAElD,MAAM,OAAO,GAAG,IAAI,mBAAO,EAAE,CAAC;AAE9B,iBAAiB;AACjB,MAAM,UAAU,GAAG,GAAG,EAAE;IACtB,OAAO,CAAC,GAAG,EAAE,CAAC;IACd,OAAO,CAAC,GAAG,CAAC,eAAK,CAAC,IAAI,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC,CAAC;IAC3C,OAAO,CAAC,GAAG,CAAC,eAAK,CAAC,IAAI,CAAC,yCAAyC,CAAC,CAAC,CAAC;IACnE,OAAO,CAAC,GAAG,EAAE,CAAC;AAChB,CAAC,CAAC;AAEF,OAAO;KACJ,IAAI,CAAC,UAAU,CAAC;KAChB,WAAW,CAAC,qEAAqE,CAAC;KAClF,OAAO,CAAC,WAAW,CAAC,OAAO,EAAE,eAAe,EAAE,wBAAwB,CAAC;KACvE,IAAI,CAAC,WAAW,EAAE,GAAG,EAAE;IACtB,wEAAwE;IACxE,kEAAkE;IAClE,MAAM,KAAK,GACT,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC;QAChC,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC;QAC3B,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;IAClC,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,UAAU,EAAE,CAAC;IACf,CAAC;AACH,CAAC,CAAC,CAAC;AAEL,iBAAiB;AACjB,OAAO;KACJ,MAAM,CAAC,eAAe,EAAE,uBAAuB,CAAC;KAChD,MAAM,CAAC,aAAa,EAAE,gCAAgC,CAAC;KACvD,MAAM,CAAC,SAAS,EAAE,mBAAmB,CAAC,CAAC;AAE1C,eAAe;AACf,OAAO,CAAC,UAAU,CAAC,kBAAW,CAAC,CAAC;AAChC,OAAO,CAAC,UAAU,CAAC,kBAAW,CAAC,CAAC;AAChC,OAAO,CAAC,UAAU,CAAC,gBAAU,CAAC,CAAC;AAC/B,OAAO,CAAC,UAAU,CAAC,wBAAc,CAAC,CAAC;AACnC,OAAO,CAAC,UAAU,CAAC,wBAAc,CAAC,CAAC;AACnC,OAAO,CAAC,UAAU,CAAC,qCAAoB,CAAC,CAAC;AACzC,OAAO,CAAC,UAAU,CAAC,sBAAa,CAAC,CAAC;AAElC,kBAAkB;AAClB,OAAO,CAAC,KAAK,EAAE,CAAC;AAEhB,mCAAmC;AACnC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;IAClC,OAAO,CAAC,UAAU,EAAE,CAAC;AACvB,CAAC"}

package/dist/capture/element-map.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Element-map capture — the layout + computed-style digest that powers
+ * element attribution, shift classification, and the style fingerprint
+ * on the comparison side (@testivai/witness).
+ *
+ * `collectElementMap` is a SELF-CONTAINED function (no imports, no
+ * closures) so it can be serialized into the page with
+ * `(${collectElementMap.toString()})(document, window, max)` — and unit
+ * tested in Node against a duck-typed DOM. Keep it dependency-free.
+ */
+/**
+ * Minimal structural types for the DOM surface this collector touches.
+ *
+ * This module lives in `@testivai/witness`, which compiles for Node and
+ * deliberately has no `dom` lib — a Node package that can reference
+ * `window` by accident is a footgun. The collector is injected into a
+ * page as a string and unit-tested against a duck-typed DOM, so
+ * structural types are both sufficient and closer to how it is used.
+ */
+export interface ElementLike {
+    tagName: string;
+    classList: {
+        length: number;
+        [index: number]: string;
+    };
+    children: ArrayLike<ElementLike>;
+    parentElement: ElementLike | null;
+    getBoundingClientRect(): {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    matches?(selector: string): boolean;
+}
+export interface DocumentLike {
+    body: ElementLike;
+}
+export interface WindowLike {
+    devicePixelRatio: number;
+    scrollX: number;
+    scrollY: number;
+    getComputedStyle(el: ElementLike): {
+        getPropertyValue(prop: string): string;
+    };
+}
+export interface CollectedElement {
+    path: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    styleHash: string;
+}
+/**
+ * Walk the document and produce [{path, rect, styleHash}] in document
+ * coordinates (DPR-scaled to match full-page screenshot pixels).
+ *
+ * - `path` is deterministic: tag + first class + :nth-of-type when the
+ *   element has same-tag element siblings.
+ * - Elements smaller than 4×4 px and invisible elements are skipped.
+ * - The walk is depth-first and capped at `maxElements`.
+ * - `styleHash` digests a fixed, documented list of computed properties
+ *   (FNV-1a 32-bit, hex) — deterministic for identical rendering.
+ */
+export declare function collectElementMap(doc: DocumentLike, win: WindowLike, maxElements: number, ignoreSelectors?: string[]): CollectedElement[];
+/** Default element cap — bounds capture time and elements.json size. */
+export declare const DEFAULT_MAX_ELEMENTS = 3000;
+/**
+ * The page-side expression evaluated by the adapter. Serializes the
+ * collector so page code and unit-tested code are the same function.
+ */
+export declare function buildElementMapExpression(maxElements?: number, ignoreSelectors?: string[]): string;
+//# sourceMappingURL=element-map.d.ts.map

package/dist/capture/element-map.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"element-map.d.ts","sourceRoot":"","sources":["../../src/capture/element-map.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH;;;;;;;;GAQG;AACH,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAC;IACvD,QAAQ,EAAE,SAAS,CAAC,WAAW,CAAC,CAAC;IACjC,aAAa,EAAE,WAAW,GAAG,IAAI,CAAC;IAClC,qBAAqB,IAAI;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IACjF,OAAO,CAAC,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;CACrC;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,WAAW,CAAC;CACnB;AAED,MAAM,WAAW,UAAU;IACzB,gBAAgB,EAAE,MAAM,CAAC;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,gBAAgB,CAAC,EAAE,EAAE,WAAW,GAAG;QAAE,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAC;CAC/E;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,YAAY,EACjB,GAAG,EAAE,UAAU,EACf,WAAW,EAAE,MAAM,EACnB,eAAe,GAAE,MAAM,EAAO,GAC7B,gBAAgB,EAAE,CAiHpB;AAED,wEAAwE;AACxE,eAAO,MAAM,oBAAoB,OAAO,CAAC;AAEzC;;;GAGG;AACH,wBAAgB,yBAAyB,CACvC,WAAW,GAAE,MAA6B,EAC1C,eAAe,GAAE,MAAM,EAAO,GAC7B,MAAM,CAER"}

package/dist/capture/element-map.js

@@ -0,0 +1,153 @@
+"use strict";
+/**
+ * Element-map capture — the layout + computed-style digest that powers
+ * element attribution, shift classification, and the style fingerprint
+ * on the comparison side (@testivai/witness).
+ *
+ * `collectElementMap` is a SELF-CONTAINED function (no imports, no
+ * closures) so it can be serialized into the page with
+ * `(${collectElementMap.toString()})(document, window, max)` — and unit
+ * tested in Node against a duck-typed DOM. Keep it dependency-free.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_MAX_ELEMENTS = void 0;
+exports.collectElementMap = collectElementMap;
+exports.buildElementMapExpression = buildElementMapExpression;
+/**
+ * Walk the document and produce [{path, rect, styleHash}] in document
+ * coordinates (DPR-scaled to match full-page screenshot pixels).
+ *
+ * - `path` is deterministic: tag + first class + :nth-of-type when the
+ *   element has same-tag element siblings.
+ * - Elements smaller than 4×4 px and invisible elements are skipped.
+ * - The walk is depth-first and capped at `maxElements`.
+ * - `styleHash` digests a fixed, documented list of computed properties
+ *   (FNV-1a 32-bit, hex) — deterministic for identical rendering.
+ */
+function collectElementMap(doc, win, maxElements, ignoreSelectors = []) {
+    var STYLE_PROPS = [
+        'color', 'background-color', 'background-image',
+        'border-top-color', 'border-right-color', 'border-bottom-color', 'border-left-color',
+        'border-top-width', 'border-right-width', 'border-bottom-width', 'border-left-width',
+        'border-top-style', 'border-bottom-style', 'border-radius',
+        'font-family', 'font-size', 'font-weight', 'font-style', 'line-height',
+        'text-align', 'text-transform', 'letter-spacing',
+        'padding-top', 'padding-right', 'padding-bottom', 'padding-left',
+        'margin-top', 'margin-right', 'margin-bottom', 'margin-left',
+        'display', 'opacity', 'visibility', 'box-shadow',
+    ];
+    function fnv1a(str) {
+        var h = 0x811c9dc5;
+        for (var i = 0; i < str.length; i++) {
+            h ^= str.charCodeAt(i);
+            h = (h + ((h << 1) + (h << 4) + (h << 7) + (h << 8) + (h << 24))) >>> 0;
+        }
+        return ('0000000' + h.toString(16)).slice(-8);
+    }
+    function segment(el) {
+        var tag = el.tagName.toLowerCase();
+        var cls = '';
+        if (el.classList && el.classList.length > 0) {
+            cls = '.' + el.classList[0];
+        }
+        var parent = el.parentElement;
+        if (!parent)
+            return tag + cls;
+        var sameTag = 0;
+        var index = 0;
+        for (var i = 0; i < parent.children.length; i++) {
+            var sib = parent.children[i];
+            if (sib.tagName === el.tagName) {
+                sameTag++;
+                if (sib === el)
+                    index = sameTag;
+            }
+        }
+        return sameTag > 1 ? tag + cls + ':nth-of-type(' + index + ')' : tag + cls;
+    }
+    function pathOf(el, stopAt) {
+        var parts = [];
+        var node = el;
+        while (node && node !== stopAt.parentElement) {
+            parts.unshift(segment(node));
+            node = node.parentElement;
+        }
+        return parts.join(' > ');
+    }
+    var dpr = win.devicePixelRatio || 1;
+    var scrollX = win.scrollX || 0;
+    var scrollY = win.scrollY || 0;
+    var out = [];
+    var body = doc.body;
+    if (!body)
+        return out;
+    var stack = [body];
+    while (stack.length > 0 && out.length < maxElements) {
+        var el = stack.pop();
+        // The consistency rule: elements covered by ignoreSelectors are
+        // excluded from pixels and the DOM snapshot — they must be excluded
+        // from the element map too (subtree included), or their dynamic
+        // styles would trip the style fingerprint they were meant to escape.
+        var ignored = false;
+        if (ignoreSelectors.length > 0 && typeof el.matches === 'function') {
+            for (var g = 0; g < ignoreSelectors.length; g++) {
+                try {
+                    if (el.matches(ignoreSelectors[g])) {
+                        ignored = true;
+                        break;
+                    }
+                }
+                catch (e) {
+                    // invalid selector — never breaks the walk
+                }
+            }
+        }
+        if (ignored)
+            continue; // skip element AND subtree
+        var rect = el.getBoundingClientRect();
+        if (rect.width >= 4 && rect.height >= 4) {
+            var styleParts = [];
+            var hidden = false;
+            try {
+                var cs = win.getComputedStyle(el);
+                for (var p = 0; p < STYLE_PROPS.length; p++) {
+                    var value = cs.getPropertyValue(STYLE_PROPS[p]);
+                    if (STYLE_PROPS[p] === 'visibility' && value === 'hidden')
+                        hidden = true;
+                    styleParts.push(STYLE_PROPS[p] + ':' + value);
+                }
+            }
+            catch (e) {
+                // styleHash stays a digest of the empty string — still deterministic
+            }
+            // visibility:hidden elements paint no pixels, so their style changes
+            // can never explain a pixel diff — keep them out of the map. Their
+            // CHILDREN may override visibility, so the subtree still walks.
+            if (!hidden) {
+                out.push({
+                    path: pathOf(el, body),
+                    x: Math.round((rect.x + scrollX) * dpr),
+                    y: Math.round((rect.y + scrollY) * dpr),
+                    width: Math.round(rect.width * dpr),
+                    height: Math.round(rect.height * dpr),
+                    styleHash: fnv1a(styleParts.join(';')),
+                });
+            }
+        }
+        // Push children in reverse so the walk stays document-ordered
+        for (var c = el.children.length - 1; c >= 0; c--) {
+            stack.push(el.children[c]);
+        }
+    }
+    return out;
+}
+/** Default element cap — bounds capture time and elements.json size. */
+exports.DEFAULT_MAX_ELEMENTS = 3000;
+/**
+ * The page-side expression evaluated by the adapter. Serializes the
+ * collector so page code and unit-tested code are the same function.
+ */
+function buildElementMapExpression(maxElements = exports.DEFAULT_MAX_ELEMENTS, ignoreSelectors = []) {
+    return `(${collectElementMap.toString()})(document, window, ${maxElements}, ${JSON.stringify(ignoreSelectors)})`;
+}
+//# sourceMappingURL=element-map.js.map

package/dist/capture/element-map.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"element-map.js","sourceRoot":"","sources":["../../src/capture/element-map.ts"],"names":[],"mappings":";AAAA;;;;;;;;;GASG;;;AAmDH,8CAsHC;AASD,8DAKC;AA/ID;;;;;;;;;;GAUG;AACH,SAAgB,iBAAiB,CAC/B,GAAiB,EACjB,GAAe,EACf,WAAmB,EACnB,kBAA4B,EAAE;IAE9B,IAAI,WAAW,GAAG;QAChB,OAAO,EAAE,kBAAkB,EAAE,kBAAkB;QAC/C,kBAAkB,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,mBAAmB;QACpF,kBAAkB,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,mBAAmB;QACpF,kBAAkB,EAAE,qBAAqB,EAAE,eAAe;QAC1D,aAAa,EAAE,WAAW,EAAE,aAAa,EAAE,YAAY,EAAE,aAAa;QACtE,YAAY,EAAE,gBAAgB,EAAE,gBAAgB;QAChD,aAAa,EAAE,eAAe,EAAE,gBAAgB,EAAE,cAAc;QAChE,YAAY,EAAE,cAAc,EAAE,eAAe,EAAE,aAAa;QAC5D,SAAS,EAAE,SAAS,EAAE,YAAY,EAAE,YAAY;KACjD,CAAC;IAEF,SAAS,KAAK,CAAC,GAAW;QACxB,IAAI,CAAC,GAAG,UAAU,CAAC;QACnB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YACpC,CAAC,IAAI,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;YACvB,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;QAC1E,CAAC;QACD,OAAO,CAAC,SAAS,GAAG,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IAChD,CAAC;IAED,SAAS,OAAO,CAAC,EAAe;QAC9B,IAAI,GAAG,GAAG,EAAE,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC;QACnC,IAAI,GAAG,GAAG,EAAE,CAAC;QACb,IAAI,EAAE,CAAC,SAAS,IAAI,EAAE,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC5C,GAAG,GAAG,GAAG,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;QAC9B,CAAC;QACD,IAAI,MAAM,GAAG,EAAE,CAAC,aAAa,CAAC;QAC9B,IAAI,CAAC,MAAM;YAAE,OAAO,GAAG,GAAG,GAAG,CAAC;QAC9B,IAAI,OAAO,GAAG,CAAC,CAAC;QAChB,IAAI,KAAK,GAAG,CAAC,CAAC;QACd,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,QAAQ,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YAChD,IAAI,GAAG,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;YAC7B,IAAI,GAAG,CAAC,OAAO,KAAK,EAAE,CAAC,OAAO,EAAE,CAAC;gBAC/B,OAAO,EAAE,CAAC;gBACV,IAAI,GAAG,KAAK,EAAE;oBAAE,KAAK,GAAG,OAAO,CAAC;YAClC,CAAC;QACH,CAAC;QACD,OAAO,OAAO,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,GAAG,GAAG,GAAG,eAAe,GAAG,KAAK,GAAG,GAAG,CAAC,CAAC,CAAC,GAAG,GAAG,GAAG,CAAC;IAC7E,CAAC;IAED,SAAS,MAAM,CAAC,EAAe,EAAE,MAAmB;QAClD,IAAI,KAAK,GAAa,EAAE,CAAC;QACzB,IAAI,IAAI,GAAuB,EAAE,CAAC;QAClC,OAAO,IAAI,IAAI,IAAI,KAAK,MAAM,CAAC,aAAa,EAAE,CAAC;YAC7C,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;YAC7B,IAAI,GAAG,IAAI,CAAC,aAAa,CAAC;QAC5B,CAAC;QACD,OAAO,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC3B,CAAC;IAED,IAAI,GAAG,GAAG,GAAG,CAAC,gBAAgB,IAAI,CAAC,CAAC;IACpC,IAAI,OAAO,GAAG,GAAG,CAAC,OAAO,IAAI,CAAC,CAAC;IAC/B,IAAI,OAAO,GAAG,GAAG,CAAC,OAAO,IAAI,CAAC,CAAC;IAC/B,IAAI,GAAG,GAAuB,EAAE,CAAC;IACjC,IAAI,IAAI,GAAG,GAAG,CAAC,IAAI,CAAC;IACpB,IAAI,CAAC,IAAI;QAAE,OAAO,GAAG,CAAC;IAEtB,IAAI,KAAK,GAAkB,CAAC,IAAI,CAAC,CAAC;IAClC,OAAO,KAAK,CAAC,MAAM,GAAG,CAAC,IAAI,GAAG,CAAC,MAAM,GAAG,WAAW,EAAE,CAAC;QACpD,IAAI,EAAE,GAAG,KAAK,CAAC,GAAG,EAAiB,CAAC;QAEpC,gEAAgE;QAChE,oEAAoE;QACpE,gEAAgE;QAChE,qEAAqE;QACrE,IAAI,OAAO,GAAG,KAAK,CAAC;QACpB,IAAI,eAAe,CAAC,MAAM,GAAG,CAAC,IAAI,OAAO,EAAE,CAAC,OAAO,KAAK,UAAU,EAAE,CAAC;YACnE,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,eAAe,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;gBAChD,IAAI,CAAC;oBACH,IAAI,EAAE,CAAC,OAAQ,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;wBAAC,OAAO,GAAG,IAAI,CAAC;wBAAC,MAAM;oBAAC,CAAC;gBACjE,CAAC;gBAAC,OAAO,CAAC,EAAE,CAAC;oBACX,2CAA2C;gBAC7C,CAAC;YACH,CAAC;QACH,CAAC;QACD,IAAI,OAAO;YAAE,SAAS,CAAC,2BAA2B;QAElD,IAAI,IAAI,GAAG,EAAE,CAAC,qBAAqB,EAAE,CAAC;QACtC,IAAI,IAAI,CAAC,KAAK,IAAI,CAAC,IAAI,IAAI,CAAC,MAAM,IAAI,CAAC,EAAE,CAAC;YACxC,IAAI,UAAU,GAAa,EAAE,CAAC;YAC9B,IAAI,MAAM,GAAG,KAAK,CAAC;YACnB,IAAI,CAAC;gBACH,IAAI,EAAE,GAAG,GAAG,CAAC,gBAAgB,CAAC,EAAE,CAAC,CAAC;gBAClC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,WAAW,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;oBAC5C,IAAI,KAAK,GAAG,EAAE,CAAC,gBAAgB,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC;oBAChD,IAAI,WAAW,CAAC,CAAC,CAAC,KAAK,YAAY,IAAI,KAAK,KAAK,QAAQ;wBAAE,MAAM,GAAG,IAAI,CAAC;oBACzE,UAAU,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,GAAG,GAAG,GAAG,KAAK,CAAC,CAAC;gBAChD,CAAC;YACH,CAAC;YAAC,OAAO,CAAC,EAAE,CAAC;gBACX,qEAAqE;YACvE,CAAC;YACD,qEAAqE;YACrE,mEAAmE;YACnE,gEAAgE;YAChE,IAAI,CAAC,MAAM,EAAE,CAAC;gBACZ,GAAG,CAAC,IAAI,CAAC;oBACP,IAAI,EAAE,MAAM,CAAC,EAAE,EAAE,IAAI,CAAC;oBACtB,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,OAAO,CAAC,GAAG,GAAG,CAAC;oBACvC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,OAAO,CAAC,GAAG,GAAG,CAAC;oBACvC,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,GAAG,GAAG,CAAC;oBACnC,MAAM,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,GAAG,GAAG,CAAC;oBACrC,SAAS,EAAE,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;iBACvC,CAAC,CAAC;YACL,CAAC;QACH,CAAC;QACD,8DAA8D;QAC9D,KAAK,IAAI,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;YACjD,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;QAC7B,CAAC;IACH,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,wEAAwE;AAC3D,QAAA,oBAAoB,GAAG,IAAI,CAAC;AAEzC;;;GAGG;AACH,SAAgB,yBAAyB,CACvC,cAAsB,4BAAoB,EAC1C,kBAA4B,EAAE;IAE9B,OAAO,IAAI,iBAAiB,CAAC,QAAQ,EAAE,uBAAuB,WAAW,KAAK,IAAI,CAAC,SAAS,CAAC,eAAe,CAAC,GAAG,CAAC;AACnH,CAAC"}

package/dist/capture/settle.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Page-settled probe — "has this page stopped changing?" answered without
+ * screenshotting repeatedly.
+ *
+ * WHY NOT NETWORK IDLE
+ * --------------------
+ * Playwright's own docs mark `networkidle` **DISCOURAGED**: "Don't use this
+ * method for testing, rely on web assertions to assess readiness instead." It
+ * is the wrong signal for a visual snapshot anyway — a page with analytics
+ * beacons or long-polling never goes quiet yet is perfectly settled, while a
+ * page can be network-idle with a CSS animation still running.
+ *
+ * WHY NOT A SETTLE LOOP
+ * ---------------------
+ * Playwright's built-in screenshots repeatedly until two consecutive images
+ * match. That costs a capture per attempt. TestivAI already absorbs render
+ * jitter through the DOM/style layer (identical DOM + identical styles reads as
+ * noise, not a change), so the only gap left is content that had not *loaded*
+ * yet — which is a load question, not a pixel question.
+ *
+ * WHAT THIS DOES
+ * --------------
+ * A cheap synchronous probe the adapter polls from the host language, exactly
+ * like the existing fonts wait. It reports whether the document is complete,
+ * whether images have finished, and how long the DOM has been quiet — the last
+ * measured with a MutationObserver, which observes rather than monkey-patching
+ * `fetch`/`XHR` and so cannot alter the behaviour of the page under test.
+ *
+ * SELF-CONTAINED on purpose: no imports, no closures, so it can be serialised
+ * into the page and shipped to the Python, Java and Ruby adapters as a
+ * generated asset — the same approach as the element-map collector.
+ */
+export interface SettleState {
+    /** document.readyState === 'complete' */
+    ready: boolean;
+    /** Images still decoding. `complete` is true for failed loads, so a 404 never hangs us. */
+    imagesPending: number;
+    /** Web fonts still loading, when the Font Loading API is available. */
+    fontsPending: boolean;
+    /** Milliseconds since the last DOM mutation. */
+    quietFor: number;
+    /** Everything above satisfied, including the quiet threshold. */
+    settled: boolean;
+}
+/** Global key holding the observer state between polls. */
+export declare const SETTLE_STATE_KEY = "__testivaiSettleState";
+/**
+ * One poll. Installs the MutationObserver on first call and reuses it after,
+ * so repeated polls are cheap.
+ */
+export declare function settleProbe(doc: {
+    readyState: string;
+    documentElement: unknown;
+    images: ArrayLike<{
+        complete: boolean;
+    }>;
+    fonts?: {
+        status?: string;
+    };
+}, win: Record<string, unknown> & {
+    MutationObserver?: new (cb: () => void) => {
+        observe: (t: unknown, o: unknown) => void;
+    };
+}, quietMs: number): SettleState;
+/** Default DOM-quiet threshold. Long enough to span a render, short enough not to be felt. */
+export declare const DEFAULT_QUIET_MS = 150;
+/** Default ceiling on waiting. A page that never settles must not hang the suite. */
+export declare const DEFAULT_SETTLE_TIMEOUT_MS = 5000;
+/** The expression an adapter evaluates for one poll. */
+export declare function buildSettleProbeExpression(quietMs?: number): string;
+/**
+ * Disconnect the observer and drop the global. Adapters call this in the same
+ * `finally` that removes the injected CSS — leaving an observer attached to
+ * someone else's page would be rude and would keep firing for the rest of the
+ * test.
+ */
+export declare const SETTLE_STOP_EXPRESSION = "(function (w) {\n  try {\n    var s = w['__testivaiSettleState'];\n    if (s && s.observer && typeof s.observer.disconnect === 'function') s.observer.disconnect();\n  } catch (e) {}\n  try { delete w['__testivaiSettleState']; } catch (e) { w['__testivaiSettleState'] = undefined; }\n})(window)";
+//# sourceMappingURL=settle.d.ts.map

package/dist/capture/settle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"settle.d.ts","sourceRoot":"","sources":["../../src/capture/settle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,MAAM,WAAW,WAAW;IAC1B,yCAAyC;IACzC,KAAK,EAAE,OAAO,CAAC;IACf,2FAA2F;IAC3F,aAAa,EAAE,MAAM,CAAC;IACtB,uEAAuE;IACvE,YAAY,EAAE,OAAO,CAAC;IACtB,gDAAgD;IAChD,QAAQ,EAAE,MAAM,CAAC;IACjB,iEAAiE;IACjE,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,2DAA2D;AAC3D,eAAO,MAAM,gBAAgB,0BAA0B,CAAC;AAExD;;;GAGG;AACH,wBAAgB,WAAW,CACzB,GAAG,EAAE;IACH,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,EAAE,OAAO,CAAC;IACzB,MAAM,EAAE,SAAS,CAAC;QAAE,QAAQ,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IACzC,KAAK,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAC7B,EACD,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG;IAAE,gBAAgB,CAAC,EAAE,KAAK,EAAE,EAAE,MAAM,IAAI,KAAK;QAAE,OAAO,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,KAAK,IAAI,CAAA;KAAE,CAAA;CAAE,EAC3H,OAAO,EAAE,MAAM,GACd,WAAW,CAoDb;AAED,8FAA8F;AAC9F,eAAO,MAAM,gBAAgB,MAAM,CAAC;AAEpC,qFAAqF;AACrF,eAAO,MAAM,yBAAyB,OAAO,CAAC;AAE9C,wDAAwD;AACxD,wBAAgB,0BAA0B,CAAC,OAAO,GAAE,MAAyB,GAAG,MAAM,CAErF;AAED;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,0SAMxB,CAAC"}

package/dist/capture/settle.js

@@ -0,0 +1,117 @@
+"use strict";
+/**
+ * Page-settled probe — "has this page stopped changing?" answered without
+ * screenshotting repeatedly.
+ *
+ * WHY NOT NETWORK IDLE
+ * --------------------
+ * Playwright's own docs mark `networkidle` **DISCOURAGED**: "Don't use this
+ * method for testing, rely on web assertions to assess readiness instead." It
+ * is the wrong signal for a visual snapshot anyway — a page with analytics
+ * beacons or long-polling never goes quiet yet is perfectly settled, while a
+ * page can be network-idle with a CSS animation still running.
+ *
+ * WHY NOT A SETTLE LOOP
+ * ---------------------
+ * Playwright's built-in screenshots repeatedly until two consecutive images
+ * match. That costs a capture per attempt. TestivAI already absorbs render
+ * jitter through the DOM/style layer (identical DOM + identical styles reads as
+ * noise, not a change), so the only gap left is content that had not *loaded*
+ * yet — which is a load question, not a pixel question.
+ *
+ * WHAT THIS DOES
+ * --------------
+ * A cheap synchronous probe the adapter polls from the host language, exactly
+ * like the existing fonts wait. It reports whether the document is complete,
+ * whether images have finished, and how long the DOM has been quiet — the last
+ * measured with a MutationObserver, which observes rather than monkey-patching
+ * `fetch`/`XHR` and so cannot alter the behaviour of the page under test.
+ *
+ * SELF-CONTAINED on purpose: no imports, no closures, so it can be serialised
+ * into the page and shipped to the Python, Java and Ruby adapters as a
+ * generated asset — the same approach as the element-map collector.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SETTLE_STOP_EXPRESSION = exports.DEFAULT_SETTLE_TIMEOUT_MS = exports.DEFAULT_QUIET_MS = exports.SETTLE_STATE_KEY = void 0;
+exports.settleProbe = settleProbe;
+exports.buildSettleProbeExpression = buildSettleProbeExpression;
+/** Global key holding the observer state between polls. */
+exports.SETTLE_STATE_KEY = '__testivaiSettleState';
+/**
+ * One poll. Installs the MutationObserver on first call and reuses it after,
+ * so repeated polls are cheap.
+ */
+function settleProbe(doc, win, quietMs) {
+    var KEY = '__testivaiSettleState';
+    var state = win[KEY];
+    if (!state) {
+        state = { last: Date.now() };
+        try {
+            if (typeof win.MutationObserver === 'function') {
+                var observer = new win.MutationObserver(function () {
+                    win[KEY].last = Date.now();
+                });
+                observer.observe(doc.documentElement, {
+                    subtree: true,
+                    childList: true,
+                    attributes: true,
+                    characterData: true,
+                });
+                state.observer = observer;
+            }
+        }
+        catch (e) {
+            // No MutationObserver (or a hostile document): quietness degrades to
+            // "always quiet" rather than blocking the capture.
+        }
+        win[KEY] = state;
+    }
+    var imagesPending = 0;
+    try {
+        for (var i = 0; i < doc.images.length; i++) {
+            if (!doc.images[i].complete)
+                imagesPending++;
+        }
+    }
+    catch (e) {
+        imagesPending = 0;
+    }
+    var fontsPending = false;
+    try {
+        fontsPending = !!(doc.fonts && doc.fonts.status && doc.fonts.status !== 'loaded');
+    }
+    catch (e) {
+        fontsPending = false;
+    }
+    var ready = doc.readyState === 'complete';
+    var quietFor = Date.now() - state.last;
+    return {
+        ready: ready,
+        imagesPending: imagesPending,
+        fontsPending: fontsPending,
+        quietFor: quietFor,
+        settled: ready && imagesPending === 0 && !fontsPending && quietFor >= quietMs,
+    };
+}
+/** Default DOM-quiet threshold. Long enough to span a render, short enough not to be felt. */
+exports.DEFAULT_QUIET_MS = 150;
+/** Default ceiling on waiting. A page that never settles must not hang the suite. */
+exports.DEFAULT_SETTLE_TIMEOUT_MS = 5000;
+/** The expression an adapter evaluates for one poll. */
+function buildSettleProbeExpression(quietMs = exports.DEFAULT_QUIET_MS) {
+    return `(${settleProbe.toString()})(document, window, ${quietMs})`;
+}
+/**
+ * Disconnect the observer and drop the global. Adapters call this in the same
+ * `finally` that removes the injected CSS — leaving an observer attached to
+ * someone else's page would be rude and would keep firing for the rest of the
+ * test.
+ */
+exports.SETTLE_STOP_EXPRESSION = `(function (w) {
+  try {
+    var s = w['${exports.SETTLE_STATE_KEY}'];
+    if (s && s.observer && typeof s.observer.disconnect === 'function') s.observer.disconnect();
+  } catch (e) {}
+  try { delete w['${exports.SETTLE_STATE_KEY}']; } catch (e) { w['${exports.SETTLE_STATE_KEY}'] = undefined; }
+})(window)`;
+//# sourceMappingURL=settle.js.map

package/dist/capture/settle.js.map

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

package/dist/capture/shard.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Shard participation — the framework-agnostic half of parallel runs.
+ *
+ * Playwright can tell its reporter `--shard=i/N`; pytest, JUnit, RSpec and a
+ * bare Selenium script cannot. So the mechanism is environment, not framework
+ * API, and every adapter honours the same two variables:
+ *
+ *   TESTIVAI_CAPTURE_ONLY=1   capture, do not compare or write a report
+ *   TESTIVAI_SHARD=3/8        this process is shard 3 of 8
+ *
+ * A framework that happens to know its own shard (Playwright) may fill these in
+ * itself, but the env var is the contract — that is what keeps a Selenium or
+ * pytest suite a first-class citizen of the same sharded CI flow.
+ */
+export interface ShardInfo {
+    current: number;
+    total: number;
+}
+export declare const SHARD_MANIFEST = "testivai-shard.json";
+/** Parse `TESTIVAI_SHARD` in either `3/8` or `3of8` form. Invalid → null. */
+export declare function parseShardEnv(value: string | undefined): ShardInfo | null;
+/**
+ * Capture-only resolution shared by every JS adapter.
+ * An explicit argument wins; then the env var; then "are we a shard of many".
+ */
+export declare function resolveCaptureOnly(explicit: boolean | undefined, shard: ShardInfo | null, env?: NodeJS.ProcessEnv): boolean;
+export interface ShardManifest {
+    shard: ShardInfo;
+    captures: string[];
+    /**
+     * True once the run finished. Adapters with a run-end hook (Playwright,
+     * pytest, JUnit) set it; adapters without one (a bare Selenium script, RSpec)
+     * write the manifest per capture and leave it false. `merge-captures` uses it
+     * to tell "this shard finished" from "this shard started and vanished".
+     */
+    complete: boolean;
+    status?: string;
+    timestamp: string;
+}
+/**
+ * Write (or refresh) the manifest for this shard.
+ *
+ * Safe to call on every capture: it rewrites the file with the captures present
+ * so far, which is what makes it usable by adapters that have no end-of-run
+ * hook to attach to.
+ */
+export declare function writeShardManifest(tempRoot: string, shard: ShardInfo, options?: {
+    complete?: boolean;
+    status?: string;
+}): void;
+//# sourceMappingURL=shard.d.ts.map

package/dist/capture/shard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shard.d.ts","sourceRoot":"","sources":["../../src/capture/shard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAKH,MAAM,WAAW,SAAS;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,eAAO,MAAM,cAAc,wBAAwB,CAAC;AAEpD,6EAA6E;AAC7E,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,GAAG,IAAI,CASzE;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,OAAO,GAAG,SAAS,EAC7B,KAAK,EAAE,SAAS,GAAG,IAAI,EACvB,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,OAAO,CAKT;AAED,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,SAAS,CAAC;IACjB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB;;;;;OAKG;IACH,QAAQ,EAAE,OAAO,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,SAAS,EAChB,OAAO,GAAE;IAAE,QAAQ,CAAC,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAO,GACpD,IAAI,CAqBN"}