@pygmalionjs/pygmalion 0.6.28 → 0.6.30

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/App.d.ts

@@ -1,5 +1,8 @@
+import type { DesignCodegenProjectManifest } from './editor/designCompiler';
 export interface AppProps {
     /** The route identity is stable enough to read or produce preview artifacts. */
     previewIdentityReady?: boolean;
+    /** Checked-in host contract used by repository-aware codegen adapters. */
+    codegenProject?: DesignCodegenProjectManifest;
 }
 export declare const App: import("react").FunctionComponent<AppProps>;

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/designCompiler.d.ts

@@ -2,6 +2,8 @@ import { type CodegenFrameOptions, type CodegenNode } from './codegen';
 import { type NodeJSON } from './store';
 export declare const DESIGN_IR_SCHEMA: "pygmalion.design-ir";
 export declare const DESIGN_IR_VERSION: 1;
+export declare const DESIGN_CODEGEN_PROJECT_SCHEMA: "pygmalion.codegen-project";
+export declare const DESIGN_CODEGEN_PROJECT_VERSION: 1;
 export type DesignCompilePurpose = 'interactive' | 'export';
 export type DesignCompileSeverity = 'info' | 'warning' | 'error';
 export type DesignCompileStage = 'normalize' | 'analyze' | 'generate' | 'resource';
@@ -43,6 +45,70 @@ export interface DesignIRMetrics {
     componentCount: number;
     assetCount: number;
 }
+/** JSON-shaped host data produced from a repository-owned codegen contract. */
+export type DesignCodegenData = null | string | number | boolean | readonly DesignCodegenData[] | {
+    readonly [key: string]: DesignCodegenData;
+};
+export interface DesignCodegenPromptReference {
+    /** Repository-relative agent instruction file used to author this manifest. */
+    sourcePath: string;
+    /** Host-owned revision bumped when the instructions or output contract change. */
+    revision: string;
+}
+export interface DesignCodegenFrameContract {
+    /** Canonical source anchors chosen by the host, in addition to observed files. */
+    sourcePaths?: readonly string[];
+    /** Adapter-specific, deterministic metadata. It is never interpreted by core. */
+    metadata?: Readonly<Record<string, DesignCodegenData>>;
+}
+/**
+ * Checked-in output of a repository's codegen instructions.
+ *
+ * The prompt is provenance, not a runtime dependency: adapters consume this
+ * manifest synchronously and never call a model while the editor is open.
+ */
+export interface DesignCodegenProjectManifest {
+    schema: typeof DESIGN_CODEGEN_PROJECT_SCHEMA;
+    version: typeof DESIGN_CODEGEN_PROJECT_VERSION;
+    defaultTarget?: string;
+    prompt?: DesignCodegenPromptReference;
+    frames?: Readonly<Record<string, DesignCodegenFrameContract>>;
+}
+export interface DesignCodegenPageContext {
+    /** Canonical import id when available, otherwise the editor-local page id. */
+    id: string;
+    name: string;
+    route?: string;
+    previewRoute?: string;
+    sourcePaths: readonly string[];
+    flow?: string;
+    scenario?: string;
+    state?: string;
+    stateKind?: string;
+    scenarioId?: string;
+    scenarioIds: readonly string[];
+    desiredState?: Readonly<Record<string, DesignCodegenData>>;
+    /** Current reproducible recipe; direct state stays separate for easy adapters. */
+    capture: {
+        environment?: DesignCodegenData;
+        preset?: DesignCodegenData;
+        interactions: readonly DesignCodegenData[];
+        assertions: readonly DesignCodegenData[];
+    };
+    interactiveStateId?: string;
+    interactiveOptionId?: string;
+    interactiveOptionIds?: readonly string[];
+    viewport: {
+        width: number;
+        height: number;
+    };
+    /** Frame-specific checked-in contract selected by id. */
+    contract?: DesignCodegenFrameContract;
+}
+export interface DesignCodegenRuntimeContext {
+    page?: DesignCodegenPageContext;
+    project?: DesignCodegenProjectManifest;
+}
 export interface DesignIntermediateDocumentV1 {
     schema: typeof DESIGN_IR_SCHEMA;
     version: typeof DESIGN_IR_VERSION;
@@ -61,7 +127,7 @@ export interface DesignCompileLimits {
     maxOutputBytes: number;
 }
 export declare const DEFAULT_DESIGN_COMPILE_LIMITS: Readonly<DesignCompileLimits>;
-export interface DesignCodegenAdapterContext {
+export interface DesignCodegenAdapterContext extends DesignCodegenRuntimeContext {
     document: DesignIntermediateDocumentV1;
 }
 export interface DesignCodegenAdapterOutput {
@@ -73,6 +139,13 @@ export interface DesignCodegenAdapter {
     label: string;
     language: string;
     extension: string;
+    /**
+     * Repository adapters generate from checked-in source contracts rather than
+     * approximating the captured design tree. They still receive the document
+     * for source-map context, but design-IR warnings and preview size deferral do
+     * not describe their output.
+     */
+    basis?: 'design-ir' | 'repository';
     generate(context: DesignCodegenAdapterContext): string | DesignCodegenAdapterOutput;
 }
 export interface DesignCompileOptions {
@@ -81,6 +154,8 @@ export interface DesignCompileOptions {
     force?: boolean;
     frame?: CodegenFrameOptions;
     limits?: Partial<DesignCompileLimits>;
+    /** Current repository frame and checked-in codegen contract for host adapters. */
+    context?: DesignCodegenRuntimeContext;
 }
 export interface DesignCompileResult {
     target: string;

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/dist-lib/types/lib.d.ts

@@ -18,6 +18,7 @@ import type { StoryboardDefinition } from './editor/storyboardGraph';
 import { type TokenDef } from './editor/tokens';
 import { type ViewportPresetDef } from './editor/viewportPresets';
 import { type PreviewEnvironmentControlDef } from './editor/previewEnvironmentControls';
+import type { DesignCodegenProjectManifest } from './editor/designCompiler';
 
 export { setComponentRegistry } from './editor/registry';
 export { PYGMALION_PREVIEW_CAPTURE_PROGRESS_SUFFIX, previewCaptureProgressEndpoint, usePygmalionPreviewCaptureProgress, } from './editor/previewCaptureProgress';
@@ -27,8 +28,8 @@ export type { FrameInteractionPhase, FrameInteractionScrollState, FrameInteracti
 export type { ComponentRegistry, RegistryEntry, RegistryPropValue, } from './editor/registry';
 export { enumerateDesignComponentConnectionCases, getDesignComponentConnection, getDesignComponentConnectionForComponent, getDesignComponentConnections, setDesignComponentConnections, validateDesignComponentConnections, } from './editor/componentConnections';
 export type { DesignComponentConnectionCase, DesignComponentConnectionCases, DesignComponentConnectionDef, DesignComponentReference, DesignConnectionDiagnostic, DesignConnectionPropertyDef, DesignConnectionPropertyKind, } from './editor/componentConnections';
-export { compileDesignDocument, createDesignIntermediateDocument, DEFAULT_DESIGN_COMPILE_LIMITS, DESIGN_IR_SCHEMA, DESIGN_IR_VERSION, getDesignCodegenAdapters, registerDesignCodegenAdapter, } from './editor/designCompiler';
-export type { DesignCodegenAdapter, DesignCodegenAdapterContext, DesignCodegenAdapterOutput, DesignCompileDiagnostic, DesignCompileLimits, DesignCompileOptions, DesignCompilePurpose, DesignCompileResult, DesignCompileSeverity, DesignCompileStage, DesignCompileStatus, DesignIntermediateDocumentV1, DesignIRAsset, DesignIRComponent, DesignIRMetrics, } from './editor/designCompiler';
+export { compileDesignDocument, createDesignIntermediateDocument, DEFAULT_DESIGN_COMPILE_LIMITS, DESIGN_CODEGEN_PROJECT_SCHEMA, DESIGN_CODEGEN_PROJECT_VERSION, DESIGN_IR_SCHEMA, DESIGN_IR_VERSION, getDesignCodegenAdapters, registerDesignCodegenAdapter, } from './editor/designCompiler';
+export type { DesignCodegenAdapter, DesignCodegenAdapterContext, DesignCodegenAdapterOutput, DesignCodegenData, DesignCodegenFrameContract, DesignCodegenPageContext, DesignCodegenProjectManifest, DesignCodegenPromptReference, DesignCodegenRuntimeContext, DesignCompileDiagnostic, DesignCompileLimits, DesignCompileOptions, DesignCompilePurpose, DesignCompileResult, DesignCompileSeverity, DesignCompileStage, DesignCompileStatus, DesignIntermediateDocumentV1, DesignIRAsset, DesignIRComponent, DesignIRMetrics, } from './editor/designCompiler';
 export type { CodegenFrameOptions } from './editor/codegen';
 export { createDesignComponentCatalog, createDesignComponentVariantMatrix, createDesignGalleryCatalog, designCatalogKey, designCatalogRegistryName, PygmalionCatalogDocument, PygmalionCatalogMatrix, PygmalionCatalogSection, } from './editor/catalog';
 export type { DesignCatalogBuild, DesignCatalogFrame, DesignCatalogItem, DesignCatalogKind, DesignCatalogPageDescriptor, DesignComponentCatalogOptions, DesignComponentVariantMatrix, DesignGalleryCatalogOptions, PygmalionCatalogDocumentProps, PygmalionCatalogMatrixProps, PygmalionCatalogSectionProps, } from './editor/catalog';
@@ -281,7 +282,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, sessionPresets, 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, screenStateAxes, interactiveStates, surfaceClassifications, onApply, onDesignChange, onInspectApply, onInspectPreview, onInspectImpact, storyboard, storyboardScenarios, sessionStoryboards, storyboardDiscovery, storyboardDiscoveryEndpoint, }: {
+export declare function PygmalionEditor({ registry, tokens, initialPages, initialCanvas, initialEditMode, componentConnections, codegenProject, viewportPresets, sessionPresets, 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, screenStateAxes, interactiveStates, surfaceClassifications, onApply, onDesignChange, onInspectApply, onInspectPreview, onInspectImpact, storyboard, storyboardScenarios, sessionStoryboards, storyboardDiscovery, storyboardDiscoveryEndpoint, }: {
     registry?: ComponentRegistry;
     tokens?: TokenDef[];
     initialPages?: InitialPageDef[];
@@ -296,6 +297,11 @@ export declare function PygmalionEditor({ registry, tokens, initialPages, initia
     initialEditMode?: 'edit' | 'view-only';
     /** Explicit external-design to registered-code component mappings. */
     componentConnections?: readonly DesignComponentConnectionDef[];
+    /**
+     * Checked-in repository contract for deterministic, state-aware codegen.
+     * Its prompt reference is provenance only; no model runs in the editor.
+     */
+    codegenProject?: DesignCodegenProjectManifest;
     /** Named frame widths the application supports — rendered as one-click buttons beside the W/H boxes. */
     viewportPresets?: readonly ViewportPresetDef[];
     /**

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

@@ -1 +1,4 @@
-export declare const CodePanel: import("react").FunctionComponent<object>;
+import { type DesignCodegenProjectManifest } from '../editor/designCompiler';
+export declare const CodePanel: import("react").FunctionComponent<{
+    codegenProject?: DesignCodegenProjectManifest;
+}>;

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.30",
   "description": "Code-backed DOM design sandbox and visual QA editor",
   "license": "UNLICENSED",
   "publishConfig": {