@pygmalionjs/pygmalion 0.7.4 → 0.8.1

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

@@ -1,22 +1,24 @@
-import { type PreviewMotionState } from './automaticMotion';
-import { type InteractiveStateDef } from './interactiveStates';
-import { type ScreenDimensionDef } from './screenDimensions';
-import { type CardBadgeOption, type CardSlotDef, type ScreenCardDef } from './screenCards';
-import { type ScreenListDef } from './screenLists';
-import { type DesignImportAsset, type DesignImportInitialPage, type DesignImportKind, type DesignFrameSizeMode, type DesignScreenAssertion, type DesignScreenDesiredState, type DesignScreenInteraction, type DesignScreenPreset, type StoryboardEnvironment } from './designImport';
-import { type DomImportDiagnostic, type DomImportResult } from './domImport';
-import { type LayerImportFidelityReport, type MeasurableElement } from './importFidelity';
-import { type DesignFrameHeightMode } from './frameHeight';
-import { type RegistryPropValue } from './registry';
-import { type PrimitiveSourceValue } from './inspect';
-import { type SourceJournalSnapshot } from './sourceJournal';
-import { type SharedSourceEditScope, type SharedSourceImpact } from './sharedSource';
-import { type DesignAssetEditRequest } from './assetEditing';
+import { type InteractiveStateDef } from './interactiveStates.js';
+import { type ScreenDimensionDef } from './screenDimensions.js';
+import { type CardBadgeOption, type CardSlotDef, type ScreenCardDef } from './screenCards.js';
+import { type ScreenListDef } from './screenLists.js';
+import { type DesignImportAsset, type DesignImportInitialPage, type DesignImportKind, type DesignFrameSizeMode, type DesignScreenAssertion, type DesignScreenDesiredState, type DesignScreenInteraction, type DesignScreenPreset, type StoryboardEnvironment } from './designImport.js';
+import { type DomImportDiagnostic, type DomImportResult } from './domImport.js';
+import { type LayerImportFidelityReport, type MeasurableElement } from './importFidelity.js';
+import { type InteractiveSessionSurfaces } from './interactiveSessionSurface.js';
+import { type EditorDeclarations } from './declarations.js';
+import { type MountedShadowPreviews } from './frozenImport.js';
+import { type DesignFrameHeightMode } from './frameHeight.js';
+import type { RegistryPropValue } from './registry.js';
+import { type PrimitiveSourceValue } from './inspect.js';
+import { type SourceJournalSnapshot } from './sourceJournal.js';
+import { type SharedSourceEditScope, type SharedSourceImpact } from './sharedSource.js';
+import { type DesignAssetEditRequest } from './assetEditing.js';
 export type NodeType = 'rows' | 'columns' | 'text' | 'component';
 /** Autolayout container type (with direction, gap, and alignment). */
 export declare const isContainerType: (t: NodeType) => t is "rows" | "columns";
 /** Can contain child nodes — container + children:'nodes' components (Card, etc.). */
-export declare const canHaveChildren: (n: NodeModel) => boolean;
+export declare const canHaveChildren: (declarations: Pick<EditorDeclarations, "getRegistry">, n: NodeModel) => boolean;
 export type SizeMode = 'fill' | 'fit' | 'fixed';
 export type TextAlign = 'left' | 'center' | 'right';
 export type JustifyMode = 'start' | 'center' | 'end' | 'between';
@@ -135,6 +137,11 @@ export interface DropHint {
         height: number;
     };
 }
+/**
+ * A live boot that has reported nothing for this long no longer blocks the
+ * standby queue: a document that failed to load must not stall every sibling.
+ */
+export declare const LIVE_ROUTE_BOOT_STALE_MS = 20000;
 export interface PageModel {
     /** Frame size (px). Default 390×600 (mobile). */
     width?: number;
@@ -349,9 +356,30 @@ export interface EditorStoreHost {
     readonly flowCanvas: string;
     readonly onPreviewOpenChange: ((open: boolean) => void) | null;
 }
+/**
+ * What the store needs from its runtime's interactive-session surfaces: the
+ * direct-state requests an option click starts, and the release of a slot a
+ * state no longer presents. A store created on its own gets a detached
+ * registry whose requests answer false.
+ */
+export type DirectStateSurfaces = Pick<InteractiveSessionSurfaces, 'requestDirectInteractiveState' | 'requestDirectInteractiveStatePreview' | 'clearInteractiveSessionSurface'>;
+/** What a store is built from; a runtime supplies all three, a test what it needs. */
+export interface EditorStoreOptions {
+    host?: EditorStoreHost;
+    surfaces?: DirectStateSurfaces;
+    declarations?: EditorDeclarations;
+    /** The frozen previews mounted for this editor's pages. */
+    shadowMounts?: Pick<MountedShadowPreviews, 'getMountedShadowPreviewHandle'>;
+}
 export declare class EditorStore {
     /** Host bindings this store reads; excluded from MobX so the bindings object stays plain. */
     readonly host: EditorStoreHost;
+    /** The runtime's session surfaces the store's option clicks reach; excluded from MobX. */
+    readonly surfaces: DirectStateSurfaces;
+    /** The runtime's host declarations the store reads; excluded from MobX. */
+    readonly declarations: EditorDeclarations;
+    /** The frozen previews mounted for this editor's pages; excluded from MobX. */
+    readonly shadowMounts: Pick<MountedShadowPreviews, 'getMountedShadowPreviewHandle'>;
     /** Multi-page — each page has an independent tree. */
     pages: PageModel[];
     activePageId: string;
@@ -420,6 +448,40 @@ export declare class EditorStore {
      */
     isInSelectedRuntime(page: PageModel): boolean;
     isScreenStateShown(page: PageModel): boolean;
+    /** The declared state variants of the active frame's group, base first; empty outside a group. */
+    get activeScreenStateGroup(): PageModel[];
+    /**
+     * A folded variant of the active frame's group. Standby frames stay
+     * mounted at the group's slot, hidden, so switching to one is a visibility
+     * change rather than a mount, and their live instances boot ahead of the
+     * switch. Variants of other groups stay folded away entirely.
+     */
+    isScreenStateStandby(page: PageModel): boolean;
+    /**
+     * Live routes booting or preparing right now, by page id, with the time
+     * each began. Standby variants boot one at a time and only while nothing
+     * else is booting, so the frame the designer is looking at settles first.
+     */
+    liveRouteLoadingSince: Map<string, number>;
+    setLiveRouteLoading(pageId: string, loading: boolean): void;
+    /** True when no live route has been booting for less than the stale limit. */
+    liveRouteBootFree(now?: number): boolean;
+    /** Takes the one boot slot for a standby variant; false while another boot runs. */
+    claimLiveRouteBoot(pageId: string, now?: number): boolean;
+    /**
+     * Live reproductions that failed, by page id, with the step or reason. A
+     * frame records its own failure so the panel can name it and offer a
+     * retry; the frame keeps its capture on screen meanwhile.
+     */
+    liveRouteFailures: Map<string, string>;
+    /** Retry counts by page id; a frame reloads its live document when its count changes. */
+    liveRouteRetries: Map<string, number>;
+    setLiveRouteFailure(pageId: string, message: string | null): void;
+    liveRouteFailure(pageId: string): string | undefined;
+    retryLiveRoute(pageId: string): void;
+    liveRouteRetryCount(pageId: string): number;
+    /** Standby page ids of the active group, in declaration order. */
+    get activeScreenStateSiblingIds(): string[];
     /** Swaps a folded variant into its group's canvas slot; the camera stays. */
     private revealScreenState;
     /** Switch canvases, restore their view, and activate the first frame. */
@@ -503,10 +565,9 @@ export declare class EditorStore {
     /** pageId → source geometry awaiting its post-mount fidelity measurement. */
     private pendingLayerImportGeometry;
     /** View-only motion playback never becomes part of a frame recipe or undo history. */
-    private previewMotionStates;
     private contentLayoutScheduled;
     private contentLayoutCanvases;
-    constructor(host?: EditorStoreHost);
+    constructor(options?: EditorStoreOptions);
     /** Releases the reactions this store owns. A runtime calls it when its editor unmounts. */
     dispose(): void;
     get activePage(): PageModel;
@@ -801,11 +862,6 @@ export declare class EditorStore {
         selector?: string;
         targetLabel?: string;
     } | null): boolean;
-    previewMotionState(pageId: string): Readonly<PreviewMotionState>;
-    playPreviewMotion(pageId: string, targetId?: string): void;
-    pausePreviewMotion(pageId: string, targetId?: string): void;
-    seekPreviewMotion(pageId: string, targetId: string | undefined, progress: number): void;
-    resetPreviewMotion(pageId: string): void;
     /** Pages whose mounted frozen preview was refused at the import boundary. */
     private frozenPromotionRefusals;
     /** True when the page's frozen capture was refused and activation should boot live instead. */
@@ -875,6 +931,16 @@ export declare class EditorStore {
     /** Section name whose name is entered immediately after creation/double-clicking — SectionBoxes are rendered as input. */
     sectionRenameTarget: string | null;
     setTool(tool: 'select' | 'hand' | 'zoom' | 'section'): void;
+    /** Inspecting picks DOM elements inside live frames and records source edits. */
+    inspectOn: boolean;
+    /**
+     * Which discovered element the variant panel's Elements row is about, per
+     * page. A held pseudo-state outranks it; the canvas inspector writes it.
+     */
+    pseudoTargets: Map<string, string>;
+    setPseudoTarget(pageId: string, targetId: string | null): void;
+    pseudoTargetFor(pageId: string): string | undefined;
+    setInspectOn(on: boolean): void;
     setSectionRenameTarget(name: string | null): void;
     /**
    * Completing a section drag creates the rectangle immediately and includes intersecting frames.

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

@@ -1,5 +1,5 @@
-import { type StoryboardDefinition, type StoryboardGraph } from './storyboardGraph';
-import type { DesignImportAsset, DesignImportInitialPage, DesignScenarioSource } from './designImport';
+import { type StoryboardDefinition, type StoryboardGraph } from './storyboardGraph.js';
+import type { DesignImportAsset, DesignImportInitialPage, DesignScenarioSource } from './designImport.js';
 export type AuthoredStoryboardGraphOptions = {
     pages: readonly DesignImportInitialPage[];
     assets?: readonly DesignImportAsset[];

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

@@ -1,6 +1,7 @@
-import type { DesignImportAsset, DesignImportKind, DesignScreenCase, StoryboardEnvironment } from './designImport';
+import type { DesignImportAsset, DesignImportKind, DesignScreenCase, StoryboardEnvironment } from './designImport.js';
 import type { EditorTransport } from '../contract/transport.js';
-import { type StoryboardGraph, type StoryboardDefinition } from './storyboardGraph';
+import { type StoryboardGraph, type StoryboardDefinition } from './storyboardGraph.js';
+import type { StoryboardGraphRuntime } from './storyboardGraphRuntime.js';
 export interface StoryboardDiscoveryScenario {
     id?: string;
     name?: string;
@@ -94,4 +95,4 @@ export declare function loadStoryboardDiscovery(transport: EditorTransport, opti
  * Replaces the editor graph atomically from source discovery. A stale graph is
  * cleared both before the request and after any transport or parsing failure.
  */
-export declare function publishStoryboardDiscovery(transport: EditorTransport, options: LoadStoryboardDiscoveryOptions): Promise<StoryboardDiscoveryResult>;
+export declare function publishStoryboardDiscovery(transport: EditorTransport, graph: Pick<StoryboardGraphRuntime, 'setStoryboardGraph'>, options: LoadStoryboardDiscoveryOptions): Promise<StoryboardDiscoveryResult>;

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

@@ -1,10 +1,6 @@
-import type { StoryboardEnvironment } from './designImport';
-export declare function bumpPreviewIdentityEpoch(): void;
-export declare function getPreviewIdentityEpoch(): number;
+import type { StoryboardEnvironment } from './designImport.js';
 export declare const STORYBOARD_ENVIRONMENT_QUERY: "__pygmalion_environment";
 export declare const STORYBOARD_ENVIRONMENT_CONTROL: "/__pygmalion-storyboard/environment";
-export declare function setStoryboardBaselineEnvironment(environment?: StoryboardEnvironment): void;
-export declare function getStoryboardBaselineEnvironment(): StoryboardEnvironment | undefined;
 export declare function mergeStoryboardEnvironment(base?: StoryboardEnvironment, override?: StoryboardEnvironment): StoryboardEnvironment | undefined;
 /**
  * Boot-time environment derived from a screen preset — parity with the Node
@@ -29,3 +25,11 @@ export declare function resolveStoryboardBootEnvironment(preset: Readonly<Record
  * application modules execute, so routers continue to see the original URL.
  */
 export declare function createStoryboardRouteUrl(appOrigin: string, route: string, environment?: StoryboardEnvironment): string;
+/** One editor's storyboard baseline environment and preview identity epoch. */
+export declare function createStoryboardEnvironmentState(): {
+    bumpPreviewIdentityEpoch: () => void;
+    getPreviewIdentityEpoch: () => number;
+    setStoryboardBaselineEnvironment: (environment?: StoryboardEnvironment) => void;
+    getStoryboardBaselineEnvironment: () => StoryboardEnvironment | undefined;
+};
+export type StoryboardEnvironmentState = ReturnType<typeof createStoryboardEnvironmentState>;

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

@@ -1,4 +1,4 @@
-import type { DesignImportAsset, DesignScenarioSource, DesignScreenCase } from './designImport';
+import type { DesignImportAsset, DesignScenarioSource, DesignScreenCase } from './designImport.js';
 export type StoryboardGraphEdgeOrigin = 'explicit' | 'inferred';
 export type StoryboardGraphEdgeLabelScope = 'edge' | 'path';
 export interface StoryboardGraphEdgeInput {

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

@@ -1,12 +1,10 @@
-import type { StoryboardGraph } from './storyboardGraph';
+import type { StoryboardGraph } from './storyboardGraph.js';
 type StoryboardGraphListener = () => void;
-/**
- * Publishes a project-owned storyboard graph to the editor shell.
- *
- * The runtime only stores the generic graph contract. Projects remain
- * responsible for creating their manifest, meanings, presets, and assertions.
- */
-export declare function setStoryboardGraph(graph: StoryboardGraph | null): void;
-export declare function getStoryboardGraph(): StoryboardGraph | null;
-export declare function subscribeStoryboardGraph(listener: StoryboardGraphListener): () => void;
+/** One editor's published storyboard graph and its subscribers. */
+export declare function createStoryboardGraphRuntime(): {
+    setStoryboardGraph: (graph: StoryboardGraph | null) => void;
+    getStoryboardGraph: () => StoryboardGraph | null;
+    subscribeStoryboardGraph: (listener: StoryboardGraphListener) => () => void;
+};
+export type StoryboardGraphRuntime = ReturnType<typeof createStoryboardGraphRuntime>;
 export {};

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

@@ -1,4 +1,4 @@
-import type { StoryboardGraph, StoryboardGraphEdgeOrigin, StoryboardGraphWarning } from './storyboardGraph';
+import type { StoryboardGraph, StoryboardGraphEdgeOrigin, StoryboardGraphWarning } from './storyboardGraph.js';
 export interface StoryboardFrameReference {
     frameId: string;
     screenId: string;

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

@@ -1,4 +1,4 @@
-import type { StoryboardGraphFrameView, StoryboardGraphViewModel } from './storyboardGraphView';
+import type { StoryboardGraphFrameView, StoryboardGraphViewModel } from './storyboardGraphView.js';
 /**
  * The journey a catalog actually tells, and everything that hangs off it.
  *

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

@@ -3,6 +3,13 @@ export interface SurfaceCandidate {
     kind: SurfaceDemandKind;
     /** Stable identity — the same surface must produce the same id across runs. */
     id: string;
+    /**
+     * The host's own identity for the surface, carried through untouched: the
+     * route id discovery reported, for a route candidate. A diagnostic repeats
+     * it so the host joins back to a route name or a source path by key rather
+     * than by parsing the candidate id.
+     */
+    sourceId?: string;
     /** Frame the candidate was found in. Absent for route candidates. */
     frameId?: string;
     /**
@@ -33,14 +40,67 @@ export type SurfaceVerdict = {
 export type SurfaceClassification = SurfaceVerdict & {
     id: string;
 };
+/**
+ * What went wrong, as a value a gate can branch on.
+ *
+ * - `duplicate-candidate` — an enumerator reported one surface twice.
+ * - `stale-verdict` — a verdict names a surface no enumerator reports.
+ * - `duplicate-verdict` — two verdicts answer one surface.
+ * - `exclusion-reason` — an exclusion's reason is below the floor.
+ * - `empty-target` — a covered verdict names nothing.
+ * - `unknown-target` — a covered verdict names a declaration that does not
+ *   exist among the known targets the caller supplied.
+ * - `unclassified` — a surface has no verdict at all.
+ */
+export type SurfaceDemandDiagnosticCode = 'duplicate-candidate' | 'stale-verdict' | 'duplicate-verdict' | 'exclusion-reason' | 'empty-target' | 'unknown-target' | 'unclassified';
 export interface SurfaceDemandDiagnostic {
     severity: 'error' | 'warning';
+    code: SurfaceDemandDiagnosticCode;
     kind: SurfaceDemandKind | 'unknown';
     candidateId: string;
+    /** The candidate's host-side identity, when the enumerator carried one. */
+    sourceId?: string;
+    /** Frame the candidate was found in, when it was found in one. */
+    frameId?: string;
+    /** The coverage target the verdict named, for target diagnostics. */
+    target?: string;
     message: string;
 }
+export interface SurfaceDemandOptions {
+    /**
+     * Every declaration a `covered` verdict may name.
+     *
+     * Without it a verdict passes as long as it names something, so a screen
+     * that was deleted keeps covering its route through the verdict that named
+     * it. With it, `by` must be one of these ids; `declaredCoverageTargets`
+     * builds the set from the host's declarations.
+     */
+    knownTargets?: readonly string[] | ReadonlySet<string>;
+}
 /** Reasons must say something; the scenario ledger uses the same floor. */
 export declare const MIN_SURFACE_REASON_LENGTH = 10;
+/**
+ * The ids a `covered` verdict may name, built from what the host declared.
+ *
+ * A screen is named by its own id — the same string a coverage claim's
+ * `screenId` uses, prefix and all. A registered component is named
+ * `component:<name>`, since a bare component name and a screen id could
+ * collide. Anything else the host counts as a coverage target (an
+ * interactive axis, a card slot) is passed through `targets` as written. A
+ * host with its own vocabulary builds the set itself and hands it to
+ * `knownTargets` directly.
+ */
+export interface CoverageTargetDeclarations {
+    /** Declared screens — the cases handed to `createDesignScreenCollection` qualify. */
+    screens?: readonly {
+        id: string;
+    }[];
+    /** Registered component names, or the registry object itself. */
+    components?: readonly string[] | ReadonlySet<string> | Readonly<Record<string, unknown>>;
+    /** Further target ids, verbatim. */
+    targets?: readonly string[];
+}
+export declare function declaredCoverageTargets(declarations: CoverageTargetDeclarations): Set<string>;
 /**
  * Compares what the editor found against what the host answered.
  *
@@ -48,28 +108,145 @@ export declare const MIN_SURFACE_REASON_LENGTH = 10;
  * green while a surface goes unreviewed, which is the state this module exists
  * to end. Callers that need a migration window hold a baseline of known ids
  * rather than downgrading the severity.
+ *
+ * Pass `knownTargets` to also require that every `covered` verdict names a
+ * declaration that exists. Without it the target is only required to be
+ * nonempty, which is what let a deleted screen keep covering its route.
  */
-export declare function validateSurfaceDemands(candidates: readonly SurfaceCandidate[], classifications: readonly SurfaceClassification[]): SurfaceDemandDiagnostic[];
+export declare function validateSurfaceDemands(candidates: readonly SurfaceCandidate[], classifications: readonly SurfaceClassification[], options?: SurfaceDemandOptions): SurfaceDemandDiagnostic[];
+/**
+ * Counts by outcome. Four buckets and nothing moves between them: a surface is
+ * covered only when a valid verdict names a valid target, an exclusion is
+ * visible in its own count rather than folded into coverage, and a verdict
+ * that failed validation counts as invalid — never as covered.
+ */
+export interface SurfaceCoverageSummary {
+    total: number;
+    covered: number;
+    excluded: number;
+    /** Surfaces whose verdict failed validation. */
+    invalid: number;
+    unclassified: number;
+    excludedIds: string[];
+    invalidIds: string[];
+    unclassifiedIds: string[];
+}
+export declare function summarizeSurfaceDemands(candidates: readonly SurfaceCandidate[], classifications: readonly SurfaceClassification[], options?: SurfaceDemandOptions): SurfaceCoverageSummary;
 /** Candidates with no verdict yet — what the panel shows on a frame. */
 export declare function unclassifiedSurfaces(candidates: readonly SurfaceCandidate[], classifications: readonly SurfaceClassification[]): SurfaceCandidate[];
+/**
+ * A route as the host's discovery reported it.
+ *
+ * `path` is the canonical pattern in whatever syntax the host normalized to
+ * (`/items/:id`, or `/items/[id]` left as the framework wrote it); `id` is the
+ * host's stable identity for it, which the candidate carries as `sourceId`.
+ * Either alone is enough: a route with only an id is treated as a path.
+ */
+export interface DiscoveredRoute {
+    path?: string;
+    id?: string;
+}
+/**
+ * What a declared screen says about source routes.
+ *
+ * `route` is the concrete address the screen boots; it represents a
+ * discovered pattern when it satisfies that pattern segment for segment.
+ * `coverageRoutes` is the explicit form: the source routes this screen stands
+ * for, matched by the discovered route's `id` or by its normalized path,
+ * exactly. It is how a screen that renders a registered component
+ * (`componentName`) covers a route without inventing a navigation URL, and
+ * how a screen booted at one concrete address claims a dynamic pattern
+ * without the core guessing at parameters. A `DesignScreenCase` satisfies
+ * this shape as written.
+ */
+export interface DeclaredScreenRoute {
+    id: string;
+    route?: string;
+    componentName?: string;
+    coverageRoutes?: readonly string[];
+}
 export interface RouteEnumerationInput {
     /** Routes discovered in the codebase. */
-    routes: readonly {
-        path?: string;
-        id?: string;
-    }[];
-    /** Screen cases the host declared, with the route each one boots. */
-    declaredScreens: readonly {
-        id: string;
-        route?: string;
-    }[];
+    routes: readonly DiscoveredRoute[];
+    /** Screen cases the host declared, with the route or component each one renders. */
+    declaredScreens: readonly DeclaredScreenRoute[];
+    /**
+     * Registered component names, or the registry itself. When given, a screen
+     * whose `componentName` is not among them represents nothing: the fixture
+     * it names is gone, and the routes it mapped stay unrepresented.
+     */
+    registeredComponents?: readonly string[] | ReadonlySet<string> | Readonly<Record<string, unknown>>;
+}
+/** How a declared screen came to represent a discovered route. */
+export type RouteRepresentationKind = 
+/** The screen's concrete `route` satisfies the discovered pattern. */
+'preview'
+/** The screen lists the route in `coverageRoutes` and boots a route of its own. */
+ | 'mapping'
+/** The screen lists the route in `coverageRoutes` and renders a registered component. */
+ | 'fixture';
+export interface RouteRepresentation {
+    /** The candidate id the route would have had, `route:<path>`. */
+    candidateId: string;
+    path: string;
+    sourceId?: string;
+    screenId: string;
+    via: RouteRepresentationKind;
+    componentName?: string;
+}
+/**
+ * - `unknown-route` — a `coverageRoutes` entry matches no discovered route:
+ *   the source route was removed or renamed, and the mapping is stale.
+ * - `unregistered-component` — the screen's `componentName` is not among
+ *   `registeredComponents`: its fixture registration is gone.
+ * - `empty-mapping` — a `coverageRoutes` entry is blank.
+ * - `missing-render-source` — a mapped screen has neither a nonempty preview
+ *   route nor a component fixture to render.
+ */
+export type RouteCoverageDiagnosticCode = 'unknown-route' | 'unregistered-component' | 'empty-mapping' | 'missing-render-source';
+export interface RouteCoverageDiagnostic {
+    severity: 'error';
+    code: RouteCoverageDiagnosticCode;
+    screenId: string;
+    /** The `coverageRoutes` entry as the host wrote it. */
+    route?: string;
+    componentName?: string;
+    message: string;
+}
+export interface RouteCoverageAudit {
+    /** Discovered routes nothing represents — each still owes a verdict. */
+    candidates: SurfaceCandidate[];
+    /** Every (route, screen) pair that holds, so a host can join routes to screens. */
+    represented: RouteRepresentation[];
+    /** Mappings that name something missing. Separate from the candidates on purpose. */
+    diagnostics: RouteCoverageDiagnostic[];
 }
 /**
+ * Which declared screens represent each discovered route, and which routes
+ * nothing represents.
+ *
  * A discovered route with no screen case is the plainest hole there is: the
  * codebase can render it and the storyboard never shows it. Resolution today
  * is silent — `resolveStoryboardScreenCases` maps declared pages and never
  * looks at the discovered route list.
+ *
+ * Two ways a screen represents a route, checked in this order:
+ *
+ * 1. Explicitly, by listing the route in `coverageRoutes`. The entry must
+ *    equal the discovered route's `id` or normalize to its path — no
+ *    parameter substitution, no prefix. A screen that renders a registered
+ *    component covers the route this way without a navigation URL; a screen
+ *    booted at `/items/fixture-1` covers `/items/[id]` this way without the
+ *    core parsing bracket syntax.
+ * 2. Implicitly, by booting a concrete `route` that satisfies the pattern
+ *    segment for segment (`:param` and `*` accept any nonempty segment).
+ *
+ * A mapping that names a missing route or an unregistered component is a
+ * diagnostic, not a representation: a stale mapping must not keep covering,
+ * and the route it named is reported among the candidates as well.
  */
+export declare function auditRouteCoverage(input: RouteEnumerationInput): RouteCoverageAudit;
+/** The unrepresented routes of `auditRouteCoverage`, for callers that only need the holes. */
 export declare function enumerateRouteCandidates(input: RouteEnumerationInput): SurfaceCandidate[];
 export interface ControlNodeLike {
     id: string;
@@ -111,28 +288,18 @@ export declare function requestEndpointShape(url: string): string;
  * (`StoryboardEnvironment.network`), which is what makes asking fair.
  */
 export declare function enumerateRequestCandidates(frameId: string, requests: readonly ObservedRequest[]): SurfaceCandidate[];
-export declare function setSurfaceClassifications(classifications: readonly SurfaceClassification[] | undefined): void;
-export declare function getSurfaceClassifications(): readonly SurfaceClassification[];
-/**
- * Records what a frame asked for while booting.
- *
- * Replaces rather than appends: a re-supplied frame boots again, and appending
- * would keep questions alive for endpoints the current recipe no longer calls.
- */
-export declare function setObservedRequests(frameId: string, requests: readonly ObservedRequest[]): void;
-export declare function getObservedRequests(frameId: string): readonly ObservedRequest[];
 export interface FrameSurfaceDemands {
     candidates: SurfaceCandidate[];
     unclassified: SurfaceCandidate[];
 }
-/**
- * The questions one frame owes an answer to.
- *
- * Controls come from the tree the editor already imported for editing, requests
- * from what the frame asked for while booting. Both are facts about this frame,
- * so the panel can show them next to the axes the host did declare — which is
- * where a missing axis becomes visible instead of merely absent.
- */
-export declare function frameSurfaceDemands(frameId: string, root?: (ControlNodeLike & {
-    children?: readonly ControlNodeLike[];
-}) | null, classifications?: readonly SurfaceClassification[]): FrameSurfaceDemands;
+/** One editor's declared surface classifications and the requests its frames observed. */
+export declare function createSurfaceDemands(): {
+    setSurfaceClassifications: (classifications: readonly SurfaceClassification[] | undefined) => void;
+    getSurfaceClassifications: () => readonly SurfaceClassification[];
+    setObservedRequests: (frameId: string, requests: readonly ObservedRequest[]) => void;
+    getObservedRequests: (frameId: string) => readonly ObservedRequest[];
+    frameSurfaceDemands: (frameId: string, root?: (ControlNodeLike & {
+        children?: readonly ControlNodeLike[];
+    }) | null, classifications?: readonly SurfaceClassification[]) => FrameSurfaceDemands;
+};
+export type SurfaceDemands = ReturnType<typeof createSurfaceDemands>;

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

@@ -1,3 +1,4 @@
+import type { DocumentSync } from './documentSync.js';
 export interface TokenDef {
     /** CSS variable name — e.g. `--app-color-surface-brand`. */
     name: string;
@@ -8,28 +9,26 @@ export interface TokenDef {
     /** Optional group label. */
     group?: string;
 }
-export declare function setTokens(t: TokenDef[]): void;
-export declare function getTokens(): TokenDef[];
-export declare function setOnTokensChange(cb: ((changed: {
-    name: string;
-    value: string;
-}[]) => void) | null): void;
-/** Value being edited (overridden) — if not present, injected raw value. */
-export declare function getTokenValue(name: string): string;
-export declare function getTokenOverrides(): {
-    name: string;
-    value: string;
-}[];
-/**
- * Replaces revision-local token edits without reporting them as new user edits.
- * Catalog installation uses this to retire one checkout's CSS overrides and to
- * restore them if the surrounding atomic install fails.
- */
-export declare function replaceTokenOverrides(next: readonly {
-    name: string;
-    value: string;
-}[]): void;
-/** Edit token value — Immediately override document root (live) + notify cumulative changes to host callback. */
-export declare function applyTokenOverride(name: string, value: string): void;
-/** Disable all overrides (return to original value). */
-export declare function resetTokenOverrides(): void;
+/** The part of a runtime's document sync a token edit queues into. */
+export type TokenSyncQueue = Pick<DocumentSync, 'queueTokenDesignChange'>;
+/** One editor's design tokens and the overrides the designer applied. */
+export declare function createTokens(): {
+    setTokens: (t: TokenDef[]) => void;
+    getTokens: () => 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: TokenSyncQueue, name: string, value: string) => void;
+    resetTokenOverrides: (sync: TokenSyncQueue) => void;
+};
+export type Tokens = ReturnType<typeof createTokens>;