@pygmalionjs/pygmalion 0.5.17 → 0.5.19

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 = {
@@ -87,6 +95,8 @@ export type RoutePreviewArtifactFrameRequestResult = {
 } | {
     status: 'unavailable';
     message?: string;
+    notPrepared?: boolean;
+    absent?: readonly string[];
 } | {
     status: 'rejected';
     message: string;
@@ -163,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;
 /**
@@ -171,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;
@@ -194,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');

package/node/preview-artifact-plugin.mjs

@@ -11,6 +11,24 @@ const MAX_IDENTITY_LENGTH = 1_024;
 const MAX_CAPTURE_BASE_URL_LENGTH = 2_048;
 const MAX_FRAME_REQUEST_BYTES = 64 * 1024;
 const MAX_FRAME_REQUEST_COUNT = 2_048;
+// A batch that generates carries a recipe per frame, which a query string
+// cannot hold past a handful of frames (Node refuses the request at 16KB of
+// headers). Those arrive as a JSON body instead; the ceiling keeps a stray
+// client from parking megabytes in memory.
+const MAX_FRAME_REQUEST_BODY_BYTES = 4 * 1024 * 1024;
+/**
+ * Where a request sits among captures waiting on the same identity. Smaller
+ * runs first. The editor sends a frame the designer selected ahead of a
+ * canvas being filled, and a canvas being filled ahead of one nobody is
+ * looking at; a request that says nothing sits with the canvas.
+ */
+export const PREVIEW_CAPTURE_PRIORITY = Object.freeze({
+  selected: 0,
+  canvas: 10,
+  background: 20,
+});
+const DEFAULT_CAPTURE_PRIORITY = PREVIEW_CAPTURE_PRIORITY.canvas;
+const MAX_CAPTURE_PRIORITY = 1_000;
 
 function isLocalRequestHost(value) {
   const raw = Array.isArray(value) ? value[0] : value;
@@ -33,15 +51,25 @@ function sendJson(response, statusCode, body) {
   response.end(payload);
 }
 
-function requestedIdentity(url, key) {
-  const value = url.searchParams.get(key);
+function requestedIdentity(params, key) {
+  const value = params.get(key);
   return value && value === value.trim() && value.length <= MAX_IDENTITY_LENGTH
     ? value
     : null;
 }
 
-function requestedCaptureBaseUrl(url, requestHost) {
-  const value = url.searchParams.get('captureBaseUrl');
+function requestedPriority(params) {
+  const raw = params.get('priority');
+  if (raw == null || raw === '') return DEFAULT_CAPTURE_PRIORITY;
+  const value = Number(raw);
+  if (!Number.isInteger(value) || value < 0 || value > MAX_CAPTURE_PRIORITY) {
+    return null;
+  }
+  return value;
+}
+
+function requestedCaptureBaseUrl(params, requestHost) {
+  const value = params.get('captureBaseUrl');
   if (!value) return undefined;
   if (value !== value.trim() || value.length > MAX_CAPTURE_BASE_URL_LENGTH) {
     return null;
@@ -79,27 +107,40 @@ function requestedCaptureBaseUrl(url, requestHost) {
  * without starting work — otherwise naming every frame on mount would capture
  * the whole catalog, which is the cost this mode exists to remove.
  */
-function generationAllowed(url) {
-  const raw = url.searchParams.get('generate');
+function generationAllowed(params) {
+  const raw = params.get('generate');
   if (raw == null) return true;
   return !['0', 'false', 'no'].includes(raw.trim().toLowerCase());
 }
 
-function resolutionOnly(url) {
-  const raw = url.searchParams.get('resolve');
+function resolutionOnly(params) {
+  const raw = params.get('resolve');
   return raw != null && ['1', 'true', 'yes'].includes(raw.trim().toLowerCase());
 }
 
-function requestedFrames(url) {
-  const raw = url.searchParams.get('frames');
+/**
+ * The frame list of a request, whichever way it arrived.
+ *
+ * A GET carries it as JSON in the `frames` query parameter, capped so it fits a
+ * query string; a POST carries it in the body, where a batch of recipes fits.
+ */
+function requestedFrames(params) {
+  const raw = params.get('frames');
   if (raw == null) return undefined;
-  if (Buffer.byteLength(raw) > MAX_FRAME_REQUEST_BYTES) return null;
-  let parsed;
-  try {
-    parsed = JSON.parse(raw);
-  } catch {
+  const parsedBody = params.parsedFrames;
+  if (parsedBody === undefined && Buffer.byteLength(raw) > MAX_FRAME_REQUEST_BYTES) {
     return null;
   }
+  let parsed;
+  if (parsedBody !== undefined) {
+    parsed = parsedBody;
+  } else {
+    try {
+      parsed = JSON.parse(raw);
+    } catch {
+      return null;
+    }
+  }
   if (!Array.isArray(parsed) || parsed.length > MAX_FRAME_REQUEST_COUNT) return null;
   const wanted = [];
   for (const entry of parsed) {
@@ -113,11 +154,75 @@ function requestedFrames(url) {
       if (typeof fingerprint !== 'string' || !fingerprint.trim()) return null;
       if (fingerprint.length > MAX_IDENTITY_LENGTH) return null;
     }
-    wanted.push(fingerprint === undefined ? { id } : { id, fingerprint });
+    // The recipe the fingerprint stands for. A fingerprint is a hash — a
+    // generator handed one alone can only re-capture what the host declared for
+    // that id, which is a different screen wearing the requested name. Carried
+    // through opaquely: this plugin never interprets it, and the whole request
+    // is already capped by MAX_FRAME_REQUEST_BYTES.
+    const recipe = item.recipe;
+    if (recipe !== undefined) {
+      if (typeof recipe !== 'object' || recipe === null || Array.isArray(recipe)) {
+        return null;
+      }
+    }
+    wanted.push({
+      id,
+      ...(fingerprint === undefined ? {} : { fingerprint }),
+      ...(recipe === undefined ? {} : { recipe }),
+    });
   }
   return wanted;
 }
 
+/**
+ * The parameters of a request, read the same way for both transports.
+ *
+ * GET keeps every field in the query string. POST carries a JSON object with
+ * the same field names; scalar fields are read as strings so the validators
+ * above apply unchanged, and `frames` is kept parsed so a large batch is not
+ * re-serialized only to be parsed again.
+ */
+function paramsFromQuery(url) {
+  return { get: (key) => url.searchParams.get(key), parsedFrames: undefined };
+}
+
+function paramsFromBody(body) {
+  const scalar = (value) => {
+    if (value === undefined || value === null) return null;
+    if (typeof value === 'string') return value;
+    if (typeof value === 'number' || typeof value === 'boolean') return String(value);
+    return null;
+  };
+  return {
+    get: (key) => {
+      if (key === 'frames') return body.frames === undefined ? null : '[]';
+      return scalar(body[key]);
+    },
+    parsedFrames: body.frames,
+  };
+}
+
+async function readJsonBody(request, limit) {
+  const chunks = [];
+  let received = 0;
+  for await (const chunk of request) {
+    const buffer = typeof chunk === 'string' ? Buffer.from(chunk) : chunk;
+    received += buffer.length;
+    if (received > limit) return { ok: false, error: 'body_too_large' };
+    chunks.push(buffer);
+  }
+  if (received === 0) return { ok: false, error: 'invalid_body' };
+  try {
+    const parsed = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+      return { ok: false, error: 'invalid_body' };
+    }
+    return { ok: true, body: parsed };
+  } catch {
+    return { ok: false, error: 'invalid_body' };
+  }
+}
+
 function exactArtifact(artifact, namespace, sourceRevision) {
   const validation = validateRoutePreviewArtifactBundle(artifact);
   return (
@@ -140,6 +245,8 @@ export function pygmalionPreviewArtifactPlugin({
   disabled = () => false,
   generateArtifact,
   acquireLease,
+  requestRuntime,
+  runtimePrepared = () => true,
 } = {}) {
   const resolvedRoot = path.resolve(root);
   const resolvedArtifact = path.resolve(resolvedRoot, artifactFile);
@@ -165,6 +272,16 @@ export function pygmalionPreviewArtifactPlugin({
       'Preview artifact generator option must be a function.',
     );
   }
+  if (requestRuntime != null && typeof requestRuntime !== 'function') {
+    throw new TypeError(
+      'Preview artifact runtime request option must be a function.',
+    );
+  }
+  if (typeof runtimePrepared !== 'function') {
+    throw new TypeError(
+      'Preview artifact runtime readiness option must be a function.',
+    );
+  }
 
   const artifactStore = createPreviewArtifactStore({
     artifactFile: resolvedArtifact,
@@ -175,20 +292,52 @@ export function pygmalionPreviewArtifactPlugin({
   const identityQueues = new Map();
   const inFlightRequests = new Map();
 
-  function enqueueIdentity(namespace, sourceRevision, task) {
+  /**
+   * Captures on one identity run one at a time — they share the checkout and
+   * the worker — but not in the order they were asked. A frame the designer
+   * just selected must not sit behind a canvas being filled in the background,
+   * so the queue is ordered by priority and by arrival within a priority.
+   * The running capture is never interrupted; the next pick happens when it
+   * finishes.
+   */
+  function enqueueIdentity(namespace, sourceRevision, task, priority = DEFAULT_CAPTURE_PRIORITY) {
     const identity = `${namespace}\u0000${sourceRevision}`;
-    const previous = identityQueues.get(identity) ?? Promise.resolve();
-    const current = previous.catch(() => undefined).then(task);
-    identityQueues.set(identity, current);
-    void current.then(
-      () => {
-        if (identityQueues.get(identity) === current) identityQueues.delete(identity);
-      },
-      () => {
-        if (identityQueues.get(identity) === current) identityQueues.delete(identity);
-      },
-    );
-    return current;
+    let queue = identityQueues.get(identity);
+    if (!queue) {
+      queue = { pending: [], running: false, arrivals: 0 };
+      identityQueues.set(identity, queue);
+    }
+    return new Promise((resolve, reject) => {
+      queue.arrivals += 1;
+      queue.pending.push({
+        priority,
+        arrival: queue.arrivals,
+        run: task,
+        resolve,
+        reject,
+      });
+      queue.pending.sort(
+        (left, right) => left.priority - right.priority || left.arrival - right.arrival,
+      );
+      pumpIdentity(identity, queue);
+    });
+  }
+
+  function pumpIdentity(identity, queue) {
+    if (queue.running) return;
+    const next = queue.pending.shift();
+    if (!next) {
+      if (identityQueues.get(identity) === queue) identityQueues.delete(identity);
+      return;
+    }
+    queue.running = true;
+    Promise.resolve()
+      .then(next.run)
+      .then(next.resolve, next.reject)
+      .finally(() => {
+        queue.running = false;
+        pumpIdentity(identity, queue);
+      });
   }
 
   function deduplicateRequest(key, task) {
@@ -230,6 +379,26 @@ export function pygmalionPreviewArtifactPlugin({
     });
   }
 
+  /**
+   * Answers a frame whose capture cannot run yet, and starts what it needs.
+   *
+   * Asking for a frame is asking for the checkout — the capture reads it. The
+   * editor holds no preview origin until the mirror is ready, so this endpoint
+   * is the only place that demand arrives before one exists. Without starting
+   * the work here the canvas waited on a preparation nobody had ordered, and
+   * the only way out was a human pressing refresh.
+   */
+  function answerPreparing(response) {
+    requestRuntime?.();
+    sendJson(response, 503, {
+      ok: false,
+      error: 'artifact_generation_unavailable',
+      retryable: true,
+      preparing: true,
+      details: ['The dev screen checkout is being prepared.'],
+    });
+  }
+
   /**
    * A generator that ran and produced the wrong thing.
    *
@@ -300,7 +469,7 @@ export function pygmalionPreviewArtifactPlugin({
    * The stored bundle becomes a cache keyed per frame rather than one artifact
    * per revision, so replacing one screen no longer re-renders the others.
    */
-  function generateFrames(namespace, sourceRevision, captureBaseUrl, wanted) {
+  function generateFrames(namespace, sourceRevision, captureBaseUrl, wanted, priority) {
     const request = `frames\u0000${namespace}\u0000${sourceRevision}\u0000${wanted
       .map((frame) => `${frame.id}@${frame.fingerprint ?? ''}`)
       .sort()
@@ -346,7 +515,7 @@ export function pygmalionPreviewArtifactPlugin({
             wanted,
           )
         ).bundle;
-      }),
+      }, priority),
     );
   }
 
@@ -365,8 +534,8 @@ export function pygmalionPreviewArtifactPlugin({
           next();
           return;
         }
-        if (request.method !== 'GET') {
-          response.setHeader('allow', 'GET');
+        if (request.method !== 'GET' && request.method !== 'POST') {
+          response.setHeader('allow', 'GET, POST');
           sendJson(response, 405, {
             ok: false,
             error: 'method_not_allowed',
@@ -380,14 +549,33 @@ export function pygmalionPreviewArtifactPlugin({
           });
           return;
         }
-        const namespace = requestedIdentity(url, 'namespace');
-        const sourceRevision = requestedIdentity(url, 'sourceRevision');
+        let params;
+        if (request.method === 'POST') {
+          const read = await readJsonBody(request, MAX_FRAME_REQUEST_BODY_BYTES);
+          if (!read.ok) {
+            sendJson(response, read.error === 'body_too_large' ? 413 : 400, {
+              ok: false,
+              error: read.error,
+            });
+            return;
+          }
+          params = paramsFromBody(read.body);
+        } else {
+          params = paramsFromQuery(url);
+        }
+        const namespace = requestedIdentity(params, 'namespace');
+        const sourceRevision = requestedIdentity(params, 'sourceRevision');
         const captureBaseUrl = requestedCaptureBaseUrl(
-          url,
+          params,
           Array.isArray(request.headers.host)
             ? request.headers.host[0]
             : request.headers.host,
         );
+        const priority = requestedPriority(params);
+        if (priority === null) {
+          sendJson(response, 400, { ok: false, error: 'invalid_priority' });
+          return;
+        }
         if (!namespace || !sourceRevision) {
           sendJson(response, 400, {
             ok: false,
@@ -416,13 +604,13 @@ export function pygmalionPreviewArtifactPlugin({
           return;
         }
 
-        const wanted = requestedFrames(url);
+        const wanted = requestedFrames(params);
         if (wanted === null) {
           sendJson(response, 400, { ok: false, error: 'invalid_frames' });
           return;
         }
         if (wanted !== undefined) {
-          if (resolutionOnly(url)) {
+          if (resolutionOnly(params)) {
             const resolution = await artifactStore.resolveFrameSelection(
               namespace,
               sourceRevision,
@@ -449,7 +637,11 @@ export function pygmalionPreviewArtifactPlugin({
             wanted,
           );
           const absent = [...picked.missing, ...picked.stale];
-          if (absent.length && generateArtifact && generationAllowed(url)) {
+          if (absent.length && generateArtifact && generationAllowed(params)) {
+            if (!runtimePrepared()) {
+              answerPreparing(response);
+              return;
+            }
             const requested = new Set(absent);
             try {
               await generateFrames(
@@ -457,6 +649,7 @@ export function pygmalionPreviewArtifactPlugin({
                 sourceRevision,
                 captureBaseUrl,
                 wanted.filter((frame) => requested.has(frame.id)),
+                priority,
               );
               picked = await artifactStore.readFrameSelection(
                 namespace,
@@ -480,12 +673,16 @@ export function pygmalionPreviewArtifactPlugin({
         // A consumer that forbids capture must be obeyed in every mode. Honouring
         // it only for frame requests left the expensive path one missing
         // parameter away.
-        const mayGenerate = generateArtifact && generationAllowed(url);
+        const mayGenerate = generateArtifact && generationAllowed(params);
         let artifact = await artifactStore.readExactArtifact(
           namespace,
           sourceRevision,
         );
         if (!artifact && mayGenerate) {
+          if (!runtimePrepared()) {
+            answerPreparing(response);
+            return;
+          }
           try {
             artifact = await generateExactArtifact(
               namespace,