@pygmalionjs/pygmalion 0.5.33 → 0.6.0

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

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

@@ -21,7 +21,13 @@ export interface DesignImportAsset {
     scenarioId?: string;
     description?: string;
 }
-export type DesignScreenInteractionAction = 'click' | 'focus' | 'fill' | 'check' | 'press' | 'wait' | 'storage';
+export type DesignScreenInteractionAction = 'click' | 'focus'
+/** Holds the pointer over the target through capture. */
+ | 'hover'
+/** Holds keyboard focus, including the `:focus-visible` presentation. */
+ | 'focus-visible'
+/** Holds the pointer-down `:active` presentation through capture. */
+ | 'active' | 'fill' | 'check' | 'press' | 'wait' | 'storage';
 /**
  * A critical step to capture the actual app screen after putting it in a specific user flow state.
  * A CSS selector is used first, and if text is present, the selector candidates are narrowed down to the display string.

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

@@ -1,5 +1,18 @@
 /** Explains a control that is inert because the editor is in view-only. */
 export declare const VIEW_ONLY_REASON = "View only \u2014 switch to Editing to change this.";
+export type ImportedRoutePresentation = 'editable-layers' | 'source-preview';
+/**
+ * Chooses the visible surface for a route whose DOM has already been imported.
+ *
+ * Imported layers are an editing model, not the source screen itself. View-only
+ * therefore keeps the captured source preview on screen whenever one exists;
+ * switching to Editing is the explicit hand-off to the reconstructed layers.
+ * A missing preview falls back to layers instead of turning the frame blank.
+ */
+export declare function resolveImportedRoutePresentation({ editMode, sourcePreviewAvailable, }: {
+    editMode: boolean;
+    sourcePreviewAvailable: boolean;
+}): ImportedRoutePresentation;
 interface ModeKeyEvent {
     key: string;
     code?: string;

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

@@ -0,0 +1,18 @@
+import type { DesignScreenInteraction } from './designImport';
+export type HeldPseudoState = 'hover' | 'focus' | 'focus-visible' | 'active';
+/** The pseudo gestures still held after the complete recipe has run. */
+export declare function heldPseudoInteractionsFromRecipe(interactions: readonly DesignScreenInteraction[]): DesignScreenInteraction[];
+export declare function heldPseudoStatesFromInteractions(interactions: readonly DesignScreenInteraction[]): HeldPseudoState[];
+/**
+ * Converts pseudo-class selectors into stable attribute selectors while
+ * leaving comments and quoted CSS values untouched.
+ */
+export declare function materializeHeldPseudoCss(cssText: string, states: readonly HeldPseudoState[]): string;
+export interface HeldPseudoMaterialization {
+    cleanup(): void;
+    issues: string[];
+}
+/** Applies the stable selector attributes that correspond to held gestures. */
+export declare function applyHeldPseudoAttributes(root: ParentNode, interactions: readonly DesignScreenInteraction[]): HeldPseudoMaterialization;
+/** Materializes held pseudo classes in a live same-origin preview document. */
+export declare function materializeHeldPseudoDocument(document: Document, interactions: readonly DesignScreenInteraction[]): HeldPseudoMaterialization;

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

@@ -1,7 +1,8 @@
 import type { DesignScreenInteraction, StoryboardEnvironment } from './designImport';
 import type { PageModel } from './store';
 /**
- * Interactive states — axes a screen can be put into by acting on it.
+ * Screen-state axes — same-frame variations reproduced by a gesture or a boot
+ * condition.
  *
  * A collapsed sidebar or a hovered row is not a separate screen: it is the
  * same screen after one gesture, reachable on every frame that has the
@@ -61,9 +62,20 @@ export interface InteractiveStateOption {
         };
     };
 }
+export type ScreenStateAxisKind = 'interaction' | 'condition';
 export interface InteractiveStateDef {
     id: string;
     label: string;
+    /**
+     * Why this variation belongs on the frame instead of becoming another frame.
+     *
+     * `interaction` is a deterministic local state reached by a gesture on the
+     * already booted screen. `condition` is an external state that must exist
+     * before the screen boots, such as an empty response, denied permission, or
+     * stalled request. The validator refuses mixed axes so a sample value cannot
+     * quietly masquerade as a review state.
+     */
+    kind: ScreenStateAxisKind;
     /**
      * Frames the axis applies to. A frame qualifies when its route matches
      * (prefix) and its imported tree carries the test id, so an axis declared
@@ -98,6 +110,12 @@ export interface InteractiveStateDiagnostic {
     interactionId: string;
     message: string;
 }
+/** Preferred public name: the collection contains interaction and condition axes. */
+export type ScreenStateAxisDef = InteractiveStateDef;
+/** Preferred public name: an option on either kind of screen-state axis. */
+export type ScreenStateOption = InteractiveStateOption;
+/** Preferred public name for validation output. */
+export type ScreenStateAxisDiagnostic = InteractiveStateDiagnostic;
 /**
  * Whether selecting this option asks supply for a different screen.
  *
@@ -108,12 +126,16 @@ export interface InteractiveStateDiagnostic {
  */
 export declare function optionChangesSupply(option: InteractiveStateOption): boolean;
 export declare function validateInteractiveStates(defs: readonly InteractiveStateDef[]): InteractiveStateDiagnostic[];
+/** Validates both interaction and condition axes. */
+export declare const validateScreenStateAxes: typeof validateInteractiveStates;
 /**
  * Axes available on one frame. The test-id requirement is checked against
  * the imported tree, so an axis stays hidden until the frame actually shows
  * the control it drives — a frame without a sidebar never offers to fold it.
  */
 export declare function interactiveStatesForPage(page: PageModel, defs: readonly InteractiveStateDef[]): InteractiveStateDef[];
+/** Preferred public name for axes applicable to one frame. */
+export declare const screenStateAxesForPage: typeof interactiveStatesForPage;
 /**
  * The option this frame's capture already shows, or undefined when the axis
  * declares a single base instead of witnessing each option.
@@ -126,5 +148,8 @@ export declare function capturedInteractiveOption(def: InteractiveStateDef, page
  * one option declared without steps.
  */
 export declare function baseInteractiveOption(def: InteractiveStateDef, page?: PageModel): InteractiveStateOption | undefined;
+export declare function setScreenStateAxes(defs: readonly InteractiveStateDef[] | undefined): void;
+/** @deprecated Use setScreenStateAxes. */
 export declare function setInteractiveStates(defs: readonly InteractiveStateDef[] | undefined): void;
 export declare function getInteractiveStates(): readonly InteractiveStateDef[];
+export declare const getScreenStateAxes: typeof getInteractiveStates;

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

@@ -1,3 +1,4 @@
+import type { DesignScreenInteraction } from './designImport';
 export interface PreparedShadowPreview {
     bodyHtml: string;
     sharedCssText: string;
@@ -28,12 +29,17 @@ export interface ShadowPreviewMountInput {
     overrideCssText?: string;
     /** Resolves relative element and CSS resource URLs. */
     baseUrl?: string;
+    /** Recipe whose terminal pseudo gestures must remain visible in frozen DOM. */
+    interactions?: readonly DesignScreenInteraction[];
 }
 export interface ShadowPreviewHandle {
     readonly root: ShadowRoot;
     readonly contentElement: HTMLElement;
     readonly sharedCssHash: string;
     readonly overrideKey: string;
+    readonly heldPseudoIssues: readonly string[];
+    /** Rebuilds held pseudo rules from external stylesheets after their links load. */
+    refreshLinkedHeldPseudoCss(): void;
     updateBodyHtml(bodyHtml: string, baseUrl?: string): void;
     updateOverrideCss(cssText: string): void;
     updateSharedCss(cssText: string): void;

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

@@ -5,7 +5,7 @@ import { type ApplyPayload, type DesignChangePayload, type DesignChangeResult, t
 import { type InspectApplyPayload } from './editor/inspect';
 import { type ScreenFlowPath } from './editor/screenFlows';
 import { type ScenarioCoverageClaim } from './editor/scenarioCoverage';
-import { type InteractiveStateDef } from './editor/interactiveStates';
+import { type InteractiveStateDef, type ScreenStateAxisDef } from './editor/interactiveStates';
 import { type SurfaceClassification } from './editor/surfaceDemands';
 import { type ScreenDimensionDef } from './editor/screenDimensions';
 import { type FrameBranchKindDef, type FrameLabelLabels } from './editor/frameLabels';
@@ -46,8 +46,8 @@ export { applyScenarioCoverageClaim, validateScenarioCoverage, } from './editor/
 export type { ApplyCoverageResult, ScenarioCoverageClaim, ScenarioCoverageContext, ScenarioCoverageDiagnostic, } from './editor/scenarioCoverage';
 export { enumerateControlCandidates, enumerateRequestCandidates, enumerateRouteCandidates, frameSurfaceDemands, getObservedRequests, getSurfaceClassifications, MIN_SURFACE_REASON_LENGTH, requestEndpointShape, setObservedRequests, setSurfaceClassifications, unclassifiedSurfaces, validateSurfaceDemands, } from './editor/surfaceDemands';
 export type { ControlNodeLike, FrameSurfaceDemands, ObservedRequest, RouteEnumerationInput, SurfaceCandidate, SurfaceClassification, SurfaceDemandDiagnostic, SurfaceDemandKind, SurfaceVerdict, } from './editor/surfaceDemands';
-export { validateInteractiveStates } from './editor/interactiveStates';
-export type { InteractiveStateDef, InteractiveStateDiagnostic, InteractiveStateOption, } from './editor/interactiveStates';
+export { validateInteractiveStates, validateScreenStateAxes, } from './editor/interactiveStates';
+export type { InteractiveStateDef, InteractiveStateDiagnostic, InteractiveStateOption, ScreenStateAxisDef, ScreenStateAxisDiagnostic, ScreenStateAxisKind, ScreenStateOption, } from './editor/interactiveStates';
 export { validateScreenCards } from './editor/screenCards';
 export type { CardBadgeOption, CardSlotDef, ScreenCardDef, ScreenCardDiagnostic, } from './editor/screenCards';
 export { validateFrameBranchKinds, framesMissingScenario } from './editor/frameLabels';
@@ -210,7 +210,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, interactiveStates, surfaceClassifications, onApply, onDesignChange, onInspectApply, onInspectPreview, onInspectImpact, storyboard, storyboardDiscovery, storyboardDiscoveryEndpoint, }: {
+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, storyboardDiscovery, storyboardDiscoveryEndpoint, }: {
     registry?: ComponentRegistry;
     tokens?: TokenDef[];
     initialPages?: InitialPageDef[];
@@ -362,9 +362,14 @@ export declare function PygmalionEditor({ registry, tokens, initialPages, initia
      */
     liveScreenBudget?: number;
     /**
-     * Host-declared interactive states: axes a screen reaches by acting on it
-     * (folding the sidebar, hovering a row) rather than by being a separate
-     * captured frame. Validate with validateInteractiveStates.
+     * Host-declared screen-state axes. Interaction axes replay local gestures;
+     * condition axes recreate external boot conditions. Both stay attached to
+     * the same frame instead of multiplying the canvas. Validate with
+     * validateScreenStateAxes.
+     */
+    screenStateAxes?: readonly ScreenStateAxisDef[];
+    /**
+     * @deprecated Use screenStateAxes. Kept as a migration bridge.
      */
     interactiveStates?: readonly InteractiveStateDef[];
     /**

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

@@ -81,11 +81,7 @@ export declare const FrameScreenLists: import("react").FunctionComponent<{
 export declare const FrameCardBadges: import("react").FunctionComponent<{
     page: PageModel;
 }>;
-/**
- * Interactive states — axes reachable by acting on the screen (folding the
- * sidebar, hovering a row). They are not sibling frames: the same frame is
- * re-supplied with the option's steps appended to its recipe.
- */
+/** Same-frame states, separated by the mechanism that reproduces them. */
 export declare const FrameInteractiveStates: import("react").FunctionComponent<{
     page: PageModel;
 }>;

package/docs/screen-state-contract.md

@@ -0,0 +1,127 @@
+# Screen state contract
+
+Pygmalion uses five review placements. A host must choose the placement from
+how the variation is reproduced, not from how different its pixels look.
+
+| Placement | Use when | Pygmalion declaration |
+| --- | --- | --- |
+| Frame | The variation is an independent task, journey checkpoint, structural composition, overlay context, or supported viewport that reviewers must navigate to directly. | `DesignScreenCase` |
+| Interaction state | The same booted screen reaches a deterministic, reversible visual endpoint through a local gesture. | `ScreenStateAxisDef` with `kind: 'interaction'` |
+| Condition state | The same screen needs external data, network, storage, permission, media, or timing conditions before it boots. | `ScreenStateAxisDef` with `kind: 'condition'` |
+| Editable parameter | The variation only samples text length, row count, content, or another freely editable value and has no distinct product endpoint. | Edit mode, component props, list controls, viewport controls, or QA data |
+| Behavior | The action has no stable visual endpoint to preserve. | `DesignBehaviorScenario` or an automated interaction test |
+
+The practical test is: after reproducing the variation, is there a stable state
+that another reviewer should be able to select again? If yes, use a frame or a
+screen-state axis. If the answer is only “this value is longer” or “the request
+was sent,” keep it in editing or QA instead.
+
+## Frame versus same-frame state
+
+Preserve a separate frame when at least one of these is true:
+
+- it is a named step in a user journey;
+- it changes the screen's primary task or structural composition;
+- it provides an independent review anchor that must remain visible beside
+  another screen;
+- it is a supported viewport whose responsive composition must be compared.
+
+Use a same-frame axis when all of these are true:
+
+- the route, task, and main structure stay the same;
+- the variation is deterministic and can be recreated from the captured base;
+- choosing it does not depend on an undocumented sequence;
+- the final visual state remains visible long enough to capture.
+
+Pseudo states such as hover, keyboard focus, and pointer active are always
+interaction states. They must not become duplicate frames.
+
+## Required axis classification
+
+`kind` is mandatory and is enforced when the editor installs the axes.
+`validateScreenStateAxes` is also exported for host validation gates.
+
+```ts
+import type { ScreenStateAxisDef } from '@pygmalionjs/pygmalion';
+
+export const screenStateAxes: readonly ScreenStateAxisDef[] = [
+  {
+    id: 'editable-heading',
+    label: 'Heading',
+    kind: 'interaction',
+    requires: { testId: 'editable-heading' },
+    options: [
+      { id: 'rest', label: 'Rest' },
+      {
+        id: 'hover',
+        label: 'Hover',
+        steps: [
+          {
+            action: 'hover',
+            label: 'Hover heading',
+            selector: '[data-testid="editable-heading"]',
+          },
+        ],
+      },
+      {
+        id: 'editing',
+        label: 'Editing',
+        steps: [
+          {
+            action: 'click',
+            label: 'Open heading editor',
+            selector: '[data-testid="editable-heading"]',
+          },
+          {
+            action: 'wait',
+            label: 'Heading input is visible',
+            selector: '[data-testid="heading-input"]',
+          },
+        ],
+      },
+    ],
+  },
+  {
+    id: 'results',
+    label: 'Results',
+    kind: 'condition',
+    options: [
+      { id: 'loaded', label: 'Loaded' },
+      {
+        id: 'failed',
+        label: 'Failed',
+        environment: {
+          network: {
+            conditions: [
+              { match: '/api/results', outcome: { kind: 'fail', status: 500 } },
+            ],
+          },
+        },
+      },
+    ],
+  },
+];
+
+<PygmalionEditor screenStateAxes={screenStateAxes} />;
+```
+
+An interaction option cannot declare `environment`. Every non-base condition
+option must declare one. An interaction option ending in `fill` is rejected
+unless a later targeted `wait` proves that the input reached a distinct visual
+result. This keeps empty strings and maximum-length samples out of the state
+panel while still allowing a search input to reproduce a real empty-result
+state.
+
+## Held pseudo states
+
+Recipes support `hover`, `focus-visible`, and `active` in addition to `focus`.
+These actions remain held through capture. The browser runner dispatches the
+corresponding events, the Playwright worker performs the real pointer or focus
+gesture, and frozen DOM previews materialize `:hover`, `:focus`,
+`:focus-visible`, `:focus-within`, and `:active` selectors as scoped data
+attributes. A DOM preview therefore preserves the same pseudo-state styling as
+the captured application rather than relying on the editor's current pointer.
+
+A held pseudo action must be terminal; only `wait` steps may follow it. This
+prevents a declaration from claiming a transient hover that a later click has
+already replaced.

package/node/storyboard-capture-runtime.mjs

@@ -381,6 +381,13 @@ export async function runStoryboardInteraction(page, interaction) {
       await target.click({ timeout: timeoutMs });
     } else if (interaction.action === 'focus') {
       await target.focus({ timeout: timeoutMs });
+    } else if (interaction.action === 'hover') {
+      await target.hover({ timeout: timeoutMs });
+    } else if (interaction.action === 'focus-visible') {
+      await target.focus({ timeout: timeoutMs });
+    } else if (interaction.action === 'active') {
+      await target.hover({ timeout: timeoutMs });
+      await page.mouse.down();
     } else if (interaction.action === 'fill') {
       await target.fill(interaction.value ?? '', { timeout: timeoutMs });
     } else if (interaction.action === 'check') {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pygmalionjs/pygmalion",
-  "version": "0.5.33",
+  "version": "0.6.0",
   "description": "Code-backed DOM design sandbox and visual QA editor",
   "license": "UNLICENSED",
   "publishConfig": {
@@ -32,6 +32,7 @@
   },
   "files": [
     "dist-lib",
+    "docs/screen-state-contract.md",
     "node/component-branches.mjs",
     "node/design-session.mjs",
     "node/dev-mirror.mjs",