@pygmalionjs/pygmalion 0.8.1 → 0.9.0

package/docs/screen-state-contract.md

@@ -1,252 +0,0 @@
-# Screen state contract
-
-Pygmalion uses six 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 has a deterministic, reversible visual endpoint, reached either directly or through a local gesture. | `ScreenStateAxisDef` with `kind: 'interaction'` and `desiredState` or `steps` |
-| 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 |
-| Motion preview | The same screen continuously changes through CSS or Web Animations without becoming a new product state. | Nothing to declare: a live frame animates on its own; a capture holds the settled baseline |
-| 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.
-
-## Frame size
-
-The W and H controls in the frame inspector change the frame viewport, not the
-canvas camera. A committed size is part of the frame fingerprint and its exact
-capture recipe. The request carries the route, width, height, conditions,
-desired state, and interactions that produced that fingerprint. A returned
-artifact is seeded under that requested recipe instead of the authored catalog
-key.
-
-This distinction is observable: resizing a frame may change responsive layout,
-while changing canvas zoom only changes how large the same frame appears in the
-editor. Hosts that implement an on-demand capture adapter must apply the
-requested `route`, `width`, and `height` overrides before launching the capture.
-
-## Automatic pseudo-state coverage
-
-Pygmalion discovers pseudo-state surfaces while it serializes a screen. Every
-rendered target matched by `:hover`, `:focus`, `:focus-visible`,
-`:focus-within`, or `:active` is stamped into the inert DOM preview. React
-hover and focus handlers are discovered from the rendered element props; the
-inspect transform also marks native JSX event surfaces. The right panel's
-variant matrix shows the chosen target as an **Elements** row with Default,
-Hover, Focus, and Pressed options as applicable; a filterable picker chooses
-the target, and picking an element with Inspect on chooses it from the canvas.
-
-Discovery does not apply a semantic or size threshold. A plain button whose
-only hover effect is a color, border, shadow, or opacity change belongs in the
-panel just as much as a title that reveals an edit affordance. Transparent hit
-areas are included when they occupy layout space. This makes pseudo-state
-coverage a property of the captured UI instead of a list each host must keep
-in sync by hand.
-
-Hosts still declare an interaction axis when the endpoint needs several steps,
-a product-specific label, or behavior beyond a pseudo gesture. If a declared
-axis targets the same element and pseudo action, Pygmalion suppresses that
-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 **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
-
-Pygmalion discovers visible CSS animation owners, animated pseudo elements,
-matching animation rules, and Web Animations API targets while it serializes a
-screen, and stamps every target into the inert preview. The stamps are what
-the capture runtime settles: finite animations at their terminal state,
-repeating animations at the start of their cycle. This keeps entrance motion
-from hiding the base UI while screenshots and visual comparisons remain
-repeatable, and a mounted frozen preview holds the same baseline.
-
-Motion discovery has no semantic or size threshold. Small progress dots,
-ordinary status indicators, shimmer bars, and full-surface animation are
-settled the same way. There are no playback controls in the editor: a live
-frame runs the real application, so its motion plays as it does in the
-product, and a capture is by definition still.
-
-An animation does not need duplicate frames merely to show several points in
-its cycle. Preserve a separate frame only when the motion ends in an independent
-task, journey checkpoint, structural composition, or other state that already
-meets the frame criteria above.
-
-## 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: 'collapsed',
-        label: 'Collapsed',
-        desiredState: 'collapsed',
-      },
-    ],
-  },
-  {
-    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. A direct `desiredState` value cannot be combined with
-steps or an environment on the same option. 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.
-
-## Direct desired state
-
-Use direct desired state for a locally controlled endpoint whose final visual
-state matters more than the gestures used to reach it. Pygmalion builds a
-complete map from selected axes, such as `{ sidebar: 'collapsed' }`, and calls
-the host's `executeDesiredState` adapter after mount and before any remaining
-interaction steps. The map participates in capture and preview identity.
-
-The adapter must replace its whole preview state, not merge it. Pygmalion calls
-it with `{}` as well, so a warm iframe reused for another frame cannot retain a
-previous override. A typical React host exposes the map through an external
-store and lets each component read only its own axis. The adapter is preview
-infrastructure: it must not dispatch the application's production store or
-write persistent product state. When a reviewer uses the real control, the
-component should release its preview override and continue from the currently
-displayed value.
-
-The right-panel selection starts delivery in the same input task. Once one
-option has a live document, sibling direct-state options share that document:
-Pygmalion skips boot, route entry, gesture replay, assertions, and geometry
-settling, then sends the replacement map to the host adapter. The React commit
-is the presentation boundary; snapshot serialization may continue afterward
-without blocking the visible state. A live direct-state document is pinned
-against normal warm-pool eviction and cannot be claimed through gesture-prefix
-matching, because those signatures do not describe host-owned state.
-Sibling delivery calls the live adapter directly rather than joining the replay
-runner's FIFO. Frames that expose a direct-state axis also reserve their
-activation-warmed document from unrelated gesture prefetch and align it
-invisibly behind the frozen frame. The first selection can therefore reveal the
-already-positioned React document after its adapter commit; speculative work
-cannot reintroduce a queue between the panel click and that commit.
-
-Keep gesture steps when the transition itself is under review, when effects
-outside local render state establish the endpoint, or when the host has no safe
-preview-only adapter for that state.
-
-## Scroll positions
-
-A stable scroll endpoint is an interaction state. Use a `scroll` recipe step
-with absolute `scrollX` and/or `scrollY` coordinates. With no selector the step
-restores the document viewport; a selector targets a specific overflow
-container. An omitted axis keeps its current position.
-
-Absolute coordinates make the endpoint repeatable in both the in-editor replay
-and the capture worker. A free wheel gesture remains transient until the host
-preserves its endpoint as a recipe. The frame inspector enumerates the document
-viewport and independently scrollable nested surfaces. Preserving one records
-both its stable selector and coordinates; the target picker keeps nested list
-or panel scroll distinct from the document viewport.
-
-## 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.