@pygmalionjs/pygmalion 0.11.1 → 0.13.0

package/dist-lib/testing.js

@@ -1,6 +1,6 @@
-import { bW as l, T as u } from "./runtime-Bxn8116i.js";
-import { bi as y, cc as b, cd as E, ce as P, be as T, as as $ } from "./runtime-Bxn8116i.js";
-const v = {
+import { bY as l, T as u } from "./runtime-DkCf4iKe.js";
+import { bk as y, ce as b, cf as E, cg as P, bg as T, as as $ } from "./runtime-DkCf4iKe.js";
+const f = {
   mirror: ["status", "refresh", "refs"],
   session: ["open", "check", "previewVisual", "applyVisual", "revertVisual"],
   inspect: ["impact"],
@@ -8,12 +8,12 @@ const v = {
   preview: ["artifact", "progress", "catalog"],
   storyboard: ["environment", "sourceUsage", "componentBranches"]
 };
-function g(m = {}, t = {}) {
-  const n = [], d = t.origin ?? "", e = (r) => {
+function v(m = {}, t = {}) {
+  const n = [], d = t.origin ?? "", r = (e) => {
     var a;
     const i = {};
-    for (const o of v[r]) {
-      const s = `${r}.${String(o)}`, c = (a = m[r]) == null ? void 0 : a[o];
+    for (const o of f[e]) {
+      const s = `${e}.${String(o)}`, c = (a = m[e]) == null ? void 0 : a[o];
       i[String(o)] = (...p) => (n.push({ operation: s, request: p[0] }), c ? Promise.resolve(c(...p)) : Promise.reject(
         new u({
           operation: s,
@@ -27,13 +27,13 @@ function g(m = {}, t = {}) {
   return {
     calls: n,
     endpoints: l(t.endpoints),
-    resolveUrl: (r) => `${d}${r}`,
-    mirror: e("mirror"),
-    session: e("session"),
-    inspect: e("inspect"),
-    qa: e("qa"),
-    preview: e("preview"),
-    storyboard: e("storyboard")
+    resolveUrl: (e) => `${d}${e}`,
+    mirror: r("mirror"),
+    session: r("session"),
+    inspect: r("inspect"),
+    qa: r("qa"),
+    preview: r("preview"),
+    storyboard: r("storyboard")
   };
 }
 export {
@@ -42,6 +42,6 @@ export {
   E as FrozenRoutePreviewView,
   P as NodeModel,
   T as createEditorRuntime,
-  g as createMemoryTransport,
+  v as createMemoryTransport,
   $ as serializeNode
 };

package/dist-lib/types/document/prototype.d.ts

@@ -9,6 +9,8 @@
  */
 import type { DesignDocument, DocumentDiagnostic, DocumentDuplicateMetadataRemapper, DocumentNode, DocumentResolveOptions, DocumentTransaction, ResolvedDocumentNode } from './contracts.js';
 import type { PrototypeOccurrence, PrototypeRowPath } from './prototypeOccurrence.js';
+import type { PrototypeDragAddress, PrototypeDragConfiguration } from './prototypeMotionContracts.js';
+import { type PrototypeSpringPlan } from './prototypeSpring.js';
 export type { PrototypeOccurrence, PrototypeRowPath } from './prototypeOccurrence.js';
 export declare const PROTOTYPE_METADATA_KEY = "prototype";
 export declare const PROTOTYPE_INTERACTIONS_PROPERTY = "interactions";
@@ -21,6 +23,7 @@ export interface PrototypeTrigger {
     type: PrototypeTriggerType;
     key?: string;
     delayMs?: number;
+    drag?: PrototypeDragConfiguration;
 }
 export declare const prototypeTransitionTypes: readonly ["instant", "dissolve", "smart-animate", "move-in", "move-out", "push", "slide-in", "slide-out"];
 export type PrototypeTransitionType = typeof prototypeTransitionTypes[number];
@@ -244,6 +247,9 @@ export interface PrototypeSceneLayer {
     path: string[];
     /** Names from the scene root down to this layer, the smart-animate hierarchy key. */
     namePath: string;
+    /** Opaque name segments; slashes in a name never form a hierarchy. */
+    nameSegments: string[];
+    instancePath: readonly string[];
     name: string;
     kind: DocumentNode['kind'];
     x: number;
@@ -285,9 +291,17 @@ export interface PrototypeSmartAnimatePlan {
     pairs: PrototypeSmartAnimatePair[];
     leaving: PrototypeSceneLayer[];
     entering: PrototypeSceneLayer[];
+    diagnostics: {
+        code: string;
+        message: string;
+    }[];
 }
-/** Smart animate pairs equal names within equal hierarchy paths. Unmatched layers fade. */
-export declare function matchSmartAnimateLayers(document: DesignDocument, fromScreenId: string, toScreenId: string, variants?: Readonly<Record<string, string>>): PrototypeSmartAnimatePlan;
+/** Model and DOM playback share occurrence-aware matching; ambiguous layers remain unmatched. */
+export declare function matchSmartAnimateLayers(document: DesignDocument, fromScreenId: string, toScreenId: string, variants?: Readonly<Record<string, string>>, options?: {
+    from: PrototypeState;
+    to: PrototypeState;
+    context?: PrototypeRuntimeContext;
+}): PrototypeSmartAnimatePlan;
 export interface PrototypeTimer {
     id: string;
     at: number;
@@ -337,6 +351,8 @@ export interface PrototypeTransitionState {
     transition: PrototypeTransition;
     startedAt: number;
     endsAt: number;
+    /** Physical spring plan shared by the interpreter deadline and the renderer. */
+    spring?: PrototypeSpringPlan;
 }
 export interface PrototypeState {
     flowId: string | null;
@@ -441,5 +457,19 @@ export interface PrototypeStartOptions {
 export declare function createPrototypeState(document: DesignDocument, options?: PrototypeStartOptions): PrototypeState;
 /** The earliest moment the state changes without input, or null when it is at rest. */
 export declare function prototypeNextDeadline(state: PrototypeState): number | null;
+export type PrototypeDragPreparation = {
+    status: 'none';
+} | {
+    status: 'fallback';
+    message: string;
+} | {
+    status: 'ready';
+    configuration: PrototypeDragConfiguration;
+    state: PrototypeState;
+    effects: PrototypeEffect[];
+    transition: PrototypeTransition;
+};
+/** Prepare a captured target without advancing timers or publishing effects. Authoring stays untouched. */
+export declare function preparePrototypeDrag(document: DesignDocument, previous: PrototypeState, address: PrototypeDragAddress, now: number, runtime?: PrototypeRuntimeContext): PrototypeDragPreparation;
 /** One pure step: the event (or the passage of time) against a frozen document; time is `now`. */
 export declare function stepPrototype(document: DesignDocument, previous: PrototypeState, event: PrototypeEvent, now: number, runtime?: PrototypeRuntimeContext): PrototypeStepResult;

package/dist-lib/types/document/prototypeDrag.d.ts

@@ -0,0 +1,43 @@
+import type { PrototypeDragAddress, PrototypeDragConfiguration, PrototypeDragPoint } from './prototypeMotionContracts.js';
+export interface PrototypeDragSampleInput {
+    pointerId: number;
+    point: PrototypeDragPoint;
+    /** Injected logical time in milliseconds. */
+    now: number;
+}
+export interface PrototypeDragStartInput extends PrototypeDragSampleInput, PrototypeDragAddress {
+}
+export interface PrototypeDragFinishInput extends PrototypeDragSampleInput {
+    cancel?: boolean;
+}
+export interface PrototypeDragSession {
+    readonly config: Readonly<PrototypeDragConfiguration>;
+    readonly address: {
+        readonly path: readonly string[];
+        readonly occurrence?: {
+            readonly sceneId: string;
+            readonly rowPath: readonly Readonly<{
+                repeatId: string;
+                key: string | number;
+            }>[];
+        };
+    };
+    readonly pointerId: number;
+    readonly origin: Readonly<PrototypeDragPoint>;
+    readonly lastPoint: Readonly<PrototypeDragPoint>;
+    readonly startedAt: number;
+    readonly updatedAt: number;
+    readonly progress: number;
+    /** Velocity of the clamped progress in progress units per second. */
+    readonly velocity: number;
+    readonly phase: 'active' | 'ended';
+    readonly outcome: 'commit' | 'cancel' | null;
+}
+export declare function isPrototypeDragConfiguration(value: unknown): value is PrototypeDragConfiguration;
+/** Capture one gesture without resolving scenes, dispatching actions, or reading a clock. */
+export declare function startPrototypeDrag(config: PrototypeDragConfiguration, input: PrototypeDragStartInput): PrototypeDragSession;
+/** Other pointers and samples after release are inert. Invalid owned samples leave the session unchanged. */
+export declare function updatePrototypeDrag(session: PrototypeDragSession, input: PrototypeDragSampleInput): PrototypeDragSession;
+/** End once. Only position determines commit. An unchanged release axis retains its last
+ * velocity for at most 80ms; a longer pause rests. Cancellation never commits. */
+export declare function finishPrototypeDrag(session: PrototypeDragSession, input: PrototypeDragFinishInput): PrototypeDragSession;

package/dist-lib/types/document/prototypeEasing.d.ts

@@ -0,0 +1,3 @@
+import { type PrototypeEasing } from './prototype.js';
+/** Sample an authored non-spring timing curve, preserving back-curve overshoot. */
+export declare function samplePrototypeEasing(easing: PrototypeEasing, progress: number): number;

package/dist-lib/types/document/prototypeMotion.d.ts

@@ -0,0 +1,25 @@
+import type { PrototypeRowPath } from './prototypeOccurrence.js';
+/** Names are opaque relative segments; the scene root name is excluded. */
+export interface PrototypeMotionLayer<T> {
+    nodeId: string;
+    names: readonly string[];
+    kind: string;
+    rowPath: PrototypeRowPath;
+    instancePath: readonly string[];
+    root?: boolean;
+    value: T;
+}
+export interface PrototypeMotionMatch<T> {
+    pairs: {
+        from: PrototypeMotionLayer<T>;
+        to: PrototypeMotionLayer<T>;
+    }[];
+    leaving: PrototypeMotionLayer<T>[];
+    entering: PrototypeMotionLayer<T>[];
+    diagnostics: {
+        code: string;
+        message: string;
+    }[];
+}
+/** Uncertain matches remain separate so the caller can crossfade them. Caller values stay untouched. */
+export declare function matchPrototypeMotionLayers<T>(from: readonly PrototypeMotionLayer<T>[], to: readonly PrototypeMotionLayer<T>[]): PrototypeMotionMatch<T>;

package/dist-lib/types/document/prototypeMotionContracts.d.ts

@@ -0,0 +1,30 @@
+import type { PrototypeOccurrence } from './prototypeOccurrence.js';
+/** A transient scalar sample. Velocity is measured in progress units per second. */
+export interface PrototypeMotionSample {
+    progress: number;
+    velocity: number;
+    finished: boolean;
+    reason?: 'settled' | 'duration-cap' | 'cancelled';
+}
+/** Positive scene-space distance; the direction supplies its sign. */
+export interface PrototypeDragConfiguration {
+    mode: 'scrub';
+    axis: 'x' | 'y';
+    direction: 1 | -1;
+    distance: number;
+    commitThreshold: number;
+}
+export interface PrototypeDragPoint {
+    x: number;
+    y: number;
+}
+export interface PrototypeDragAddress {
+    path: readonly string[];
+    occurrence?: PrototypeOccurrence;
+}
+/** A finite physical oscillator. Time supplied to its sampler is in milliseconds. */
+export interface PrototypeSpringParameters {
+    mass: number;
+    stiffness: number;
+    damping: number;
+}

package/dist-lib/types/document/prototypeSpring.d.ts

@@ -0,0 +1,28 @@
+import type { PrototypeEasing } from './prototype.js';
+import type { PrototypeMotionSample, PrototypeSpringParameters } from './prototypeMotionContracts.js';
+export interface PrototypeSpringPlan {
+    readonly from: number;
+    readonly to: number;
+    /** Absolute progress units per second, including when to < from. */
+    readonly initialVelocity: number;
+    readonly parameters: Readonly<PrototypeSpringParameters>;
+    readonly maxDurationMs: number;
+    readonly durationMs: number;
+    readonly reason: 'settled' | 'duration-cap';
+}
+export interface CreatePrototypeSpringPlanOptions {
+    parameters: PrototypeSpringParameters;
+    from?: number;
+    to?: number;
+    initialVelocity?: number;
+    /** Maximum physical time, bounded to ten seconds; never a trajectory scaling factor. */
+    durationMs: number;
+}
+export declare function resolvePrototypeSpringParameters(easing: Extract<PrototypeEasing, {
+    type: 'spring';
+}>): PrototypeSpringParameters;
+export declare function createPrototypeSpringPlan(input: CreatePrototypeSpringPlanOptions): PrototypeSpringPlan;
+export declare function samplePrototypeSpring(plan: PrototypeSpringPlan, elapsedMs: number): PrototypeMotionSample;
+/** Bounded piecewise-linear CSS approximation of physical samples, including overshoot and truncated endpoints.
+ * The last value is never forced to one. Equal endpoints with nonzero velocity need actual sampled keyframes. */
+export declare function prototypeSpringEasingCss(plan: PrototypeSpringPlan, sampleCount?: number): string;

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

@@ -10,6 +10,10 @@ export type { StylesPanelProps } from './workspace/edit/StylesPanel.js';
 export { TokenLibraryProvider, useTokenLibraryController, useHasTokenLibraryProvider } from './workspace/tokens/TokenLibraryContext.js';
 export { createTokenLibraryEngine, reopenTokenLibrary, validateTokenLibraryDocument, resolveTokenLibraryValue, tokenValueEditability, TokenLibraryValidationError } from './token-library/engine.js';
 export type * from './token-library/contracts.js';
+export { createTokenLibraryCache } from './token-library/cache.js';
+export type { TokenLibraryTextResolver, TokenLibraryPreviewContext, TokenLibraryCacheOptions, TokenLibraryCache } from './token-library/cache.js';
+export { formatTokenReferences, TokenReferenceFormatError } from './token-library/formatReferences.js';
+export type { TokenReferenceFormatContext } from './token-library/formatReferences.js';
 export { createTokenValueResolver } from './token-library/valueResolver.js';
 export type { TokenValueReferenceRange, TokenValueResolverOptions, ResolvedTokenText } from './token-library/valueResolver.js';
 export type * from './workspace/tokens/contracts.js';
@@ -419,10 +423,16 @@ export * from './workspace/edit/clipboard.js';
 export { AssetsPanel } from './workspace/edit/AssetsPanel.js';
 export type { AssetsPanelProps } from './workspace/edit/AssetsPanel.js';
 export * from './document/prototype.js';
+export * from './document/prototypeMotionContracts.js';
+export * from './document/prototypeDrag.js';
+export * from './document/prototypeSpring.js';
+export * from './document/prototypeEasing.js';
+export * from './document/prototypeMotion.js';
 export { remapPrototypeProperties } from './document/prototypeReferences.js';
 export { PrototypePanel } from './workspace/edit/PrototypePanel.js';
 export { PrototypePlayer } from './workspace/view/PrototypePlayer.js';
 export type { PrototypePlayerProps } from './workspace/view/PrototypePlayer.js';
 export * from './workspace/view/prototypePlayback.js';
+export type { PrototypeInputFrame } from './workspace/view/prototypeInputFrame.js';
 export { createPrototypeProjectionContext } from './workspace/edit/prototypeProjection.js';
 export type { PrototypeProjectionContext } from './workspace/edit/prototypeProjection.js';

package/dist-lib/types/token-library/cache.d.ts

@@ -0,0 +1,20 @@
+import type { TokenLibraryDocument } from './contracts.js';
+import type { ResolvedTokenText } from './valueResolver.js';
+export type TokenLibraryTextResolver = (tokenId: string, modeId: string) => ResolvedTokenText;
+export interface TokenLibraryPreviewContext {
+    document: TokenLibraryDocument;
+    modeId: string;
+    resolve: TokenLibraryTextResolver;
+}
+export interface TokenLibraryCacheOptions<Preview> {
+    createResolver(document: TokenLibraryDocument): TokenLibraryTextResolver;
+    createPreview(context: TokenLibraryPreviewContext): Preview;
+}
+export interface TokenLibraryCache<Preview> {
+    resolver(document: TokenLibraryDocument): TokenLibraryTextResolver;
+    preview(document: TokenLibraryDocument, modeId: string): Preview;
+    /** Invalidate callbacks' external baseline inputs; previously returned resolvers remain usable. */
+    clear(): void;
+}
+/** Cache immutable document snapshots by object identity without retaining discarded snapshots. */
+export declare function createTokenLibraryCache<Preview>(options: TokenLibraryCacheOptions<Preview>): TokenLibraryCache<Preview>;

package/dist-lib/types/token-library/formatReferences.d.ts

@@ -0,0 +1,12 @@
+import type { TokenReferenceSpan, TokenValue } from './contracts.js';
+export interface TokenReferenceFormatContext {
+    readonly reference: Readonly<TokenReferenceSpan>;
+    /** The exact original UTF-16 slice, unaffected by replacements of other spans. */
+    readonly original: string;
+}
+export declare class TokenReferenceFormatError extends Error {
+    readonly code: 'invalid-range' | 'invalid-replacement';
+    constructor(code: TokenReferenceFormatError['code'], message: string);
+}
+/** Validate every span before invoking a syntax-specific replacement callback. */
+export declare function formatTokenReferences(value: Pick<TokenValue, 'text' | 'references'>, replace: (context: TokenReferenceFormatContext) => string): string;

package/dist-lib/types/workspace/WorkspaceConditions.d.ts

@@ -0,0 +1,7 @@
+import type { EditorDeclarations } from '../editor/declarations.js';
+
+export interface WorkspaceConditionsProps {
+    declarations: Pick<EditorDeclarations, 'getSessionPresets' | 'getSelectedSessionPreset' | 'selectSessionPreset' | 'subscribeSessionPresets' | 'getPreviewEnvironmentControls' | 'getPreviewEnvironmentControlValue' | 'getPreviewEnvironmentControlSelections' | 'setPreviewEnvironmentControlValue' | 'clearPreviewEnvironmentControlValues' | 'subscribePreviewEnvironmentControls' | 'getPreviewEnvironmentControlRevision'>;
+}
+/** Present declared catalog sessions and preview values without interpreting product policy. */
+export declare function WorkspaceConditions({ declarations }: WorkspaceConditionsProps): import("react").JSX.Element | null;

package/dist-lib/types/workspace/WorkspaceShell.d.ts

@@ -1,4 +1,4 @@
-import type { WorkspaceConfiguration } from './configuration.js';
+import { type WorkspaceConfiguration } from './configuration.js';
 
 export interface WorkspaceShellProps {
     configuration: WorkspaceConfiguration;

package/dist-lib/types/workspace/edit/projection.d.ts

@@ -4,6 +4,8 @@ import type { DesignDocument, DocumentNode, DocumentResolveOptions } from '../..
 export interface ProjectedDocumentNode {
     sourceNodeId: string;
     instanceId?: string;
+    /** Runtime presentation may attach the canonical enclosing instance path. */
+    instancePath?: readonly string[];
     rowPath: BindingRuntimeScope['rowPath'];
     node: DocumentNode;
     children: ProjectedDocumentNode[];

package/dist-lib/types/workspace/view/StoryboardWorkspace.d.ts

@@ -1,3 +1,5 @@
-export declare const StoryboardWorkspace: import("react").FunctionComponent<{
+export interface StoryboardWorkspaceProps {
     sourceRevision: string;
-}>;
+    canEditSelected: boolean;
+}
+export declare const StoryboardWorkspace: import("react").FunctionComponent<StoryboardWorkspaceProps>;

package/dist-lib/types/workspace/view/prototypeInputFrame.d.ts

@@ -0,0 +1,13 @@
+/** Frame scheduling only. Input timestamps continue to come from the playback clock. */
+export interface PrototypeInputFrame {
+    request(callback: () => void): unknown;
+    cancel(handle: unknown): void;
+}
+/** Retain one latest value and publish it at most once per requested frame.
+ * Flush is for an owned release; cancel discards input on lifecycle changes.
+ * Generation checks also reject callbacks delivered after scheduler cancellation. */
+export declare function createPrototypeInputFrame<T>(frame: PrototypeInputFrame, publish: (value: T) => void): {
+    push(value: T): void;
+    flush: () => void;
+    cancel: () => void;
+};

package/dist-lib/types/workspace/view/prototypeMotionDom.d.ts

@@ -0,0 +1,5 @@
+import type { PrototypeMotionLayer } from '../../document/prototypeMotion.js';
+/** Collect both incoming and inert outgoing scenes without traversing outside the supplied scene.
+ * Legacy renderers can recover kinds from their source document. Unresolved or malformed
+ * identities remain invalid descriptors so they crossfade without being paired. */
+export declare function collectPrototypeMotionLayers(scene: HTMLElement, resolveKind?: (sourceNodeId: string) => string | undefined): PrototypeMotionLayer<HTMLElement>[];

package/dist-lib/types/workspace/view/prototypePlayback.d.ts

@@ -1,5 +1,7 @@
 import type { DesignDocument, DocumentNode, ResolvedDocumentNode } from '../../document/contracts.js';
 import { type PrototypeEffect, type PrototypeEvent, type PrototypeRuntimeContext, type PrototypeStartOptions, type PrototypeState } from '../../document/prototype.js';
+import { type PrototypeDragFinishInput, type PrototypeDragStartInput } from '../../document/prototypeDrag.js';
+import { type PrototypeInputFrame } from './prototypeInputFrame.js';
 export interface PrototypeClock {
     now(): number;
     schedule(callback: () => void, delayMs: number): unknown;
@@ -10,9 +12,18 @@ export interface PrototypePlayerSnapshot {
     previous: PrototypeState | null;
     effects: readonly PrototypeEffect[];
     playing: boolean;
+    drag: {
+        id: number;
+        phase: 'dragging' | 'settling';
+        progress: number;
+        velocity: number;
+        outcome: 'commit' | 'cancel' | null;
+    } | null;
 }
 export interface PrototypePlayerOptions extends PrototypeStartOptions {
     clock: PrototypeClock;
+    /** Optional presentation batching; raw samples still use this player's clock immediately. */
+    inputFrame?: PrototypeInputFrame;
     /** Effects describe intended links and scrolling; the adapter decides how to execute them. */
     onEffect?(effect: PrototypeEffect): void;
 }
@@ -20,6 +31,9 @@ export interface PrototypePlayerController {
     getSnapshot(): PrototypePlayerSnapshot;
     subscribe(listener: () => void): () => void;
     dispatch(event: PrototypeEvent): void;
+    beginDrag(input: Omit<PrototypeDragStartInput, 'now'>): boolean;
+    updateDrag(input: Pick<PrototypeDragStartInput, 'pointerId' | 'point'>): void;
+    endDrag(input: Omit<PrototypeDragFinishInput, 'now'>): void;
     pause(): void;
     resume(): void;
     dispose(): void;

package/dist-lib/types/workspace/view/storyboardCanvas.d.ts

@@ -0,0 +1,42 @@
+import type { PageModel } from '../../editor/store.js';
+import type { StoryboardGraph, StoryboardGraphEdge } from '../../editor/storyboardGraph.js';
+import type { WorkspaceCamera } from '../contracts.js';
+export interface StoryboardBounds {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface StoryboardViewport {
+    width: number;
+    height: number;
+}
+export interface StoryboardArtboard extends StoryboardBounds {
+    page: PageModel;
+    screenId: string;
+    group: string;
+}
+export interface StoryboardConnection {
+    edge: StoryboardGraphEdge;
+    from: StoryboardArtboard;
+    to: StoryboardArtboard;
+    path: string;
+    labelX: number;
+    labelY: number;
+}
+export declare const storyboardFlow: (page: PageModel) => string;
+/** Arrange source-sized screens in flow lanes; never rewrite authored page geometry. */
+export declare function layoutStoryboard(pages: readonly PageModel[]): {
+    frames: StoryboardArtboard[];
+    bounds: StoryboardBounds;
+};
+export declare function storyboardFrameBounds(frame: StoryboardBounds): StoryboardBounds;
+export declare function fitStoryboard(bounds: StoryboardBounds, viewport: StoryboardViewport): WorkspaceCamera;
+/** Preserve the world point under the pointer when zooming. */
+export declare function zoomStoryboard(camera: WorkspaceCamera, point: {
+    x: number;
+    y: number;
+}, requested: number): WorkspaceCamera;
+export declare function visibleStoryboardFrames(frames: readonly StoryboardArtboard[], camera: WorkspaceCamera, viewport: StoryboardViewport): StoryboardArtboard[];
+/** A line means an authored transition. Layout proximity never creates an edge. */
+export declare function storyboardConnections(frames: readonly StoryboardArtboard[], graph: StoryboardGraph | null): StoryboardConnection[];

package/dist-lib/types/workspace/view/storyboardCaptures.d.ts

@@ -0,0 +1,26 @@
+import type { EditorRuntime } from '../../core/runtime.js';
+import { type CaptureSupplyDriverDeps } from '../../editor/captureSupply.js';
+import type { RoutePreviewArtifactOutcome } from '../../editor/routePreview.js';
+import type { PageModel } from '../../editor/store.js';
+type Runtime = Pick<EditorRuntime, 'host' | 'previews' | 'declarations'>;
+export interface StoryboardCaptureDemand {
+    sourceRevision: string;
+    /** Only frames intersecting the canvas viewport, after its catalog filters. */
+    pages: readonly PageModel[];
+    selected?: PageModel;
+}
+export interface StoryboardCaptureState {
+    outcome: RoutePreviewArtifactOutcome | null;
+    status: 'missing' | 'generating' | 'ready' | 'stale' | 'failed';
+    message?: string;
+    retry(): void;
+}
+/** Demand comes from the canvas; transport, deduplication and bounded readiness retries remain shared. */
+export declare function createStoryboardCaptureController(runtime: Runtime, timers?: Pick<CaptureSupplyDriverDeps, 'setTimeout' | 'clearTimeout'>): {
+    update: (next: StoryboardCaptureDemand, retryId?: string) => void;
+    dispose: () => void;
+    subscribe: (listener: () => void) => () => void;
+    getSnapshot: () => import("../../editor/captureSupply.js").CaptureSupplyStatus;
+    capture(page: PageModel, sourceRevision?: string): StoryboardCaptureState;
+};
+export {};

package/dist-lib/types/workspace/view/useStoryboardCaptures.d.ts

@@ -0,0 +1,5 @@
+import type { EditorRuntime } from '../../core/runtime.js';
+import type { PageModel } from '../../editor/store.js';
+import { type StoryboardCaptureDemand } from './storyboardCaptures.js';
+/** Canvas visibility is supplied by its layout; repeated renders cannot enqueue another identical plan. */
+export declare function useStoryboardCaptures(runtime: EditorRuntime, demand: StoryboardCaptureDemand): (page: PageModel) => import("./storyboardCaptures.js").StoryboardCaptureState;

package/node/preview-capture-worker.mjs

@@ -231,6 +231,7 @@ export function createPreviewCaptureWorkerChannel({
   let degraded = false;
   let disposed = false;
   let idleTimer = null;
+  let restartWait = null;
   let requestCounter = 0;
   const crashTimestamps = [];
 
@@ -441,14 +442,21 @@ export function createPreviewCaptureWorkerChannel({
         // The wedged worker was killed and the crash recorded. When that
         // crash exhausted the restart budget, the caller takes the degraded
         // path; otherwise fall through to a fresh spawn below.
+        if (disposed) throw new Error('Preview capture worker channel is disposed.');
         if (degraded) return null;
       }
     }
     const backoff = restartBackoffMs();
     if (backoff > 0) {
-      await new Promise((resolve) => {
-        const timer = setTimeout(resolve, backoff);
-        timer.unref?.();
+      await new Promise((resolve, reject) => {
+        const pending = { timer: null, reject };
+        // There is no child process during backoff. The active capture owns
+        // this delay until it completes or dispose cancels the request.
+        pending.timer = setTimeout(() => {
+          if (restartWait === pending) restartWait = null;
+          resolve();
+        }, backoff);
+        restartWait = pending;
       });
     }
     if (disposed) {
@@ -595,6 +603,12 @@ export function createPreviewCaptureWorkerChannel({
     if (disposed) return;
     disposed = true;
     clearIdleTimer();
+    if (restartWait) {
+      const pending = restartWait;
+      restartWait = null;
+      clearTimeout(pending.timer);
+      pending.reject(new Error('Preview capture worker channel is disposed.'));
+    }
     await stopWorker();
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pygmalionjs/pygmalion",
-  "version": "0.11.1",
+  "version": "0.13.0",
   "description": "Code-backed DOM design sandbox and visual QA editor",
   "license": "Apache-2.0",
   "repository": {