@juxtapose/core 0.9.0 → 0.11.0

package/dist/capture/network-policy.js

@@ -0,0 +1,114 @@
+// `network.external: 'block'` (issue #147): requests to origins other than
+// the page's own fail at once, through CDP Fetch, instead of fetching bytes
+// that change between runs (a random photo, a CDN) or holding the page to the
+// settle cap (a broken link that answers after 20 s, issue #125).
+//
+// Blocked requests fail with BlockedByClient, which arrives as
+// Network.loadingFailed: the settle tracker drops them like any failed
+// request, an <img> becomes `complete`, and nothing is pending or flagged.
+//
+// Limits: WebSockets are not intercepted, and neither is anything running on
+// a session this page does not hold (an out-of-process iframe; measured:
+// headless-shell ran a cross-site iframe in-process, and dedicated-worker
+// fetches were blocked, but a real Chrome with site isolation may differ).
+// data:, blob:, about: and file: URLs have no remote origin and always pass; so does the top-level
+// document, so a story URL that redirects elsewhere still loads.
+import { SettleConfigError } from './config-errors.js';
+/** Validate a `network` value where it is declared; `where` names the place to edit. */
+export function checkNetwork(raw, where) {
+    if (raw === undefined)
+        return undefined;
+    const fail = (m) => new SettleConfigError(`${where}: ${m}`);
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw))
+        throw fail(`'network' must be an object`);
+    for (const k of Object.keys(raw))
+        if (k !== 'external')
+            throw fail(`unknown network option '${k}' (expected external)`);
+    const ext = raw.external;
+    if (ext !== undefined && ext !== 'allow' && ext !== 'block')
+        throw fail(`network.external must be 'allow' or 'block', got ${JSON.stringify(ext)}`);
+    return ext === undefined ? {} : { external: ext };
+}
+/** call > story > project, default 'allow'. */
+export function resolveExternal(project, story, call) {
+    return (call?.network?.external ??
+        story?.network?.external ??
+        project?.network?.external ??
+        'allow');
+}
+/** Whether `url` is a remote request to a different origin than `origin`. */
+export function isExternal(url, origin) {
+    let u;
+    try {
+        u = new URL(url);
+    }
+    catch {
+        return false;
+    }
+    if (u.protocol !== 'http:' && u.protocol !== 'https:')
+        return false;
+    return u.origin !== origin;
+}
+const applied = new WeakMap();
+/**
+ * Make the page's request policy match `mode` for the origin of `baseUrl`.
+ * Called before every navigation; a page keeps its policy until the next call,
+ * so a pooled page never carries one capture's block into the next.
+ */
+export async function applyNetworkPolicy(page, mode, baseUrl) {
+    const current = applied.get(page);
+    let origin;
+    try {
+        origin = new URL(baseUrl).origin;
+    }
+    catch {
+        origin = 'null';
+    }
+    if (mode === 'allow') {
+        if (!current)
+            return;
+        applied.delete(page);
+        current.off();
+        await page.send('Fetch.disable').catch(() => { });
+        return;
+    }
+    if (current) {
+        // In place, never off() then on(): a request paused in between would
+        // never be answered and would hang the page.
+        current.origin = origin;
+        return;
+    }
+    if (!page.on)
+        return;
+    const tree = await page.send('Page.getFrameTree').catch(() => undefined);
+    const mainFrameId = tree?.frameTree?.frame?.id;
+    const state = { origin, off: () => { } };
+    state.off = page.on('Fetch.requestPaused', (e) => {
+        const top = e.resourceType === 'Document' && e.frameId === mainFrameId;
+        // The page's own origin is the committed main document's: a top-level
+        // redirect (127.0.0.1 -> localhost) moves it, and the new document's own
+        // CSS, scripts and images must not count as external.
+        if (top)
+            state.origin = originOf(e.request.url) ?? state.origin;
+        const block = !top && isExternal(e.request.url, state.origin);
+        const done = block
+            ? page.send('Fetch.failRequest', {
+                requestId: e.requestId,
+                errorReason: 'BlockedByClient',
+            })
+            : page.send('Fetch.continueRequest', { requestId: e.requestId });
+        done.catch(() => { });
+    });
+    applied.set(page, state);
+    await page.send('Fetch.enable', { patterns: [{ urlPattern: '*' }] });
+}
+function originOf(url) {
+    try {
+        const u = new URL(url);
+        return u.protocol === 'http:' || u.protocol === 'https:' ? u.origin : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=network-policy.js.map

package/dist/capture/network-policy.js.map

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

package/dist/capture/pool.d.ts

@@ -1,6 +1,7 @@
 import { type Browser } from '../browser/browser.js';
 import type { Platform } from '../platform.js';
 import type { Snapshot, StoryManifest, Viewport } from '../types.js';
+import type { SettleLayer } from './settle-options.js';
 /**
  * Default parallelism.
  *
@@ -25,6 +26,11 @@ export interface PoolOptions {
     warmSwitch?: boolean;
     /** Non-fatal notices from capture, e.g. an ignored live variant override. */
     onWarning?: (message: string) => void;
+    /** Settle options around each story's own; see CaptureDeps. */
+    settleLayers?: {
+        project?: SettleLayer;
+        call?: SettleLayer;
+    };
 }
 export interface CaptureOutcome {
     story: StoryManifest;

package/dist/capture/pool.js

@@ -63,6 +63,7 @@ export async function* capturePool(stories, opts) {
             baseUrl: opts.baseUrl,
             warmSwitch: opts.warmSwitch,
             ...(opts.onWarning ? { onWarning: opts.onWarning } : {}),
+            ...(opts.settleLayers ? { settleLayers: opts.settleLayers } : {}),
         };
         try {
             for (;;) {

package/dist/capture/pool.js.map

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

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

@@ -0,0 +1,80 @@
+import type { CaptureFlag, NetworkParams, 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;
+    network?: NetworkParams;
+    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;
+    network?: unknown;
+    waitForSelector?: unknown;
+    delay?: unknown;
+}): void;

package/dist/capture/settle-options.js

@@ -0,0 +1,236 @@
+// 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';
+import { checkNetwork } from './network-policy.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);
+    checkNetwork(config.network, 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.
  *
@@ -29,6 +11,66 @@ export declare const FREEZE_ANIMATIONS_CSS = "\n*, *::before, *::after {\n  anim
 /** Wait for an explicit selector. Escape hatch for async content the network
  *  drain can't observe — SDK init, canvas paint, third-party widgets. */
 export declare function waitForSelector(page: Page, selector: string, timeoutMs: number): Promise<void>;
+/**
+ * Drop and rebuild every `will-change` compositor layer, so each is rastered
+ * once, from the page as it stands now.
+ *
+ * Chrome picks a layer's raster translation (the subpixel offset its content
+ * is rasterized at) when it first rasterizes the layer, and keeps it on a
+ * `will-change: transform` layer so a moving transform never re-rasters. When
+ * the transform changes after that first raster (an animation that ran a
+ * frame before the freeze, or a `translateX(-100%)` whose width grew when a
+ * font loaded) the layer keeps the old offset, and its glyph antialiasing
+ * records the page's history instead of its final state. That history is
+ * timing: one Chakra marquee captured 3 different hashes depending on run
+ * context (issue #136), with the same frozen transform in all of them.
+ *
+ * A frame with `will-change: auto` composites the element into its parent;
+ * removing the override makes a new layer, rastered at its current
+ * transform. Measured on a translateX marquee fixture through snapPages, 40
+ * captures per arm: animated 39/40 and load-delayed 40/40 differed from the
+ * same page with a static transform; with this, 0/80. On the Chakra story
+ * the three contexts now capture one hash, the same one a page frozen from
+ * its first frame and then rebuilt this way gives. A device-scale round trip
+ * and `--disable-threaded-animation` leave the stale raster; freezing
+ * animations from the first frame (an init script) fixes the fixture but not
+ * Chakra, whose marquee widens when its font loads.
+ *
+ * Only the elements whose computed `will-change` is not `auto` are touched,
+ * through an inline `!important` declaration, in the document and in every
+ * open shadow root. The first version adopted a `* { will-change: auto
+ * !important }` sheet instead, and that went wrong in four measured ways:
+ *  - `will-change: transform` (or filter, perspective) gives an element a
+ *    containing block for fixed descendants and a stacking context. Dropping
+ *    it moved those descendants to the viewport for two frames, so a latching
+ *    IntersectionObserver captured "seen" 6/6, a ResizeObserver reacting
+ *    through a 30 ms timer captured the wrong layout 3-4/6, and every such
+ *    page took the recheck. Where the computed transform, translate and
+ *    filter are all `none`, the element also gets `translate: 0px
+ *    !important` for the two frames: an identity 2D transform, with no layer
+ *    of its own and the same containing block. 0/6 after, and no recheck.
+ *  - An adopted sheet does not reach shadow roots: a marquee in one stayed
+ *    stale 4/4. 0/4 after.
+ *  - An inline `will-change: transform !important` beats an author
+ *    `!important` sheet: stale 4/4. 0/4 after.
+ *  - Adopting any `*` sheet forces a whole-document style recalc, which by
+ *    itself re-rastered a frozen fill-forwards transform animation with no
+ *    will-change (Chakra button--custom-spinner) to a hash a static page
+ *    never gives. Touching only will-change elements leaves those alone.
+ * The writes run through `__juxIdle.untracked` (idle.ts), so the mutation
+ * counter, and with it the recheck in captureStory, never sees them. Each
+ * declaration is put back as it was, in the second frame or on timeout.
+ * A page with no will-change element, most stories, skips the two frames:
+ * 16-18 ms became the scan, 0.7 / 1.9 / 6.9 ms on 200 / 2k / 10k elements.
+ *
+ * Scope: this rebuilds `will-change: transform` layers. A layer promoted
+ * another way (`translateZ(0)`, `translate3d`, `backdrop-filter`) or by
+ * `will-change: opacity` or `filter` keeps its first raster: stale 3-4/4 when
+ * it grows after that raster, before and after this. Will-change on a
+ * pseudo-element is not reached either, since it takes no inline style.
+ * Those need a different mechanism than a style toggle (see #145).
+ */
+export declare function rerasterLayers(page: Page, timeoutMs?: number): Promise<void>;
 /**
  * Block until the compositor has actually presented a frame.
  *