@pygmalionjs/pygmalion 0.5.14 → 0.5.16

package/dist-lib/types/editor/interactiveStates.d.ts

@@ -0,0 +1,103 @@
+import type { DesignScreenInteraction, StoryboardEnvironment } from './designImport';
+import type { PageModel } from './store';
+/**
+ * Interactive states — axes a screen can be put into by acting on it.
+ *
+ * A collapsed sidebar or a hovered row is not a separate screen: it is the
+ * same screen after one gesture, reachable on every frame that has the
+ * control. Declaring it as an axis keeps those variations out of the
+ * catalog (where each would cost a captured frame) and puts them in the
+ * right panel, where a designer flips between them.
+ *
+ * The steps are ordinary interactions, so a selected option simply extends
+ * the frame's recipe. Everything downstream — the preview cache key, the
+ * live replay, the session walk — already keys off that recipe, which is
+ * why no supply path needs to know this feature exists.
+ */
+export interface InteractiveStateOption {
+    id: string;
+    label: string;
+    /** Absent or empty marks the base state — the screen as captured. */
+    steps?: readonly DesignScreenInteraction[];
+    /**
+     * Boot condition this option puts the frame under, for states no gesture can
+     * reach: a failed request, an empty result, a stalled stream.
+     *
+     * Those are the states QA most wants to hold still, and until now they had no
+     * declaration. A gesture cannot produce them, so the only options were a
+     * dedicated capture (a frame per failure) or burying a mock flag inside one
+     * case's recipe — so hosts did neither, and their error/empty/loading markers
+     * sat in the product with nothing pointing at them.
+     *
+     * The environment is merged into the frame's own, which already belongs to the
+     * recipe identity — so selecting the option changes the cache key and the
+     * existing supply path (live replay, flow session, artifact lookup) reproduces
+     * it. Nothing downstream needs to know this option kind exists.
+     *
+     * May be combined with `steps` when the state needs a gesture AFTER booting
+     * under the condition.
+     */
+    environment?: StoryboardEnvironment;
+    /**
+     * Recognizes this option in the CAPTURED tree, which is what makes the base
+     * a property of the frame instead of the axis.
+     *
+     * One axis covers every frame carrying the control, but "the screen as
+     * captured" differs between them: a result panel captured mid-recording sits
+     * on its transcript tab, and the same panel captured after conversion sits on
+     * its summary tab. With a single declared base the axis is a no-op on every
+     * frame whose capture is the other option — selecting it only reproduces the
+     * capture that is already showing.
+     *
+     * Declare it on EVERY option (each with its own steps) and the axis resolves
+     * per frame: whichever option the capture already shows needs no steps, and
+     * the others run theirs.
+     */
+    capturedWhen?: {
+        testId: string;
+        attribute?: {
+            name: string;
+            value: string;
+        };
+    };
+}
+export interface InteractiveStateDef {
+    id: string;
+    label: string;
+    /**
+     * Frames the axis applies to. A frame qualifies when its route matches
+     * (prefix) and its imported tree carries the test id, so an axis declared
+     * once covers every screen that actually has the control.
+     */
+    requires?: {
+        testId?: string;
+        route?: string;
+    };
+    options: readonly InteractiveStateOption[];
+}
+export interface InteractiveStateDiagnostic {
+    severity: 'error' | 'warning';
+    interactionId: string;
+    message: string;
+}
+export declare function validateInteractiveStates(defs: readonly InteractiveStateDef[]): InteractiveStateDiagnostic[];
+/**
+ * Axes available on one frame. The test-id requirement is checked against
+ * the imported tree, so an axis stays hidden until the frame actually shows
+ * the control it drives — a frame without a sidebar never offers to fold it.
+ */
+export declare function interactiveStatesForPage(page: PageModel, defs: readonly InteractiveStateDef[]): InteractiveStateDef[];
+/**
+ * The option this frame's capture already shows, or undefined when the axis
+ * declares a single base instead of witnessing each option.
+ */
+export declare function capturedInteractiveOption(def: InteractiveStateDef, page: PageModel): InteractiveStateOption | undefined;
+/**
+ * The option that reproduces the capture — the frame's base.
+ *
+ * A witnessed axis resolves it against this frame's tree; otherwise it is the
+ * one option declared without steps.
+ */
+export declare function baseInteractiveOption(def: InteractiveStateDef, page?: PageModel): InteractiveStateOption | undefined;
+export declare function setInteractiveStates(defs: readonly InteractiveStateDef[] | undefined): void;
+export declare function getInteractiveStates(): readonly InteractiveStateDef[];

package/dist-lib/types/editor/livePreviewInstances.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Shared live application instances for producing screen previews.
+ *
+ * A frame that has no frozen snapshot yet has to run the real application once.
+ * Doing that per frame means one boot per screen, which is what made opening a
+ * catalog feel like waiting for a build. A screen whose state is declared does
+ * not need its own boot: the instance is already running, so the state is
+ * switched and the next snapshot is taken from the same document.
+ *
+ * A lease is exclusive. Snapshot production reads the document while it freezes,
+ * so two frames must never drive one instance at the same time.
+ */
+export interface LivePreviewInstanceOptions {
+    /** Creates the offscreen frame. Injected so the pool can be tested without a browser. */
+    createIframe?: () => HTMLIFrameElement;
+    /** Where offscreen instances live. Defaults to the document body. */
+    resolveContainer?: () => HTMLElement | null;
+    /** Upper bound on booted instances. Groups beyond it fall back to their own frame. */
+    maximumInstances?: number;
+}
+export interface LivePreviewLease {
+    iframe: HTMLIFrameElement;
+    /** False on the boot that created the instance, true when an existing one was reused. */
+    reused: boolean;
+    release(): void;
+}
+export declare const LIVE_PREVIEW_INSTANCE_LIMIT = 4;
+/**
+ * Names the group of screens that one running instance can serve.
+ *
+ * Screens agree on a group only when the application would boot identically:
+ * same origin, same route, same pre-mount environment, same viewport. Anything
+ * else is a different application state before the first render, and switching
+ * state cannot reach it.
+ */
+export declare function livePreviewInstanceKey(input: {
+    origin: string;
+    route: string;
+    environment?: Record<string, unknown> | null;
+    width: number;
+    height: number;
+}): string;
+/**
+ * Reports whether a screen may be previewed on a shared running instance.
+ *
+ * Three things disqualify a screen. It has no declared group, so the host never
+ * promised the declaration is the whole state. It replays interactions, and only
+ * the screen knows how to undo what a click opened. Or it is the frame the
+ * designer is looking at, which is shown rather than only read, and imports its
+ * layers from the running document.
+ */
+export declare function canShareLivePreviewInstance(page: {
+    session?: string;
+    route?: string | null;
+    interactions?: readonly unknown[];
+    layersImported?: boolean;
+}, options?: {
+    detailActive?: boolean;
+}): boolean;
+export declare function createLivePreviewInstances(options?: LivePreviewInstanceOptions): {
+    lease: (input: {
+        key: string;
+        url: string;
+        width: number;
+        height: number;
+    }) => Promise<LivePreviewLease | null>;
+    /**
+     * Boots an instance for a group without keeping the lease.
+     *
+     * Warming pays the boot before any screen asks for it, so the first real
+     * lease of the group reuses a running document instead of waiting on a
+     * load. A warmed instance is an ordinary pool member afterwards: leases,
+     * discards, and failure handling treat it exactly like one that a frame
+     * booted itself.
+     *
+     * Returns true only when this call booted a new instance. Warming is
+     * best-effort and never throws — a failed boot is discarded through the
+     * lease path and reported as false.
+     */
+    warm(input: {
+        key: string;
+        url: string;
+        width: number;
+        height: number;
+    }): Promise<boolean>;
+    /** Drops an instance whose document can no longer be trusted. */
+    discard(key: string): void;
+    size(): number;
+    dispose(): void;
+};
+export type LivePreviewInstances = ReturnType<typeof createLivePreviewInstances>;
+export declare function getLivePreviewInstances(): LivePreviewInstances;
+export declare function resetLivePreviewInstances(): void;

package/dist-lib/types/editor/liveScreens.d.ts

@@ -0,0 +1,20 @@
+export declare function subscribeLiveScreens(listener: () => void): () => void;
+/**
+ * Sets how many frames may render live at once. Lowering it releases the
+ * least recently requested frames back to the frozen surface.
+ */
+export declare function setLiveScreenBudget(next: number): void;
+export declare function getLiveScreenBudget(): number;
+/**
+ * Claims a live slot for a page, or refreshes its recency when it already
+ * holds one. Returns whether the page holds a slot afterwards, so a caller
+ * can fall back to the frozen surface without waiting for a re-render.
+ */
+export declare function requestLiveScreen(pageId: string): boolean;
+/** Releases a page's slot, if it holds one. */
+export declare function releaseLiveScreen(pageId: string): void;
+export declare function holdsLiveScreen(pageId: string): boolean;
+/** Page ids currently rendering live, least recently requested first. */
+export declare function liveScreenHolders(): readonly string[];
+/** Test seam — drops every claim and the budget. */
+export declare function resetLiveScreens(): void;

package/dist-lib/types/editor/nodeSelector.d.ts

@@ -0,0 +1,20 @@
+import type { NodeModel } from './store';
+export interface NodeSelector {
+    testId?: string;
+    classIncludes?: string | readonly string[];
+}
+export declare function nodeMatchesSelector(node: NodeModel, selector: NodeSelector): boolean;
+/**
+ * Matching nodes in document order, the subtree root included. The cap keeps
+ * a careless declaration (a class prefix that matches half the screen) from
+ * filling the panel with hundreds of controls.
+ */
+export declare function collectMatchingNodes(root: NodeModel, matches: (node: NodeModel) => boolean, limit: number): NodeModel[];
+/** Chain from the subtree root down to the node, or null when unrelated. */
+export declare function pathToNode(root: NodeModel, id: string): NodeModel[] | null;
+/**
+ * The first few words a subtree shows, used to name a row in the panel.
+ * Captured markup carries its identity in text (a chart number, a name, an
+ * age), so the leading text is what a designer recognizes a row by.
+ */
+export declare function leadingText(node: NodeModel, maxLength?: number): string;

package/dist-lib/types/editor/previewBootstrap.d.ts

@@ -0,0 +1,189 @@
+import type { RoutePreviewArtifactBundle } from './routePreview.js';
+import type { DesignScreenCase, StoryboardEnvironment } from './designImport';
+export interface PreviewRecipeIdentity {
+    id: string;
+    recipe: unknown;
+}
+export interface PreviewCacheNamespaceOptions {
+    sourceRevision: string;
+    recipes: readonly PreviewRecipeIdentity[];
+    recipeVersion?: number;
+    scope?: string;
+}
+export type StoryboardCaptureRecipeInput = Pick<DesignScreenCase, 'route' | 'path' | 'componentName' | 'gallery' | 'width' | 'height' | 'environment' | 'preset' | 'interactions' | 'assertions'>;
+export interface PreviewArtifactExpectation {
+    namespace: string;
+    sourceRevision: string;
+}
+export interface PreviewArtifactFrameRequest {
+    id: string;
+    fingerprint?: string;
+}
+export interface PreviewArtifactTransportRequest extends PreviewArtifactExpectation {
+    /** Frames to fetch. Omitted asks for the whole bundle, as earlier versions did. */
+    frames?: readonly PreviewArtifactFrameRequest[];
+    /** Set false to seed only what exists instead of capturing what is absent. */
+    generate?: boolean;
+    /** Return only exact/missing/stale classification, without frame payloads. */
+    resolveOnly?: boolean;
+    signal?: AbortSignal;
+    captureBaseUrl?: string;
+}
+export type PreviewArtifactTransport = (request: PreviewArtifactTransportRequest) => Promise<unknown | null | undefined>;
+export interface PreviewArtifactHttpResponse {
+    readonly ok: boolean;
+    readonly status?: number;
+    readonly statusText?: string;
+    json(): Promise<unknown>;
+}
+export type PreviewArtifactFetch = (input: string, init: {
+    method: 'GET';
+    headers: {
+        accept: 'application/json';
+    };
+    cache: 'no-store';
+    signal?: AbortSignal;
+}) => Promise<PreviewArtifactHttpResponse>;
+export interface PreviewArtifactHttpTransportOptions {
+    endpoint: string;
+    fetcher?: PreviewArtifactFetch;
+    captureBaseUrl?: string;
+}
+export type PreviewArtifactValidationReason = 'invalid-bundle' | 'namespace-mismatch' | 'revision-mismatch';
+/** Exactness of the frames named by a partial artifact request. */
+export interface PreviewArtifactFrameResolution {
+    /** Frames whose source revision or opaque fingerprint matches the request. */
+    exact: readonly string[];
+    /** Frames that were not present in the returned artifact. */
+    missing: readonly string[];
+    /** Frames that were present but did not match the requested identity. */
+    stale: readonly string[];
+}
+export declare const PREVIEW_ARTIFACT_FRAME_REQUEST_CHUNK_SIZE = 20;
+/** Keeps GET-based local transports below common query/header limits. */
+export declare function chunkPreviewArtifactFrameRequests(frames: readonly PreviewArtifactFrameRequest[], chunkSize?: number): PreviewArtifactFrameRequest[][];
+export type PreviewArtifactValidationResult = {
+    valid: true;
+    artifact: RoutePreviewArtifactBundle;
+    errors: readonly [];
+} | {
+    valid: false;
+    artifact: null;
+    reason: PreviewArtifactValidationReason;
+    errors: readonly string[];
+};
+export type PreviewArtifactBootstrapResult = {
+    status: 'accepted';
+    artifact: RoutePreviewArtifactBundle;
+    /** Present when the caller asked for individual frames. */
+    frameResolution?: PreviewArtifactFrameResolution;
+} | {
+    status: 'unavailable';
+    artifact: null;
+    error?: unknown;
+} | {
+    status: 'rejected';
+    artifact: null;
+    reason: PreviewArtifactValidationReason;
+    errors: readonly string[];
+};
+export type PreviewArtifactFrameProbeResult = {
+    status: 'accepted';
+    resolution: PreviewArtifactFrameResolution;
+} | {
+    status: 'unavailable';
+    resolution: null;
+    error?: unknown;
+} | {
+    status: 'rejected';
+    resolution: null;
+    errors: readonly string[];
+};
+export declare function createPreviewRecipeFingerprint(recipes: readonly PreviewRecipeIdentity[]): string;
+/**
+ * Identity of one frame's capture, so freshness is decided per screen.
+ *
+ * The namespace fingerprints the whole catalog, which is why one edited screen
+ * used to invalidate every frame. This value covers a single screen's recipe and,
+ * when a caller passes one, the revision or content digest that screen depends
+ * on — the piece a dependency-closure digest replaces later.
+ */
+export declare function createPreviewFrameFingerprint(screen: StoryboardCaptureRecipeInput & {
+    id?: string;
+}, options?: {
+    dependencyDigest?: string;
+}): string;
+/**
+ * Per-route content digests published by the storyboard scan.
+ *
+ * A source revision remains the provenance boundary. Within that boundary, the
+ * route digest makes an edited screen move without invalidating unrelated ones.
+ */
+export declare function setPreviewDependencyDigests(routes: readonly {
+    path?: string;
+    dependencyDigest?: string;
+}[] | null): void;
+export declare function previewDependencyDigest(route: string): string | undefined;
+export interface PreviewFramePage {
+    canonicalId: string;
+    route: string;
+    width?: number;
+    height?: number;
+    environment?: StoryboardEnvironment;
+    preset?: unknown;
+    interactions?: unknown;
+    assertions?: unknown;
+}
+/**
+ * Identity of one frame's capture, derived the same way wherever it is needed.
+ *
+ * The revision is folded in until a dependency-closure digest replaces it, so a
+ * frame is invalidated no less often than before; what changes is that a consumer
+ * now captures per frame instead of demanding the whole catalog up front.
+ */
+export declare function createRoutePreviewFrameFingerprint(page: PreviewFramePage, previewRevision: string, baselineEnvironment?: StoryboardEnvironment): string;
+export declare function createPreviewCacheNamespace({ sourceRevision, recipes, recipeVersion, scope, }: PreviewCacheNamespaceOptions): string;
+/**
+ * Device pixels captured per CSS pixel. Must mirror
+ * `STORYBOARD_CAPTURE_SCREENSHOT_SCALE` in `storyboard-capture-runtime.mjs`
+ * (browser code cannot import the Node runtime); a shared test pins the pair.
+ */
+export declare const STORYBOARD_CAPTURE_RECIPE_SCREENSHOT_SCALE = 2;
+/**
+ * Returns the portable runtime identity of a resolved storyboard capture.
+ * Descriptive labels and editor-only grouping are intentionally omitted.
+ * The screenshot scale participates so that changing the capture density
+ * retires every artifact captured at the old density.
+ */
+export declare function createStoryboardCaptureRecipeIdentity(screen: StoryboardCaptureRecipeInput): unknown;
+/**
+ * Creates the default same-origin HTTP transport for preview artifacts.
+ * Hosts provide only an endpoint; identity query parameters and safe fetch
+ * semantics remain owned by Pygmalion.
+ */
+export declare function createPreviewArtifactHttpTransport({ endpoint, fetcher, captureBaseUrl, }: PreviewArtifactHttpTransportOptions): PreviewArtifactTransport;
+/** Resolves frame freshness without downloading or validating snapshot payloads. */
+export declare function probePreviewArtifactFrames({ namespace, sourceRevision, transport, signal, frames, }: PreviewArtifactExpectation & {
+    transport: PreviewArtifactTransport;
+    signal?: AbortSignal;
+    frames: readonly PreviewArtifactFrameRequest[];
+}): Promise<PreviewArtifactFrameProbeResult>;
+export declare function validatePreviewArtifactBundle(value: unknown, expectation?: PreviewArtifactExpectation, options?: {
+    perFrameIdentity?: boolean;
+}): PreviewArtifactValidationResult;
+/**
+ * Resolves partial artifact exactness per requested frame.
+ *
+ * A bundle revision is sufficient for v1/v2. Version 3 requires both the source
+ * revision and opaque fingerprint; matching content from another revision stays
+ * useful as last-known evidence but never becomes exact.
+ * This keeps a valid partial response distinct from a current frame response:
+ * an empty or stale subset is valid transport data, but it is not a warm cache.
+ */
+export declare function resolvePreviewArtifactFrames(artifact: RoutePreviewArtifactBundle, expectation: PreviewArtifactExpectation, frames: readonly PreviewArtifactFrameRequest[]): PreviewArtifactFrameResolution;
+export declare function bootstrapPreviewArtifact({ namespace, sourceRevision, transport, signal, frames, generate, }: PreviewArtifactExpectation & {
+    transport: PreviewArtifactTransport;
+    signal?: AbortSignal;
+    frames?: readonly PreviewArtifactFrameRequest[];
+    generate?: boolean;
+}): Promise<PreviewArtifactBootstrapResult>;

package/dist-lib/types/editor/previewEnvironmentControls.d.ts

@@ -0,0 +1,33 @@
+import type { StoryboardEnvironment } from './designImport';
+/** A host-declared value for a portable browser condition such as color scheme. */
+export interface PreviewEnvironmentControlOptionDef {
+    value: string;
+    label: string;
+    description?: string;
+    environment?: StoryboardEnvironment;
+}
+/**
+ * An orthogonal preview condition. These controls do not create storyboard
+ * nodes: they temporarily alter only the active frame's live route preview.
+ */
+export interface PreviewEnvironmentControlDef {
+    id: string;
+    label: string;
+    description?: string;
+    defaultValue: string;
+    options: readonly PreviewEnvironmentControlOptionDef[];
+}
+/** Configure the inspector controls once from the host application. */
+export declare function setPreviewEnvironmentControls(next: readonly PreviewEnvironmentControlDef[]): void;
+export declare function getPreviewEnvironmentControls(): readonly PreviewEnvironmentControlDef[];
+export declare function getPreviewEnvironmentControlValue(controlId: string): string | undefined;
+/**
+ * Selects a condition. Defaults are visually selected but remain inert until a
+ * user changes a control, preserving existing exact preview artifact identities.
+ */
+export declare function setPreviewEnvironmentControlValue(controlId: string, value: string): void;
+export declare function clearPreviewEnvironmentControlValues(): void;
+/** Merged explicit override for the active frame, if the user selected one. */
+export declare function getPreviewEnvironmentOverride(): StoryboardEnvironment | undefined;
+export declare function subscribePreviewEnvironmentControls(listener: () => void): () => void;
+export declare function getPreviewEnvironmentControlRevision(): number;

package/dist-lib/types/editor/previewHydration.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Produces a content identity for a set of preview cache keys. Runtime priority
+ * may reorder the keys, but that must not invalidate an already hydrated set.
+ */
+export declare function createPreviewHydrationSignature(keys: readonly string[]): string;

package/dist-lib/types/editor/previewIntent.d.ts

@@ -0,0 +1,17 @@
+export declare const PREVIEW_INTENT_LIMIT = 2;
+/** Marks a frame as likely to be opened next. Returns true when the slot set changed. */
+export declare function notePreviewIntent(pageId: string, limit?: number): boolean;
+/**
+ * Drops preparation for a frame.
+ *
+ * Leaving a frame is not a reason to drop it — the work is already paid for and
+ * the designer often comes back. This exists for frames that stop being
+ * previewable at all, such as one whose layers have been imported.
+ */
+export declare function releasePreviewIntent(pageId: string): void;
+export declare function hasPreviewIntent(pageId: string): boolean;
+export declare function getPreviewIntentSlots(): readonly string[];
+export declare function subscribePreviewIntent(listener: () => void): () => void;
+/** Fires only when this page enters or leaves the intent slots. */
+export declare function subscribePreviewIntentFor(pageId: string, listener: () => void): () => void;
+export declare function resetPreviewIntent(): void;

package/dist-lib/types/editor/previewSweep.d.ts

@@ -0,0 +1,129 @@
+/**
+ * Background capture sweep planning and driving.
+ *
+ * A cold canvas shows placeholders wherever no frozen snapshot exists yet, and
+ * the editor only produces snapshots for frames the designer touches. The sweep
+ * fills the rest while the editor is idle: it plans the missing screens once,
+ * then produces them one at a time at a priority below all user work, joining
+ * any production a user action already started for the same screen.
+ *
+ * The planner is pure so ordering is testable; the driver takes injected
+ * dependencies so it can run in tests without a browser.
+ */
+export interface SweepFrameIdentity {
+    id: string;
+    fingerprint?: string;
+}
+export interface SweepCandidate {
+    pageId: string;
+    /** Persistent recipe cache key of the screen. */
+    key: string;
+    /**
+     * Producer dedup key shared with the frame's own producer, so a user opening
+     * a screen mid-sweep joins the in-flight production instead of restarting it.
+     */
+    runtimeKey: string;
+    /**
+     * Shared live instance group when the screen may run on the boot pool,
+     * null when the screen needs its own throwaway frame.
+     */
+    groupKey: string | null;
+    /** Interaction screens are never booted by the sweep; they are delegated. */
+    hasInteractions: boolean;
+    /**
+     * Screen-space distance from the viewport center. The caller encodes
+     * "active canvas first" by giving frames on other canvases an infinite
+     * distance, so nearby visible work is always produced before offscreen work.
+     */
+    distance: number;
+    /** Exact-artifact identity used when the screen is delegated to capture. */
+    frame?: SweepFrameIdentity;
+}
+export interface SweepUnit {
+    pageId: string;
+    key: string;
+    runtimeKey: string;
+    groupKey: string | null;
+    /** Planned position. The producer priority derives from it so earlier units run first. */
+    index: number;
+}
+export interface PreviewSweepPlan {
+    units: SweepUnit[];
+    interactionFrames: SweepFrameIdentity[];
+}
+export interface PlanPreviewSweepOptions {
+    /**
+     * Screens that already have a snapshot are not swept. A warm reopen finds
+     * every key present after prehydration, so it plans zero units.
+     */
+    hasSnapshot?: (key: string) => boolean;
+}
+/** Screen-space distance from the viewport center to a frame center. */
+export declare function sweepViewportDistance(frame: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}, camera: {
+    panX: number;
+    panY: number;
+    zoom: number;
+    viewportWidth: number;
+    viewportHeight: number;
+}): number;
+/**
+ * Orders missing screens for background production.
+ *
+ * Distance ascending, with members of one instance group kept contiguous at
+ * the position of their nearest member — the editor-side mirror of "one boot,
+ * many screens": one lease serves the whole group by switching declared state
+ * between serializations. Interaction screens are split out for delegation.
+ */
+export declare function planPreviewSweep(candidates: readonly SweepCandidate[], options?: PlanPreviewSweepOptions): PreviewSweepPlan;
+export type PreviewSweepPhase = 'idle' | 'running' | 'paused' | 'done' | 'cancelled';
+export interface PreviewSweepStatus {
+    phase: PreviewSweepPhase;
+    total: number;
+    completed: number;
+    failed: number;
+}
+export interface PreviewSweepLease {
+    /** True when the pool served an already booted instance. */
+    reused?: boolean;
+    /** The live document a unit serializes from. */
+    iframe?: HTMLIFrameElement;
+    release(): void;
+    /** Drops the instance behind the lease when its document can no longer be trusted. */
+    discard(): void;
+}
+export interface PreviewSweeperDeps {
+    /**
+     * Provides the live document for one unit: a pooled lease for grouped
+     * screens, an ephemeral offscreen frame otherwise.
+     */
+    leaseInstance(unit: SweepUnit): Promise<PreviewSweepLease | null>;
+    /** Produces and stores the snapshot for one unit off the leased document. */
+    produce(unit: SweepUnit, lease: PreviewSweepLease | null, isCancelled: () => boolean): Promise<unknown>;
+    /** Delegates interaction screens to the exact capture pipeline, one call per chunk. */
+    requestArtifactFrames(frames: readonly SweepFrameIdentity[]): unknown;
+    /** Checked before each unit; a paused sweep retries on a short backoff. */
+    shouldPause(): boolean;
+    now?: () => number;
+    log?: (message: string) => void;
+}
+export interface PreviewSweeperOptions {
+    pauseBackoffMs?: number;
+    interactionChunkSize?: number;
+    interactionRequestCap?: number;
+}
+export interface PreviewSweeper {
+    /** Runs one plan to completion. A later run or cancel abandons this one. */
+    run(plan: PreviewSweepPlan): Promise<void>;
+    /** Releases the held lease and invalidates in-flight unit completions. */
+    cancel(): void;
+}
+export declare const SWEEP_INTERACTION_CHUNK_SIZE = 8;
+export declare const SWEEP_INTERACTION_REQUEST_CAP = 32;
+export declare function getPreviewSweepStatus(): PreviewSweepStatus;
+export declare function subscribePreviewSweep(listener: () => void): () => void;
+export declare function createPreviewSweeper(deps: PreviewSweeperDeps, options?: PreviewSweeperOptions): PreviewSweeper;