@juxtapose/core 0.9.0 → 0.10.0

package/dist/capture/settle-options.d.ts

@@ -0,0 +1,78 @@
+import type { CaptureFlag, SettleParams, SettleReport, StoryParams } from '../types.js';
+import { SettleConfigError } from './config-errors.js';
+export { SettleConfigError };
+/** Default cap on the settle wait. Measured on the examples (29 stories, 5
+ *  runs each): the event-driven wait settles in 34-39 ms p50, 43 ms max, so
+ *  the cap only matters for a page that really has outstanding work; 1500 ms
+ *  lets a 1000 ms timer finish with room to paint. */
+export declare const DEFAULT_SETTLE_TIMEOUT_MS = 1500;
+/** A cap above this is a typo, not a slow page: it would be paid per story. */
+export declare const MAX_SETTLE_TIMEOUT_MS = 60000;
+/** Timers longer than this are never waited for, at any cap. The spike
+ *  measured horizon 1000 / cap 1500; the horizon must stay below the cap or a
+ *  long timer is tracked and then abandoned at the cap, so it shrinks with a
+ *  smaller cap (two thirds of it). */
+export declare const MAX_TIMER_HORIZON_MS = 1000;
+/** Request types that never finish while the page is open, or never affect
+ *  pixels. A WebSocket handshake emits no request events today; it is listed
+ *  so it stays ignored if Chrome starts reporting it. */
+export declare const DEFAULT_NETWORK_IGNORE: readonly string[];
+export interface UrlPattern {
+    /** As written, for messages. */
+    source: string;
+    /** Canonical resource type, when the pattern has `type:`. */
+    type?: string;
+    /** Absent when the pattern is a type alone. */
+    glob?: RegExp;
+    /** A glob starting with `/` matches the URL's path, not the whole URL. */
+    pathOnly: boolean;
+}
+/**
+ * `[type:<ResourceType>] [<glob>]`, at least one of the two. In the glob `**`
+ * matches anything, `*` anything but `/`, `?` one character but `/`. A glob
+ * starting with `/` matches the path (`/api/feed`), anything else the whole
+ * URL (`https://cdn.example.com/**`). Throws with the reason; the caller
+ * prefixes where the pattern came from.
+ */
+export declare function parsePattern(source: string): UrlPattern;
+export declare function matchPattern(p: UrlPattern, url: string, type: string | undefined): boolean;
+/** One layer: the options a story, the project or a call can set. */
+export interface SettleLayer {
+    settle?: SettleParams;
+    waitForSelector?: string;
+    delay?: number;
+}
+export interface ResolvedSettle {
+    timeoutMs: number;
+    horizonMs: number;
+    ready: boolean;
+    ignore: UrlPattern[];
+    require: UrlPattern[];
+}
+/** Merge two `settle` objects: scalars from `over`, lists concatenated
+ *  without duplicates. Keys absent from both stay absent. */
+export declare function mergeSettle(under: SettleParams | undefined, over: SettleParams | undefined): SettleParams | undefined;
+/** The settle wait for one capture, from its layers, lowest first. Assumes
+ *  each layer passed checkSettle. */
+export declare function resolveSettle(...layers: Array<SettleParams | undefined>): ResolvedSettle;
+/** waitForSelector and delay: call > story > project. */
+export declare function layerScalars(project: SettleLayer | undefined, params: StoryParams, call: SettleLayer | undefined): Pick<StoryParams, 'waitForSelector' | 'delay'>;
+/** The flag a settle report raises. */
+export declare const settleFlag: (s: Pick<SettleReport, "status">) => CaptureFlag;
+/** A settle cap: a whole number of ms, 1 to MAX_SETTLE_TIMEOUT_MS. The CLI
+ *  and the MCP server check per-call values with this too. */
+export declare function isSettleTimeout(v: unknown): v is number;
+/**
+ * Validate a `settle` value where it is declared, so the error names the
+ * place to edit. `where` is e.g. `project config` or `story 'button--primary'`.
+ * Throws SettleConfigError; returns the value typed.
+ */
+export declare function checkSettle(raw: unknown, where: string): SettleParams | undefined;
+/** Validate a pattern list; `fail` makes the error. */
+export declare function checkPatterns(list: unknown, name: string, fail: (m: string) => Error): string[];
+/** The project config's settle options: `settle`, `waitForSelector`, `delay`. */
+export declare function checkProjectSettle(config: {
+    settle?: unknown;
+    waitForSelector?: unknown;
+    delay?: unknown;
+}): void;

package/dist/capture/settle-options.js

@@ -0,0 +1,234 @@
+// Settle options: validation, layering and the URL patterns behind
+// `settle.network.ignore` / `settle.network.require`.
+//
+// Layers, lowest first: built-in defaults < project config < story params
+// (variants included) < per call (CLI flags, MCP tool arguments). Scalars
+// override; pattern lists accumulate, so a story adds to the project's ignore
+// list rather than replacing it, and `require` is the way to take a request
+// back out of an ignore list (both match: require wins).
+//
+// Pure on purpose: nothing here touches a page, so every rule has a unit test.
+import { SettleConfigError } from './config-errors.js';
+export { SettleConfigError };
+/** Default cap on the settle wait. Measured on the examples (29 stories, 5
+ *  runs each): the event-driven wait settles in 34-39 ms p50, 43 ms max, so
+ *  the cap only matters for a page that really has outstanding work; 1500 ms
+ *  lets a 1000 ms timer finish with room to paint. */
+export const DEFAULT_SETTLE_TIMEOUT_MS = 1500;
+/** A cap above this is a typo, not a slow page: it would be paid per story. */
+export const MAX_SETTLE_TIMEOUT_MS = 60_000;
+/** Timers longer than this are never waited for, at any cap. The spike
+ *  measured horizon 1000 / cap 1500; the horizon must stay below the cap or a
+ *  long timer is tracked and then abandoned at the cap, so it shrinks with a
+ *  smaller cap (two thirds of it). */
+export const MAX_TIMER_HORIZON_MS = 1000;
+/** Request types that never finish while the page is open, or never affect
+ *  pixels. A WebSocket handshake emits no request events today; it is listed
+ *  so it stays ignored if Chrome starts reporting it. */
+export const DEFAULT_NETWORK_IGNORE = [
+    'type:WebSocket',
+    'type:EventSource',
+    'type:Ping',
+    'type:Prefetch',
+];
+/** CDP Network.ResourceType values, for `type:` validation. */
+const RESOURCE_TYPES = [
+    'Document',
+    'Stylesheet',
+    'Image',
+    'Media',
+    'Font',
+    'Script',
+    'TextTrack',
+    'XHR',
+    'Fetch',
+    'Prefetch',
+    'EventSource',
+    'WebSocket',
+    'Manifest',
+    'SignedExchange',
+    'Ping',
+    'CSPViolationReport',
+    'Preflight',
+    'FedCM',
+    'Other',
+];
+/**
+ * `[type:<ResourceType>] [<glob>]`, at least one of the two. In the glob `**`
+ * matches anything, `*` anything but `/`, `?` one character but `/`. A glob
+ * starting with `/` matches the path (`/api/feed`), anything else the whole
+ * URL (`https://cdn.example.com/**`). Throws with the reason; the caller
+ * prefixes where the pattern came from.
+ */
+export function parsePattern(source) {
+    const tokens = source.trim().split(/\s+/).filter(Boolean);
+    let type;
+    let glob;
+    for (const t of tokens) {
+        if (/^type:/i.test(t)) {
+            if (type !== undefined)
+                throw new Error(`pattern '${source}' has two types`);
+            const name = t.slice(5);
+            const known = RESOURCE_TYPES.find((r) => r.toLowerCase() === name.toLowerCase());
+            if (!known)
+                throw new Error(`pattern '${source}': unknown resource type '${name}' (one of ${RESOURCE_TYPES.join(', ')})`);
+            type = known;
+        }
+        else {
+            if (glob !== undefined)
+                throw new Error(`pattern '${source}' has two URL globs; write one, or one pattern per glob`);
+            glob = t;
+        }
+    }
+    if (type === undefined && glob === undefined)
+        throw new Error('a pattern must not be empty');
+    return {
+        source,
+        ...(type !== undefined ? { type } : {}),
+        ...(glob !== undefined ? { glob: globToRegExp(glob) } : {}),
+        pathOnly: glob?.startsWith('/') === true,
+    };
+}
+function globToRegExp(glob) {
+    let re = '';
+    for (let i = 0; i < glob.length; i++) {
+        const c = glob[i];
+        if (c === '*') {
+            if (glob[i + 1] === '*') {
+                re += '.*';
+                i++;
+            }
+            else
+                re += '[^/]*';
+        }
+        else if (c === '?')
+            re += '[^/]';
+        else
+            re += c.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+    }
+    return new RegExp(`^${re}$`);
+}
+export function matchPattern(p, url, type) {
+    if (p.type !== undefined && p.type !== (type ?? 'Other'))
+        return false;
+    if (!p.glob)
+        return true;
+    if (!p.pathOnly)
+        return p.glob.test(url);
+    try {
+        return p.glob.test(new URL(url).pathname);
+    }
+    catch {
+        return false;
+    }
+}
+/** Merge two `settle` objects: scalars from `over`, lists concatenated
+ *  without duplicates. Keys absent from both stay absent. */
+export function mergeSettle(under, over) {
+    if (!under)
+        return over;
+    if (!over)
+        return under;
+    const list = (a, b) => a || b ? [...new Set([...(a ?? []), ...(b ?? [])])] : undefined;
+    const ignore = list(under.network?.ignore, over.network?.ignore);
+    const require = list(under.network?.require, over.network?.require);
+    const timeout = over.timeout ?? under.timeout;
+    const ready = over.ready ?? under.ready;
+    return {
+        ...(timeout !== undefined ? { timeout } : {}),
+        ...(ready !== undefined ? { ready } : {}),
+        ...(ignore || require
+            ? { network: { ...(ignore ? { ignore } : {}), ...(require ? { require } : {}) } }
+            : {}),
+    };
+}
+/** The settle wait for one capture, from its layers, lowest first. Assumes
+ *  each layer passed checkSettle. */
+export function resolveSettle(...layers) {
+    let merged;
+    for (const l of layers)
+        merged = mergeSettle(merged, l);
+    const timeoutMs = merged?.timeout ?? DEFAULT_SETTLE_TIMEOUT_MS;
+    return {
+        timeoutMs,
+        horizonMs: Math.min(MAX_TIMER_HORIZON_MS, Math.floor((timeoutMs * 2) / 3)),
+        ready: merged?.ready === true,
+        ignore: [...DEFAULT_NETWORK_IGNORE, ...(merged?.network?.ignore ?? [])].map(parsePattern),
+        require: (merged?.network?.require ?? []).map(parsePattern),
+    };
+}
+/** waitForSelector and delay: call > story > project. */
+export function layerScalars(project, params, call) {
+    const waitForSelector = call?.waitForSelector ?? params.waitForSelector ?? project?.waitForSelector;
+    const delay = call?.delay ?? params.delay ?? project?.delay;
+    return {
+        ...(waitForSelector !== undefined ? { waitForSelector } : {}),
+        ...(delay !== undefined ? { delay } : {}),
+    };
+}
+const isRecord = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+/** The flag a settle report raises. */
+export const settleFlag = (s) => s.status === 'timeout' ? 'settle-timeout' : 'settle-fallback';
+/** A settle cap: a whole number of ms, 1 to MAX_SETTLE_TIMEOUT_MS. The CLI
+ *  and the MCP server check per-call values with this too. */
+export function isSettleTimeout(v) {
+    return (Number.isInteger(v) && v >= 1 && v <= MAX_SETTLE_TIMEOUT_MS);
+}
+/**
+ * Validate a `settle` value where it is declared, so the error names the
+ * place to edit. `where` is e.g. `project config` or `story 'button--primary'`.
+ * Throws SettleConfigError; returns the value typed.
+ */
+export function checkSettle(raw, where) {
+    if (raw === undefined)
+        return undefined;
+    const fail = (m) => new SettleConfigError(`${where}: ${m}`);
+    if (!isRecord(raw))
+        throw fail(`'settle' must be an object`);
+    for (const k of Object.keys(raw)) {
+        if (k !== 'timeout' && k !== 'ready' && k !== 'network')
+            throw fail(`unknown settle option '${k}' (expected timeout, ready, network)`);
+    }
+    if (raw['timeout'] !== undefined && !isSettleTimeout(raw['timeout']))
+        throw fail(`settle.timeout must be a whole number of ms from 1 to ${MAX_SETTLE_TIMEOUT_MS}, got ${JSON.stringify(raw['timeout'])}`);
+    if (raw['ready'] !== undefined && typeof raw['ready'] !== 'boolean')
+        throw fail(`settle.ready must be true or false, got ${JSON.stringify(raw['ready'])}`);
+    const net = raw['network'];
+    if (net !== undefined) {
+        if (!isRecord(net))
+            throw fail(`settle.network must be an object`);
+        for (const k of Object.keys(net)) {
+            if (k !== 'ignore' && k !== 'require')
+                throw fail(`unknown settle.network option '${k}' (expected ignore, require)`);
+            checkPatterns(net[k], `settle.network.${k}`, fail);
+        }
+    }
+    return raw;
+}
+/** Validate a pattern list; `fail` makes the error. */
+export function checkPatterns(list, name, fail) {
+    if (!Array.isArray(list) || !list.every((p) => typeof p === 'string'))
+        throw fail(`${name} must be an array of URL patterns`);
+    for (const p of list) {
+        try {
+            parsePattern(p);
+        }
+        catch (e) {
+            throw fail(`${name}: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    }
+    return list;
+}
+/** The project config's settle options: `settle`, `waitForSelector`, `delay`. */
+export function checkProjectSettle(config) {
+    const where = 'project config';
+    checkSettle(config.settle, where);
+    if (config.waitForSelector !== undefined && typeof config.waitForSelector !== 'string')
+        throw new SettleConfigError(`${where}: waitForSelector must be a CSS selector`);
+    if (config.delay !== undefined &&
+        (typeof config.delay !== 'number' ||
+            !Number.isFinite(config.delay) ||
+            config.delay < 0))
+        throw new SettleConfigError(`${where}: delay must be a number of ms, 0 or more`);
+}
+//# sourceMappingURL=settle-options.js.map

package/dist/capture/settle-options.js.map

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

package/dist/capture/settle.d.ts

@@ -1,22 +1,4 @@
 import type { Page } from '../browser/page.js';
-/** Quiet period with no DOM mutations and no in-flight fetches before we
- *  declare the page settled. */
-export declare const DOM_IDLE_MS = 150;
-/** Hard cap on waiting for quiescence. A story that never goes idle — a
- *  spinner that survived the CSS freeze, a polling widget — still gets
- *  captured rather than hanging the run. Kept tight: this cost is paid on
- *  every such story, times the whole suite. */
-export declare const DOM_IDLE_TIMEOUT_MS = 500;
-/** Arm the quiescence observer. Call before triggering a story render. */
-export declare function armSettle(page: Page): Promise<void>;
-/**
- * Await quiescence, webfonts and image decode in a single round trip.
- *
- * Deliberately one `evaluate` rather than three. At ~1.2s per story and 8
- * parallel pages, CDP round-trips are a measurable share of wall clock; the
- * original tool cut per-story time meaningfully by collapsing these.
- */
-export declare function drain(page: Page): Promise<void>;
 /**
  * Zero out animations and transitions.
  *

package/dist/capture/settle.js

@@ -2,106 +2,13 @@
 // (Platform.settle) has resolved. Everything here applies to any DOM, which is
 // why it lives in core rather than in an adapter.
 //
-// The ordering matters and is not arbitrary:
-//   arm → platform render signal → DOM/network quiescence → fonts → images
-// Arming must happen before the render is triggered, or the observer misses
-// the mutations it is supposed to be watching.
-/** Quiet period with no DOM mutations and no in-flight fetches before we
- *  declare the page settled. */
-export const DOM_IDLE_MS = 150;
-/** Hard cap on waiting for quiescence. A story that never goes idle — a
- *  spinner that survived the CSS freeze, a polling widget — still gets
- *  captured rather than hanging the run. Kept tight: this cost is paid on
- *  every such story, times the whole suite. */
-export const DOM_IDLE_TIMEOUT_MS = 500;
-/**
- * Installed via evaluate before each story render. Resolves `window.__juxWait`
- * once the DOM has been mutation-free for `idleMs`, or `timeoutMs` elapses.
- *
- * Counts in-flight fetches too: a story that fires a request on mount would
- * otherwise report "idle" in the gap between mount and response, and we'd
- * screenshot the loading state — intermittently.
- */
-const SETTLE_SCRIPT = `
-  var done = false;
-  window.__juxWait = new Promise(function (resolve) {
-    var pending = 0;
-    var idleTimer = null;
-
-    function finish() {
-      if (done) return;
-      done = true;
-      observer.disconnect();
-      clearTimeout(idleTimer);
-      clearTimeout(capTimer);
-      if (window.__juxFetchOrig) {
-        window.fetch = window.__juxFetchOrig;
-        delete window.__juxFetchOrig;
-      }
-      resolve();
-    }
-
-    var capTimer = setTimeout(finish, timeoutMs);
-
-    function scheduleIdle() {
-      clearTimeout(idleTimer);
-      if (pending === 0) idleTimer = setTimeout(finish, idleMs);
-    }
-
-    if (!window.__juxFetchOrig) {
-      window.__juxFetchOrig = window.fetch;
-      window.fetch = function () {
-        pending++;
-        clearTimeout(idleTimer);
-        return window.__juxFetchOrig.apply(this, arguments).finally(function () {
-          pending--;
-          scheduleIdle();
-        });
-      };
-    }
-
-    var observer = new MutationObserver(scheduleIdle);
-    observer.observe(document.documentElement, {
-      childList: true, subtree: true, attributes: true, characterData: true,
-    });
-    scheduleIdle();
-  });
-`;
-/** Arm the quiescence observer. Call before triggering a story render. */
-export async function armSettle(page) {
-    await page
-        .evaluate(`(function (idleMs, timeoutMs) { ${SETTLE_SCRIPT} })(${DOM_IDLE_MS}, ${DOM_IDLE_TIMEOUT_MS})`)
-        .catch(() => { });
-}
-/**
- * Await quiescence, webfonts and image decode in a single round trip.
- *
- * Deliberately one `evaluate` rather than three. At ~1.2s per story and 8
- * parallel pages, CDP round-trips are a measurable share of wall clock; the
- * original tool cut per-story time meaningfully by collapsing these.
- */
-export async function drain(page) {
-    // The window cast inside is a cast, not a global Window augmentation: the
-    // callback runs in the page, and declaring the hook globally would leak it
-    // into core's public types. (Comments stay out here: TypeScript keeps them
-    // in the callback's source, which is what the page evaluates.)
-    await page
-        .evaluate(async () => {
-        const w = window;
-        await (w.__juxWait ?? Promise.resolve());
-        // Webfonts: a story captured mid-swap diffs against one captured after,
-        // for every glyph on the page.
-        await document.fonts?.ready?.catch?.(() => { });
-        // Decode, not just load — an undecoded image can still paint late.
-        await Promise.all(Array.from(document.images).map((img) => img.complete
-            ? Promise.resolve()
-            : new Promise((r) => {
-                img.addEventListener('load', () => r(), { once: true });
-                img.addEventListener('error', () => r(), { once: true });
-            })));
-    })
-        .catch(() => { });
-}
+// The order, in captureStory:
+//   freeze animations → platform render signal → waitForSelector →
+//   event-driven idle wait (idle.ts) → delay → paint barrier → recheck
+//
+// The idle wait replaced a 150 ms DOM-quiet window plus a `drain` that awaited
+// fonts and every incomplete image with no cap; see idle.ts for what was
+// measured and why.
 /**
  * Zero out animations and transitions.
  *

package/dist/capture/settle.js.map

@@ -1 +1 @@
-{"version":3,"file":"settle.js","sourceRoot":"","sources":["../../src/capture/settle.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"settle.js","sourceRoot":"","sources":["../../src/capture/settle.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAC3E,+EAA+E;AAC/E,kDAAkD;AAClD,EAAE;AACF,8BAA8B;AAC9B,mEAAmE;AACnE,uEAAuE;AACvE,EAAE;AACF,+EAA+E;AAC/E,yEAAyE;AACzE,oBAAoB;AAIpB;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG;;;;;;;;;CASpC,CAAC;AAEF;yEACyE;AACzE,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,IAAU,EACV,QAAgB,EAChB,SAAiB;IAEjB,2EAA2E;IAC3E,8EAA8E;IAC9E,MAAM,IAAI,CAAC,eAAe,CAAC,QAAQ,EAAE,EAAE,OAAO,EAAE,SAAS,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;AAC/E,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,IAAU,EAAE,SAAS,GAAG,IAAI;IAC7D,MAAM,IAAI;SACP,QAAQ,CACP,CAAC,GAAG,EAAE,EAAE,CACN,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE;QAC5B,MAAM,IAAI,GAAG,GAAG,EAAE,CAAC,OAAO,EAAE,CAAC;QAC7B,MAAM,KAAK,GAAG,UAAU,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;QACpC,qBAAqB,CAAC,GAAG,EAAE,CACzB,qBAAqB,CAAC,GAAG,EAAE;YACzB,MAAM,MAAM,GAAG,GAAG,EAAE;gBAClB,YAAY,CAAC,KAAK,CAAC,CAAC;gBACpB,IAAI,EAAE,CAAC;YACT,CAAC,CAAC;YACF,IAAI,OAAO,mBAAmB,KAAK,UAAU,EAAE,CAAC;gBAC9C,mBAAmB,CAAC,MAAM,EAAE,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC,CAAC;YAChD,CAAC;iBAAM,CAAC;gBACN,MAAM,EAAE,CAAC;YACX,CAAC;QACH,CAAC,CAAC,CACH,CAAC;IACJ,CAAC,CAAC,EACJ,SAAS,CACV;SACA,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;AACrB,CAAC"}

package/dist/capture/snap.d.ts

@@ -1,5 +1,6 @@
 import type { Browser } from '../browser/browser.js';
 import type { CaptureEnv, Snapshot, StoryParams, Viewport } from '../types.js';
+import type { SettleLayer } from './settle-options.js';
 export interface SnapOptions {
     url: string;
     viewport?: Viewport;
@@ -17,6 +18,8 @@ export interface SnapPagesOptions {
     urls: string[];
     viewport?: Viewport;
     params?: StoryParams;
+    /** The project config's settle options, below `params`. */
+    projectSettle?: SettleLayer;
     /** Acquired by the caller (acquireBrowser); not closed here. */
     browser: Browser;
 }

package/dist/capture/snap.js

@@ -34,7 +34,13 @@ export async function snapPages(opts) {
             try {
                 // A url platform enumerates exactly the one entry it was given.
                 const [story] = await platform.enumerate({ projectRoot: process.cwd() });
-                const snapshot = await captureStory(page, story, { platform, baseUrl: url }, viewport);
+                const snapshot = await captureStory(page, story, {
+                    platform,
+                    baseUrl: url,
+                    ...(opts.projectSettle
+                        ? { settleLayers: { project: opts.projectSettle } }
+                        : {}),
+                }, viewport);
                 if (!snapshot)
                     throw new Error('page declared skip');
                 pages.push({ url, snapshot, status });

package/dist/capture/snap.js.map

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

package/dist/capture/variants.d.ts

@@ -2,10 +2,7 @@ import type { StoryManifest, StoryParams, VariantSpec } from '../types.js';
 /** Underscores are excluded so the `__` key separator can't occur in a name. */
 export declare const VARIANT_NAME: RegExp;
 export declare const VARIANT_SEPARATOR = "__";
-/** A bad variant declaration. The CLI reports it and exits 2. */
-export declare class VariantConfigError extends Error {
-    constructor(message: string);
-}
+export { VariantConfigError } from './config-errors.js';
 export declare const captureKey: (baseStoryId: string, variant: string) => string;
 /** The id every platform call receives: the platform's own, never the key. */
 export declare const platformStoryId: (story: {

package/dist/capture/variants.js

@@ -7,16 +7,12 @@
 // url entry, or a preview extract), so a platform can change how it discovers
 // them without touching this.
 import { compareCodeUnits } from '../diff/structural/deltas.js';
+import { VariantConfigError } from './config-errors.js';
+import { checkSettle, mergeSettle } from './settle-options.js';
 /** Underscores are excluded so the `__` key separator can't occur in a name. */
 export const VARIANT_NAME = /^[a-z0-9][a-z0-9-]{0,31}$/;
 export const VARIANT_SEPARATOR = '__';
-/** A bad variant declaration. The CLI reports it and exits 2. */
-export class VariantConfigError extends Error {
-    constructor(message) {
-        super(`jux: ${message}`);
-        this.name = 'VariantConfigError';
-    }
-}
+export { VariantConfigError } from './config-errors.js';
 export const captureKey = (baseStoryId, variant) => `${baseStoryId}${VARIANT_SEPARATOR}${variant}`;
 /** The id every platform call receives: the platform's own, never the key. */
 export const platformStoryId = (story) => story.baseStoryId ?? story.storyId;
@@ -35,6 +31,7 @@ export function expandVariants(stories, projectVariants) {
         // `variants` is a declaration, not a capture setting, and `colorScheme`
         // is variant-only: the default capture is always light.
         const { variants: ownRaw, colorScheme: _ignored, ...baseParams } = story.params;
+        checkSettle(baseParams.settle, `story '${story.storyId}'`);
         out.push({ ...story, params: baseParams });
         // A skipped story skips every variant: there is nothing to vary.
         if (baseParams.skip === true)
@@ -61,7 +58,7 @@ export function expandVariants(stories, projectVariants) {
                 variant: name,
                 variantParams: layer,
                 // Base params, then the extends chain, then the variant itself.
-                params: { ...baseParams, ...layer },
+                params: withSettle({ ...baseParams, ...layer }, baseParams.settle, layer.settle),
             });
         }
     }
@@ -102,6 +99,7 @@ function checkDeclared(raw, where) {
         if (scheme !== undefined && scheme !== 'light' && scheme !== 'dark') {
             throw new VariantConfigError(`${where}: variant '${name}' colorScheme must be 'light' or 'dark'`);
         }
+        checkSettle(spec['settle'], `${where}: variant '${name}'`);
         const ext = spec['extends'];
         if (ext !== undefined && typeof ext !== 'string') {
             throw new VariantConfigError(`${where}: variant '${name}' extends must be a variant name`);
@@ -129,11 +127,22 @@ function resolveChain(storyId, name, merged) {
         cur = spec.extends;
     }
     const layer = {};
-    for (const spec of chain)
+    for (const spec of chain) {
+        const settle = mergeSettle(layer.settle, spec.settle);
         Object.assign(layer, spec);
+        if (settle)
+            layer.settle = settle;
+    }
     delete layer.extends;
     return layer;
 }
+/** `params` with `settle` merged field by field rather than replaced, so a
+ *  variant's `settle.timeout` keeps the story's `settle.network`. Untouched
+ *  (no `settle` key) when neither side sets one. */
+function withSettle(params, under, over) {
+    const settle = mergeSettle(under, over);
+    return settle ? { ...params, settle } : params;
+}
 /**
  * Merge live params (read from the rendered preview) for one capture.
  *
@@ -149,7 +158,10 @@ export function mergeLiveParams(story, live) {
         return params;
     const { variants: _v, colorScheme: _c, ...settings } = live;
     Object.assign(params, settings, story.variantParams ?? {});
-    return params;
+    const variantSettle = story.variantParams?.settle;
+    return variantSettle
+        ? withSettle(params, settings.settle ?? story.params.settle, variantSettle)
+        : params;
 }
 /**
  * Pick items by story id: a base id selects the story and every variant of