@pygmalionjs/pygmalion 0.7.4 → 0.8.0

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

@@ -1,6 +1,6 @@
-import type { EditorStore } from '../editor/store';
-import type { HostBindings, HostCallbacks } from './hostBindings';
-import type { EditorRuntime } from './runtime';
+import type { EditorStore } from '../editor/store.js';
+import type { HostBindings, HostCallbacks } from './hostBindings.js';
+import type { EditorRuntime } from './runtime.js';
 export declare const EditorRuntimeContext: import("react").Context<EditorRuntime | null>;
 export declare function useEditorRuntime(): EditorRuntime;
 export declare function useEditorStore(): EditorStore;

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

@@ -0,0 +1,67 @@
+import { type CaptureSupply } from '../editor/captureSupply.js';
+import { type FrameInteraction } from '../editor/frameInteraction.js';
+import { type FrameLodRuntime } from '../editor/frameLodRuntime.js';
+import { type LivePreviewInstances } from '../editor/livePreviewInstances.js';
+import { type LiveScreens } from '../editor/liveScreens.js';
+import { type MountScheduler } from '../editor/mountScheduler.js';
+import type { MountedShadowPreviews } from '../editor/frozenImport.js';
+import { type PreviewIntent } from '../editor/previewIntent.js';
+import { type PreviewSweepChannel } from '../editor/previewSweep.js';
+import { type PreviewCaptureProgress } from '../editor/previewCaptureProgress.js';
+import type { StateSwitchMetrics } from '../editor/stateSwitchMetrics.js';
+import type { InteractiveSessionSurfaces } from '../editor/interactiveSessionSurface.js';
+import { type FlowSessions } from '../editor/flowSessions.js';
+import { type FlowSessionScheduler } from '../editor/flowSessionScheduler.js';
+import { type VariantPrefetch } from '../editor/variantPrefetch.js';
+import type { EditorStore } from '../editor/store.js';
+import type { EditorDeclarations } from '../editor/declarations.js';
+import type { HostBindings } from './hostBindings.js';
+import type { RoutePreviewCache } from '../editor/routePreview.js';
+export interface EditorSchedulers {
+    /** Which frame the designer is inside, and the scroll it carries. */
+    readonly interaction: FrameInteraction;
+    /** Published lifecycle tier and magnification per frame. */
+    readonly frameLod: FrameLodRuntime;
+    /** Which screens hold a live iframe, under the host's budget. */
+    readonly liveScreens: LiveScreens;
+    /** The capture supply mode and the status the canvas probe shows. */
+    readonly captureSupply: CaptureSupply;
+    /** The pool of live application instances frames borrow. */
+    readonly livePreviews: LivePreviewInstances;
+    /** Walk timings and producer decisions, recorded by the previews and the runners. */
+    readonly metrics: StateSwitchMetrics;
+    /** Live documents presenting a screen state, and the direct-state handlers. */
+    readonly surfaces: InteractiveSessionSurfaces;
+    /** The warm pool, the runner factory, and the canonical canvas runner. */
+    readonly sessions: FlowSessions;
+    /** The canvas fill, activation warm, viewport and interactive runners, direct-state paths. */
+    readonly flows: FlowSessionScheduler;
+    /** Speculative walks of the active frame's sibling states. */
+    readonly prefetch: VariantPrefetch;
+    /** The per-animation-frame budget for mounting frozen previews. */
+    readonly mounts: MountScheduler;
+    /** The frozen previews mounted for this editor's pages, by page id. */
+    readonly shadowMounts: MountedShadowPreviews;
+    /** The frames a reader means to see next. */
+    readonly previewIntent: PreviewIntent;
+    /** The canvas sweep status and the sweeper factory. */
+    readonly previewSweep: PreviewSweepChannel;
+    /** Catalog capture progress, published by the canvas probe and read by the host hook. */
+    readonly captureProgress: PreviewCaptureProgress;
+}
+export interface EditorSchedulerDeps {
+    /** Created before the preview cache, which records into it. */
+    metrics: StateSwitchMetrics;
+    /** Created before the store, whose option clicks request through it. */
+    surfaces: InteractiveSessionSurfaces;
+    /** The cache runners publish into. */
+    previews: RoutePreviewCache;
+    /** The store and host the schedulers read pages, origins, and revisions from. */
+    store: EditorStore;
+    host: HostBindings;
+    /** The host declarations the schedulers resolve flows and environments from. */
+    declarations: EditorDeclarations;
+    /** Created before the store, which reads mounted handles from it. */
+    shadowMounts: MountedShadowPreviews;
+}
+export declare function createEditorSchedulers(deps: EditorSchedulerDeps): EditorSchedulers;

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

@@ -1,5 +1,5 @@
-import type { DesignImportAsset, DesignImportKind } from './designImport';
-import type { NodeModel, PageModel } from './store';
+import type { DesignImportAsset, DesignImportKind } from './designImport.js';
+import type { NodeModel, PageModel } from './store.js';
 export interface DesignAssetEditRequest {
     kind: DesignImportKind;
     asset: DesignImportAsset;

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

@@ -1,4 +1,3 @@
-import type { PageModel } from './store';
 export declare const AUTOMATIC_MOTION_METADATA_ATTRIBUTE = "data-pygmalion-auto-motion";
 export declare const AUTOMATIC_MOTION_LEDGER_ATTRIBUTE = "data-pygmalion-auto-motions";
 export declare const MOTION_DECLARATION_ATTRIBUTE = "data-pygmalion-motion";
@@ -8,17 +7,7 @@ export interface AutomaticMotionTarget {
     selector: string;
     index: number;
 }
-export type PreviewMotionMode = 'frozen' | 'playing' | 'paused';
-export interface PreviewMotionState {
-    mode: PreviewMotionMode;
-    targetId?: string;
-    progress: number;
-    seekRevision: number;
-}
-export declare const DEFAULT_PREVIEW_MOTION_STATE: Readonly<PreviewMotionState>;
 /** Discovers every visible rendered element that owns CSS or Web Animation motion. */
 export declare function discoverAutomaticMotionTargets(document: Document): AutomaticMotionTarget[];
 /** Writes discovery metadata onto the parallel serialization clone. */
 export declare function stampAutomaticMotionTargets(source: Document, clone: HTMLElement): AutomaticMotionTarget[];
-/** Reads all automatically stamped motion targets from one imported screen. */
-export declare function automaticMotionTargetsForPage(page: Pick<PageModel, 'root'>): AutomaticMotionTarget[];

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

@@ -1,5 +1,5 @@
-import type { InteractiveStateDef, ScreenStateAxisDef } from './interactiveStates';
-import type { PageModel } from './store';
+import type { InteractiveStateDef, ScreenStateAxisDef } from './interactiveStates.js';
+import type { PageModel } from './store.js';
 export declare const AUTOMATIC_PSEUDO_METADATA_ATTRIBUTE = "data-pygmalion-auto-pseudo";
 export declare const AUTOMATIC_PSEUDO_LEDGER_ATTRIBUTE = "data-pygmalion-auto-pseudos";
 export declare const PSEUDO_EVENT_ATTRIBUTE = "data-pygmalion-pseudo-events";
@@ -19,3 +19,9 @@ export declare function stampAutomaticPseudoTargets(source: Document, clone: HTM
 export declare function automaticPseudoTargetsForPage(page: Pick<PageModel, 'root'>): AutomaticPseudoTarget[];
 /** Synthesizes right-panel axes and suppresses states a host already labels. */
 export declare function automaticPseudoStatesForPage(page: Pick<PageModel, 'root'>, declared?: readonly InteractiveStateDef[]): ScreenStateAxisDef[];
+/**
+ * The discovered target a picked DOM element belongs to: the element itself
+ * or its closest stamped ancestor. Selectors come from serialized markup, so
+ * one the live document cannot parse is skipped rather than thrown.
+ */
+export declare function pseudoTargetForElement(targets: readonly AutomaticPseudoTarget[], element: Element): AutomaticPseudoTarget | undefined;

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

@@ -1,5 +1,5 @@
-import type { RoutePreviewFrameRecipe } from './previewBootstrap';
-import type { RoutePreviewArtifactFrameIdentity, RoutePreviewArtifactResolution } from './routePreview';
+import type { RoutePreviewFrameRecipe } from './previewBootstrap.js';
+import type { RoutePreviewArtifactFrameIdentity, RoutePreviewArtifactResolution } from './routePreview.js';
 /**
  * Who fills a canvas first.
  *
@@ -11,8 +11,6 @@ import type { RoutePreviewArtifactFrameIdentity, RoutePreviewArtifactResolution
  * `auto` picks worker-first when an artifact endpoint is configured.
  */
 export type CaptureSupplyMode = 'worker-first' | 'browser-first';
-export declare function setCaptureSupplyMode(mode: CaptureSupplyMode | 'auto' | undefined): void;
-export declare function resolveCaptureSupplyMode(endpointConfigured: boolean): CaptureSupplyMode;
 export interface CaptureSupplyFrame {
     pageId: string;
     /** Catalog screen id the capture is stored under. */
@@ -113,6 +111,17 @@ export interface CaptureSupplyDriver {
     cancel(): void;
     status(): CaptureSupplyStatus;
 }
-export declare function getCaptureSupplyStatus(): CaptureSupplyStatus;
-export declare function subscribeCaptureSupply(listener: () => void): () => void;
-export declare function createCaptureSupplyDriver(deps: CaptureSupplyDriverDeps, options?: CaptureSupplyDriverOptions): CaptureSupplyDriver;
+/**
+ * The capture supply of one editor runtime: the host's mode choice and the
+ * status channel its drivers publish on. Lives on
+ * `runtime.schedulers.captureSupply`, so two editors on one page never
+ * share a listener set or a mode.
+ */
+export declare function createCaptureSupply(): {
+    setCaptureSupplyMode: (mode: CaptureSupplyMode | "auto" | undefined) => void;
+    resolveCaptureSupplyMode: (endpointConfigured: boolean) => CaptureSupplyMode;
+    getCaptureSupplyStatus: () => CaptureSupplyStatus;
+    subscribeCaptureSupply: (listener: () => void) => () => void;
+    createCaptureSupplyDriver: (deps: CaptureSupplyDriverDeps, options?: CaptureSupplyDriverOptions) => CaptureSupplyDriver;
+};
+export type CaptureSupply = ReturnType<typeof createCaptureSupply>;

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

@@ -1,6 +1,6 @@
 import { type CSSProperties, type ReactNode } from 'react';
-import type { DesignImportCollection } from './designImport';
-import type { ComponentRegistry, RegistryEntry, RegistryPropValue } from './registry';
+import type { DesignImportCollection } from './designImport.js';
+import type { ComponentRegistry, RegistryEntry, RegistryPropValue } from './registry.js';
 export type DesignCatalogKind = 'icons' | 'design-tokens' | 'atoms' | 'components';
 export interface DesignCatalogItem {
     id: string;

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

@@ -1,4 +1,7 @@
-import type { NodeJSON, NodeModel } from './store';
+import type { EditorDeclarations } from './declarations.js';
+/** What code generation reads from the editor's declarations. */
+export type CodegenDeclarations = Pick<EditorDeclarations, 'getRegistry' | 'getDesignComponentConnectionForComponent'>;
+import type { NodeJSON, NodeModel } from './store.js';
 export type CodegenNode = NodeModel | NodeJSON;
 export interface CodegenFrameOptions {
     fill?: string;
@@ -6,6 +9,6 @@ export interface CodegenFrameOptions {
     radius?: number;
     clipContent?: boolean;
 }
-export declare function codegen(node: CodegenNode, indent?: number): string;
+export declare function codegen(declarations: CodegenDeclarations, node: CodegenNode, indent?: number): string;
 /** Generates the built-in target and keeps the historical string API stable. */
-export declare function codegenDocument(root: CodegenNode, frame?: CodegenFrameOptions): string;
+export declare function codegenDocument(declarations: CodegenDeclarations, root: CodegenNode, frame?: CodegenFrameOptions): string;

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

@@ -1,3 +1,4 @@
+import type { Registry } from './registry.js';
 export type DesignConnectionPropertyKind = 'text' | 'boolean' | 'variant' | 'instance' | 'slot';
 export interface DesignComponentReference {
     /** External design system name. Use "figma" for a Figma library. */
@@ -53,11 +54,15 @@ export interface DesignComponentConnectionCases {
     } | null;
     diagnostics: readonly DesignConnectionDiagnostic[];
 }
-export declare function setDesignComponentConnections(next: readonly DesignComponentConnectionDef[]): void;
-export declare function getDesignComponentConnections(): readonly DesignComponentConnectionDef[];
-export declare function getDesignComponentConnection(connectionId: string): DesignComponentConnectionDef | undefined;
-export declare function getDesignComponentConnectionForComponent(componentName: string): DesignComponentConnectionDef | undefined;
-export declare function validateDesignComponentConnections(): readonly DesignConnectionDiagnostic[];
-export declare function enumerateDesignComponentConnectionCases(connectionId: string, options?: {
-    limit?: number;
-}): DesignComponentConnectionCases;
+/** One editor's component connections, validated against its registry. */
+export declare function createComponentConnections(deps: Pick<Registry, 'getRegistry'>): {
+    setDesignComponentConnections: (next: readonly DesignComponentConnectionDef[]) => void;
+    getDesignComponentConnections: () => readonly DesignComponentConnectionDef[];
+    getDesignComponentConnection: (connectionId: string) => DesignComponentConnectionDef | undefined;
+    getDesignComponentConnectionForComponent: (componentName: string) => DesignComponentConnectionDef | undefined;
+    validateDesignComponentConnections: () => readonly DesignConnectionDiagnostic[];
+    enumerateDesignComponentConnectionCases: (connectionId: string, options?: {
+        limit?: number;
+    }) => DesignComponentConnectionCases;
+};
+export type ComponentConnections = ReturnType<typeof createComponentConnections>;

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

@@ -1,5 +1,5 @@
-import type { ComponentRegistry, RegistryEntry, RegistryPropValue } from './registry';
-import type { NodeModel, PageModel } from './store';
+import type { ComponentRegistry, RegistryEntry, RegistryPropValue } from './registry.js';
+import type { NodeModel, PageModel } from './store.js';
 /** One controllable component instance found in a page tree. */
 export interface ComponentInstanceSummary {
     nodeId: string;

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

@@ -0,0 +1,107 @@
+export declare function createEditorDeclarations(): {
+    setPreviewDependencyDigests: (routes: readonly {
+        path?: string;
+        dependencyDigest?: string;
+    }[] | null) => void;
+    previewDependencyDigest: (route: string) => string | undefined;
+    routePreviewFrameRecipe: (page: import("./previewBootstrap.js").PreviewFramePage, baselineEnvironment?: import("./designImport.js").StoryboardEnvironment) => import("./previewBootstrap.js").RoutePreviewFrameRecipe;
+    createRoutePreviewFrameFingerprint: (page: import("./previewBootstrap.js").PreviewFramePage, previewRevision: string, baselineEnvironment?: import("./designImport.js").StoryboardEnvironment) => string;
+    setDesignImportController: (controller: import("./designImport.js").DesignImportController | null) => void;
+    getDesignImportController: () => import("./designImport.js").DesignImportController | null;
+    setSurfaceClassifications: (classifications: readonly import("./surfaceDemands.js").SurfaceClassification[] | undefined) => void;
+    getSurfaceClassifications: () => readonly import("./surfaceDemands.js").SurfaceClassification[];
+    setObservedRequests: (frameId: string, requests: readonly import("./surfaceDemands.js").ObservedRequest[]) => void;
+    getObservedRequests: (frameId: string) => readonly import("./surfaceDemands.js").ObservedRequest[];
+    frameSurfaceDemands: (frameId: string, root?: (import("./surfaceDemands.js").ControlNodeLike & {
+        children?: readonly import("./surfaceDemands.js").ControlNodeLike[];
+    }) | null, classifications?: readonly import("./surfaceDemands.js").SurfaceClassification[]) => import("./surfaceDemands.js").FrameSurfaceDemands;
+    setStoryboardGraph: (graph: import("./storyboardGraph.js").StoryboardGraph | null) => void;
+    getStoryboardGraph: () => import("./storyboardGraph.js").StoryboardGraph | null;
+    subscribeStoryboardGraph: (listener: () => void) => () => void;
+    bumpPreviewIdentityEpoch: () => void;
+    getPreviewIdentityEpoch: () => number;
+    setStoryboardBaselineEnvironment: (environment?: import("./designImport.js").StoryboardEnvironment) => void;
+    getStoryboardBaselineEnvironment: () => import("./designImport.js").StoryboardEnvironment | undefined;
+    setPreviewEnvironmentControls: (next: readonly import("./previewEnvironmentControls.js").PreviewEnvironmentControlDef[]) => void;
+    getPreviewEnvironmentControls: () => readonly import("./previewEnvironmentControls.js").PreviewEnvironmentControlDef[];
+    getPreviewEnvironmentControlSelections: () => Readonly<Record<string, string>>;
+    getPreviewEnvironmentControlValue: (controlId: string) => string | undefined;
+    setPreviewEnvironmentControlValue: (controlId: string, value: string) => void;
+    clearPreviewEnvironmentControlValues: () => void;
+    getPreviewEnvironmentOverride: () => import("./designImport.js").StoryboardEnvironment | undefined;
+    subscribePreviewEnvironmentControls: (listener: () => void) => () => void;
+    getPreviewEnvironmentControlRevision: () => number;
+    setSessionPresets: (next: readonly import("./sessionPresets.js").SessionPresetDef[]) => void;
+    getSessionPresets: () => import("./sessionPresets.js").SessionPresetDef[];
+    getSelectedSessionPreset: () => number | null;
+    selectSessionPreset: (index: number | null) => void;
+    subscribeSessionPresets: (listener: () => void) => () => void;
+    isInSelectedSessionPreset: (runtimes: readonly string[] | undefined) => boolean;
+    applyScenarioCoverageClaim: (editor: import("./store.js").EditorStore, claim: import("./scenarioCoverage.js").ScenarioCoverageClaim) => import("./scenarioCoverage.js").ApplyCoverageResult;
+    setScenarioCoverageClaims: (claims: readonly import("./scenarioCoverage.js").ScenarioCoverageClaim[]) => void;
+    getScenarioCoverageClaims: () => readonly import("./scenarioCoverage.js").ScenarioCoverageClaim[];
+    coverageClaimsForScreen: (screenId: string) => readonly import("./scenarioCoverage.js").ScenarioCoverageClaim[];
+    coverageBadgesForComponentProp: (screenId: string, componentName: string, prop: string) => readonly string[];
+    directInteractiveStateAxisForPage: (page: import("./store.js").PageModel, defs?: readonly import("./interactiveStates.js").InteractiveStateDef[]) => import("./interactiveStates.js").InteractiveStateDef | undefined;
+    setScreenStateAxes: (defs: readonly import("./interactiveStates.js").InteractiveStateDef[] | undefined) => void;
+    setInteractiveStates: (defs: readonly import("./interactiveStates.js").InteractiveStateDef[] | undefined) => void;
+    getInteractiveStates: () => readonly import("./interactiveStates.js").InteractiveStateDef[];
+    getScreenStateAxes: () => readonly import("./interactiveStates.js").InteractiveStateDef[];
+    setScreenFlows: (paths: readonly import("./screenFlows.js").ScreenFlowPath[]) => void;
+    getScreenFlows: () => readonly import("./screenFlows.js").ScreenFlowPath[];
+    flowPathForScreen: (screenId: string) => import("./screenFlows.js").ScreenFlowPath | null;
+    setScreenLanes: (lanes: readonly import("./frameLanes.js").ScreenLaneDef[] | undefined) => void;
+    getScreenLanes: () => readonly import("./frameLanes.js").ScreenLaneDef[];
+    lanesForSection: (section: string) => import("./frameLanes.js").ScreenLaneDef[];
+    laneCaptionFor: (section: string, laneId: string) => import("./frameLanes.js").ScreenLaneDef | null;
+    groupByLane: <T extends {
+        lane?: string;
+    }>(section: string, frames: readonly T[]) => {
+        laneId: string;
+        frames: T[];
+    }[];
+    setFrameBranchKinds: (defs: readonly import("./frameLabels.js").FrameBranchKindDef[], labels?: import("./frameLabels.js").FrameLabelLabels) => void;
+    getFrameBranchKinds: () => readonly import("./frameLabels.js").FrameBranchKindDef[];
+    getFrameLabelLabels: () => import("./frameLabels.js").FrameLabelLabels | undefined;
+    frameBranchKindFor: (kind: string) => import("./frameLabels.js").FrameBranchKindDef;
+    setSectionHeaders: (defs: readonly import("./sectionHeaders.js").SectionHeaderDef[], labels?: import("./sectionHeaders.js").SectionHeaderLabels) => void;
+    getSectionHeaders: () => readonly import("./sectionHeaders.js").SectionHeaderDef[];
+    getSectionHeaderLabels: () => import("./sectionHeaders.js").SectionHeaderLabels | undefined;
+    sectionHeaderFor: (section: string) => import("./sectionHeaders.js").SectionHeaderDef | null;
+    setScreenDimensions: (dimensions: readonly import("./screenDimensions.js").ScreenDimensionDef[]) => void;
+    getScreenDimensions: () => readonly import("./screenDimensions.js").ScreenDimensionDef[];
+    setScreenCards: (defs: readonly import("./screenCards.js").ScreenCardDef[]) => void;
+    getScreenCards: () => readonly import("./screenCards.js").ScreenCardDef[];
+    setScreenLists: (defs: readonly import("./screenLists.js").ScreenListDef[]) => void;
+    getScreenLists: () => readonly import("./screenLists.js").ScreenListDef[];
+    setViewportPresets: (next: readonly import("./viewportPresets.js").ViewportPresetDef[]) => void;
+    getViewportPresets: () => import("./viewportPresets.js").ViewportPresetDef[];
+    setDesignComponentConnections: (next: readonly import("./componentConnections.js").DesignComponentConnectionDef[]) => void;
+    getDesignComponentConnections: () => readonly import("./componentConnections.js").DesignComponentConnectionDef[];
+    getDesignComponentConnection: (connectionId: string) => import("./componentConnections.js").DesignComponentConnectionDef | undefined;
+    getDesignComponentConnectionForComponent: (componentName: string) => import("./componentConnections.js").DesignComponentConnectionDef | undefined;
+    validateDesignComponentConnections: () => readonly import("./componentConnections.js").DesignConnectionDiagnostic[];
+    enumerateDesignComponentConnectionCases: (connectionId: string, options?: {
+        limit?: number;
+    }) => import("./componentConnections.js").DesignComponentConnectionCases;
+    setComponentRegistry: (r: import("./registry.js").ComponentRegistry) => void;
+    getRegistry: () => import("./registry.js").ComponentRegistry;
+    setTokens: (t: import("./tokens.js").TokenDef[]) => void;
+    getTokens: () => import("./tokens.js").TokenDef[];
+    setOnTokensChange: (cb: ((changed: {
+        name: string;
+        value: string;
+    }[]) => void) | null) => void;
+    getTokenValue: (name: string) => string;
+    getTokenOverrides: () => {
+        name: string;
+        value: string;
+    }[];
+    replaceTokenOverrides: (next: readonly {
+        name: string;
+        value: string;
+    }[]) => void;
+    applyTokenOverride: (sync: import("./tokens.js").TokenSyncQueue, name: string, value: string) => void;
+    resetTokenOverrides: (sync: import("./tokens.js").TokenSyncQueue) => void;
+};
+export type EditorDeclarations = ReturnType<typeof createEditorDeclarations>;

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

@@ -1,5 +1,6 @@
-import { type CodegenFrameOptions, type CodegenNode } from './codegen';
-import { type NodeJSON } from './store';
+import { type CodegenFrameOptions, type CodegenNode } from './codegen.js';
+import type { EditorDeclarations } from './declarations.js';
+import { type NodeJSON } from './store.js';
 export declare const DESIGN_IR_SCHEMA: "pygmalion.design-ir";
 export declare const DESIGN_IR_VERSION: 1;
 export declare const DESIGN_CODEGEN_PROJECT_SCHEMA: "pygmalion.codegen-project";
@@ -129,6 +130,8 @@ export interface DesignCompileLimits {
 export declare const DEFAULT_DESIGN_COMPILE_LIMITS: Readonly<DesignCompileLimits>;
 export interface DesignCodegenAdapterContext extends DesignCodegenRuntimeContext {
     document: DesignIntermediateDocumentV1;
+    /** The editor's declarations the adapter generates against. */
+    declarations: CompileDeclarations;
 }
 export interface DesignCodegenAdapterOutput {
     code: string;
@@ -199,7 +202,9 @@ export interface DesignCompileResult {
     };
     validation?: DesignCodegenValidationRequest;
 }
-export declare function createDesignIntermediateDocument(root: CodegenNode, frame?: CodegenFrameOptions): DesignIntermediateDocumentV1;
+/** What compilation reads from the editor's declarations. */
+export type CompileDeclarations = Pick<EditorDeclarations, 'getRegistry' | 'getDesignComponentConnectionForComponent' | 'validateDesignComponentConnections'>;
+export declare function createDesignIntermediateDocument(declarations: CompileDeclarations, root: CodegenNode, frame?: CodegenFrameOptions): DesignIntermediateDocumentV1;
 export declare function registerDesignCodegenAdapter(adapter: DesignCodegenAdapter): () => void;
 export declare function getDesignCodegenAdapters(): readonly DesignCodegenAdapter[];
-export declare function compileDesignDocument(root: CodegenNode, options?: DesignCompileOptions): DesignCompileResult;
+export declare function compileDesignDocument(declarations: CompileDeclarations, root: CodegenNode, options?: DesignCompileOptions): DesignCompileResult;

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

@@ -1,13 +1,14 @@
-import { type DomImportOptions, type DomImportResult } from './domImport';
-import { type DocumentChurnEntry, type DocumentStabilityOptions } from './documentStability';
-import type { DesignFrameHeightMode } from './frameHeight';
-import { type ScreenLaneDef } from './frameLanes';
-import type { ComponentRegistry } from './registry';
-import type { TokenDef } from './tokens';
+import { type DomImportOptions, type DomImportResult } from './domImport.js';
+import { type DocumentChurnEntry, type DocumentStabilityOptions } from './documentStability.js';
+import type { DesignFrameHeightMode } from './frameHeight.js';
+import type { ScreenLaneDef } from './frameLanes.js';
+import type { ComponentRegistry } from './registry.js';
+import type { DeclaredScreenRoute } from './surfaceDemands.js';
+import type { TokenDef } from './tokens.js';
 export declare const DESIGN_IMPORT_KINDS: readonly ["icons", "design-tokens", "atoms", "components", "screens"];
 export type DesignImportKind = (typeof DESIGN_IMPORT_KINDS)[number];
 export type DesignFrameSizeMode = 'fixed' | 'content';
-export type { DesignFrameHeightMode } from './frameHeight';
+export type { DesignFrameHeightMode } from './frameHeight.js';
 /** Individual assets discovered at source. Connect to which designer sheet it can be viewed using pageId. */
 export interface DesignImportAsset {
     id: string;
@@ -75,8 +76,13 @@ export interface DesignScreenInteractionRunOptions {
      * timer-only wait remain authoritative. Capture replay keeps the default
      * `authored` policy, while an already-visible interactive transition can use
      * `target-driven` and let the final stability pass protect serialization.
+     * `live` prepares a screen that is about to be shown running: authored
+     * settles are replaced by one short pause after each action, matched waits
+     * synchronize on their target, and a timer-only wait is capped. The screen
+     * arrives as soon as its recipe has been reproduced; a capture taken from
+     * it afterwards must run the stability pass itself.
      */
-    settlePolicy?: 'authored' | 'target-driven';
+    settlePolicy?: 'authored' | 'target-driven' | 'live';
     /** Called after boot presets succeed and immediately before actions begin. */
     onBeforeInteractions?: () => void;
     /**
@@ -294,7 +300,13 @@ export interface DesignScreenCase extends DesignImportPage {
     scenarioIds?: readonly string[];
     sourcePath?: string;
     codeName?: string;
-    /** The code route that this visual state represents. Used when reproducing the route guard state with a component fixture. */
+    /**
+     * Source routes this visual state explicitly represents, by the discovered
+     * route's id or its path. A case that renders a registered component
+     * (`componentName`) covers a guarded or dynamic route this way without a
+     * navigation URL; a case booted at one concrete `route` claims the dynamic
+     * pattern it instantiates. `auditRouteCoverage` reads them.
+     */
     coverageRoutes?: readonly string[];
 }
 /** Operational scenarios such as network, storage, bridge, etc. without separate visual state. */
@@ -311,7 +323,16 @@ export interface DesignScenarioCoverage {
 }
 export interface DesignScreenCollectionResult {
     collection: DesignImportCollection;
+    /** Scenario classification only: every supplied scenario, exactly once. */
     coverage: DesignScenarioCoverage;
+    /**
+     * What each case said about source routes, kept beside the pages the
+     * collection strips it from: `id`, the canonical `route`, `componentName`,
+     * and `coverageRoutes`. Hand it to `auditRouteCoverage` as
+     * `declaredScreens` to check the discovered route inventory against the
+     * same declarations the editor will show.
+     */
+    routeMappings: readonly DeclaredScreenRoute[];
 }
 /** A portable viewport variant used to render the same authored screen recipe responsively. */
 export interface DesignScreenViewport {
@@ -506,6 +527,12 @@ export interface DesignImportController {
     /** Reproduces and verifies state without waiting for capture-only stability. */
     prepareScreenState?(iframe: HTMLIFrameElement, spec: DesignScreenCaptureSpec, options?: DesignScreenInteractionRunOptions): Promise<DesignScreenCaptureReport>;
     prepareScreenCapture(iframe: HTMLIFrameElement, spec: DesignScreenCaptureSpec): Promise<DesignScreenCaptureReport>;
+    /**
+     * The capture-only stability pass on its own, for a caller that showed the
+     * screen before freezing it. Resolves false when the document never settled
+     * within the ceiling.
+     */
+    waitForStableDocument?(document: Document): Promise<boolean>;
 }
 /**
  * Which canvas a screen belongs to.
@@ -526,7 +553,7 @@ export interface DesignImportController {
 export declare function screensCanvasName(page: {
     section?: string;
     lane?: string;
-}, partition: CreateDesignImportOptions['screensCanvasPartition'], lanes?: readonly ScreenLaneDef[]): string;
+}, partition: CreateDesignImportOptions['screensCanvasPartition'], lanes?: readonly ScreenLaneDef[], resolveLane?: (section: string, laneId: string) => ScreenLaneDef | null): string;
 export interface CreateDesignImportOptions {
     /** Default budget for full layer mode. The host can explicitly increase it according to the screen size. */
     layerOptions?: DomImportOptions;
@@ -549,6 +576,11 @@ export interface CreateDesignImportOptions {
      * canvas named at that moment cannot wait for a later registration.
      */
     screenLanes?: readonly ScreenLaneDef[];
+    /**
+     * Fallback lane lookup for a host that registers lanes on the editor rather
+     * than passing them here; typically `runtime.declarations.laneCaptionFor`.
+     */
+    resolveScreenLane?: (section: string, laneId: string) => ScreenLaneDef | null;
     /**
      * What the editor's own capture treats as movement, and how long it waits for
      * the screen to stop. The Playwright capture answers the same question with
@@ -582,5 +614,9 @@ export declare function createDesignScreenCollection({ cases, scenarios, behavio
 /** Host basic environment + override for each case. Objects are recursively merged and arrays/primitives are replaced by cases. */
 export declare function mergeScreenPresets(defaults?: DesignScreenPreset, override?: DesignScreenPreset): DesignScreenPreset;
 export declare function createDesignImportController(manifest: DesignImportManifest, options?: CreateDesignImportOptions): DesignImportController;
-export declare function setDesignImportController(controller: DesignImportController | null): void;
-export declare function getDesignImportController(): DesignImportController | null;
+/** The design import controller the host installed for one editor. */
+export declare function createDesignImportRegistry(): {
+    setDesignImportController: (controller: DesignImportController | null) => void;
+    getDesignImportController: () => DesignImportController | null;
+};
+export type DesignImportRegistry = ReturnType<typeof createDesignImportRegistry>;

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

@@ -1,5 +1,6 @@
-import { getOnDesignChange } from './host';
-import type { EditorStore } from './store';
+import type { DesignChangeHandler } from '../core/hostBindings.js';
+import type { EditorDeclarations } from './declarations.js';
+import type { EditorStore } from './store.js';
 type SyncStatus = 'idle' | 'saving' | 'saved' | 'error';
 declare class DesignSyncState {
     status: SyncStatus;
@@ -9,34 +10,36 @@ declare class DesignSyncState {
     setPending(pending: number): void;
     setStatus(status: SyncStatus, message: string): void;
 }
-/** General purpose status to show code autosave status in right panel. */
-export declare const designSyncState: DesignSyncState;
 export interface DocumentSyncOptions {
     /** Exact checkout identity attached to every batch from this session. */
     sourceRevision?: string;
     /** Pin this session to its host callback instead of reading a later one. */
-    onDesignChange?: NonNullable<ReturnType<typeof getOnDesignChange>> | null;
+    onDesignChange?: DesignChangeHandler | null;
+}
+/** What document sync reads from the host: the callback a batch is delivered to. */
+export interface DocumentSyncHost {
+    readonly onDesignChange: DesignChangeHandler | null;
+}
+export interface DocumentSyncDeps {
+    host: DocumentSyncHost;
+    /** The declarations code generation reads (registry, connections). */
+    declarations: EditorDeclarations;
 }
 /**
- * Retire every queue, baseline, and in-flight result owned by the old catalog.
- * The host receives an abort signal for cooperative cancellation; even when it
- * ignores that signal, the retired request can no longer mutate this module's
- * new queue or status.
- */
-export declare function resetDocumentSync(): void;
-/**
- * It observes the entire edited document, but only sends the final state of changed elements to the host.
- * Continuous typing/dragging and undo/redo are combined with the same element key, so the save history and edit history are separated.
- */
-export declare function startDocumentSync(editor: EditorStore, options?: DocumentSyncOptions): () => void;
-/** Tokens also use the same element change queue as canvas documents. */
-export declare function queueTokenDesignChange(tokens: {
-    name: string;
-    value: string;
-}[]): void;
-/**
- * Clear all remaining debounce/asynchronous storage just before final reflection.
- * Save failures are propagated to the caller, and any saved pendings are retried on the next flush.
+ * One editor's code autosave: the baseline of syncable documents, the pending
+ * element changes, the debounce timer, the retirement epoch, and the status
+ * the panels show. `host.onDesignChange` is read when a batch is sent unless
+ * `startDocumentSync` pinned a handler. Every runtime owns one.
  */
-export declare function flushDesignChanges(): Promise<void>;
+export declare function createDocumentSync(deps: DocumentSyncDeps): {
+    designSyncState: DesignSyncState;
+    resetDocumentSync: () => void;
+    startDocumentSync: (editor: EditorStore, options?: DocumentSyncOptions) => () => void;
+    queueTokenDesignChange: (tokens: {
+        name: string;
+        value: string;
+    }[]) => void;
+    flushDesignChanges: () => Promise<void>;
+};
+export type DocumentSync = ReturnType<typeof createDocumentSync>;
 export {};

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

@@ -1,5 +1,5 @@
-import type { InstanceHit, InstanceResolver } from './fiberMap';
-import type { NodeJSON } from './store';
+import type { InstanceHit, InstanceResolver } from './fiberMap.js';
+import type { NodeJSON } from './store.js';
 /** Keeps a real 0 — the value that hides hover-only affordances. */
 export declare function clampOpacity(value: string): number;
 /**

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

@@ -1,4 +1,4 @@
-import type { ComponentRegistry, RegistryPropValue } from './registry';
+import type { ComponentRegistry, RegistryPropValue } from './registry.js';
 export interface InstanceHit {
     /** Registry key. */
     name: string;