@pygmalionjs/pygmalion 0.5.14 → 0.5.15

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

@@ -0,0 +1,116 @@
+/** Structural subset of an editor node; keeps this module store-free. */
+export interface CompositionNodeLike {
+    componentName?: string;
+    sourceStyle?: string;
+    domAttributes?: Readonly<Record<string, string>>;
+    children?: readonly CompositionNodeLike[];
+}
+export interface CompositionFrameSignals {
+    frameId: string;
+    name: string;
+    /** Registry component this frame is a catalog sheet for, when declared. */
+    componentName?: string;
+    /** Files the host declared for this frame (page.sourcePaths). */
+    declaredFiles?: readonly string[];
+    /** Source files observed in the frame's imported tree. */
+    sourceFiles: readonly string[];
+    /** Registry component instances observed in the frame's imported tree. */
+    componentNames: readonly string[];
+}
+export interface CompositionUsedByFrame {
+    frameId: string;
+    name: string;
+}
+/**
+ * Usage answered by the source scan for one file.
+ *
+ * `direct` is symbol-level with barrels made transparent — the files that
+ * name this piece. `transitive` is the dependency closure, which a barrel
+ * inflates to roughly the whole app; it is kept only so a number that big can
+ * be labelled as what it is.
+ */
+export interface CompositionSourceUsage {
+    direct: readonly string[];
+    barrels?: readonly string[];
+    transitive?: number;
+}
+export type CompositionEvidence = 'observed' | 'direct' | 'transitive' | 'pending' | 'unused' | 'not-traced';
+export interface CompositionEntryView {
+    frameId: string;
+    name: string;
+    /** File the entry is traced by, recovered from its own stamps. */
+    sourceFile?: string;
+    componentName?: string;
+    /** Frames observed rendering this piece. */
+    usedByFrames: readonly CompositionUsedByFrame[];
+    /** Files that name this piece, with barrels followed through. */
+    usedByFiles: readonly string[];
+    /** Size of the dependency closure, which is not a usage count. */
+    transitiveCount?: number;
+    evidence: CompositionEvidence;
+}
+export interface StoryboardCompositionModel {
+    entries: readonly CompositionEntryView[];
+    /** Entries still waiting for the source scan to answer. */
+    pendingCount: number;
+    /**
+     * Catalog frames with no traceable identity — no stamps yet and no declared
+     * component. They are listed so the index stays total; opening one gives it
+     * stamps and it moves into the entries on the next build.
+     */
+    unplacedFrameIds: readonly string[];
+}
+/**
+ * Mirror of PYGMALION_SOURCE_USAGE_CONTROL in node/storyboard-environment.mjs;
+ * a test pins the pair so the browser cannot drift from the server.
+ */
+export declare const SOURCE_USAGE_CONTROL = "/__pygmalion-storyboard/source-usage";
+/**
+ * Reads what a frame rendered out of its imported tree. Only frames that have
+ * been imported carry stamps, which is why the static graph still matters.
+ */
+export declare function collectCompositionSignals(root: CompositionNodeLike | undefined): {
+    sourceFiles: string[];
+    componentNames: string[];
+};
+/**
+ * The component a catalog sheet is about. A sheet built from one registry
+ * entry says so on its root or its only instance; a gallery listing several
+ * has no single subject, and traces by file instead.
+ */
+export declare function catalogComponentName(root: CompositionNodeLike | undefined): string | undefined;
+/**
+ * The file a catalog frame is traced by.
+ *
+ * A declared path wins: the host names the module the sheet is for, while a
+ * sheet's tree stamps every file it touched, including the atoms nested
+ * inside it. Among several candidates the one whose filename matches the
+ * component wins, so a Badge sheet traces Badge.tsx and not the row it sits
+ * in.
+ */
+export declare function traceCatalogFile(frame: CompositionFrameSignals): string | undefined;
+export declare function createStoryboardCompositionModel(input: {
+    /** Frames on the catalog canvas being indexed. */
+    catalog: readonly CompositionFrameSignals[];
+    /** Every other frame that could render them (screens and other sheets). */
+    consumers: readonly CompositionFrameSignals[];
+    /**
+     * Answers from the source scan, by traced file. A file absent from this
+     * map has not been answered yet — which is not the same as having no
+     * users, and must never be reported as one.
+     */
+    usageByFile?: Readonly<Record<string, CompositionSourceUsage>>;
+    /** True once the scan has been attempted, so absence means pending. */
+    usageRequested?: boolean;
+}): StoryboardCompositionModel;
+/**
+ * The index invariant, composition side: every catalog frame is either an
+ * entry or explicitly unplaced.
+ */
+export declare function validateCompositionCoverage(model: StoryboardCompositionModel, catalog: readonly {
+    frameId: string;
+}[]): {
+    severity: 'error';
+    frameId: string;
+    message: string;
+}[];

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

@@ -0,0 +1,105 @@
+import type { DesignImportAsset, DesignImportKind, DesignScreenCase, StoryboardEnvironment } from './designImport';
+import { type StoryboardGraph, type StoryboardDefinition } from './storyboardGraph';
+export interface StoryboardDiscoveryScenario {
+    id?: string;
+    name?: string;
+    section?: string;
+    flow?: string;
+    sourcePath?: string;
+    description?: string;
+    environment?: StoryboardEnvironment;
+}
+export interface StoryboardDiscoveryCandidate {
+    id?: string;
+    route?: string;
+    scenarioId?: string;
+    environment?: StoryboardEnvironment;
+}
+export interface StoryboardDiscoveryEdge {
+    id?: string;
+    from?: string;
+    to?: string;
+    kind?: string;
+    label?: string;
+    unresolvedTarget?: boolean;
+}
+export interface StoryboardDiscoveryRoute {
+    id?: string;
+    path?: string;
+}
+export interface StoryboardDiscoveryManifest {
+    version?: number;
+    routes?: readonly StoryboardDiscoveryRoute[];
+    scenarios?: readonly StoryboardDiscoveryScenario[];
+    candidates?: readonly StoryboardDiscoveryCandidate[];
+    edges?: readonly StoryboardDiscoveryEdge[];
+}
+export interface StoryboardResolvedPage {
+    id: string;
+    name: string;
+    canvas?: string;
+    section?: string;
+    importKind?: DesignImportKind;
+    componentName?: string;
+    gallery?: string[];
+    route?: string;
+    path?: string;
+    publish?: boolean;
+    width?: number;
+    height?: number;
+    frameSizeMode?: DesignScreenCase['frameSizeMode'];
+    heightMode?: DesignScreenCase['heightMode'];
+    maxHeight?: number;
+    sourcePaths?: string[];
+    flow?: string;
+    scenario?: string;
+    state?: string;
+    scenarioId?: string;
+    interactions?: DesignScreenCase['interactions'];
+    environment?: StoryboardEnvironment;
+    preset?: DesignScreenCase['preset'];
+    assertions?: DesignScreenCase['assertions'];
+}
+export interface StoryboardDiscoveryGraphOptions {
+    manifest: StoryboardDiscoveryManifest;
+    pages: readonly StoryboardResolvedPage[];
+    assets?: readonly DesignImportAsset[];
+    /** Host-authored user journeys layered over source-inferred transitions. */
+    storyboard?: StoryboardDefinition;
+}
+export interface StoryboardDiscoveryResult {
+    manifest: StoryboardDiscoveryManifest;
+    baselineEnvironment?: StoryboardEnvironment;
+    graph: StoryboardGraph;
+}
+export interface StoryboardDiscoveryResponse {
+    ok: boolean;
+    status: number;
+    json(): Promise<unknown>;
+}
+export type StoryboardDiscoveryFetch = (endpoint: string, init: {
+    headers: {
+        accept: 'application/json';
+    };
+    cache: 'no-store';
+    signal?: AbortSignal;
+}) => Promise<StoryboardDiscoveryResponse>;
+export interface LoadStoryboardDiscoveryOptions extends Omit<StoryboardDiscoveryGraphOptions, 'manifest'> {
+    endpoint: string;
+    signal?: AbortSignal;
+    fetcher?: StoryboardDiscoveryFetch;
+}
+export declare function createStoryboardRouteScenarioId(route: string): string;
+/**
+ * Converts the editor's resolved screen frames into graph screen cases.
+ * Explicit import kinds win; untyped hosts fall back to route-backed pages.
+ */
+export declare function resolveStoryboardScreenCases(pages: readonly StoryboardResolvedPage[], manifest: StoryboardDiscoveryManifest): DesignScreenCase[];
+export declare function getStoryboardDiscoveryBaselineEnvironment(manifest: StoryboardDiscoveryManifest): StoryboardEnvironment | undefined;
+export declare function createStoryboardGraphFromDiscovery(options: StoryboardDiscoveryGraphOptions): StoryboardGraph;
+export declare function loadStoryboardDiscovery(options: LoadStoryboardDiscoveryOptions): Promise<StoryboardDiscoveryResult>;
+/**
+ * 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(options: LoadStoryboardDiscoveryOptions): Promise<StoryboardDiscoveryResult>;

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

@@ -0,0 +1,22 @@
+import type { StoryboardEnvironment } from './designImport';
+export declare function bumpPreviewIdentityEpoch(): void;
+export declare function getPreviewIdentityEpoch(): number;
+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
+ * capture runtime's init script, which installs the preset global and seeds
+ * preset storage before any page script runs. Declared case environments
+ * still win: merge this layer UNDER the storyboard baseline.
+ */
+export declare function presetBootEnvironment(preset: Readonly<Record<string, unknown>> | undefined): StoryboardEnvironment | undefined;
+/**
+ * Adds a declarative browser environment to a route URL.
+ *
+ * The Pygmalion Vite runtime consumes and removes the query parameter before
+ * application modules execute, so routers continue to see the original URL.
+ */
+export declare function createStoryboardRouteUrl(appOrigin: string, route: string, environment?: StoryboardEnvironment): string;

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

@@ -0,0 +1,120 @@
+import type { DesignImportAsset, DesignScenarioSource, DesignScreenCase } from './designImport';
+export type StoryboardGraphEdgeOrigin = 'explicit' | 'inferred';
+export interface StoryboardGraphEdgeInput {
+    id?: string;
+    from: string;
+    to: string;
+    /** Screen or node identities that inherit this outgoing route connection. */
+    fromScope?: readonly string[];
+    /** Screen or node identities that inherit this incoming route connection. */
+    toScope?: readonly string[];
+    kind?: string;
+    label?: string;
+}
+export interface StoryboardPathInput {
+    /** Stable author-owned identity used as the edge id prefix. */
+    id: string;
+    /** Ordered screen ids visited by this path. */
+    screenIds: readonly string[];
+    kind?: string;
+    label?: string;
+}
+export interface StoryboardDefinition {
+    paths?: readonly StoryboardPathInput[];
+    edges?: readonly StoryboardGraphEdgeInput[];
+    startScreenIds?: readonly string[];
+    nonVisualScenarioIds?: readonly string[];
+}
+/** Expands readable authored paths into deterministic adjacent graph edges. */
+export declare function createStoryboardPathEdges(paths: readonly StoryboardPathInput[]): StoryboardGraphEdgeInput[];
+export interface StoryboardGraphBuildOptions {
+    screens: readonly DesignScreenCase[];
+    assets?: readonly DesignImportAsset[];
+    scenarios?: readonly DesignScenarioSource[];
+    explicitEdges?: readonly StoryboardGraphEdgeInput[];
+    inferredEdges?: readonly StoryboardGraphEdgeInput[];
+    startScreenIds?: readonly string[];
+    nonVisualScenarioIds?: readonly string[];
+    recipeKey?: (screen: DesignScreenCase) => string;
+}
+export interface StoryboardGraphNode {
+    id: string;
+    canonicalScreenId: string;
+    screenIds: readonly string[];
+    names: readonly string[];
+    recipeKey: string;
+    routes: readonly string[];
+    scenarioIds: readonly string[];
+    sourceKeys: readonly string[];
+    flows: readonly string[];
+    states: readonly string[];
+}
+export interface StoryboardGraphEdge {
+    id: string;
+    from: string;
+    to: string;
+    /** Canonical nodes that expose this edge as an outgoing connection. */
+    fromNodeIds?: readonly string[];
+    /** Canonical nodes that expose this edge as an incoming connection. */
+    toNodeIds?: readonly string[];
+    kind?: string;
+    label?: string;
+    origin: StoryboardGraphEdgeOrigin;
+    sourceEdgeIds: readonly string[];
+}
+export interface StoryboardGraphSourceGroup {
+    sourceKey: string;
+    nodeIds: readonly string[];
+    screenIds: readonly string[];
+    shared: boolean;
+}
+export interface StoryboardGraphBranch {
+    nodeId: string;
+    edgeIds: readonly string[];
+    targetNodeIds: readonly string[];
+}
+export type StoryboardGraphWarningCode = 'duplicate-screen-id' | 'invalid-recipe' | 'unknown-edge-source' | 'unknown-edge-target' | 'ambiguous-edge-source' | 'ambiguous-edge-target' | 'unknown-start-screen' | 'disconnected-screen' | 'missing-code-scenario';
+export interface StoryboardGraphWarning {
+    code: StoryboardGraphWarningCode;
+    severity: 'warning' | 'error';
+    message: string;
+    screenId?: string;
+    nodeId?: string;
+    edgeId?: string;
+    scenarioId?: string;
+}
+export interface StoryboardGraphCoverage {
+    screens: number;
+    canonicalNodes: number;
+    mergedScreens: number;
+    edges: number;
+    connectedNodes: number;
+    disconnectedScreens: readonly string[];
+    codeScenarios: number;
+    representedScenarios: number;
+    missingScenarios: readonly string[];
+    complete: boolean;
+}
+export interface StoryboardGraph {
+    version: 1;
+    nodes: readonly StoryboardGraphNode[];
+    edges: readonly StoryboardGraphEdge[];
+    aliases: Readonly<Record<string, string>>;
+    sourceGroups: readonly StoryboardGraphSourceGroup[];
+    startNodeIds: readonly string[];
+    branches: readonly StoryboardGraphBranch[];
+    warnings: readonly StoryboardGraphWarning[];
+    coverage: StoryboardGraphCoverage;
+}
+/**
+ * Returns a portable identity for the authored reproduction recipe. Descriptive
+ * labels and scenario classification are intentionally excluded so aliases of
+ * the same rendered state collapse into one canonical graph node.
+ */
+export declare function storyboardScreenRecipeKey(screen: DesignScreenCase): string;
+/**
+ * Builds a deterministic storyboard graph without executing application code.
+ * Explicit edges are processed before inferred edges and win when both describe
+ * the same canonical transition.
+ */
+export declare function createStoryboardGraph(options: StoryboardGraphBuildOptions): StoryboardGraph;

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

@@ -0,0 +1,12 @@
+import type { StoryboardGraph } from './storyboardGraph';
+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;
+export {};

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

@@ -0,0 +1,104 @@
+import type { StoryboardGraph, StoryboardGraphEdgeOrigin, StoryboardGraphWarning } from './storyboardGraph';
+export interface StoryboardFrameReference {
+    frameId: string;
+    screenId: string;
+    name: string;
+}
+export interface StoryboardGraphFrameView {
+    frameId: string;
+    screenId: string;
+    name: string;
+    nodeId: string;
+    canonicalScreenId: string;
+    canonicalFrameId?: string;
+    isCanonical: boolean;
+    isStart: boolean;
+    isBranch: boolean;
+    routes: readonly string[];
+    flows: readonly string[];
+    states: readonly string[];
+    /** Shortest directed distance from an authored storyboard start. */
+    depth?: number;
+    aliasScreenIds: readonly string[];
+    relatedFrameIds: readonly string[];
+    branchTargetFrameIds: readonly string[];
+    incomingTransitions: readonly StoryboardGraphTransitionView[];
+    outgoingTransitions: readonly StoryboardGraphTransitionView[];
+    warnings: readonly StoryboardGraphWarning[];
+}
+export interface StoryboardGraphTransitionView {
+    edgeId: string;
+    sourceFrameId: string;
+    targetFrameId: string;
+    label?: string;
+    kind?: string;
+    origin: StoryboardGraphEdgeOrigin;
+}
+export interface StoryboardGraphCanonicalView {
+    nodeId: string;
+    canonicalScreenId: string;
+    canonicalFrameId?: string;
+    aliasScreenIds: readonly string[];
+    aliasFrameIds: readonly string[];
+}
+export interface StoryboardGraphSourceView {
+    sourceKey: string;
+    frameIds: readonly string[];
+    nodeIds: readonly string[];
+}
+/**
+ * Why a frame is not listed by any structural section.
+ *
+ * `outside-graph` — the storyboard has no node for it at all (a frame with no
+ * route, so nothing authored or inferred could place it).
+ * `no-structure` — the graph knows it, but it is not a start, a branch, an
+ * alias, a shared source or a warning, so no section names it.
+ */
+export type StoryboardUnplacedReason = 'outside-graph' | 'no-structure';
+export interface StoryboardUnplacedFrameView {
+    frameId: string;
+    screenId: string;
+    name: string;
+    reason: StoryboardUnplacedReason;
+}
+export interface StoryboardGraphViewModel {
+    frames: readonly StoryboardGraphFrameView[];
+    canonicalGroups: readonly StoryboardGraphCanonicalView[];
+    sharedSources: readonly StoryboardGraphSourceView[];
+    startFrameIds: readonly string[];
+    branchFrameIds: readonly string[];
+    warnings: readonly StoryboardGraphWarning[];
+    unresolvedWarnings: readonly StoryboardGraphWarning[];
+    coverage: StoryboardGraph['coverage'];
+    /**
+     * Frames the structure cannot place. An index that silently omits a frame
+     * is not an index, so these are carried through to be shown rather than
+     * dropped — which is what hid most of one section's frames and every
+     * catalog frame until now.
+     */
+    unplacedFrames: readonly StoryboardUnplacedFrameView[];
+}
+/**
+ * An index with no journey in it. A canvas can have structure worth showing
+ * (composition) while no storyboard graph exists at all, and the panel still
+ * has to list its frames rather than render nothing.
+ */
+export declare function emptyStoryboardViewModel(frameReferences?: readonly StoryboardFrameReference[]): StoryboardGraphViewModel;
+export interface StoryboardCoverageDiagnostic {
+    severity: 'error';
+    frameId: string;
+    message: string;
+}
+/**
+ * The index invariant: every frame handed to the view model is accounted for
+ * exactly once — either listed by a structural section or carried as
+ * unplaced. Hosts and tests assert this; the panel relies on it to promise
+ * that the storyboard reaches everything.
+ */
+export declare function validateStoryboardCoverage(model: StoryboardGraphViewModel, frameReferences: readonly StoryboardFrameReference[]): StoryboardCoverageDiagnostic[];
+/**
+ * Maps canonical graph identities onto editor frame identities. The graph stays
+ * independent from MobX and canvas state; consumers can memoize this projection
+ * and wire frame ids to their existing focus action.
+ */
+export declare function createStoryboardGraphViewModel(graph: StoryboardGraph, frameReferences: readonly StoryboardFrameReference[]): StoryboardGraphViewModel;

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

@@ -0,0 +1,138 @@
+export type SurfaceDemandKind = 'route' | 'control' | 'request';
+export interface SurfaceCandidate {
+    kind: SurfaceDemandKind;
+    /** Stable identity — the same surface must produce the same id across runs. */
+    id: string;
+    /** Frame the candidate was found in. Absent for route candidates. */
+    frameId?: string;
+    /**
+     * Frame-independent form of the same surface, so one verdict can answer it
+     * everywhere it appears.
+     *
+     * An application shell repeats: the same send button, the same sidebar toggle,
+     * the same navigation tab are in most frames. Demanding a per-frame verdict
+     * for each would mean writing the same product fact tens of times over, which
+     * is the kind of tax that gets a gate switched off rather than answered. A
+     * frame-scoped verdict still wins when the answer genuinely differs there.
+     */
+    matchId?: string;
+    /** Description of what was found, for the panel and the gate message. */
+    detail: string;
+}
+/**
+ * The host's answer. `covered` names the declaration that handles the surface
+ * so a stale answer breaks loudly; `excluded` carries the reason instead.
+ */
+export type SurfaceVerdict = {
+    verdict: 'covered';
+    by: string;
+} | {
+    verdict: 'excluded';
+    reason: string;
+};
+export type SurfaceClassification = SurfaceVerdict & {
+    id: string;
+};
+export interface SurfaceDemandDiagnostic {
+    severity: 'error' | 'warning';
+    kind: SurfaceDemandKind | 'unknown';
+    candidateId: string;
+    message: string;
+}
+/** Reasons must say something; the scenario ledger uses the same floor. */
+export declare const MIN_SURFACE_REASON_LENGTH = 10;
+/**
+ * Compares what the editor found against what the host answered.
+ *
+ * Errors, not warnings, on every branch: a warning would let the build stay
+ * 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.
+ */
+export declare function validateSurfaceDemands(candidates: readonly SurfaceCandidate[], classifications: readonly SurfaceClassification[]): SurfaceDemandDiagnostic[];
+/** Candidates with no verdict yet — what the panel shows on a frame. */
+export declare function unclassifiedSurfaces(candidates: readonly SurfaceCandidate[], classifications: readonly SurfaceClassification[]): SurfaceCandidate[];
+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;
+    }[];
+}
+/**
+ * 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.
+ */
+export declare function enumerateRouteCandidates(input: RouteEnumerationInput): SurfaceCandidate[];
+export interface ControlNodeLike {
+    id: string;
+    domTag?: string;
+    domAttributes?: Readonly<Record<string, string>>;
+    hidden?: boolean;
+}
+/**
+ * Enumerates the operable elements of one frame's imported tree.
+ *
+ * The host declares the axes it thought of, which is why axis coverage has
+ * always been a memory exercise. The tree is already imported for editing, so
+ * the elements are right there — asking about each one makes a forgotten axis
+ * impossible rather than unlikely.
+ *
+ * Elements with no identifying attribute are skipped: there would be no stable
+ * id to attach a verdict to, and a positional id would churn on every layout
+ * edit. Hosts that want those asked about mark them.
+ */
+export declare function enumerateControlCandidates(frameId: string, nodes: readonly ControlNodeLike[]): SurfaceCandidate[];
+export interface ObservedRequest {
+    /** Absolute or app-relative URL as the page requested it. */
+    url: string;
+    method?: string;
+}
+/**
+ * Collapses a URL to one endpoint shape.
+ *
+ * Numeric and uuid path segments become `:id` so a list of fixture rows asks
+ * one question instead of one per row, and the query string is dropped for the
+ * same reason.
+ */
+export declare function requestEndpointShape(url: string): string;
+/**
+ * Every request a frame makes is a state the product can be in and usually is
+ * not shown: the failure, the empty result, the slow wait. Declaring one used
+ * to mean inventing a host flag and a mock branch per state, so hosts declared
+ * almost none. The core now supplies the mechanism
+ * (`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;

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

@@ -0,0 +1,26 @@
+export interface TokenDef {
+    /** CSS variable name — e.g. `--app-color-surface-brand`. */
+    name: string;
+    /** Value for swatch display (hex, etc., light). The canvas is rendered with var(name) so it is for display only. */
+    value: string;
+    /** Dark mode value (if present, displays the swatch as half light/dark). */
+    dark?: string;
+    /** 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;
+}[];
+/** 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;

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

@@ -0,0 +1 @@
+export declare function useObserved<T>(render: () => T): T;

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

@@ -0,0 +1,21 @@
+export interface ViewportPresetDef {
+    /** Button text. The panel column is narrow, so keep it to a few characters. */
+    label: string;
+    /** Frame width in CSS pixels. */
+    width: number;
+    /** Frame height. Omit to resize width only and leave the current height alone. */
+    height?: number;
+    /** Tooltip text. Defaults to the dimensions. */
+    description?: string;
+}
+/**
+ * Declares the preset list. A malformed entry throws here rather than producing a
+ * button that silently collapses a frame — the host configures this once at mount.
+ */
+export declare function setViewportPresets(next: readonly ViewportPresetDef[]): void;
+export declare function getViewportPresets(): ViewportPresetDef[];
+/** Whether a frame currently sits at the preset, so the button can read as active. */
+export declare function matchesViewportPreset(preset: ViewportPresetDef, size: {
+    width: number;
+    height: number;
+}): boolean;