@pygmalionjs/pygmalion 0.4.0 → 0.5.1

package/types.d.ts

@@ -18,6 +18,14 @@ export interface RegistryEntry {
   defaultProps?: Record<string, RegistryPropValue>;
   /** 'text' = children Edit string · 'nodes' = Place canvas nodes as children (Card, etc.). */
   children?: 'text' | 'none' | 'nodes';
+  /**
+   * Whether a captured screen subtree may be REPLACED by this entry when a
+   * screen is imported. Declare it only for entries that render the real
+   * component from literal props — a catalog demo or a fixture-seeded adapter
+   * draws its own sample content, so collapsing into it swaps the captured
+   * screen for that sample. Default false.
+   */
+  collapsible?: boolean;
   /** Static children default values ​​to use when inserting from the palette. */
   defaultChildren?: string;
   /** Path for generating codegen import statements. */
@@ -435,6 +443,13 @@ export interface StoryboardEnvironment {
     devices?: readonly StoryboardMediaDevice[];
     getUserMedia?: 'passthrough' | StoryboardMediaFailure;
   };
+  /**
+   * 'sandbox' virtualizes the whole origin storage for the document: reads
+   * of undeclared keys see a pristine profile and writes never reach the
+   * shared storage. Hidden preview instances set it so persisted UI state
+   * from one walk cannot poison sibling instances or the designer's tab.
+   */
+  storageIsolation?: 'sandbox';
 }
 
 export type DesignScreenAssertionVisibility = 'visible' | 'hidden';
@@ -479,7 +494,13 @@ export interface DesignImportPage {
   flow?: string;
   scenario?: string;
   state?: string;
+  /** Host-declared kind of the state branch (overlay, badge, layout, ...). Presentation hint for the Screen states control. */
+  stateKind?: string;
+  /** Host-declared situation lane the canvas arranges the frame into. */
+  lane?: string;
   scenarioId?: string;
+  /** Every scenario the screen demonstrates; coverage counts this set. */
+  scenarioIds?: readonly string[];
   interactions?: readonly DesignScreenInteraction[];
   environment?: StoryboardEnvironment;
   preset?: DesignScreenPreset;
@@ -768,6 +789,10 @@ export interface DesignImportInitialPage extends InitialPageDef {
   flow?: string;
   scenario?: string;
   state?: string;
+  /** Host-declared kind of the state branch (overlay, badge, layout, ...). Presentation hint for the Screen states control. */
+  stateKind?: string;
+  /** Host-declared situation lane the canvas arranges the frame into. */
+  lane?: string;
   scenarioId?: string;
   interactions?: DesignScreenInteraction[];
   environment?: StoryboardEnvironment;
@@ -813,6 +838,12 @@ export interface DesignImportController {
 export interface CreateDesignImportOptions {
   layerOptions?: DomImportOptions;
   executeScreenPreset?: DesignScreenPresetExecutor;
+  /**
+   * `section` gives each screen section its own canvas
+   * (`<screens canvas> · <section>`), so the camera, the LOD budget, and
+   * decoded previews scale with a section instead of the whole catalog.
+   */
+  screensCanvasPartition?: 'single' | 'section';
 }
 
 export declare function createDesignImportController(
@@ -1173,6 +1204,414 @@ export declare function createPreviewCacheNamespace(
 export declare function createStoryboardCaptureRecipeIdentity(
   screen: StoryboardCaptureRecipeInput,
 ): unknown;
+/** The declaration-relevant slice of a page: everything grouping keys off. */
+export interface ScreenStateGroupInput {
+  name: string;
+  canvas?: string;
+  route?: string;
+  scenario?: string;
+  state?: string;
+  width?: number;
+  height?: number;
+}
+export interface ScreenStateGroupDiagnostic {
+  severity: 'warning' | 'info';
+  code: 'mixed-viewport' | 'duplicate-state' | 'cross-canvas' | 'singleton-group';
+  scenario: string;
+  message: string;
+}
+/**
+ * Validates host-declared screen-state groups against the contract the
+ * Screen states panel enforces — same canvas, one frame per state label, a
+ * shared viewport, at least one sibling. Hosts own membership; the core
+ * validates the declaration.
+ */
+export declare function validateScreenStateGroups(
+  pages: readonly ScreenStateGroupInput[],
+): ScreenStateGroupDiagnostic[];
+/** One waypoint of a flow path: the screen it materializes and the walk delta reaching it. */
+export interface ScreenFlowWaypoint {
+  /** Catalog id of the screen this waypoint materializes (importPageId). */
+  screenId: string;
+  /** Interactions from the previous waypoint (or the boot) to this screen's state. */
+  steps?: readonly DesignScreenInteraction[];
+}
+/**
+ * One captureless surface path: a hidden live instance boots `route` with
+ * `environment` and walks the waypoints in order, publishing one frozen
+ * snapshot per screen. A single-waypoint path is a per-screen recipe; a
+ * multi-waypoint path amortizes one boot across a user journey.
+ */
+export interface ScreenFlowPath {
+  id: string;
+  route: string;
+  environment?: StoryboardEnvironment;
+  waypoints: readonly ScreenFlowWaypoint[];
+}
+export interface ScreenFlowDiagnostic {
+  severity: 'error' | 'warning';
+  pathId: string;
+  message: string;
+}
+/** Structural validation of flow paths against the screen catalog. */
+export declare function validateScreenFlows(
+  paths: readonly ScreenFlowPath[],
+  screens: readonly { id: string }[],
+): ScreenFlowDiagnostic[];
+/**
+ * Where one QA scenario is verified: a dedicated frame, a folded screen
+ * state, a component toggle, a viewport preset, or a declared behavior/todo.
+ * Claims are host-declared, core-validated, and executable in the editor.
+ */
+export type ScenarioCoverageClaim =
+  | { scenarioId: string; kind: 'frame'; screenId: string; reason?: string }
+  | { scenarioId: string; kind: 'screen-state'; screenId: string; reason?: string }
+  | {
+      scenarioId: string;
+      kind: 'component-state';
+      screenId: string;
+      componentName: string;
+      prop: string;
+      value: RegistryPropValue;
+      reason?: string;
+    }
+  | {
+      scenarioId: string;
+      kind: 'viewport';
+      screenId: string;
+      preset: string;
+      reason?: string;
+    }
+  | { scenarioId: string; kind: 'catalog'; screenId: string; reason?: string }
+  | {
+      scenarioId: string;
+      /** A declared interactive axis reaches the scenario in one gesture. */
+      kind: 'interactive-state';
+      /** InteractiveStateDef id. */
+      interaction: string;
+      /** InteractiveStateOption id within that axis. */
+      option: string;
+      screenId: string;
+      reason?: string;
+    }
+  | {
+      scenarioId: string;
+      /** A badge composition on the screen's repeated card demonstrates it. */
+      kind: 'card-slot';
+      /** ScreenCardDef id. */
+      card: string;
+      /** CardSlotDef id within that card. */
+      slot: string;
+      /** CardBadgeOption id within that slot. */
+      option: string;
+      screenId: string;
+      reason?: string;
+    }
+  | {
+      scenarioId: string;
+      /** A row count on the screen's declared list demonstrates it. */
+      kind: 'list-length';
+      /** ScreenListDef id. */
+      list: string;
+      count: number;
+      screenId: string;
+      reason?: string;
+    }
+  | { scenarioId: string; kind: 'behavior'; reason: string }
+  | { scenarioId: string; kind: 'todo'; reason: string };
+export interface ScenarioCoverageDiagnostic {
+  severity: 'error' | 'warning';
+  scenarioId: string;
+  message: string;
+}
+export interface ScenarioCoverageContext {
+  scenarios: readonly { id: string }[];
+  screens: readonly { id: string; scenario?: string; state?: string }[];
+  registry: Readonly<
+    Record<string, { props?: Readonly<Record<string, readonly RegistryPropValue[]>> }>
+  >;
+  viewportPresets: readonly { label: string }[];
+  catalogPages?: readonly { id: string }[];
+  /** Host-declared interactive axes, for interactive-state claims. */
+  interactiveStates?: readonly {
+    id: string;
+    options: readonly { id: string; steps?: readonly unknown[] }[];
+  }[];
+  /** Host-declared card compositions, for card-slot claims. */
+  screenCards?: readonly {
+    id: string;
+    slots: readonly { id: string; options: readonly { id: string }[] }[];
+  }[];
+  /** Host-declared list axes, for list-length claims. */
+  screenLists?: readonly { id: string; min?: number; max?: number }[];
+}
+export declare function validateScenarioCoverage(
+  claims: readonly ScenarioCoverageClaim[],
+  context: ScenarioCoverageContext,
+): ScenarioCoverageDiagnostic[];
+/** One discovered conditional-render branch from the component scanner. */
+export interface ComponentBranch {
+  kind: 'conditional' | 'enum';
+  condition: string;
+  element?: string;
+  renders?: string;
+  values?: readonly string[];
+  line?: number;
+}
+export interface ScreenDimensionOption {
+  label: string;
+  props: Readonly<Record<string, RegistryPropValue>>;
+}
+/**
+ * Points at captured markup by a test id or css-module class prefix. A list
+ * of prefixes matches any one of them, which lets a single axis cover
+ * sibling elements the product renders from different branches.
+ */
+export interface NodeSelector {
+  testId?: string;
+  classIncludes?: string | readonly string[];
+}
+/**
+ * A curated right-panel control that swaps a captured piece's state by
+ * adopting the matched node into a registry adapter instance.
+ */
+export interface ScreenDimensionDef {
+  id: string;
+  label: string;
+  component: string;
+  prop?: string;
+  options?: readonly ScreenDimensionOption[];
+  match: NodeSelector;
+  /**
+   * 'first' (default) drives the one piece a screen shows once; 'each'
+   * opens a control per match, which is what a list of rows needs.
+   */
+  sourcePath?: string;
+}
+export interface ScreenDimensionDiagnostic {
+  severity: 'error' | 'warning';
+  dimensionId: string;
+  message: string;
+}
+export declare function validateScreenDimensions(
+  dimensions: readonly ScreenDimensionDef[],
+  context: {
+    registry: Readonly<
+      Record<string, { props?: Readonly<Record<string, readonly RegistryPropValue[]>> }>
+    >;
+    scansBySource?: Readonly<Record<string, readonly ComponentBranch[]>>;
+  },
+): ScreenDimensionDiagnostic[];
+/**
+ * A repeating list whose row count becomes a right-panel control. Growing
+ * clones the last row (identical on purpose — the per-row dimension
+ * controls are what make rows differ); shrinking drops trailing rows. It
+ * edits the captured tree, so it applies instantly and undoes in one step.
+ */
+export interface ScreenListDef {
+  id: string;
+  label: string;
+  container: NodeSelector;
+  item: NodeSelector;
+  /** Fewest rows the control offers. Default 0. */
+  min?: number;
+  /** Most rows the control offers. Default 12. */
+  max?: number;
+}
+export interface ScreenListDiagnostic {
+  severity: 'error' | 'warning';
+  listId: string;
+  message: string;
+}
+export declare function validateScreenLists(
+  defs: readonly ScreenListDef[],
+): ScreenListDiagnostic[];
+/**
+ * One badge a card slot may hold. `match` recognizes the captured element;
+ * `component`/`props` build it from the registry when the screen has no
+ * captured instance to clone; `anchor` is its fixed position in the slot.
+ */
+export interface CardBadgeOption {
+  id: string;
+  label: string;
+  component: string;
+  props: Readonly<Record<string, RegistryPropValue>>;
+  match: NodeSelector;
+  anchor?: { before?: NodeSelector; after?: NodeSelector };
+}
+/** A region of a card with its own vocabulary and capacity. */
+export interface CardSlotDef {
+  id: string;
+  label: string;
+  container: NodeSelector;
+  /** 'multiple' (the default) when the product can show several at once. */
+  arity?: 'single' | 'multiple';
+  /** The product renders the container only when it has content. */
+  hideWhenEmpty?: boolean;
+  /** Where to create the container on a card that lacks one. */
+  placement?: { parent: NodeSelector; before?: NodeSelector; after?: NodeSelector };
+  options: readonly CardBadgeOption[];
+}
+/**
+ * The badge composition of a repeated card, declared the way the component
+ * is built: slots, what each may hold, how many at once.
+ */
+export interface ScreenCardDef {
+  id: string;
+  label: string;
+  card: NodeSelector;
+  slots: readonly CardSlotDef[];
+  sourcePath?: string;
+}
+export interface ScreenCardDiagnostic {
+  severity: 'error' | 'warning';
+  cardId: string;
+  message: string;
+}
+export declare function validateScreenCards(
+  defs: readonly ScreenCardDef[],
+  context: {
+    registry: Readonly<
+      Record<string, { props?: Readonly<Record<string, readonly RegistryPropValue[]>> }>
+    >;
+    scansBySource?: Readonly<Record<string, readonly ComponentBranch[]>>;
+  },
+): ScreenCardDiagnostic[];
+/**
+ * An axis a screen reaches by acting on it (folding the sidebar, hovering a
+ * row) rather than by being a separate captured frame. Selecting an option
+ * appends its steps to the frame's recipe, so the ordinary supply produces
+ * the variant.
+ */
+export interface InteractiveStateOption {
+  id: string;
+  label: string;
+  /** Absent or empty marks the base state — the screen as captured. */
+  steps?: readonly DesignScreenInteraction[];
+}
+export interface InteractiveStateDef {
+  id: string;
+  label: string;
+  /** Frames the axis applies to: exact route and/or a test id in the tree. */
+  requires?: { testId?: string; route?: string };
+  options: readonly InteractiveStateOption[];
+}
+export interface InteractiveStateDiagnostic {
+  severity: 'error' | 'warning';
+  interactionId: string;
+  message: string;
+}
+export declare function validateInteractiveStates(
+  defs: readonly InteractiveStateDef[],
+): InteractiveStateDiagnostic[];
+/**
+ * Host-declared description of one canvas section — the band above its box.
+ * The core counts frames, folded variants, scenarios and viewport itself.
+ */
+/**
+ * A situation group within one section. Declaration order is lane order, and
+ * one lane is one row of the canvas — the axis that replaces area packing so
+ * an arrangement reads as the product's structure.
+ */
+export interface ScreenLaneDef {
+  /** Unique within its section. */
+  id: string;
+  /** Human-readable, drawn as the lane caption. */
+  label: string;
+  /** Section name exactly as the frames carry it. */
+  section: string;
+  /** Caption rule colour (hex). Defaults to a neutral. */
+  accent?: string;
+}
+export interface ScreenLaneDiagnostic {
+  severity: 'error' | 'warning';
+  laneId: string;
+  message: string;
+}
+export declare function validateScreenLanes(
+  lanes: readonly ScreenLaneDef[],
+  context?: { sections?: readonly string[] },
+): ScreenLaneDiagnostic[];
+export interface SectionHeaderDef {
+  /** Section name exactly as the frames carry it — the join key. */
+  section: string;
+  /** Short handle shown large, e.g. "02". */
+  code: string;
+  /** Section title. */
+  title: string;
+  /** Secondary clause after the title: what kind of group this is. */
+  kind?: string;
+  /** One line a planner needs: what the section covers. */
+  purpose: string;
+  /** Accent colour (hex) for the rule and the category pill. */
+  accent: string;
+  /** Category shown in the pill. */
+  pill?: string;
+}
+/** Words for the facts a section header counts. Defaults are English. */
+export interface SectionHeaderLabels {
+  code?: string;
+  frames?: string;
+  folded?: string;
+  scenarios?: string;
+  flows?: string;
+}
+export interface SectionHeaderDiagnostic {
+  severity: 'error' | 'warning';
+  section: string;
+  message: string;
+}
+export interface SectionHeaderFacts {
+  frameCount: number;
+  foldedCount: number;
+  scenarioCount: number;
+  flows: string[];
+  viewport: string | null;
+}
+export declare function validateSectionHeaders(
+  defs: readonly SectionHeaderDef[],
+  context: { sections: readonly string[] },
+): SectionHeaderDiagnostic[];
+/**
+ * Presentation of one branch kind a frame label can carry: a state kind the
+ * catalog declares, or the core's own `step` (a plain screen) and `variant`
+ * (a numbered branch that declares no state kind).
+ */
+export interface FrameBranchKindDef {
+  kind: string;
+  /** Word shown in the label's pill. */
+  label: string;
+  /** Accent colour for the rule and the pill text. */
+  accent: string;
+}
+/** Words for the facts a frame label counts. English by default. */
+export interface FrameLabelLabels {
+  layers?: string;
+  noScenario?: string;
+  omissions?: string;
+  checkFlow?: string;
+}
+export interface FrameBranchKindDiagnostic {
+  severity: 'error' | 'warning';
+  kind: string;
+  message: string;
+}
+export declare function validateFrameBranchKinds(
+  defs: readonly FrameBranchKindDef[],
+  context?: { stateKinds?: readonly string[] },
+): FrameBranchKindDiagnostic[];
+/** Screen frames claiming no scenario at all — the holes in the ledger. */
+export declare function framesMissingScenario(
+  pages: readonly { route?: string; scenarioId?: string; scenarioIds?: readonly string[] }[],
+): readonly { name: string; section?: string }[];
+export interface ApplyCoverageResult {
+  status: 'applied' | 'pending-import' | 'failed';
+  message?: string;
+}
+/** Reproduces the reviewed state a claim describes inside the editor. */
+export declare function applyScenarioCoverageClaim(
+  claim: ScenarioCoverageClaim,
+): ApplyCoverageResult;
 export declare function createPreviewArtifactHttpTransport(
   options: PreviewArtifactHttpTransportOptions,
 ): PreviewArtifactTransport;
@@ -1464,6 +1903,8 @@ export interface StoryboardResolvedPage {
   flow?: string;
   scenario?: string;
   state?: string;
+  /** Host-declared kind of the state branch (overlay, badge, layout, ...). Presentation hint for the Screen states control. */
+  stateKind?: string;
   scenarioId?: string;
   interactions?: readonly DesignScreenInteraction[];
   environment?: StoryboardEnvironment;
@@ -1558,6 +1999,10 @@ export interface InitialPageDef {
   flow?: string;
   scenario?: string;
   state?: string;
+  /** Host-declared kind of the state branch (overlay, badge, layout, ...). Presentation hint for the Screen states control. */
+  stateKind?: string;
+  /** Host-declared situation lane the canvas arranges the frame into. */
+  lane?: string;
   scenarioId?: string;
   interactions?: DesignScreenInteraction[];
   environment?: StoryboardEnvironment;
@@ -1975,6 +2420,12 @@ export declare function PygmalionEditor(props: {
   initialPages?: InitialPageDef[];
   /** Canvas shown on first mount. Useful when an earlier catalog canvas is expensive to render. */
   initialCanvas?: string;
+  /**
+   * Mode the editor opens in. Defaults to 'edit'. Declare 'view-only' when the
+   * editor is a review surface: it applies once, so the toggle still belongs to
+   * the designer, and nothing is persisted across reloads.
+   */
+  initialEditMode?: 'edit' | 'view-only';
   /** Explicit external-design to registered-code component mappings. */
   componentConnections?: readonly DesignComponentConnectionDef[];
   /** Named frame widths the application supports — rendered as one-click buttons beside the W/H boxes. */
@@ -2003,6 +2454,50 @@ export declare function PygmalionEditor(props: {
   onPreviewOpenChange?: (open: boolean) => void;
   /** ▶ The name of the “app screen flow” canvas that the preview will always play — Enter this canvas screen even if you press it on another canvas. */
   flowCanvas?: string;
+  /**
+   * Static surface for route frames: `bitmap` (default) renders captured
+   * screenshots and reconstructs frozen DOM on demand; `dom` mounts the
+   * frozen DOM from the start — recommended with per-section canvases.
+   */
+  frameSurface?: 'bitmap' | 'dom';
+  /**
+   * Host-declared flow paths — the captureless surface supply. One hidden
+   * live instance walks each path and publishes a frozen snapshot per
+   * waypoint; frames a flow claims wait for delivery instead of booting
+   * live. Screens no flow claims keep the artifact/sweep/boot supply.
+   */
+  screenFlows?: readonly ScreenFlowPath[];
+  /**
+   * Host-declared scenario coverage ledger. The right panel lists a screen's
+   * claims as executable rows and badges component controls with the
+   * scenarios they demonstrate.
+   */
+  scenarioCoverage?: readonly ScenarioCoverageClaim[];
+  /** Curated per-screen dimension controls (see ScreenDimensionDef). */
+  screenDimensions?: readonly ScreenDimensionDef[];
+  /** Row-count controls for repeating lists (see ScreenListDef). */
+  screenLists?: readonly ScreenListDef[];
+  /** Section header bands (see SectionHeaderDef). */
+  sectionHeaders?: readonly SectionHeaderDef[];
+  /** Situation lanes: one lane is one canvas row (see ScreenLaneDef). */
+  screenLanes?: readonly ScreenLaneDef[];
+  /** Branch-kind presentation for frame labels (see FrameBranchKindDef). */
+  frameBranchKinds?: readonly FrameBranchKindDef[];
+  /** Words for the facts a frame label counts. */
+  frameLabelLabels?: FrameLabelLabels;
+  /** Words for the facts a section header counts. */
+  sectionHeaderLabels?: SectionHeaderLabels;
+  /** Badge composition per repeated card (see ScreenCardDef). */
+  screenCards?: readonly ScreenCardDef[];
+  /**
+   * How many frames may render the running application instead of their
+   * capture. Default 0 — every frame is served from its capture. Raise it
+   * to keep the frames in use interactive; the least recently activated
+   * holder gives its slot back.
+   */
+  liveScreenBudget?: number;
+  /** Interactive axes reachable by acting on a screen (see InteractiveStateDef). */
+  interactiveStates?: readonly InteractiveStateDef[];
   /** Reflect button — Returns { branch } after the host saves the file and commits the branch (push is done directly by the user). */
   onApply?: (payload: ApplyPayload) => Promise<{ branch: string } | void>;
   /** Code auto-save path that does not differentiate between icon/token/atom/component/screen. */

package/vite.d.ts

@@ -612,3 +612,34 @@ export declare function findAffectedSourceFiles(
 
 /** source.ref value that previews the current working tree, uncommitted changes included. */
 export declare const PYGMALION_WORKTREE_SOURCE_REF: 'worktree';
+
+
+// ── Component branch scanner ────────────────────────────────────────────────
+
+export interface ScannedComponentBranch {
+  kind: 'conditional' | 'enum';
+  condition: string;
+  element?: string;
+  renders?: string;
+  values?: readonly string[];
+  line?: number;
+}
+
+export interface ComponentBranchManifest {
+  sourcePath: string;
+  branches: readonly ScannedComponentBranch[];
+}
+
+export declare const PYGMALION_COMPONENT_BRANCHES_CONTROL: string;
+
+/** Extracts conditional-render guards and string-literal enum chains. */
+export declare function scanComponentBranches(
+  source: string,
+  sourcePath: string,
+): ComponentBranchManifest;
+
+/** Reads and scans one source file, refusing paths outside the root. */
+export declare function scanComponentBranchesFile(
+  root: string,
+  sourcePath: string,
+): Promise<ComponentBranchManifest>;