@pygmalionjs/pygmalion 0.5.18 → 0.5.20

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

@@ -18,7 +18,24 @@ export interface PreviewArtifactExpectation {
 export interface PreviewArtifactFrameRequest {
     id: string;
     fingerprint?: string;
+    /** The recipe the fingerprint stands for; travels only where a capture may run. */
+    recipe?: RoutePreviewFrameRecipe;
 }
+/**
+ * Where a capture request sits among captures waiting on the same identity.
+ * Smaller runs first. Mirrors `PREVIEW_CAPTURE_PRIORITY` in
+ * `node/preview-artifact-plugin.mjs` (browser code cannot import the Node
+ * plugin); a shared test pins the pair.
+ */
+export declare const PREVIEW_CAPTURE_PRIORITY: Readonly<{
+    /** A frame the designer selected: whatever else is queued waits. */
+    selected: 0;
+    /** The canvas in front of the designer being filled. */
+    canvas: 10;
+    /** A canvas nobody is looking at yet. */
+    background: 20;
+}>;
+export type PreviewCapturePriority = (typeof PREVIEW_CAPTURE_PRIORITY)[keyof typeof PREVIEW_CAPTURE_PRIORITY];
 export interface PreviewArtifactTransportRequest extends PreviewArtifactExpectation {
     /** Frames to fetch. Omitted asks for the whole bundle, as earlier versions did. */
     frames?: readonly PreviewArtifactFrameRequest[];
@@ -26,6 +43,8 @@ export interface PreviewArtifactTransportRequest extends PreviewArtifactExpectat
     generate?: boolean;
     /** Return only exact/missing/stale classification, without frame payloads. */
     resolveOnly?: boolean;
+    /** Where this capture queues among others on the identity; see PREVIEW_CAPTURE_PRIORITY. */
+    priority?: number;
     signal?: AbortSignal;
     captureBaseUrl?: string;
 }
@@ -36,14 +55,29 @@ export interface PreviewArtifactHttpResponse {
     readonly statusText?: string;
     json(): Promise<unknown>;
 }
-export type PreviewArtifactFetch = (input: string, init: {
+/**
+ * A probe reads; it travels as GET with the frame identities in the query. A
+ * capture request carries a recipe per frame, which a query string cannot
+ * hold past a handful of frames, so it travels as a JSON body.
+ */
+export type PreviewArtifactFetchInit = {
     method: 'GET';
     headers: {
         accept: 'application/json';
     };
     cache: 'no-store';
     signal?: AbortSignal;
-}) => Promise<PreviewArtifactHttpResponse>;
+} | {
+    method: 'POST';
+    headers: {
+        accept: 'application/json';
+        'content-type': 'application/json';
+    };
+    body: string;
+    cache: 'no-store';
+    signal?: AbortSignal;
+};
+export type PreviewArtifactFetch = (input: string, init: PreviewArtifactFetchInit) => Promise<PreviewArtifactHttpResponse>;
 export interface PreviewArtifactHttpTransportOptions {
     endpoint: string;
     fetcher?: PreviewArtifactFetch;
@@ -134,6 +168,23 @@ export interface PreviewFramePage {
     interactions?: unknown;
     assertions?: unknown;
 }
+/**
+ * What the fingerprint of a frame stands for.
+ *
+ * The fingerprint is a hash, so a generator handed one alone can only capture
+ * what the host declared for that id — a different screen wearing the requested
+ * name. Sending the recipe beside it is what lets a frame held in a declared
+ * state be captured as the state it is actually in.
+ *
+ * The interaction list stays opaque here for the same reason the page's does:
+ * this package transports the host's recipe, it does not read it.
+ */
+export interface RoutePreviewFrameRecipe {
+    environment?: StoryboardEnvironment;
+    interactions?: unknown;
+}
+/** The recipe behind createRoutePreviewFrameFingerprint, for the same page. */
+export declare function routePreviewFrameRecipe(page: PreviewFramePage, baselineEnvironment?: StoryboardEnvironment): RoutePreviewFrameRecipe | undefined;
 /**
  * Identity of one frame's capture, derived the same way wherever it is needed.
  *
@@ -181,9 +232,10 @@ export declare function validatePreviewArtifactBundle(value: unknown, expectatio
  * 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 & {
+export declare function bootstrapPreviewArtifact({ namespace, sourceRevision, transport, signal, frames, generate, priority, }: PreviewArtifactExpectation & {
     transport: PreviewArtifactTransport;
     signal?: AbortSignal;
     frames?: readonly PreviewArtifactFrameRequest[];
     generate?: boolean;
+    priority?: number;
 }): Promise<PreviewArtifactBootstrapResult>;

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

@@ -5,6 +5,16 @@
  * install, preview boot). 420s gives that chain a minute of headroom.
  */
 export declare const MIRROR_SYNC_POLL_TIMEOUT_MS = 420000;
+/**
+ * Poll cadence while the mirror sits idle.
+ *
+ * Idle means nobody has asked for the checkout yet, and the ask can come from
+ * outside this editor's own controls — a frame requesting its capture reaches
+ * the server directly. The server has no way to tell the page that the work it
+ * triggered has landed, so an idle mirror is watched rather than assumed
+ * settled. This only reads status; it never orders a checkout.
+ */
+export declare const MIRROR_IDLE_POLL_INTERVAL_MS = 2000;
 /** Poll cadence while the mirror reports 'syncing'. */
 export declare const MIRROR_SYNC_POLL_INTERVAL_MS = 500;
 /** First automatic boot-retry delay after a failed refresh. */

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

@@ -1,6 +1,7 @@
 import { type RoutePreviewArtifactBundleV2 } from './routePreviewArtifactV2.js';
 import { type RoutePreviewArtifactBundleV3, type RoutePreviewArtifactV3Diagnostic, type RoutePreviewArtifactV3Status } from './routePreviewArtifactV3.js';
 import type { StoryboardEnvironment } from './designImport';
+import type { RoutePreviewFrameRecipe } from './previewBootstrap';
 import { type InstanceResolver } from './fiberMap';
 type SlotRelease = () => void;
 export interface RoutePreviewRecipe {
@@ -64,6 +65,13 @@ export interface RoutePreviewArtifactSeedResult {
 export interface RoutePreviewArtifactFrameIdentity {
     id: string;
     fingerprint?: string;
+    /**
+     * The recipe the fingerprint stands for, carried so a generator can reproduce
+     * it. Without this a host can only re-capture what it declared for the id and
+     * label it with the requested fingerprint — the frame then answers "exact"
+     * with the screen the axis was supposed to change.
+     */
+    recipe?: RoutePreviewFrameRecipe;
 }
 /** Lifecycle of resolving one frame against an exact artifact endpoint. */
 export type RoutePreviewArtifactResolution = {
@@ -88,6 +96,7 @@ export type RoutePreviewArtifactFrameRequestResult = {
     status: 'unavailable';
     message?: string;
     notPrepared?: boolean;
+    absent?: readonly string[];
 } | {
     status: 'rejected';
     message: string;
@@ -164,7 +173,11 @@ export declare function isRoutePreviewSnapshotHydrated(key: string): boolean;
  * Persistent cache identity excluding random mirror ports.
  * By normalizing the object key order, the same screen recipe always uses the same key.
  */
-type RoutePreviewFrameRequester = (frames: readonly RoutePreviewArtifactFrameIdentity[]) => RoutePreviewArtifactFrameRequestResult | Promise<RoutePreviewArtifactFrameRequestResult> | void;
+export interface RoutePreviewFrameRequestOptions {
+    /** Where the capture queues among others; see PREVIEW_CAPTURE_PRIORITY. */
+    priority?: number;
+}
+type RoutePreviewFrameRequester = (frames: readonly RoutePreviewArtifactFrameIdentity[], options?: RoutePreviewFrameRequestOptions) => RoutePreviewArtifactFrameRequestResult | Promise<RoutePreviewArtifactFrameRequestResult> | void;
 /** Installed by the host adapter, which owns the transport. */
 export declare function setRoutePreviewArtifactFrameRequester(requester: RoutePreviewFrameRequester | null): void;
 /**
@@ -172,6 +185,7 @@ export declare function setRoutePreviewArtifactFrameRequester(requester: RoutePr
  * only an active or deliberately hovered frame may boot the live application.
  */
 export declare function setRoutePreviewArtifactEndpointConfigured(configured: boolean): void;
+export declare function isRoutePreviewArtifactEndpointConfigured(): boolean;
 export declare function shouldStartRoutePreviewProducer({ detailActive, previewIntended, }: {
     detailActive: boolean;
     previewIntended: boolean;
@@ -195,19 +209,25 @@ export declare function shouldRequestRoutePreviewArtifactFrame({ cacheHydrated,
  */
 export declare function requestRoutePreviewArtifactFrame(id: string, fingerprint?: string, options?: {
     retry?: boolean;
+    recipe?: RoutePreviewFrameRecipe;
+    priority?: number;
 }): Promise<RoutePreviewArtifactResolution> | null;
 /**
  * Asks for many frames' captures in one requester call.
  *
- * The background sweep delegates its interaction screens in chunks, and a
- * chunk must not fan out into one transport round trip per frame. Identities
- * already resolved exactly, already generating, or already failed are skipped
- * (an error is retried only on request); the remaining frames share a single
- * requester call and a single resolution, and each identity joins the same
- * in-flight dedupe map the single-frame request uses.
+ * A canvas being filled and the background sweep both name frames in chunks,
+ * and a chunk must not fan out into one transport round trip per frame — nor
+ * into one capture job per frame, which is what left the worker's lanes idle.
+ * Identities already resolved exactly, already generating, or already failed
+ * are skipped (an error is retried only on request); the remaining frames
+ * share a single requester call and a single resolution, and each identity
+ * joins the same in-flight dedupe map the single-frame request uses. Each
+ * frame's recipe travels with it, so a generator can reproduce a variant
+ * instead of re-capturing what the host declared for the id.
  */
 export declare function requestRoutePreviewArtifactFrames(frames: readonly RoutePreviewArtifactFrameIdentity[], options?: {
     retry?: boolean;
+    priority?: number;
 }): Promise<RoutePreviewArtifactResolution> | null;
 export declare function createRoutePreviewRecipeKey(recipe: RoutePreviewRecipe): string;
 /**

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

@@ -196,6 +196,12 @@ export interface PageModel {
     /** Declared interactive axis the frame is currently held in, if any. */
     interactiveStateId?: string;
     interactiveOptionId?: string;
+    /**
+     * Options held together on a combining axis (InteractiveStateDef.multiple).
+     * Kept beside the single-option field rather than replacing it so an
+     * exclusive axis reads exactly as before.
+     */
+    interactiveOptionIds?: string[];
     /**
      * The case's own environment, kept so clearing an interactive option can put
      * `environment` back without reconstructing what the case declared. Same shape

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

@@ -0,0 +1,37 @@
+import type { StoryboardGraphFrameView, StoryboardGraphViewModel } from './storyboardGraphView';
+/**
+ * The journey a catalog actually tells, and everything that hangs off it.
+ *
+ * A storyboard reads as a list of relations: starts, branches, aliases. Each
+ * is true and none of them is the thing a person is looking for, which is
+ * "where am I in the walk through this product". Measured on one real catalog:
+ * 75 screens, 50 declared paths, and 30 of those paths two screens long — so
+ * the previous/next of a single frame was, for most frames, a fragment with
+ * nothing before or after it. The walk itself was never shown.
+ *
+ * The spine is the longest run of declared transitions from a start. On that
+ * same catalog it is twelve steps — entry through to the recommendations after
+ * a recording — and every other screen sits one hop off it. That makes the
+ * spine an index a reader can hold: the product's main line, with each
+ * detour named under the step it leaves from.
+ */
+export interface StoryboardJourney {
+    /** Frame ids along the main line, in order. Empty when nothing is declared. */
+    spine: readonly string[];
+    /** Frames one hop off the spine, keyed by the spine step they leave from. */
+    detours: ReadonlyMap<string, readonly string[]>;
+    /** Where a frame sits: its spine step, for a frame that is not on the spine. */
+    detourParent: ReadonlyMap<string, string>;
+    /**
+     * Frames the walk never reaches. A frame is not automatically wrong for
+     * being here — an error state is a real end — but a catalog where half the
+     * screens are unreachable from its own main line is describing that.
+     */
+    offJourney: readonly string[];
+}
+/** Resolves the journey a model describes. */
+export declare function storyboardJourney(model: StoryboardGraphViewModel): StoryboardJourney;
+/** The step a frame is read against: itself when on the spine, else its parent. */
+export declare function journeyAnchorFor(journey: StoryboardJourney, frameId: string | null | undefined): string | null;
+/** Frames that end the walk — nothing declared follows them. */
+export declare function journeyDeadEnds(model: StoryboardGraphViewModel): readonly StoryboardGraphFrameView[];

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

@@ -205,7 +205,7 @@ export declare function pygmalionOpenPreview(): void;
 export declare function pygmalionResetCurrentEdits(): boolean;
 export interface InitialPageDef extends DesignImportInitialPage {
 }
-export declare function PygmalionEditor({ registry, tokens, initialPages, initialCanvas, initialEditMode, componentConnections, viewportPresets, previewEnvironmentControls, designImport, onTokensChange, appOrigin, previewRevision, previewCacheNamespace, previewArtifacts, previewArtifactEndpoint, previewConcurrency, previewOpen, onPreviewOpenChange, flowCanvas, frameSurface, screenFlows, scenarioCoverage, screenDimensions, screenLists, sectionHeaders, sectionHeaderLabels, screenLanes, frameBranchKinds, frameLabelLabels, screenCards, liveScreenBudget, interactiveStates, surfaceClassifications, onApply, onDesignChange, onInspectApply, onInspectPreview, onInspectImpact, storyboard, storyboardDiscovery, storyboardDiscoveryEndpoint, }: {
+export declare function PygmalionEditor({ registry, tokens, initialPages, initialCanvas, initialEditMode, componentConnections, viewportPresets, previewEnvironmentControls, designImport, onTokensChange, appOrigin, previewRevision, previewCacheNamespace, previewArtifacts, previewArtifactEndpoint, previewConcurrency, previewOpen, onPreviewOpenChange, flowCanvas, frameSurface, captureSupply, screenFlows, screenFlowConcurrency, scenarioCoverage, screenDimensions, screenLists, sectionHeaders, sectionHeaderLabels, screenLanes, frameBranchKinds, frameLabelLabels, screenCards, liveScreenBudget, interactiveStates, surfaceClassifications, onApply, onDesignChange, onInspectApply, onInspectPreview, onInspectImpact, storyboard, storyboardDiscovery, storyboardDiscoveryEndpoint, }: {
     registry?: ComponentRegistry;
     tokens?: TokenDef[];
     initialPages?: InitialPageDef[];
@@ -257,14 +257,34 @@ export declare function PygmalionEditor({ registry, tokens, initialPages, initia
      * promotion-ready without a mount wait.
      */
     frameSurface?: 'bitmap' | 'dom';
+    /**
+     * Who fills a canvas first. `worker-first` asks the capture worker behind
+     * `previewArtifactEndpoint` for the active canvas in batches (nearest the
+     * viewport first, other canvases after, in the background) and keeps the
+     * walking sessions and per-screen sweep as the fallback for what the worker
+     * cannot answer. `browser-first` fills the canvas inside the editor — the
+     * walking sessions and sweep — and uses the worker only for the frame the
+     * designer selects. Defaults to worker-first when an endpoint is configured
+     * and browser-first otherwise.
+     */
+    captureSupply?: 'worker-first' | 'browser-first';
     /**
      * Host-declared flow paths — the captureless surface supply. One hidden
      * live instance boots per path and walks its waypoints, publishing a
      * frozen snapshot per screen into the preview store; frames whose screen a
      * flow claims wait for the delivery instead of booting live themselves.
      * Screens no flow claims keep the classic artifact/sweep/boot supply.
+     * Under worker-first supply, flows walk only the screens the worker
+     * released.
      */
     screenFlows?: readonly ScreenFlowPath[];
+    /**
+     * How many flow walks run at once. Defaults to 1, because mocked backends
+     * are commonly single-session; a host whose fixtures survive concurrent
+     * sessions can raise it — measured, two walks filled a canvas in half the
+     * time with no more long tasks on the editor thread.
+     */
+    screenFlowConcurrency?: number;
     /**
      * Host-declared scenario coverage ledger: where each QA scenario is
      * verified (frame, folded screen state, component toggle, viewport

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

@@ -1,7 +1,10 @@
-import type { StoryboardConnectionMode } from '../canvas/StoryboardConnections';
 export declare const LayerTree: import("react").FunctionComponent<{
+    /**
+     * Which half of the panel to draw. 'story' answers where am I going — the
+     * canvases and the walk through them; 'frames' answers what is this made of
+     * — the frame list and the tree of the one in front of you.
+     */
+    view?: "story" | "frames";
     onFrameFocus?: (id: string) => void;
-    storyboardConnectionMode?: StoryboardConnectionMode;
-    onStoryboardConnectionModeChange?: (mode: StoryboardConnectionMode) => void;
     storyboardReady?: boolean;
 }>;

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

@@ -1,12 +1,9 @@
 import type { StoryboardGraphViewModel } from '../editor/storyboardGraphView';
 import type { StoryboardCompositionModel } from '../editor/storyboardComposition';
-import type { StoryboardConnectionMode } from '../canvas/StoryboardConnections';
 export interface StoryboardGraphPanelProps {
     model: StoryboardGraphViewModel;
     onSelectFrame: (frameId: string) => void;
     activeFrameId?: string | null;
-    connectionMode: StoryboardConnectionMode;
-    onConnectionModeChange: (mode: StoryboardConnectionMode) => void;
     /**
      * Structure for a canvas with no routes, where a journey graph has nothing
      * to say. Present only on catalog canvases.
@@ -15,9 +12,4 @@ export interface StoryboardGraphPanelProps {
     /** Frame names for composition rows, which carry ids rather than frames. */
     frameNameById?: ReadonlyMap<string, string>;
 }
-/**
- * Generic navigation and coverage surface for a project-supplied storyboard
- * graph. It never interprets domain labels and delegates camera focus to the
- * editor's existing frame-selection action.
- */
-export declare function StoryboardGraphPanel({ model, onSelectFrame, activeFrameId, connectionMode, onConnectionModeChange, composition, frameNameById, }: StoryboardGraphPanelProps): import("react").JSX.Element | null;
+export declare function StoryboardGraphPanel({ model, onSelectFrame, activeFrameId, composition, frameNameById, }: StoryboardGraphPanelProps): import("react").JSX.Element | null;

package/node/dev-mirror.mjs

@@ -879,6 +879,10 @@ export function pygmalionDevMirrorPlugin(options) {
   let previewPort = null;
   let syncPromise = null;
   let sharedLockPathPromise = null;
+  // Assigned once the server is configured. A capture asks for the checkout
+  // through the composition handle below, and that demand has to reach the same
+  // starter the preview-origin requests use.
+  let demandRuntime = () => {};
   let lastVerifiedAt = 0;
   let revision = 0;
   let status = {
@@ -1197,6 +1201,12 @@ export function pygmalionDevMirrorPlugin(options) {
     pygmalion: {
       acquireLease: (label) => acquireDevMirrorLease({ repoRoot, mirrorRoot, label }),
       activeMirrorRoot: () => mirrorRoot,
+      // A capture needs the checkout as much as a live frame does, but it asks
+      // at another plugin's endpoint. Without these two the demand never
+      // reached the starter: the frame had no origin to request, so nothing
+      // ever started the work the frame was waiting for.
+      requestRuntime: () => demandRuntime(),
+      runtimePrepared: () => status.state === 'ready',
     },
     configureServer(server) {
       server.httpServer?.once('close', () => {
@@ -1248,6 +1258,7 @@ export function pygmalionDevMirrorPlugin(options) {
           })
           .catch(() => undefined);
       };
+      demandRuntime = startRuntime;
 
       server.middlewares.use(async (req, res, next) => {
         const url = new URL(req.url ?? '/', 'http://localhost');