@pygmalionjs/pygmalion 0.6.28 → 0.6.29

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-Xm7o3urC.js";
+import { F as s, N as a, e as r, s as i, a as t } from "./FrozenRoutePreview-D9J35QsM.js";
 export {
   s as FrozenRoutePreviewView,
   a as NodeModel,

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

@@ -17,4 +17,7 @@ export declare const ShadowRoutePreview: import("react").FunctionComponent<{
     mountPriority?: number;
     onDocumentHeightChange?: (height: number) => void;
     onReplayIssuesChange?: (issues: string[]) => void;
+    onReachableTestIdsChange?: (testIds: readonly string[]) => void;
+    /** Enables immediate scrolling while the live React document warms. */
+    interactionEnabled?: boolean;
 }>;

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

@@ -144,7 +144,9 @@ export declare const __flowSessionWarmDebug: {
     bootsByRunner: Record<string, number>;
 };
 /** Drops parked instances globally, or only those owned by one runner. */
-export declare function evictFlowSessionWarmInstances(ownerLabel?: string): void;
+export declare function evictFlowSessionWarmInstances(ownerLabel?: string, options?: {
+    preservePinned?: boolean;
+}): void;
 /**
  * True when a walk of this path would resume on a parked instance. Activation
  * warming reads it to decide whether the frame already has a resumable

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

@@ -1,4 +1,4 @@
-export type FrameInteractionPhase = 'idle' | 'starting' | 'interacting';
+export type FrameInteractionPhase = 'idle' | 'starting' | 'preview' | 'interacting';
 export interface FrameInteractionScrollState {
     x: number;
     y: number;
@@ -51,6 +51,12 @@ export declare function subscribeFrameInteraction(listener: () => void): () => v
  * without learning whether the running surface is an iframe or another host.
  */
 export declare function connectFrameInteractionViewport(frameId: string, adapter: FrameInteractionViewportAdapter): () => void;
+/**
+ * Makes the frozen DOM useful immediately while its live React document warms.
+ * The preview is a scroll-only bridge: navigation and form submission stay
+ * contained, and the live iframe later replaces it without ending the session.
+ */
+export declare function connectFrameInteractionPreview(frameId: string, root: ShadowRoot, contentElement: HTMLElement): () => void;
 /** Scrolls the running frame viewport and immediately republishes its reading. */
 export declare function setFrameInteractionScroll(position: {
     x?: number;

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

@@ -6,6 +6,7 @@
  * published, while the active frame may mirror the running document
  * immediately so capture stability never becomes interaction latency.
  */
+import type { DesignScreenDesiredState } from './designImport';
 export interface InteractiveSessionSurface {
     iframe: HTMLIFrameElement;
     screenId: string;
@@ -19,8 +20,26 @@ export declare function directInteractiveSessionSurfaceId(pageId: string, stateI
 export declare function setDirectInteractiveStateRequestHandler(handler: ((pageId: string) => void) | null): void;
 /** Starts direct-state delivery in the same task as the right-panel click. */
 export declare function requestDirectInteractiveState(pageId: string): boolean;
+/** Installs the paint-first path used before the observable page recipe changes. */
+export declare function setDirectInteractiveStatePreviewHandler(handler: ((request: {
+    pageId: string;
+    stateId: string;
+    desiredState: DesignScreenDesiredState;
+}) => boolean) | null): void;
+/** Applies a direct host state without invalidating the editor model yet. */
+export declare function requestDirectInteractiveStatePreview(request: {
+    pageId: string;
+    stateId: string;
+    desiredState: DesignScreenDesiredState;
+}): boolean;
 /** Exposes a runner-owned iframe without transferring its ownership. */
 export declare function exposeInteractiveSessionSurface(screenId: string, iframe: HTMLIFrameElement): void;
+/**
+ * Hands an in-flight prewarm slot to the frame that has just exposed its axis.
+ * If preparation has not presented the iframe yet, its first exposure follows
+ * the redirect instead of landing in the now-private staging slot.
+ */
+export declare function redirectInteractiveSessionSurface(fromScreenId: string, toScreenId: string): boolean;
 /** Releases a surface only when the caller still owns the registered iframe. */
 export declare function releaseInteractiveSessionSurface(screenId: string, iframe: HTMLIFrameElement): void;
 /** Clears a presentation slot when its page returns to an authored state. */

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

@@ -1,5 +1,6 @@
 import type { DesignScreenInteraction, DesignSerializable, StoryboardEnvironment } from './designImport';
 import type { PageModel } from './store';
+export { reachablePreviewTestIds } from './previewReachability';
 /**
  * Screen-state axes — same-frame variations reproduced by a gesture or a boot
  * condition.
@@ -136,10 +137,10 @@ export declare function validateInteractiveStates(defs: readonly InteractiveStat
 /** Validates both interaction and condition axes. */
 export declare const validateScreenStateAxes: typeof validateInteractiveStates;
 /** Reads only the control-presence evidence needed by the view-only inspector. */
-export declare function previewMarkupTestIds(markup: string | null | undefined): readonly string[];
+export declare function previewMarkupTestIds(markup: string | null | undefined, bodyAttributes?: string | null): readonly string[];
 /**
  * Axes available on one frame. The test-id requirement is checked against
- * either the imported tree or the frozen preview's lightweight test-id index.
+ * either the imported tree or the frozen preview's reachable test-id index.
  * View-only can therefore offer a real screen control without importing the
  * whole layer tree, while a frame without that control still hides the axis.
  */

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

@@ -0,0 +1,7 @@
+export declare const REACHABLE_TEST_IDS_ATTRIBUTE = "data-pygmalion-reachable-testids";
+/** Test ids whose rendered controls can actually be reached from this frame. */
+export declare function reachablePreviewTestIds(root: ParentNode): readonly string[];
+/** Stamps capture-time reachability without mutating the running document. */
+export declare function stampReachablePreviewTestIds(source: Document, clone: HTMLElement): void;
+/** Reads a capture-time reachability index, or null for a legacy snapshot. */
+export declare function indexedReachablePreviewTestIds(markup: string): readonly string[] | null;

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

@@ -221,6 +221,12 @@ export interface PageModel {
     interactiveStateId?: string;
     /** The active option is rendered through host desired state, without replay. */
     interactiveStateUsesDesiredState?: boolean;
+    /**
+     * Imported layers still showing behind a direct live surface. The surface
+     * paints first; FrameView consumes this key and invalidates the old layers
+     * on the following frame so a large tree cannot block the visible switch.
+     */
+    interactiveLayerRefreshKey?: string;
     interactiveOptionId?: string;
     /**
      * Options held together on a combining axis (InteractiveStateDef.multiple).
@@ -260,7 +266,7 @@ export interface PageModel {
     assertions?: DesignScreenAssertion[];
     /** Host-declared warm instance group. Set when the screen state is declared, not replayed. */
     session?: string;
-    /** Test ids observed in the frozen preview before editable layers are imported. */
+    /** Reachable test ids observed in the frozen preview before editable layers are imported. */
     previewTestIds?: readonly string[];
     layerImportCount?: number;
     layerImportTruncated?: boolean;
@@ -467,6 +473,8 @@ export declare class EditorStore {
     private pageEditRevisions;
     /** pageId → edit revision at the moment a frozen preview was promoted without a boot (D2). */
     private provisionalLayerImports;
+    /** Latest paint-first direct-state commit scheduled for each page. */
+    private directStateCommitRevisions;
     /** pageId → source geometry awaiting its post-mount fidelity measurement. */
     private pendingLayerImportGeometry;
     /** View-only motion playback never becomes part of a frame recipe or undo history. */
@@ -737,7 +745,11 @@ export declare class EditorStore {
      * Pure-CSS pseudo options short-circuit through the held-pseudo fast path
      * (applyHeldPseudoInteractiveState) and never touch the recipe.
      */
-    applyInteractiveState(pageId: string, def: InteractiveStateDef, optionId: string): boolean;
+    applyInteractiveState(pageId: string, def: InteractiveStateDef, optionId: string, options?: {
+        skipPaintFirstPreview?: boolean;
+    }): boolean;
+    /** Invalidates retained layers only after their direct live replacement painted. */
+    commitInteractiveLayerRefresh(pageId: string, refreshKey: string): boolean;
     /** The root viewport endpoint currently preserved in this frame recipe. */
     frameScrollRecipe(pageId: string): Readonly<{
         x: number;

package/docs/screen-state-contract.md

@@ -75,10 +75,13 @@ automatic duplicate. Click-driven toggles and other application states remain
 declared axes unless they already have their own review frame.
 
 In view-only mode, `requires.testId` is matched against the frozen preview's
-lightweight test-id index as well as an imported layer tree. This keeps right
-panel state controls available without turning selection into a layer import or
-live boot, and still hides an axis from screens whose captured DOM lacks its
-target.
+lightweight **reachable** test-id index as well as an imported layer tree. A
+test id under `display: none`, hidden visibility, zero opacity, or an inert
+ancestor does not qualify merely because React kept that branch mounted. This
+keeps right-panel state controls available without turning selection into a
+layer import or live boot, while hiding axes that the captured frame cannot
+actually reach. Legacy snapshots without a capture-time index are measured
+after their inert DOM mounts.
 
 ## Automatic motion coverage
 

package/node/storyboard-capture-runtime.mjs

@@ -1056,6 +1056,56 @@ export function serializeStoryboardPreviewDocument(
   const clone = document.documentElement.cloneNode(true);
   if (!(clone instanceof HTMLElement)) return null;
 
+  // A frozen snapshot preserves branches that are mounted but visually absent
+  // (for example, two workspace panels cross-faded with opacity). Presence
+  // alone therefore cannot tell the inspector which controls this captured
+  // frame can actually reach. Record a compact, capture-time visibility index
+  // on the body; older snapshots without it are measured again after mount.
+  try {
+    const reachableTestIds = new Set();
+    const hasRenderedBox = (element) => {
+      const rect = element.getBoundingClientRect();
+      if (rect.width > 0 && rect.height > 0) return true;
+      return [...element.querySelectorAll('*')].some((descendant) => {
+        const descendantRect = descendant.getBoundingClientRect();
+        return descendantRect.width > 0 && descendantRect.height > 0;
+      });
+    };
+    const isReachable = (element) => {
+      for (
+        let current = element;
+        current;
+        current = current.parentElement
+      ) {
+        const style = window.getComputedStyle(current);
+        const opacity = Number.parseFloat(style.opacity || '1');
+        if (
+          current.hasAttribute('hidden') ||
+          current.hasAttribute('inert') ||
+          style.display === 'none' ||
+          style.visibility === 'hidden' ||
+          style.visibility === 'collapse' ||
+          (Number.isFinite(opacity) && opacity <= 0)
+        ) {
+          return false;
+        }
+      }
+      return hasRenderedBox(element);
+    };
+    for (const element of document.documentElement.querySelectorAll('*')) {
+      const testId = element.getAttribute('data-testid');
+      if (testId && isReachable(element)) reachableTestIds.add(testId);
+    }
+    const cloneBody = clone.querySelector('body');
+    cloneBody?.setAttribute(
+      'data-pygmalion-reachable-testids',
+      encodeURIComponent(JSON.stringify([...reachableTestIds].sort())),
+    );
+  } catch {
+    // Reachability metadata is additive. A constrained capture realm may not
+    // implement layout; the mounted-preview fallback handles that snapshot.
+  }
+
   const sourceInputs = [...document.querySelectorAll('input')];
   const cloneInputs = [...clone.querySelectorAll('input')];
   sourceInputs.forEach((source, index) => {

package/package.json

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