@pygmalionjs/pygmalion 0.5.14 → 0.5.15

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

@@ -0,0 +1,50 @@
+import type { InspectApplyPayload } from './inspect';
+export interface InspectQaArtifactHash {
+    domStructureHash: string;
+    screenshotHash: string;
+    screenshotUrl?: string;
+}
+export interface InspectQaPixelDimensions {
+    width: number;
+    height: number;
+}
+export interface InspectQaPixelDiff {
+    before: InspectQaPixelDimensions;
+    after: InspectQaPixelDimensions;
+    dimensionsMatch: boolean;
+    changedPixels: number;
+    totalPixels: number;
+    diffRatio: number;
+    threshold: number;
+    heatmapUrl: string | null;
+}
+export interface InspectQaFrameResult {
+    id: string;
+    before: InspectQaArtifactHash;
+    after?: InspectQaArtifactHash;
+    domChanged?: boolean;
+    screenshotChanged?: boolean;
+    pixelDiff?: InspectQaPixelDiff;
+}
+export interface InspectQaFailure {
+    id: string;
+    error: string;
+}
+export interface InspectQaResult {
+    phase: 'baseline' | 'changed';
+    baselineId: string;
+    complete: boolean;
+    frames: InspectQaFrameResult[];
+    failures: InspectQaFailure[];
+}
+export interface InspectQaCaptureRequest {
+    phase: 'baseline' | 'changed';
+    basePath: string;
+    frameIds: string[];
+    baselineId?: string;
+}
+export declare function inspectQaBaseUrl(basePath: string, origin: string): string;
+/** Among all change impact frames calculated by the source graph, only the canonical screen that the host can capture is selected. */
+export declare function inspectQaFrameIds(payload: InspectApplyPayload, eligibleFrameIds?: readonly string[]): string[];
+/** Host Vite middleware strictly normalizes DOM·PNG hashes created with Playwright. */
+export declare function requestInspectQaCapture(fetcher: typeof fetch, endpoint: string, request: InspectQaCaptureRequest): Promise<InspectQaResult>;

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

@@ -0,0 +1,345 @@
+import { type DesignImportController, type DesignImportInitialPage } from './editor/designImport';
+import { type ComponentRegistry } from './editor/registry';
+import { type DesignComponentConnectionDef } from './editor/componentConnections';
+import { type ApplyPayload, type DesignChangePayload, type DesignChangeResult, type InspectApplyResult, type InspectImpactResult, type InspectPreviewResult } from './editor/host';
+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 SurfaceClassification } from './editor/surfaceDemands';
+import { type ScreenDimensionDef } from './editor/screenDimensions';
+import { type FrameBranchKindDef, type FrameLabelLabels } from './editor/frameLabels';
+import { type ScreenCardDef } from './editor/screenCards';
+import { type SectionHeaderDef, type SectionHeaderLabels } from './editor/sectionHeaders';
+import { type ScreenLaneDef } from './editor/frameLanes';
+import { type ScreenListDef } from './editor/screenLists';
+import { type RoutePreviewArtifactBundle } from './editor/routePreview';
+import type { StoryboardDefinition } from './editor/storyboardGraph';
+import { type TokenDef } from './editor/tokens';
+import { type ViewportPresetDef } from './editor/viewportPresets';
+import { type PreviewEnvironmentControlDef } from './editor/previewEnvironmentControls';
+
+export { setComponentRegistry } from './editor/registry';
+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 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';
+export { setTokens, applyTokenOverride, resetTokenOverrides, } from './editor/tokens';
+export { setAppOrigin as setPygmalionAppOrigin } from './editor/host';
+export { setPreviewRevision as setPygmalionPreviewRevision } from './editor/host';
+export { clearRoutePreviewSnapshots as clearPygmalionPreviewCache, recommendedRoutePreviewConcurrency as getRecommendedPygmalionPreviewConcurrency, setRoutePreviewConcurrency as setPygmalionPreviewConcurrency, } from './editor/routePreview';
+export type { RoutePreviewArtifactBundle } from './editor/routePreview';
+export { reconstructRoutePreviewArtifactScreenshotV3, reconstructRoutePreviewArtifactSnapshotV3, validateRoutePreviewArtifactV3Browser, } from './editor/routePreviewArtifactV3';
+export type { RoutePreviewArtifactBundleV3, RoutePreviewArtifactV3Diagnostic, RoutePreviewArtifactV3Frame, RoutePreviewArtifactV3ReconstructedScreenshot, RoutePreviewArtifactV3ScreenshotAsset, RoutePreviewArtifactV3ScreenshotMediaType, RoutePreviewArtifactV3ScreenshotReference, RoutePreviewArtifactV3Status, RoutePreviewArtifactV3ValidationResult, RoutePreviewArtifactV3Viewport, } from './editor/routePreviewArtifactV3';
+export { bootstrapPreviewArtifact, createPreviewArtifactHttpTransport, createPreviewCacheNamespace, createPreviewFrameFingerprint, createPreviewRecipeFingerprint, createStoryboardCaptureRecipeIdentity, resolvePreviewArtifactFrames, validatePreviewArtifactBundle, } from './editor/previewBootstrap';
+export type { PreviewArtifactBootstrapResult, PreviewArtifactExpectation, PreviewArtifactFetch, PreviewArtifactFrameRequest, PreviewArtifactFrameResolution, PreviewArtifactHttpResponse, PreviewArtifactHttpTransportOptions, PreviewArtifactTransport, PreviewArtifactTransportRequest, PreviewArtifactValidationReason, PreviewArtifactValidationResult, PreviewCacheNamespaceOptions, PreviewRecipeIdentity, StoryboardCaptureRecipeInput, } from './editor/previewBootstrap';
+export { validateScreenStateGroups } from './editor/screenStateGroups';
+export type { ScreenStateGroupDiagnostic, ScreenStateGroupInput, } from './editor/screenStateGroups';
+export { validateScreenFlows } from './editor/screenFlows';
+export type { ScreenFlowDiagnostic, ScreenFlowPath, ScreenFlowWaypoint, } from './editor/screenFlows';
+export { applyScenarioCoverageClaim, validateScenarioCoverage, } from './editor/scenarioCoverage';
+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 { validateScreenCards } from './editor/screenCards';
+export type { CardBadgeOption, CardSlotDef, ScreenCardDef, ScreenCardDiagnostic, } from './editor/screenCards';
+export { validateFrameBranchKinds, framesMissingScenario } from './editor/frameLabels';
+export type { FrameBranchKindDef, FrameBranchKindDiagnostic, FrameLabelLabels, } from './editor/frameLabels';
+export { validateSectionHeaders } from './editor/sectionHeaders';
+export type { SectionHeaderDef, SectionHeaderDiagnostic, SectionHeaderFacts, SectionHeaderLabels, } from './editor/sectionHeaders';
+export { validateScreenLanes } from './editor/frameLanes';
+export type { ScreenLaneDef, ScreenLaneDiagnostic } from './editor/frameLanes';
+export { validateScreenLists } from './editor/screenLists';
+export type { ScreenListDef, ScreenListDiagnostic } from './editor/screenLists';
+export type { NodeSelector } from './editor/nodeSelector';
+export { validateScreenDimensions } from './editor/screenDimensions';
+export type { ComponentBranch, ScreenDimensionDef, ScreenDimensionDiagnostic, ScreenDimensionOption, } from './editor/screenDimensions';
+export { createStoryboardPathEdges, createStoryboardGraph, storyboardScreenRecipeKey, } from './editor/storyboardGraph';
+export type { StoryboardDefinition, StoryboardGraph, StoryboardGraphBranch, StoryboardGraphBuildOptions, StoryboardGraphCoverage, StoryboardGraphEdge, StoryboardGraphEdgeInput, StoryboardGraphEdgeOrigin, StoryboardGraphNode, StoryboardGraphSourceGroup, StoryboardGraphWarning, StoryboardGraphWarningCode, StoryboardPathInput, } from './editor/storyboardGraph';
+export { createStoryboardRouteScenarioId, createStoryboardGraphFromDiscovery, getStoryboardDiscoveryBaselineEnvironment, loadStoryboardDiscovery, publishStoryboardDiscovery, resolveStoryboardScreenCases, } from './editor/storyboardDiscovery';
+export type { LoadStoryboardDiscoveryOptions, StoryboardDiscoveryCandidate, StoryboardDiscoveryEdge, StoryboardDiscoveryFetch, StoryboardDiscoveryGraphOptions, StoryboardDiscoveryManifest, StoryboardDiscoveryResponse, StoryboardDiscoveryResult, StoryboardDiscoveryRoute, StoryboardDiscoveryScenario, StoryboardResolvedPage, } from './editor/storyboardDiscovery';
+export { getStoryboardGraph, setStoryboardGraph, subscribeStoryboardGraph, } from './editor/storyboardGraphRuntime';
+export { createStoryboardGraphViewModel } from './editor/storyboardGraphView';
+export type { StoryboardFrameReference, StoryboardGraphCanonicalView, StoryboardGraphFrameView, StoryboardGraphSourceView, StoryboardGraphTransitionView, StoryboardGraphViewModel, } from './editor/storyboardGraphView';
+export { createStoryboardRouteUrl, getStoryboardBaselineEnvironment, mergeStoryboardEnvironment, setStoryboardBaselineEnvironment, STORYBOARD_ENVIRONMENT_CONTROL, STORYBOARD_ENVIRONMENT_QUERY, } from './editor/storyboardEnvironment';
+export type { ApplyPayload, DesignChangePayload, DesignChangeResult, DesignCodeDocument, DesignElementChange, DesignElementDocument, DesignTokenDocument, InspectApplyResult, InspectImpactResult, InspectPreviewResult, } from './editor/host';
+export type { InspectApplyPayload, PrimitiveSourceValue, PrimitiveSourceValueType, SourceAffectedFrame, SourceEditOperation, SourceEditScope, SourceIdentity, SourceInsertComponent, } from './editor/inspect';
+export type { InspectQaArtifactHash, InspectQaCaptureRequest, InspectQaFailure, InspectQaFrameResult, InspectQaPixelDiff, InspectQaPixelDimensions, InspectQaResult, } from './editor/visualQa';
+export { usePygmalionProject } from './editor/projectRuntime';
+export type { PygmalionDesignSessionStatus, PygmalionDevMirrorStatus, PygmalionIntegrationState, PygmalionProjectEndpoints, PygmalionProjectRuntime, PygmalionProjectRuntimeOptions, PygmalionRevertResult, PygmalionSessionOperation, PygmalionSourceRef, PygmalionSourceRefs, PygmalionVisualOperation, PygmalionVisualRevertOperation, } from './editor/projectRuntime';
+export { SourceRefControl } from './ui/SourceRefControl';
+export type { SourceRefControlProps } from './ui/SourceRefControl';
+export type { TokenDef } from './editor/tokens';
+export { getViewportPresets, setViewportPresets, } from './editor/viewportPresets';
+export type { ViewportPresetDef } from './editor/viewportPresets';
+export { clearPreviewEnvironmentControlValues, getPreviewEnvironmentControlValue, getPreviewEnvironmentControls, getPreviewEnvironmentOverride, setPreviewEnvironmentControlValue, setPreviewEnvironmentControls, subscribePreviewEnvironmentControls, } from './editor/previewEnvironmentControls';
+export type { PreviewEnvironmentControlDef, PreviewEnvironmentControlOptionDef, } from './editor/previewEnvironmentControls';
+export { createDesignImportController, createDesignScreenCollection, DESIGN_IMPORT_KINDS, expandDesignScreenCasesViewports, expandDesignScreenCollectionViewports, mergeScreenPresets, } from './editor/designImport';
+export type { CreateDesignImportOptions, DesignBehaviorScenario, DesignImportAsset, DesignImportCollection, DesignImportController, DesignImportCoverage, DesignImportCoverageItem, DesignImportInitialPage, DesignImportKind, DesignImportManifest, DesignImportPage, DesignFrameHeightMode, DesignFrameSizeMode, DesignScenarioCoverage, DesignScenarioSource, DesignScreenCase, DesignScreenAssertion, DesignScreenAssertionReport, DesignScreenAssertionVisibility, DesignScreenAttributeAssertion, DesignScreenCaptureFailure, DesignScreenCaptureFailureCode, DesignScreenCaptureFailureStage, DesignScreenCaptureDefaults, DesignScreenCaptureRequirements, DesignScreenCaptureReport, DesignScreenCaptureSpec, DesignScreenCollectionResult, DesignScreenInteraction, DesignScreenInteractionAction, DesignScreenInteractionReport, DesignScreenPreset, DesignScreenPresetContext, DesignScreenPresetExecutionResult, DesignScreenPresetExecutor, DesignScreenPresetRequest, DesignScreenViewport, DesignScreenViewportExpansionOptions, DesignScreenViewportPagePatch, DesignSerializable, StoryboardEnvironment, StoryboardMediaDevice, StoryboardMediaFailure, StoryboardNetwork, StoryboardPermissionState, StoryboardRequestCondition, StoryboardRequestOutcome, } from './editor/designImport';
+export type { DomImportDiagnostic, DomImportMetrics, DomImportOptions, DomImportResult, } from './editor/domImport';
+export type { SharedSourceEditScope, SharedSourceFrameSummary, SharedSourceImpact, } from './editor/sharedSource';
+export type { NodeJSON } from './editor/store';
+import { getObserverTree, isObservableProp } from 'mobx';
+export declare const __debug: {
+    editor: import("./editor/store").EditorStore;
+    getObserverTree: typeof getObserverTree;
+    isObservableProp: typeof isObservableProp;
+    /** Preview-surface introspection for headless diagnosis of frame surfaces. */
+    preview(frameId: string): Promise<{
+        key: string;
+        hasOutcome: boolean;
+        screenshot: {
+            width: number;
+            height: number;
+        } | null;
+        hasShadowArtifact: boolean;
+        hasSnapshot: boolean;
+        tier: import("./editor/frameLod").FrameLifecycleTier;
+        magnified: boolean;
+        promotion: {
+            mounted: boolean;
+            stamped: boolean | null;
+        };
+        lodState: {
+            tiers: [string, import("./editor/frameLod").FrameLifecycleTier][];
+            magnified: [string, boolean][];
+            lastRecompute: {
+                displayDensity?: number;
+                overview?: boolean;
+                frames?: {
+                    id: string;
+                    screenshotDensity: number | null | undefined;
+                    tier: string;
+                }[];
+            };
+        };
+        readFramesNow: (import("./editor/frameLod").FrameLodFrame & {
+            memoKey?: string;
+        }) | undefined;
+    } | null>;
+    /** Flow-session delivery states for headless diagnosis of the captureless supply. */
+    flowSessions(): Promise<{
+        declaredPaths: number;
+        scheduler: {
+            calls: number;
+            lastCanvas: string;
+            lastFlows: number;
+            lastCandidates: number;
+            lastQueued: number;
+        };
+        states: Record<string, import("./editor/flowSessions").FlowScreenState>;
+        viewport: {
+            commit: {
+                requested: number;
+                resolvedNull: number;
+                controllerMissing: number;
+                markerGone: number;
+                editsWon: number;
+                captureNull: number;
+                committed: number;
+            };
+            states: Record<string, unknown>;
+        };
+        interactive: {
+            requests: {
+                requested: number;
+                noPath: number;
+                resolvedNull: number;
+                queued: number;
+            };
+            states: Record<string, unknown>;
+        };
+        warming: {
+            requested: number;
+            noPath: number;
+            resolvedNull: number;
+            alreadyWarm: number;
+            queued: number;
+        };
+        warm: {
+            bootsByRunner: {
+                [x: string]: number;
+            };
+            parked: number;
+            boots: number;
+            reuses: number;
+            parks: number;
+            evictions: number;
+        };
+    }>;
+};
+/**
+ * Called from the actual button handler of the host screen fixture — Switches to the name matching page (common in editor and preview).
+ * Example: SettingsPage card onSelect: () => pygmalionNavigate('Settings panel')
+ */
+export declare function pygmalionNavigate(pageName: string): void;
+/** Open the prototype preview (▶) in the code — used when the host places its own entry button. */
+export declare function pygmalionOpenPreview(): void;
+/** Discard unapplied canvas and inspection edits created after the latest source load or apply. */
+export declare function pygmalionResetCurrentEdits(): boolean;
+export interface InitialPageDef extends DesignImportInitialPage {
+}
+export declare function PygmalionEditor({ registry, tokens, initialPages, initialCanvas, initialEditMode, componentConnections, viewportPresets, previewEnvironmentControls, designImport, onTokensChange, appOrigin, previewRevision, previewCacheNamespace, previewArtifacts, previewArtifactEndpoint, previewConcurrency, previewOpen, onPreviewOpenChange, flowCanvas, frameSurface, screenFlows, scenarioCoverage, screenDimensions, screenLists, sectionHeaders, sectionHeaderLabels, screenLanes, frameBranchKinds, frameLabelLabels, screenCards, liveScreenBudget, interactiveStates, surfaceClassifications, onApply, onDesignChange, onInspectApply, onInspectPreview, onInspectImpact, storyboard, storyboardDiscovery, storyboardDiscoveryEndpoint, }: {
+    registry?: ComponentRegistry;
+    tokens?: TokenDef[];
+    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'. A host whose editor is a
+     * review surface declares 'view-only' so a reader is not one keystroke from
+     * changing the design; the toggle stays where it is, and the choice applies
+     * once rather than re-asserting over whatever the designer picked.
+     */
+    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. */
+    viewportPresets?: readonly ViewportPresetDef[];
+    /** Host-declared browser conditions shown in the active frame's Preview inspector. */
+    previewEnvironmentControls?: readonly PreviewEnvironmentControlDef[];
+    /** A public importer that provides unified control over code inventory and importing of entire DOM layers. */
+    designImport?: DesignImportController;
+    /** Called with cumulative changes when editing a token in the Assets panel — the host is responsible for writing back (file saving). */
+    onTokensChange?: (changed: {
+        name: string;
+        value: string;
+    }[]) => void;
+    /** The standard origin of the route page iframe ('' if same-origin). */
+    appOrigin?: string;
+    /** Code version as of preview (dev SHA, etc.). Even if the URL is the same, if the value changes, the screen cache is updated. */
+    previewRevision?: string;
+    /** Project/branch boundaries for screen caches that are persistent in the browser. Stable string separate from random dev port. */
+    previewCacheNamespace?: string;
+    /** A canonical screen snapshot created during build. When the namespace matches, it is injected into the cache before the first render. */
+    previewArtifacts?: RoutePreviewArtifactBundle;
+    /** Same-origin endpoint that resolves an exact namespace and source revision, generating it on demand when configured by the Vite plugin. */
+    previewArtifactEndpoint?: string;
+    /** Number of actual app previews to run simultaneously. Defaults to an adaptive 12–32 lanes. */
+    previewConcurrency?: number;
+    /** Controlled by external status such as host route ▶ Whether the preview is opened or not. */
+    previewOpen?: boolean;
+    /** ▶ Called when the preview is opened or closed — allows the host to synchronize URLs. */
+    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, where
+     * a canvas holds a section's worth of frames and every activation is then
+     * promotion-ready without a mount wait.
+     */
+    frameSurface?: 'bitmap' | 'dom';
+    /**
+     * Host-declared flow paths — the captureless surface supply. One hidden
+     * live instance boots per path and walks its waypoints, publishing a
+     * frozen snapshot per screen into the preview store; frames whose screen a
+     * flow claims wait for the delivery instead of booting live themselves.
+     * Screens no flow claims keep the classic artifact/sweep/boot supply.
+     */
+    screenFlows?: readonly ScreenFlowPath[];
+    /**
+     * Host-declared scenario coverage ledger: where each QA scenario is
+     * verified (frame, folded screen state, component toggle, viewport
+     * preset, behavior, todo). The right panel lists a screen's claims as
+     * executable rows and badges component controls with the scenarios they
+     * demonstrate. Validate with validateScenarioCoverage in the host gate.
+     */
+    scenarioCoverage?: readonly ScenarioCoverageClaim[];
+    /**
+     * Host-declared screen dimensions: curated right-panel controls that swap
+     * a captured piece's state (a status bar, a row badge) by adopting the
+     * matched node into a registry adapter. Validate with
+     * validateScreenDimensions against the component-branch scan.
+     */
+    screenDimensions?: readonly ScreenDimensionDef[];
+    /**
+     * Host-declared screen lists: right-panel row-count controls for a
+     * repeating list. Growing clones the list's last row; the per-row
+     * dimension controls are what make the copies differ. Validate with
+     * validateScreenLists.
+     */
+    screenLists?: readonly ScreenListDef[];
+    /**
+     * Host-declared section headers: the band above a section box that says what
+     * the group covers. The core counts the frames, folded variants, scenarios
+     * and viewport itself; the host declares the code, the one-line purpose, the
+     * accent and the category. A section with no declaration keeps its plain
+     * name. Validate with validateSectionHeaders.
+     */
+    sectionHeaders?: readonly SectionHeaderDef[];
+    /** Words for the facts a section header counts. English by default. */
+    sectionHeaderLabels?: SectionHeaderLabels;
+    /**
+     * Host-declared situation lanes: within a section, one lane is one row of
+     * the canvas, read left to right. Packing by area produces a uniform grid
+     * that says nothing, and only the host knows which screens belong to the
+     * same situation. A section with no lanes keeps the area packing.
+     * Validate with validateScreenLanes.
+     */
+    screenLanes?: readonly ScreenLaneDef[];
+    /**
+     * Host-declared presentation of each branch kind a frame label can carry:
+     * the state kinds the catalog declares, plus the core's own `step` and
+     * `variant`. The core decides which kind a frame is and counts its facts;
+     * this says what each kind is called and what colour it reads as. Validate
+     * with validateFrameBranchKinds.
+     */
+    frameBranchKinds?: readonly FrameBranchKindDef[];
+    /** Words for the facts a frame label counts. English by default. */
+    frameLabelLabels?: FrameLabelLabels;
+    /**
+     * Host-declared card compositions: which badges each repeated card may show,
+     * in which slot, and how many at once. Declares the component's anatomy so
+     * the panel offers only combinations the product could render. Validate with
+     * validateScreenCards.
+     */
+    screenCards?: readonly ScreenCardDef[];
+    /**
+     * How many frames may render the running application instead of their
+     * capture. Default 0 — every frame is served from its capture, which is
+     * what keeps a canvas deterministic and quiet. Raise it to keep the
+     * frames a designer is working with interactive; the least recently
+     * activated holder gives its slot back.
+     */
+    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.
+     */
+    interactiveStates?: readonly InteractiveStateDef[];
+    /**
+     * Host verdicts for the surfaces the editor asks about — the routes it can
+     * render, the operable elements of an imported tree, the requests a frame
+     * makes while booting. Each answer either names the declaration that covers
+     * the surface or excludes it with a reason; anything unanswered shows up on
+     * the frame as an unclassified surface instead of quietly not existing.
+     */
+    surfaceClassifications?: readonly SurfaceClassification[];
+    /** 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>;
+    /** A common write-back pathway that automatically saves the final state of all canvas elements in your code. */
+    onDesignChange?: (payload: DesignChangePayload) => Promise<DesignChangeResult | void>;
+    /** Apply inspection edits through the host write-back endpoint. */
+    onInspectApply?: (payload: InspectApplyPayload) => Promise<InspectApplyResult | void>;
+    /** Generate a source diff before apply. When connected, apply is blocked until review. */
+    onInspectPreview?: (payload: InspectApplyPayload) => Promise<InspectPreviewResult>;
+    /** Calculate the impact screen by querying the inverse dependency closure of the changed file. */
+    onInspectImpact?: (componentFiles: string[]) => Promise<InspectImpactResult>;
+    /** Authored screen paths and starts merged with source-discovered navigation. */
+    storyboard?: StoryboardDefinition;
+    /** Detect portable browser branches from source before route frames boot. Default true. */
+    storyboardDiscovery?: boolean;
+    /** Vite endpoint that returns the generated generic storyboard environment manifest. */
+    storyboardDiscoveryEndpoint?: string;
+}): import("react").JSX.Element;

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

@@ -0,0 +1 @@
+export declare const ApplyPanel: import("react").FunctionComponent<object>;

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

@@ -0,0 +1,3 @@
+export declare function AssetsPanel({ onFrameFocus, }: {
+    onFrameFocus?: (id: string) => void;
+}): import("react").JSX.Element;

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

@@ -0,0 +1,5 @@
+export declare function CanvasStatusProbe({ previewIdentityReady, previewCacheHydrated, previewCacheKeys, }: {
+    previewIdentityReady: boolean;
+    previewCacheHydrated: boolean;
+    previewCacheKeys: readonly string[];
+}): import("react").JSX.Element;

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

@@ -0,0 +1 @@
+export declare const CodePanel: import("react").FunctionComponent<object>;

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

@@ -0,0 +1,108 @@
+import { type ReactNode } from 'react';
+import { sourceWritableRegistryProps } from '../editor/componentInstances';
+import type { RegistryEntry, RegistryPropValue } from '../editor/registry';
+import { type NodeModel, type PageModel } from '../editor/store';
+/** Property-panel section frame shared across the shell panels. */
+export declare function Sec({ title, action, children, }: {
+    title: string;
+    action?: ReactNode;
+    children: ReactNode;
+}): import("react").JSX.Element;
+export declare function componentPropValue(node: Pick<NodeModel, 'componentProps'>, key: string, options: readonly RegistryPropValue[], defaultValue: RegistryPropValue | undefined): RegistryPropValue | undefined;
+export declare function componentPropLabel(value: RegistryPropValue): string;
+/**
+ * Typed prop controls for one component instance. `sourceWritableProps`
+ * enables the per-prop "preview only" badge for imported instances whose
+ * prop is expression-bound; pass null for catalog nodes, which are
+ * themselves the source.
+ */
+export declare function ComponentPropControls({ node, entry, sourceWritableProps, propBadges, onPatch, }: {
+    node: Pick<NodeModel, 'componentProps'>;
+    entry: RegistryEntry;
+    sourceWritableProps?: readonly string[] | null;
+    /** Scenario ids each prop demonstrates — rendered as chips beside the control. */
+    propBadges?: Readonly<Record<string, readonly string[]>>;
+    onPatch: (prop: string, value: RegistryPropValue) => void;
+}): import("react").JSX.Element;
+/**
+ * State variants of the active screen — a modal that may cover it, a
+ * permission badge, an alternate panel layout. They live as sibling frames
+ * (each is its own verified capture), but the designer flips between them
+ * here instead of hunting the canvas; selection activates the sibling and
+ * swaps it into the group's canvas slot.
+ *
+ * A pair of base + one declared branch reads as an On/Off toggle; larger
+ * groups list their states as a radio. `stateKind` tags the control with the
+ * branch's category when the host declares one.
+ */
+export declare const FrameScreenStates: import("react").FunctionComponent<{
+    page: PageModel;
+}>;
+/**
+ * QA scenarios the active screen verifies, as executable rows: clicking a
+ * claim reproduces the exact reviewed state (frame activation, state reveal,
+ * prop flip, or preset resize). The ledger is host-declared and core-
+ * validated, so a renamed component or retired preset fails the gate instead
+ * of silently orphaning the scenario.
+ */
+export declare const FrameScenarioCoverage: import("react").FunctionComponent<{
+    page: PageModel;
+}>;
+/**
+ * Curated per-screen dimension controls — "swap this piece's state". The
+ * host declares the pieces (status bar states, row badge kinds); the
+ * control adopts the captured stand-in into the adapter and re-props it.
+ * Undo restores the captured node. This axis is for the single piece a
+ * screen shows once; a repeated piece belongs to the card composition axis,
+ * which knows about slots and can hold several badges at once. Below the
+ * controls, branches discovered in the declared source are listed so
+ * undeclared cases stay visible instead of silently unknown.
+ */
+export declare const FrameScreenDimensions: import("react").FunctionComponent<{
+    page: PageModel;
+}>;
+/**
+ * Screen lists — how many rows a repeating list shows. Growing clones the
+ * last row, so the copies start identical and the per-row dimension
+ * controls above are what make them differ. It edits the captured tree, so
+ * it lands instantly and undoes in one step.
+ */
+export declare const FrameScreenLists: import("react").FunctionComponent<{
+    page: PageModel;
+}>;
+/**
+ * Card badges — what each repeated card shows, slot by slot.
+ *
+ * One row per slot per card, because that is the shape of the component: the
+ * identity row and the status slot hold different vocabularies, and a slot
+ * that can hold several badges gets several independent toggles rather than
+ * a select that can only ever show one.
+ */
+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.
+ */
+export declare const FrameInteractiveStates: import("react").FunctionComponent<{
+    page: PageModel;
+}>;
+/**
+ * Surfaces this frame owes an answer to.
+ *
+ * The axes above are what the host remembered to declare, and for a long time
+ * that was the whole story: an element nobody thought about produced no axis and
+ * no complaint, because the ledger only ever compared declarations with each
+ * other. This section is the other half — the editor lists the operable elements
+ * of the tree it imported and the requests the frame made while booting, and the
+ * host either points each one at a declaration or excludes it with a reason.
+ *
+ * It renders nothing once every surface has a verdict, so a finished frame stays
+ * quiet and an unfinished one says exactly what is missing.
+ */
+export declare const FrameSurfaceDemands: import("react").FunctionComponent<{
+    page: PageModel;
+}>;
+export { sourceWritableRegistryProps };

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

@@ -0,0 +1 @@
+export declare const ContextMenu: import("react").FunctionComponent<object>;

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

@@ -0,0 +1,7 @@
+import type { StoryboardConnectionMode } from '../canvas/StoryboardConnections';
+export declare const LayerTree: import("react").FunctionComponent<{
+    onFrameFocus?: (id: string) => void;
+    storyboardConnectionMode?: StoryboardConnectionMode;
+    onStoryboardConnectionModeChange?: (mode: StoryboardConnectionMode) => void;
+    storyboardReady?: boolean;
+}>;

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

@@ -0,0 +1 @@
+export declare const PropsPanel: import("react").FunctionComponent<object>;

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

@@ -0,0 +1,23 @@
+import type { StoryboardGraphViewModel } from '../editor/storyboardGraphView';
+import type { StoryboardCompositionModel } from '../editor/storyboardComposition';
+import type { StoryboardConnectionMode } from '../canvas/StoryboardConnections';
+export interface StoryboardGraphPanelProps {
+    model: StoryboardGraphViewModel;
+    onSelectFrame: (frameId: string) => void;
+    activeFrameId?: string | null;
+    connectionMode: StoryboardConnectionMode;
+    onConnectionModeChange: (mode: StoryboardConnectionMode) => void;
+    /**
+     * Structure for a canvas with no routes, where a journey graph has nothing
+     * to say. Present only on catalog canvases.
+     */
+    composition?: StoryboardCompositionModel | null;
+    /** Frame names for composition rows, which carry ids rather than frames. */
+    frameNameById?: ReadonlyMap<string, string>;
+}
+/**
+ * Generic navigation and coverage surface for a project-supplied storyboard
+ * graph. It never interprets domain labels and delegates camera focus to the
+ * editor's existing frame-selection action.
+ */
+export declare function StoryboardGraphPanel({ model, onSelectFrame, activeFrameId, connectionMode, onConnectionModeChange, composition, frameNameById, }: StoryboardGraphPanelProps): import("react").JSX.Element | null;

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

@@ -0,0 +1,4 @@
+/** Zoom percentage cluster in the expanded right panel header. */
+export declare const ZoomIndicator: import("react").FunctionComponent<object>;
+/** Zoom buttons on the compact right-panel rail; their tooltips read the zoom. */
+export declare const CompactZoomControls: import("react").FunctionComponent<object>;

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

@@ -0,0 +1,9 @@
+import type { InspectQaFrameResult, InspectQaResult } from '../editor/visualQa';
+export interface InspectQaSummary {
+    capturedFrames: number;
+    failedFrames: number;
+    changedFrames: number;
+    changedPixels: number;
+}
+export declare function summarizeInspectQa(qa: InspectQaResult): InspectQaSummary;
+export declare function inspectQaFrameChangeLabel(frame: InspectQaFrameResult): string;

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

@@ -0,0 +1,8 @@
+/**
+ * Package-level integration test surface.
+ * Host repositories can verify frozen preview behavior without importing this
+ * repository's source tree or depending on private internal file paths.
+ */
+export { FrozenRoutePreviewView } from './canvas/FrozenRoutePreview';
+export { NodeModel, editor, serializeNode } from './editor/store';
+export { setComponentRegistry } from './editor/registry';

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

@@ -0,0 +1,38 @@
+import { type ReactNode } from 'react';
+import type { PygmalionSourceRef } from '../editor/projectRuntime';
+export interface SourceRefControlProps {
+    /** Revision the mirror follows now. */
+    value: string | null;
+    /** Commit currently rendered by the mirror. Used to expose a newer ref tip. */
+    currentCommit?: string | null;
+    /** Revisions the mirror can be repointed at. */
+    refs: readonly PygmalionSourceRef[];
+    onChange(ref: string): void;
+    /** Blocks selection while the mirror rebuilds. */
+    busy?: boolean;
+    /** Revision used when none is pinned, offered as the first entry. */
+    defaultRef?: string | null;
+    /** Ref that renders uncommitted work. Omitted from the list when absent. */
+    worktreeRef?: string | null;
+    /** Accessible name for the control. */
+    label?: string;
+    /** Menu label for reloading the selected revision after its tip moves. */
+    refreshLabel?: string;
+    /**
+     * Trigger content. A host renders its own status chip here, so the control
+     * blends into an existing toolbar instead of adding a second field.
+     * Defaults to the selected revision.
+     */
+    children?: ReactNode;
+    className?: string;
+}
+/**
+ * Selects the revision the dev mirror follows. Switching rebuilds the mirror,
+ * screen inventory, and preview on that revision, so the editor reloads.
+ *
+ * The menu is a native select layered over the trigger: the host owns how the
+ * trigger looks, while keyboard access, mobile behavior, and menu placement stay
+ * with the platform. Pygmalion owns this control because the mirror lifecycle
+ * belongs to the tool, not to a consuming application.
+ */
+export declare function SourceRefControl({ value, currentCommit, refs, onChange, busy, defaultRef, worktreeRef, label, refreshLabel, children, className, }: SourceRefControlProps): import("react").JSX.Element;