@pygmalionjs/pygmalion 0.6.17 → 0.6.19

package/dist-lib/testing.js

@@ -1,4 +1,4 @@
-import { F as s, N as a, e as r, s as i, a as t } from "./FrozenRoutePreview-BBgXrlKF.js";
+import { F as s, N as a, e as r, s as i, a as t } from "./FrozenRoutePreview-B6UY1aLt.js";
 export {
   s as FrozenRoutePreviewView,
   a as NodeModel,

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

@@ -1,3 +1,4 @@
+import { type InteractiveSessionSurface } from '../editor/interactiveSessionSurface';
 /**
  * True while a flow session still owes this screen its snapshot. Frames use
  * it exactly like the artifact-hydration gate: activation waits for the
@@ -24,11 +25,18 @@ export declare function useViewportSessionPending(page: {
  * itself — the session does that work in one instance the warm pool keeps.
  */
 export declare function useInteractiveSessionPending(page: {
-    importPageId?: string;
     id: string;
     interactiveStateId?: string;
     interactiveOptionId?: string;
-}): boolean;
+    interactiveOptionIds?: readonly string[];
+}, targetCacheKey?: string): boolean;
+/** The runner-owned live document currently reproducing this state. */
+export declare function useInteractiveSessionSurface(page: {
+    id: string;
+    interactiveStateId?: string;
+    interactiveOptionId?: string;
+    interactiveOptionIds?: readonly string[];
+}): InteractiveSessionSurface | null;
 /**
  * True while this frame holds one of the host's live screen slots, meaning it
  * renders the running app rather than its frozen capture.

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

@@ -60,6 +60,16 @@ export interface DesignScreenInteraction {
     settleMs?: number;
     optional?: boolean;
 }
+/** Timing policy for replaying a screen recipe outside the capture pipeline. */
+export interface DesignScreenInteractionRunOptions {
+    /**
+     * Fallback pause after click, focus, hover, fill, check, and press steps.
+     * The capture default is 600ms. A step's explicit `settleMs` always wins.
+     */
+    defaultActionSettleMs?: number;
+    /** Called after boot presets succeed and immediately before actions begin. */
+    onBeforeInteractions?: () => void;
+}
 /** A JSON-compatible value that conveys host-specific meaning without Pygmalion interpreting it. */
 export type DesignSerializable = string | number | boolean | null | readonly DesignSerializable[] | {
     readonly [key: string]: DesignSerializable;
@@ -442,9 +452,9 @@ export interface DesignImportController {
         timeoutMs?: number;
         minElementCount?: number;
     }): Promise<DomImportResult | null>;
-    runScreenInteractions(iframe: HTMLIFrameElement, interactions: readonly DesignScreenInteraction[]): Promise<DesignScreenInteractionReport>;
+    runScreenInteractions(iframe: HTMLIFrameElement, interactions: readonly DesignScreenInteraction[], options?: DesignScreenInteractionRunOptions): Promise<DesignScreenInteractionReport>;
     /** Reproduces and verifies state without waiting for capture-only stability. */
-    prepareScreenState?(iframe: HTMLIFrameElement, spec: DesignScreenCaptureSpec): Promise<DesignScreenCaptureReport>;
+    prepareScreenState?(iframe: HTMLIFrameElement, spec: DesignScreenCaptureSpec, options?: DesignScreenInteractionRunOptions): Promise<DesignScreenCaptureReport>;
     prepareScreenCapture(iframe: HTMLIFrameElement, spec: DesignScreenCaptureSpec): Promise<DesignScreenCaptureReport>;
 }
 /**

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

@@ -1,4 +1,9 @@
+import { type DesignImportController, type DesignScreenCaptureSpec } from './designImport';
+import type { ResolvedFlowPath } from './flowSessions';
+import type { ScreenFlowPath } from './screenFlows';
 import { type PageModel } from './store';
+/** Applies the active frame's own boot condition to a path-specific session. */
+export declare function resolveActivePagePath(resolved: ResolvedFlowPath, path: ScreenFlowPath, page: PageModel): ResolvedFlowPath;
 /** Diagnostic counters for the headless debug surface. */
 export declare const __flowSchedulerDebug: {
     calls: number;
@@ -62,6 +67,19 @@ export declare function viewportSessionWillDeliver(page: {
 }): boolean;
 /** Subscribe to viewport-variant delivery changes. */
 export declare function subscribeViewportSessions(listener: () => void): () => void;
+type InteractivePreparationController = Pick<DesignImportController, 'prepareScreenCapture' | 'prepareScreenState'>;
+/**
+ * Reproduces an editor-controlled state without capture-only quiescence.
+ * The runner already waits for a trailing paint and stable geometry before it
+ * serializes, so repeating the capture stability pass only delays the panel.
+ */
+export declare function prepareInteractiveSessionState(iframe: HTMLIFrameElement, spec: DesignScreenCaptureSpec, controller?: InteractivePreparationController | null, onBeforeInteractions?: () => void): Promise<import("./designImport").DesignScreenCaptureReport>;
+export declare function interactiveSessionScreenId(page: {
+    id: string;
+    interactiveStateId?: string;
+    interactiveOptionId?: string;
+    interactiveOptionIds?: readonly string[];
+}): string;
 /**
  * Materializes one screen in its declared interactive state through the
  * screen's flow path. The prefix walks as pass-through; the target publishes
@@ -70,14 +88,14 @@ export declare function subscribeViewportSessions(listener: () => void): () => v
  * Returns false when no flow claims the screen — those frames keep the live
  * boot fallback.
  */
-export declare function materializePageInteractiveState(page: PageModel, previewRevision: string): boolean;
+export declare function materializePageInteractiveState(page: PageModel, previewRevision: string, targetCacheKey?: string): boolean;
 /** True while an interactive-state session still owes this page its snapshot. */
 export declare function interactiveSessionWillDeliver(page: {
-    importPageId?: string;
     id: string;
     interactiveStateId?: string;
     interactiveOptionId?: string;
-}): boolean;
+    interactiveOptionIds?: readonly string[];
+}, targetCacheKey?: string): boolean;
 /** Subscribe to interactive-state delivery changes. */
 export declare function subscribeInteractiveSessions(listener: () => void): () => void;
 /** Diagnostic counters for the interactive-state path. */
@@ -101,3 +119,4 @@ export declare const __viewportCommitDebug: {
 };
 /** Viewport-runner delivery states for the headless debug surface. */
 export declare function __debugViewportSessionStates(): Record<string, unknown>;
+export {};

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

@@ -87,7 +87,7 @@ export interface FlowSessionRunnerOptions {
         preset?: DesignScreenPreset;
         interactions?: readonly DesignScreenInteraction[];
         assertions?: readonly DesignScreenAssertion[];
-    }) => Promise<DesignScreenCaptureReport>;
+    }, waypoint: ResolvedFlowWaypoint) => Promise<DesignScreenCaptureReport>;
     /** Extra settle before serializing a waypoint (fonts, trailing paints). */
     settle?: (iframe: HTMLIFrameElement, ms: number) => Promise<void>;
     /** Layout-stability wait before serializing. Defaults to waitForGeometryStability. */
@@ -95,6 +95,8 @@ export interface FlowSessionRunnerOptions {
     serialize?: (iframe: HTMLIFrameElement, fallbackUrl: string) => string | null;
     /** Writes one waypoint snapshot into the route preview store. */
     publish?: (cacheKey: string, snapshot: string) => boolean;
+    /** Releases a live document after its delivery finishes or is abandoned. */
+    onWaypointFinish?: (iframe: HTMLIFrameElement, waypoint: ResolvedFlowWaypoint, outcome: 'completed' | 'failed' | 'cancelled') => void;
     onError?: (pathId: string, error: unknown) => void;
 }
 /**
@@ -144,6 +146,11 @@ export declare function createFlowSessionRunner(options?: FlowSessionRunnerOptio
     setConcurrency(next: number): void;
     /** Session state of one screen, or null when no session claims it. */
     screenState(screenId: string): FlowScreenState | null;
+    /**
+     * Forgets a terminal delivery whose external snapshot was evicted. A
+     * running or queued screen keeps its claim and cannot be invalidated.
+     */
+    forgetScreen(screenId: string): boolean;
     /** True while the session still owes this screen its snapshot. */
     willDeliver(screenId: string): boolean;
     subscribe(listener: () => void): () => void;

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

@@ -0,0 +1,18 @@
+/**
+ * The live document currently reproducing a right-panel screen state.
+ *
+ * State preservation and state presentation are intentionally separate. The
+ * flow runner keeps this iframe alive until its exact frozen snapshot is
+ * published, while the active frame may mirror the running document
+ * immediately so capture stability never becomes interaction latency.
+ */
+export interface InteractiveSessionSurface {
+    iframe: HTMLIFrameElement;
+    screenId: string;
+}
+/** Exposes a runner-owned iframe without transferring its ownership. */
+export declare function exposeInteractiveSessionSurface(screenId: string, iframe: HTMLIFrameElement): void;
+/** Releases a surface only when the caller still owns the registered iframe. */
+export declare function releaseInteractiveSessionSurface(screenId: string, iframe: HTMLIFrameElement): void;
+export declare function getInteractiveSessionSurface(screenId: string): InteractiveSessionSurface | null;
+export declare function subscribeInteractiveSessionSurface(screenId: string, listener: () => void): () => void;

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

@@ -1,4 +1,4 @@
-import type { DesignScreenInteraction, DesignScreenInteractionReport } from './designImport';
+import type { DesignScreenInteraction, DesignScreenInteractionRunOptions, DesignScreenInteractionReport } from './designImport';
 export declare function settleScreen(iframe: HTMLIFrameElement, settleMs: number): Promise<void>;
 export declare function elementVisible(element: Element): boolean;
-export declare function runScreenInteractions(iframe: HTMLIFrameElement, interactions: readonly DesignScreenInteraction[]): Promise<DesignScreenInteractionReport>;
+export declare function runScreenInteractions(iframe: HTMLIFrameElement, interactions: readonly DesignScreenInteraction[], options?: DesignScreenInteractionRunOptions): Promise<DesignScreenInteractionReport>;

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

@@ -91,7 +91,7 @@ export type { ConditionCoverageRoute, ConditionCoverageScreen, ConformanceScreen
 export { clearPreviewEnvironmentControlValues, getPreviewEnvironmentControlValue, getPreviewEnvironmentControls, getPreviewEnvironmentOverride, setPreviewEnvironmentControlValue, setPreviewEnvironmentControls, subscribePreviewEnvironmentControls, } from './editor/previewEnvironmentControls';
 export type { PreviewEnvironmentControlDef, PreviewEnvironmentControlOptionDef, } from './editor/previewEnvironmentControls';
 export { createDesignImportController, createDesignScreenCollection, DESIGN_IMPORT_KINDS, expandDesignScreenCasesViewports, expandDesignScreenCollectionViewports, mergeScreenPresets, } from './editor/designImport';
-export type { CreateDesignImportOptions, DesignBehaviorScenario, DesignImportAsset, DesignImportCollection, DesignImportController, DesignImportCoverage, DesignImportCoverageItem, DesignImportInitialPage, DesignImportKind, DesignImportManifest, DesignImportPage, DesignFrameHeightMode, DesignFrameSizeMode, DesignScenarioCoverage, DesignScenarioSource, DesignScreenCase, DesignScreenAssertion, DesignScreenAssertionReport, DesignScreenAssertionVisibility, DesignScreenAttributeAssertion, DesignScreenCaptureFailure, DesignScreenCaptureFailureCode, DesignScreenCaptureFailureStage, DesignScreenCaptureDefaults, DesignScreenCaptureRequirements, DesignScreenCaptureReport, DesignScreenCaptureSpec, DesignScreenCollectionResult, DesignScreenInteraction, DesignScreenInteractionAction, DesignScreenInteractionReport, DesignScreenPreset, DesignScreenPresetContext, DesignScreenPresetExecutionResult, DesignScreenPresetExecutor, DesignScreenPresetRequest, DesignScreenViewport, DesignScreenViewportExpansionOptions, DesignScreenViewportPagePatch, DesignSerializable, StoryboardEnvironment, StoryboardMediaDevice, StoryboardMediaFailure, StoryboardNetwork, StoryboardPermissionState, StoryboardRequestCondition, StoryboardRequestOutcome, } from './editor/designImport';
+export type { CreateDesignImportOptions, DesignBehaviorScenario, DesignImportAsset, DesignImportCollection, DesignImportController, DesignImportCoverage, DesignImportCoverageItem, DesignImportInitialPage, DesignImportKind, DesignImportManifest, DesignImportPage, DesignFrameHeightMode, DesignFrameSizeMode, DesignScenarioCoverage, DesignScenarioSource, DesignScreenCase, DesignScreenAssertion, DesignScreenAssertionReport, DesignScreenAssertionVisibility, DesignScreenAttributeAssertion, DesignScreenCaptureFailure, DesignScreenCaptureFailureCode, DesignScreenCaptureFailureStage, DesignScreenCaptureDefaults, DesignScreenCaptureRequirements, DesignScreenCaptureReport, DesignScreenCaptureSpec, DesignScreenCollectionResult, DesignScreenInteraction, DesignScreenInteractionAction, DesignScreenInteractionRunOptions, DesignScreenInteractionReport, DesignScreenPreset, DesignScreenPresetContext, DesignScreenPresetExecutionResult, DesignScreenPresetExecutor, DesignScreenPresetRequest, DesignScreenViewport, DesignScreenViewportExpansionOptions, DesignScreenViewportPagePatch, DesignSerializable, StoryboardEnvironment, StoryboardMediaDevice, StoryboardMediaFailure, StoryboardNetwork, StoryboardPermissionState, StoryboardRequestCondition, StoryboardRequestOutcome, } from './editor/designImport';
 export type { DomImportDiagnostic, DomImportMetrics, DomImportOptions, DomImportResult, } from './editor/domImport';
 export type { SharedSourceEditScope, SharedSourceFrameSummary, SharedSourceImpact, } from './editor/sharedSource';
 export type { NodeJSON } from './editor/store';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pygmalionjs/pygmalion",
-  "version": "0.6.17",
+  "version": "0.6.19",
   "description": "Code-backed DOM design sandbox and visual QA editor",
   "license": "UNLICENSED",
   "publishConfig": {