@pygmalionjs/pygmalion 0.5.14 → 0.5.16

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

@@ -0,0 +1,64 @@
+import { type RoutePreviewArtifactBundleV2, type RoutePreviewArtifactV2Frame, type RoutePreviewArtifactV2Hash } from './routePreviewArtifactV2.js';
+export type RoutePreviewArtifactV3Status = 'ready' | 'rendered-with-qa-failure' | 'capture-error';
+export type RoutePreviewArtifactV3ScreenshotMediaType = 'image/png' | 'image/webp';
+export interface RoutePreviewArtifactV3Viewport {
+    readonly width: number;
+    readonly height: number;
+}
+export interface RoutePreviewArtifactV3Diagnostic {
+    readonly stage: string;
+    readonly code: string;
+    readonly selector?: string;
+    readonly label?: string;
+    readonly message?: string;
+    readonly viewport: RoutePreviewArtifactV3Viewport;
+}
+export interface RoutePreviewArtifactV3ScreenshotReference {
+    readonly hash: RoutePreviewArtifactV2Hash;
+    readonly mediaType: RoutePreviewArtifactV3ScreenshotMediaType;
+    readonly width: number;
+    readonly height: number;
+}
+export interface RoutePreviewArtifactV3ScreenshotAsset {
+    readonly mediaType: RoutePreviewArtifactV3ScreenshotMediaType;
+    readonly width: number;
+    readonly height: number;
+    readonly data: string;
+    readonly byteLength: number;
+}
+export interface RoutePreviewArtifactV3Frame {
+    readonly status: RoutePreviewArtifactV3Status;
+    readonly viewport: RoutePreviewArtifactV3Viewport;
+    /** Revision that produced this frame, retained when bundles mix provenance. */
+    readonly sourceRevision?: string;
+    /** What this frame was captured from, so freshness is decided per frame. */
+    readonly fingerprint?: string;
+    readonly snapshot?: RoutePreviewArtifactV2Frame;
+    readonly screenshot?: RoutePreviewArtifactV3ScreenshotReference;
+    readonly diagnostics: readonly RoutePreviewArtifactV3Diagnostic[];
+}
+export interface RoutePreviewArtifactBundleV3 {
+    readonly version: 3;
+    readonly namespace: string;
+    readonly sourceRevision?: string;
+    readonly assets: {
+        readonly head: RoutePreviewArtifactBundleV2['assets']['head'];
+        readonly stylesheets: RoutePreviewArtifactBundleV2['assets']['stylesheets'];
+        readonly screenshots: Readonly<Record<RoutePreviewArtifactV2Hash, RoutePreviewArtifactV3ScreenshotAsset>>;
+    };
+    readonly frames: Readonly<Record<string, RoutePreviewArtifactV3Frame>>;
+}
+export interface RoutePreviewArtifactV3ValidationResult {
+    readonly valid: boolean;
+    readonly errors: string[];
+    readonly bytes: number;
+}
+export interface RoutePreviewArtifactV3ReconstructedScreenshot {
+    readonly mediaType: RoutePreviewArtifactV3ScreenshotMediaType;
+    readonly width: number;
+    readonly height: number;
+    readonly dataUrl: string;
+}
+export declare function validateRoutePreviewArtifactV3Browser(value: unknown): RoutePreviewArtifactV3ValidationResult;
+export declare function reconstructRoutePreviewArtifactSnapshotV3(value: unknown, frameId: string): string | null;
+export declare function reconstructRoutePreviewArtifactScreenshotV3(value: unknown, frameId: string): RoutePreviewArtifactV3ReconstructedScreenshot | null;

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

@@ -0,0 +1,9 @@
+export type RoutePreviewPlacement = 'canvas' | 'isolated-producer' | 'none';
+/**
+ * A running route belongs inside the transformed canvas only while its frame is active.
+ * Background cache producers must stay outside that camera boundary.
+ */
+export declare function resolveRoutePreviewPlacement({ active, live, }: {
+    active: boolean;
+    live: boolean;
+}): RoutePreviewPlacement;

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

@@ -0,0 +1,48 @@
+import type { RoutePreviewArtifactResolution } from './routePreview.js';
+import type { RoutePreviewArtifactV3Status } from './routePreviewArtifactV3.js';
+export interface RoutePreviewArtifactStatusInput {
+    stale: boolean;
+    resolution: RoutePreviewArtifactResolution;
+    captureStatus?: RoutePreviewArtifactV3Status;
+    diagnostic?: string;
+}
+export interface RoutePreviewArtifactStatusPresentation {
+    title: string;
+    detail: string;
+    tone: 'info' | 'warning' | 'error';
+    role: 'status' | 'alert';
+    retryable: boolean;
+}
+export type StaticRoutePreviewSurface = 'screenshot' | 'dom' | 'none';
+/**
+ * Background canvas frames prefer the already captured bitmap. Reconstructing
+ * every frozen DOM tree at once blocks the editor main thread; the selected
+ * frame still promotes to the live/detailed path independently.
+ *
+ * The bitmap stops being enough when the camera magnifies a frame beyond the
+ * screenshot's pixel density — a design surface must not look like a blurry
+ * screenshot under zoom. `magnifiedPastBitmap` (the frame LOD controller's
+ * density signal, gated on the `full` tier) trades the screenshot for the
+ * frozen DOM tree; at magnifying zoom levels only a handful of frames fit the
+ * viewport, so reconstruction stays bounded.
+ *
+ * A frame under preview intent (`preparedForPromotion`) also mounts its
+ * frozen DOM: the mounted preview is what the D2 bootless promotion imports
+ * from, so hovering prepares a ~50ms activation instead of a live boot.
+ * Intent slots are LRU-bounded, so preparation stays bounded too.
+ */
+export declare function resolveStaticRoutePreviewSurface({ hasScreenshot, hasDomSnapshot, magnifiedPastBitmap, preparedForPromotion, preferDom, }: {
+    hasScreenshot: boolean;
+    hasDomSnapshot: boolean;
+    magnifiedPastBitmap?: boolean;
+    preparedForPromotion?: boolean;
+    /**
+     * Host preference: mount the frozen DOM from the start. On per-section
+     * canvases a canvas holds a section's worth of frames, so the whole-catalog
+     * reconstruction concern behind bitmap-first no longer applies, and every
+     * frame stays promotion-ready without a mount wait.
+     */
+    preferDom?: boolean;
+}): StaticRoutePreviewSurface;
+/** Turns artifact freshness and capture state into one unambiguous frame badge. */
+export declare function resolveRoutePreviewArtifactStatus({ stale, resolution, captureStatus, diagnostic, }: RoutePreviewArtifactStatusInput): RoutePreviewArtifactStatusPresentation | null;

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

@@ -0,0 +1,167 @@
+import type { RegistryPropValue } from './registry';
+export type ScenarioCoverageClaim = {
+    scenarioId: string;
+    kind: 'frame';
+    screenId: string;
+    reason?: string;
+} | {
+    scenarioId: string;
+    /** A folded screen-state sibling demonstrates the scenario. */
+    kind: 'screen-state';
+    screenId: string;
+    reason?: string;
+} | {
+    scenarioId: string;
+    /** A registry-typed component prop on the screen demonstrates it. */
+    kind: 'component-state';
+    screenId: string;
+    componentName: string;
+    prop: string;
+    value: RegistryPropValue;
+    reason?: string;
+} | {
+    scenarioId: string;
+    /** A named viewport preset on the screen demonstrates it. */
+    kind: 'viewport';
+    screenId: string;
+    /** ViewportPresetDef label, e.g. "Minimum". */
+    preset: string;
+    reason?: string;
+} | {
+    scenarioId: string;
+    /**
+     * A component catalog sheet demonstrates it — the surface for preview
+     * adapters whose product DOM is unstamped plain markup, so no screen
+     * instance exists to toggle.
+     */
+    kind: 'catalog';
+    screenId: string;
+    reason?: string;
+} | {
+    scenarioId: string;
+    /**
+     * A declared interactive axis demonstrates it: the scenario is one
+     * gesture away from the captured screen (a folded sidebar, a hover),
+     * so it needs a control rather than a frame of its own.
+     */
+    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 —
+     * which chips a row carries is a slot decision, not a screen.
+     */
+    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 {
+    /** The scenario inventory every claim must classify exactly once. */
+    scenarios: readonly {
+        id: string;
+    }[];
+    /** Screen catalog with state-group metadata. */
+    screens: readonly {
+        id: string;
+        scenario?: string;
+        state?: string;
+    }[];
+    /** Registry prop declarations, for component-state claims. */
+    registry: Readonly<Record<string, {
+        props?: Readonly<Record<string, readonly RegistryPropValue[]>>;
+    }>>;
+    /** Host-declared viewport presets, for viewport claims. */
+    viewportPresets: readonly {
+        label: string;
+    }[];
+    /** Catalog sheet pages, for catalog claims. */
+    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;
+    }[];
+}
+/**
+ * Validates the ledger: every scenario classified exactly once, and every
+ * claim's target actually exists — screen in the catalog, state in a group,
+ * prop and value in the registry, preset among the host's declarations.
+ */
+export declare function validateScenarioCoverage(claims: readonly ScenarioCoverageClaim[], context: ScenarioCoverageContext): ScenarioCoverageDiagnostic[];
+export interface ApplyCoverageResult {
+    status: 'applied' | 'pending-import' | 'failed';
+    message?: string;
+}
+/**
+ * Reproduces the reviewed state a claim describes, through the same actions
+ * the panels use: frame/screen-state claims activate the frame (activation
+ * reveals folded variants), viewport claims apply the preset resize, an
+ * interactive-state claim flips the axis, card-slot and list-length claims
+ * edit the imported tree, and component-state claims flip the registry prop
+ * on the imported instance.
+ */
+export declare function applyScenarioCoverageClaim(claim: ScenarioCoverageClaim): ApplyCoverageResult;
+export declare function setScenarioCoverageClaims(claims: readonly ScenarioCoverageClaim[]): void;
+export declare function getScenarioCoverageClaims(): readonly ScenarioCoverageClaim[];
+/** Claims verified on one screen — the right panel's coverage section. */
+export declare function coverageClaimsForScreen(screenId: string): readonly ScenarioCoverageClaim[];
+/**
+ * Scenario ids a component prop control demonstrates on the given screen —
+ * rendered as chips beside the control so the panel shows WHY it exists.
+ */
+export declare function coverageBadgesForComponentProp(screenId: string, componentName: string, prop: string): readonly string[];

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

@@ -0,0 +1,101 @@
+import { type NodeSelector } from './nodeSelector';
+import type { ComponentBranch } from './screenDimensions';
+import type { RegistryPropValue } from './registry';
+import type { NodeModel, PageModel } from './store';
+export interface CardBadgeOption {
+    id: string;
+    /** Panel chip text, and the witness looked for in the product source. */
+    label: string;
+    /** Registry adapter used when the capture has no donor to clone. */
+    component: string;
+    props: Readonly<Record<string, RegistryPropValue>>;
+    /** Recognizes this badge in captured markup. */
+    match: NodeSelector;
+    /**
+     * Fixed position within the slot, mirroring the component's JSX order — the
+     * duplicate-name mark sits before the name, the "new" mark after it.
+     * Without an anchor the badge is appended, which is what a list-shaped slot
+     * (the status chips) wants.
+     */
+    anchor?: {
+        before?: NodeSelector;
+        after?: NodeSelector;
+    };
+}
+export interface CardSlotDef {
+    id: string;
+    label: string;
+    /** The element inside the card that holds these badges. */
+    container: NodeSelector;
+    /** 'multiple' (the default) when the product can show several at once. */
+    arity?: 'single' | 'multiple';
+    /**
+     * True when the product renders the container only if it has content — an
+     * empty one left behind would still take its gap and padding.
+     */
+    hideWhenEmpty?: boolean;
+    /**
+     * Where the container belongs when a card does not have one, mirroring the
+     * component's JSX. Required for a `hideWhenEmpty` slot, since those cards
+     * are exactly the ones missing it.
+     */
+    placement?: {
+        parent: NodeSelector;
+        before?: NodeSelector;
+        after?: NodeSelector;
+    };
+    options: readonly CardBadgeOption[];
+}
+export interface ScreenCardDef {
+    id: string;
+    label: string;
+    /** The repeated card this composition applies to. */
+    card: NodeSelector;
+    slots: readonly CardSlotDef[];
+    /** Product source the branch scanner validates the vocabulary against. */
+    sourcePath?: string;
+}
+export interface ScreenCardDiagnostic {
+    severity: 'error' | 'warning';
+    cardId: string;
+    message: string;
+}
+/** Cards one declaration may open controls for. */
+export declare const MAX_CARD_MATCHES = 12;
+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[];
+export declare function findScreenCards(page: PageModel, def: ScreenCardDef): NodeModel[];
+export declare function findCardSlot(card: NodeModel, slot: CardSlotDef): NodeModel | null;
+/**
+ * A badge is present either as the captured element or as an adapter instance
+ * carrying this option's props — adding one can produce either.
+ */
+export declare function nodeIsBadgeOption(node: NodeModel, option: CardBadgeOption): boolean;
+/** Option ids the card currently shows in this slot. */
+export declare function cardSlotSelection(card: NodeModel, slot: CardSlotDef): string[];
+export declare function describeScreenCard(card: NodeModel, index: number): string;
+/**
+ * A captured instance of this badge somewhere else on the screen. Cloning a
+ * real one keeps the product's classes and box; only a badge no card shows
+ * has to be built from the adapter.
+ */
+export declare function findBadgeDonor(page: PageModel, option: CardBadgeOption, exclude: NodeModel): NodeModel | null;
+/** A captured slot container from another card, used when this card lacks one. */
+export declare function findSlotDonor(page: PageModel, slot: CardSlotDef, exclude: NodeModel): NodeModel | null;
+/**
+ * Parent and index where a missing slot container belongs on this card,
+ * from the declared placement. Null when the card has no such parent or the
+ * slot never declared one.
+ */
+export declare function findSlotPlacement(card: NodeModel, slot: CardSlotDef): {
+    parent: NodeModel;
+    index: number;
+} | null;
+/** Insertion point for an anchored badge, or the end of the slot. */
+export declare function badgeInsertIndex(container: NodeModel, option: CardBadgeOption): number;
+export declare function setScreenCards(defs: readonly ScreenCardDef[]): void;
+export declare function getScreenCards(): readonly ScreenCardDef[];

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

@@ -0,0 +1,63 @@
+import { type NodeSelector } from './nodeSelector';
+import type { RegistryPropValue } from './registry';
+import type { NodeModel, PageModel } from './store';
+export interface ScreenDimensionOption {
+    label: string;
+    props: Readonly<Record<string, RegistryPropValue>>;
+}
+export interface ScreenDimensionDef {
+    id: string;
+    label: string;
+    /** Registry adapter that renders every state of this piece. */
+    component: string;
+    /** Enum axis: an existing registry prop (options come from the registry). */
+    prop?: string;
+    /** Dictionary axis: named cases mapped onto adapter props. */
+    options?: readonly ScreenDimensionOption[];
+    /**
+     * Raw-node matcher: the captured stand-in this dimension adopts. Class
+     * matching uses the css-module prefix (`_bar_`), which survives hash
+     * churn; testId matches `data-testid`.
+     */
+    match: NodeSelector;
+    /** Product source the branch scanner validates this declaration against. */
+    sourcePath?: string;
+}
+/** Panel controls a single declaration may open. */
+export declare const MAX_DIMENSION_MATCHES = 24;
+export interface ScreenDimensionDiagnostic {
+    severity: 'error' | 'warning';
+    dimensionId: string;
+    message: string;
+}
+/** One discovered branch from the node-side component scanner. */
+export interface ComponentBranch {
+    kind: 'conditional' | 'enum';
+    condition: string;
+    element?: string;
+    renders?: string;
+    values?: readonly string[];
+    line?: number;
+}
+/**
+ * Validates dimension declarations against the registry and the component
+ * branch scans: the adapter and its axis must exist, and every dictionary
+ * option should correspond to a branch discovered in the declared source.
+ */
+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[];
+export declare function nodeMatchesDimension(node: NodeModel, dimension: ScreenDimensionDef): boolean;
+/** Every matching node in document order (adopted instances included). */
+export declare function findDimensionNodes(page: PageModel, dimension: ScreenDimensionDef): NodeModel[];
+/** First matching node (adopted adapter instance or raw captured stand-in). */
+export declare function findDimensionNode(page: PageModel, dimension: ScreenDimensionDef): NodeModel | null;
+/** Props payload for a chosen dimension value. */
+export declare function dimensionPropsForValue(dimension: ScreenDimensionDef, value: string): Readonly<Record<string, RegistryPropValue>> | null;
+/** Current value of a dimension on a node, or null for the captured state. */
+export declare function dimensionValueOfNode(dimension: ScreenDimensionDef, node: NodeModel): string | null;
+export declare function setScreenDimensions(dimensions: readonly ScreenDimensionDef[]): void;
+export declare function getScreenDimensions(): readonly ScreenDimensionDef[];

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

@@ -0,0 +1,47 @@
+import type { DesignScreenInteraction, StoryboardEnvironment } from './designImport';
+export interface ScreenFlowWaypoint {
+    /** Catalog id of the screen this waypoint materializes (importPageId). */
+    screenId: string;
+    /**
+     * The walk delta: interactions leading from the previous waypoint (or the
+     * boot, for the first waypoint) to this screen's state.
+     */
+    steps?: readonly DesignScreenInteraction[];
+}
+export interface ScreenFlowPath {
+    id: string;
+    /** Route the instance boots on. */
+    route: string;
+    /**
+     * Declarative browser environment of the whole instance, merged over the
+     * storyboard baseline. Branch paths (error states, special fixtures)
+     * declare their overrides here and pay their own boot.
+     */
+    environment?: StoryboardEnvironment;
+    waypoints: readonly ScreenFlowWaypoint[];
+}
+export interface ScreenFlowDiagnostic {
+    severity: 'error' | 'warning';
+    pathId: string;
+    message: string;
+}
+/**
+ * Structural validation of host-declared flow paths against the screen
+ * catalog. Errors mark paths the runner will refuse; warnings surface
+ * declarations that will behave surprisingly but still run.
+ */
+export declare function validateScreenFlows(paths: readonly ScreenFlowPath[], screens: readonly {
+    id: string;
+}[]): ScreenFlowDiagnostic[];
+/**
+ * Orders paths for a materialization round: paths that deliver a priority
+ * screen (the active frame, the hovered frame) run first; the declared order
+ * is kept otherwise.
+ */
+export declare function orderFlowPaths<T extends {
+    waypoints: readonly ScreenFlowWaypoint[];
+}>(paths: readonly T[], priorityScreenIds: ReadonlySet<string>): T[];
+export declare function setScreenFlows(paths: readonly ScreenFlowPath[]): void;
+export declare function getScreenFlows(): readonly ScreenFlowPath[];
+/** The path that delivers a screen, or null when no flow claims it. */
+export declare function flowPathForScreen(screenId: string): ScreenFlowPath | null;

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

@@ -0,0 +1,4 @@
+import type { DesignScreenInteraction, DesignScreenInteractionReport } from './designImport';
+export declare function settleScreen(iframe: HTMLIFrameElement, settleMs: number): Promise<void>;
+export declare function elementVisible(element: Element): boolean;
+export declare function runScreenInteractions(iframe: HTMLIFrameElement, interactions: readonly DesignScreenInteraction[]): Promise<DesignScreenInteractionReport>;

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

@@ -0,0 +1,40 @@
+import { type NodeSelector } from './nodeSelector';
+import type { NodeModel, PageModel } from './store';
+export interface ScreenListDef {
+    id: string;
+    label: string;
+    /** The repeating list's own element. */
+    container: NodeSelector;
+    /** One repeated row inside it. */
+    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;
+}
+/** Range a list offers when the declaration leaves it open. */
+export declare const SCREEN_LIST_DEFAULT_MIN = 0;
+export declare const SCREEN_LIST_DEFAULT_MAX = 12;
+export declare function validateScreenLists(defs: readonly ScreenListDef[]): ScreenListDiagnostic[];
+export declare function findScreenListContainer(page: PageModel, def: ScreenListDef): NodeModel | null;
+/** Repeated rows inside the container, in document order. */
+export declare function screenListItems(container: NodeModel, def: ScreenListDef): NodeModel[];
+/** Current row count, or null when the screen has no such list. */
+export declare function screenListLength(page: PageModel, def: ScreenListDef): number | null;
+export declare function clampScreenListLength(def: ScreenListDef, count: number): number;
+/** Vertical room one row takes from its parent: its own box plus the gap. */
+export declare function rowAdvance(parent: NodeModel, item: NodeModel): number;
+/**
+ * Absorbs a row-count change into the captured geometry. Pinned heights
+ * between the rows and the scroll boundary take the delta; the boundary and
+ * everything above keep the size the product gave them, and the boundary
+ * gains a scrollbar exactly while its content overflows.
+ */
+export declare function applyListHeightDelta(root: NodeModel, itemParent: NodeModel, delta: number): void;
+export declare function setScreenLists(defs: readonly ScreenListDef[]): void;
+export declare function getScreenLists(): readonly ScreenListDef[];

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

@@ -0,0 +1,36 @@
+/**
+ * Screen-state group declarations are host-owned: the host names which frames
+ * belong to a scenario (the capture pipeline proposes, the declaration on the
+ * page decides), and the core never infers membership from names, routes, or
+ * layout proximity. What the core CAN do is hold the declaration to the
+ * contract the Screen states panel actually enforces — same canvas, one frame
+ * per state label, a shared viewport, at least one sibling to flip to. A
+ * declaration that breaks the contract does not error at runtime; it just
+ * silently renders a confusing panel (or none at all), so validation surfaces
+ * those mismatches as diagnostics the host can fix at declaration time.
+ */
+/** 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 every declared screen-state group among the given pages. Only
+ * pages that actually declare membership participate: a page without a
+ * scenario has made no claim, and a page without a route is not a captured
+ * screen (mirrors the FrameScreenStates gate). Diagnostics come back with
+ * warnings before infos, then ordered by scenario, so the first entry is
+ * always the most actionable one.
+ */
+export declare function validateScreenStateGroups(pages: readonly ScreenStateGroupInput[]): ScreenStateGroupDiagnostic[];

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

@@ -0,0 +1,20 @@
+/**
+ * Display-resolution cache for frame screenshots. Captures are taken above
+ * 1:1 so zoomed frames stay sharp, but an overview showing every frame keeps
+ * the full decoded bitmaps resident — gigabytes for a large storyboard, and
+ * the canvas pans like it is buffering. When the camera draws below one
+ * device pixel per CSS pixel, frames display a CSS-resolution downscale
+ * generated here once per screenshot and cached as an object URL.
+ *
+ * Generation is best-effort: environments without OffscreenCanvas (server
+ * rendering, test realms) simply keep the native bitmap.
+ */
+export declare function subscribeScreenshotBitmaps(listener: () => void): () => void;
+/**
+ * The CSS-resolution URL for a screenshot, or null while it generates (or
+ * when it cannot be generated) — callers fall back to the native bitmap.
+ * `width`/`height` are the frame's CSS dimensions.
+ */
+export declare function getDownscaledScreenshotUrl(key: string, dataUrl: string, width: number, height: number): string | null;
+/** Test seam: forget cached and failed entries (object URLs are revoked). */
+export declare function __resetScreenshotBitmapsForTest(): void;