@pygmalionjs/pygmalion 0.7.4 → 0.8.0

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

@@ -1,7 +1,10 @@
-import { type DesignImportController, type DesignScreenCaptureSpec } from './designImport';
-import type { FlowSessionRunner, ResolvedFlowPath } from './flowSessions';
-import type { ScreenFlowPath } from './screenFlows';
-import type { EditorStore, PageModel } from './store';
+import { type DesignImportController, type DesignScreenCaptureSpec } from './designImport.js';
+import type { RoutePreviewCache } from './routePreview.js';
+import type { FlowSessionRunner, FlowSessions, ResolvedFlowPath } from './flowSessions.js';
+import { type InteractiveSessionSurfaces } from './interactiveSessionSurface.js';
+import type { ScreenFlowPath } from './screenFlows.js';
+import type { EditorStore, PageModel } from './store.js';
+import type { EditorDeclarations } from './declarations.js';
 /** What the scheduler needs from an editor runtime; `EditorRuntime` satisfies it. */
 export interface FlowSessionRuntime {
     readonly store: EditorStore;
@@ -9,86 +12,12 @@ export interface FlowSessionRuntime {
         readonly appOrigin: string;
         readonly previewRevision: string;
     };
+    readonly previews: RoutePreviewCache;
+    readonly declarations: EditorDeclarations;
 }
 /** Applies the active frame's own boot condition to a path-specific session. */
-export declare function resolveActivePagePath(resolved: ResolvedFlowPath, path: ScreenFlowPath, page: PageModel, appOrigin: string): ResolvedFlowPath;
+export declare function resolveActivePagePath(declarations: Pick<EditorDeclarations, 'getStoryboardBaselineEnvironment' | 'getPreviewEnvironmentOverride'>, resolved: ResolvedFlowPath, path: ScreenFlowPath, page: PageModel, appOrigin: string): ResolvedFlowPath;
 /** Diagnostic counters for the headless debug surface. */
-export declare const __flowSchedulerDebug: {
-    calls: number;
-    lastCanvas: string;
-    lastFlows: number;
-    lastCandidates: number;
-    lastQueued: number;
-};
-/**
- * Materializes the flow-declared screens of one canvas that still lack a
- * frozen snapshot. Paths delivering the active frame's screen run first.
- * Returns the number of paths queued.
- */
-export declare function materializeCanvasFlows(runtime: FlowSessionRuntime, input: {
-    canvas: string;
-    previewRevision: string;
-    /**
-     * Only paths that deliver one of these screens. The worker-first supply
-     * hands the walking supply exactly the screens the worker could not answer;
-     * without a filter every path on the canvas is a candidate.
-     */
-    screenIds?: ReadonlySet<string>;
-}): number;
-/** Session delivery state for one page, keyed by its catalog screen id. */
-export declare function flowSessionWillDeliverPage(page: {
-    importPageId?: string;
-    id: string;
-}): boolean;
-/**
- * Walks an instance to the active frame's screen in the background and parks
- * it, unless a parked instance already serves that path. Returns true when a
- * warming walk was queued.
- */
-export declare function warmActiveFrameInstance(runtime: FlowSessionRuntime, page: PageModel, previewRevision: string): boolean;
-/** Diagnostic counters for activation warming. */
-export declare const __warmingDebug: {
-    requested: number;
-    noPath: number;
-    resolvedNull: number;
-    alreadyWarm: number;
-    queued: number;
-};
-/**
- * Materializes one screen at an explicit viewport through its flow path.
- * Prefix waypoints walk as pass-through (steps only); the target publishes
- * under the page's recipe key at that viewport — the key its frame reads
- * after the size change commits. Returns false when no flow claims the
- * screen (the live re-import fallback stays for those).
- */
-export declare function materializePageViewport(runtime: FlowSessionRuntime, page: PageModel, viewport: {
-    width: number;
-    height: number;
-}, previewRevision: string): boolean;
-/** True while a viewport-variant session still owes this page's snapshot. */
-export declare function viewportSessionWillDeliver(page: {
-    importPageId?: string;
-    id: string;
-}, viewport: {
-    width: number;
-    height: number;
-}): boolean;
-/** Subscribe to viewport-variant delivery changes. */
-export declare function subscribeViewportSessions(listener: () => void): () => void;
-type InteractivePreparationController = Pick<DesignImportController, 'prepareScreenCapture' | 'prepareScreenState'>;
-/**
- * Reproduces an editor-controlled state without capture-only quiescence.
- * Direct desired state is presented as soon as the host commits React; replay
- * states remain hidden until their gestures finish. Frozen persistence may
- * continue afterward without delaying either live presentation path.
- */
-export declare function prepareInteractiveSessionState(iframe: HTMLIFrameElement, spec: DesignScreenCaptureSpec, controller?: InteractivePreparationController | null, onStateReady?: () => void): Promise<import("./designImport").DesignScreenCaptureReport>;
-/**
- * Test seam: replaces the interactive runner with one whose boot/prepare/
- * publish are injected fakes, so the variant-and-repark queueing can run
- * headless. Passing null restores the default runner on next use.
- */
-export declare function __setInteractiveSessionRunnerForTests(runner: FlowSessionRunner | null): void;
 export declare function interactiveSessionScreenId(page: {
     id: string;
     interactiveStateId?: string;
@@ -103,85 +32,103 @@ export declare function interactiveSessionSurfaceId(page: {
     interactiveOptionIds?: readonly string[];
     interactiveStateUsesDesiredState?: boolean;
 }): string;
-/**
- * Materializes one screen in its declared interactive state through the
- * screen's flow path. The prefix walks as pass-through; the target publishes
- * under the page's own recipe key, which already includes the option's steps
- * (the store appends them to the recipe, and resolvePath replays them).
- * Returns false when no flow claims the screen — those frames keep the live
- * boot fallback.
- */
-export declare function materializePageInteractiveState(runtime: FlowSessionRuntime, page: PageModel, previewRevision: string, targetCacheKey?: string): boolean;
-/** True while an interactive-state session still owes this page its snapshot. */
-export declare function interactiveSessionWillDeliver(page: {
-    id: string;
-    interactiveStateId?: string;
-    interactiveOptionId?: string;
-    interactiveOptionIds?: readonly string[];
-    interactiveStateUsesDesiredState?: boolean;
-}, targetCacheKey?: string): boolean;
-/** Subscribe to interactive-state delivery changes. */
-export declare function subscribeInteractiveSessions(listener: () => void): () => void;
-/** How one speculative enqueue attempt ended. */
 export type InteractiveVariantPrefetchOutcome = 'queued' | 'busy' | 'tracked' | 'unavailable';
-/** True when the interactive runner has nothing queued or walking. */
-export declare function interactiveSessionRunnerIsIdle(): boolean;
-/**
- * True when the interactive runner already tracks this variant's delivery in
- * any status. Unlike interactiveSessionWillDeliver, an untracked variant
- * reads as false here: the prefetch policy asks "is anyone already on it",
- * not "should the frame wait".
- */
-export declare function interactiveSessionTracksVariant(variantPage: {
-    importPageId?: string;
-    id: string;
-    interactiveStateId?: string;
-    interactiveOptionId?: string;
-}): boolean;
+export interface FlowSessionSchedulerDeps {
+    /** This runtime's warm pool, runner factory, and canonical runner. */
+    sessions: FlowSessions;
+    /** This runtime's session surfaces; the direct-state handlers go on them. */
+    surfaces: InteractiveSessionSurfaces;
+}
 /**
- * Queues one speculative walk for a hypothetical variant identity — a shallow
- * page clone carrying the interactions/environment/state fields the store's
- * applyInteractiveState would produce for the option (variantPrefetch.ts
- * derives it). Sibling of materializePageInteractiveState, kept separate so
- * speculation never changes the real request path.
- *
- * The user must never wait behind speculation: the runner is concurrency-1
- * FIFO, so this enqueues only into an EMPTY runner ('busy' otherwise). At
- * most one speculative walk is therefore ever queued or running, and a real
- * selection made meanwhile queues behind that single walk at worst.
+ * One editor's flow-session scheduling: the canvas fill, the activation warm,
+ * the viewport and interactive runners with their delivery states, the
+ * direct-state paths, and the counters the debug surface reads. Bound to one
+ * runtime, so it reads that runtime's store, host, and preview cache and
+ * installs its direct-state handlers on that runtime's surfaces.
  */
-export declare function prefetchPageInteractiveVariant(runtime: FlowSessionRuntime, variantPage: PageModel, previewRevision: string): InteractiveVariantPrefetchOutcome;
-/** Diagnostic counters for the interactive-state path. */
-export declare const __interactiveSessionDebug: {
-    requested: number;
-    noPath: number;
-    resolvedNull: number;
-    queued: number;
-    /** Base-prefix re-park warming walks queued behind variant deliveries. */
-    reparkQueued: number;
-    /** Re-parks skipped because a parked base instance already serves the prefix. */
-    reparkAlreadyParked: number;
-    /** Re-parks skipped because the option adds no steps over the base screen. */
-    reparkNoExtraSteps: number;
-};
-/** Interactive-runner delivery states for the headless debug surface. */
-export declare function __debugInteractiveSessionStates(): Record<string, unknown>;
-/** Diagnostic counters for the viewport-commit path. */
-export declare const __viewportCommitDebug: {
-    requested: number;
-    resolvedNull: number;
-    controllerMissing: number;
-    markerGone: number;
-    editsWon: number;
-    captureNull: number;
-    committed: number;
+export declare function createFlowSessionScheduler(runtime: FlowSessionRuntime, deps: FlowSessionSchedulerDeps): {
+    __flowSchedulerDebug: {
+        calls: number;
+        lastCanvas: string;
+        lastFlows: number;
+        lastCandidates: number;
+        lastQueued: number;
+    };
+    materializeCanvasFlows: (input: {
+        canvas: string;
+        previewRevision: string;
+        /**
+         * Only paths that deliver one of these screens. The worker-first supply
+         * hands the walking supply exactly the screens the worker could not answer;
+         * without a filter every path on the canvas is a candidate.
+         */
+        screenIds?: ReadonlySet<string>;
+    }) => number;
+    flowSessionWillDeliverPage: (page: {
+        importPageId?: string;
+        id: string;
+    }) => boolean;
+    warmActiveFrameInstance: (page: PageModel, previewRevision: string) => boolean;
+    __warmingDebug: {
+        requested: number;
+        noPath: number;
+        resolvedNull: number;
+        alreadyWarm: number;
+        queued: number;
+    };
+    materializePageViewport: (page: PageModel, viewport: {
+        width: number;
+        height: number;
+    }, previewRevision: string) => boolean;
+    viewportSessionWillDeliver: (page: {
+        importPageId?: string;
+        id: string;
+    }, viewport: {
+        width: number;
+        height: number;
+    }) => boolean;
+    subscribeViewportSessions: (listener: () => void) => () => void;
+    prepareInteractiveSessionState: (iframe: HTMLIFrameElement, spec: DesignScreenCaptureSpec, controller?: Pick<DesignImportController, "prepareScreenCapture" | "prepareScreenState"> | null, onStateReady?: () => void) => Promise<import("./designImport.js").DesignScreenCaptureReport>;
+    __setInteractiveSessionRunnerForTests: (runner: FlowSessionRunner | null) => void;
+    materializePageInteractiveState: (page: PageModel, previewRevision: string, targetCacheKey?: string) => boolean;
+    interactiveSessionWillDeliver: (previews: Pick<RoutePreviewCache, "hasExactRoutePreviewSnapshot">, page: {
+        id: string;
+        interactiveStateId?: string;
+        interactiveOptionId?: string;
+        interactiveOptionIds?: readonly string[];
+        interactiveStateUsesDesiredState?: boolean;
+    }, targetCacheKey?: string) => boolean;
+    subscribeInteractiveSessions: (listener: () => void) => () => void;
+    interactiveSessionRunnerIsIdle: () => boolean;
+    interactiveSessionTracksVariant: (variantPage: {
+        importPageId?: string;
+        id: string;
+        interactiveStateId?: string;
+        interactiveOptionId?: string;
+    }) => boolean;
+    prefetchPageInteractiveVariant: (variantPage: PageModel, previewRevision: string) => InteractiveVariantPrefetchOutcome;
+    __interactiveSessionDebug: {
+        requested: number;
+        noPath: number;
+        resolvedNull: number;
+        queued: number;
+        /** Base-prefix re-park warming walks queued behind variant deliveries. */
+        reparkQueued: number;
+        /** Re-parks skipped because a parked base instance already serves the prefix. */
+        reparkAlreadyParked: number;
+        /** Re-parks skipped because the option adds no steps over the base screen. */
+        reparkNoExtraSteps: number;
+    };
+    __debugInteractiveSessionStates: () => Record<string, unknown>;
+    __viewportCommitDebug: {
+        requested: number;
+        resolvedNull: number;
+        controllerMissing: number;
+        markerGone: number;
+        editsWon: number;
+        captureNull: number;
+        committed: number;
+    };
+    __debugViewportSessionStates: () => Record<string, unknown>;
 };
-/** Viewport-runner delivery states for the headless debug surface. */
-export declare function __debugViewportSessionStates(): Record<string, unknown>;
-/**
- * Installs the direct-state handlers for one runtime and returns their
- * remover. Called from `runtime.attach()`, so a mounted editor owns them and
- * an unmounted one releases them.
- */
-export declare function installDirectInteractiveStateHandlers(runtime: FlowSessionRuntime): () => void;
-export {};
+export type FlowSessionScheduler = ReturnType<typeof createFlowSessionScheduler>;

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

@@ -1,4 +1,7 @@
-import type { DesignScreenAssertion, DesignScreenCaptureReport, DesignScreenDesiredState, DesignScreenInteraction, DesignScreenPreset } from './designImport';
+import type { DesignScreenAssertion, DesignScreenCaptureReport, DesignScreenDesiredState, DesignScreenInteraction, DesignScreenPreset } from './designImport.js';
+import type { RoutePreviewCache } from './routePreview.js';
+import { type StateSwitchMetrics } from './stateSwitchMetrics.js';
+import type { EditorDeclarations } from './declarations.js';
 export interface ResolvedFlowWaypoint {
     screenId: string;
     /**
@@ -107,6 +110,13 @@ export interface FlowSessionRunnerOptions {
     settle?: (iframe: HTMLIFrameElement, ms: number) => Promise<void>;
     /** Layout-stability wait before serializing. Defaults to waitForGeometryStability. */
     waitForStability?: (iframe: HTMLIFrameElement) => Promise<void>;
+    /**
+     * The preview cache a walked screen is published into. Required unless
+     * both `serialize` and `publish` are supplied, as tests do.
+     */
+    previews?: Pick<RoutePreviewCache, 'serializeRoutePreview' | 'setRoutePreviewSnapshot'>;
+    /** Where walk phases are recorded; the runtime passes its own metrics. */
+    metrics?: Pick<StateSwitchMetrics, 'beginStateSwitchWalk' | 'beginStateSwitchWaypoint' | 'markStateSwitchPhase' | 'recordStateSwitchPhase' | 'endStateSwitchWalk'>;
     serialize?: (iframe: HTMLIFrameElement, fallbackUrl: string) => string | null;
     /** Writes one waypoint snapshot into the route preview store. */
     publish?: (cacheKey: string, snapshot: string) => boolean;
@@ -130,89 +140,142 @@ export interface FlowSessionRunnerOptions {
  */
 export declare function waitForGeometryStability(iframe: HTMLIFrameElement, timeoutMs?: number): Promise<void>;
 export declare function createFlowSessionIframe(): HTMLIFrameElement;
-/** Test/tuning hook for how long a parked instance stays claimable. */
-export declare function setFlowSessionWarmTtl(ms: number): void;
-/** Warm-pool counters for the headless debug surface. */
-export declare const __flowSessionWarmDebug: {
-    boots: number;
-    reuses: number;
-    parks: number;
-    evictions: number;
-    /** Warming walks answered by renewing an already-parked instance's lease. */
-    refreshes: number;
-    /** Which supply booted, so a stray second boot is attributable. */
-    bootsByRunner: Record<string, number>;
-};
-/** Drops parked instances globally, or only those owned by one runner. */
-export declare function evictFlowSessionWarmInstances(ownerLabel?: string, options?: {
-    preservePinned?: boolean;
-}): void;
+export interface FlowSessionsDeps {
+    /** The cache every runner of this editor publishes into unless told otherwise. */
+    previews?: FlowSessionRunnerOptions['previews'];
+    /** Where every runner of this editor records its walk phases. */
+    metrics?: FlowSessionRunnerOptions['metrics'];
+    /** The host declarations a runner prepares waypoints against. */
+    declarations?: EditorDeclarations;
+}
 /**
- * True when a walk of this path would resume on a parked instance. Activation
- * warming reads it to decide whether the frame already has a resumable
- * instance or one has to be walked in the background.
+ * One editor's flow sessions: the warm pool of parked application instances
+ * every runner shares, the runner factory bound to that pool, and the
+ * canonical runner that fills the canvas. Every runtime owns one.
  */
-export declare function warmInstanceServesPath(path: ResolvedFlowPath): boolean;
-/** Returns an idle document already parked at this path's exact endpoint. */
-export declare function warmInstanceAtPathEnd(path: ResolvedFlowPath): HTMLIFrameElement | null;
-export declare function createFlowSessionRunner(options?: FlowSessionRunnerOptions): {
-    /**
-     * Queues paths for materialization. Screens already delivered, failed, or
-     * claimed by a queued path are skipped — callers re-request freely.
-     */
-    materialize(paths: readonly ResolvedFlowPath[]): number;
-    /**
-     * Applies a path's terminal state on a known live document. The caller
-     * guarantees that this iframe already reached the path's route and base
-     * prefix; all gesture steps are therefore skipped and only the target's
-     * complete desired-state map is prepared. FIFO ordering keeps a document
-     * exposed by the current walk from being mutated until that walk finishes.
-     */
-    materializeOnInstance(path: ResolvedFlowPath, iframe: HTMLIFrameElement): number;
-    /**
-     * Drops queued paths the predicate rejects, releasing their pending
-     * screens so a later materialize can queue them again. Running walks are
-     * untouched. Called when the designer moves to another canvas: the
-     * paths of the canvas they left should not run ahead of the one they
-     * are looking at.
-     */
-    pruneQueue(keep: (path: ResolvedFlowPath) => boolean): number;
-    /** Live instances that may walk at once; takes effect at the next pump. */
-    setConcurrency(next: number): void;
-    /** Session state of one screen, or null when no session claims it. */
-    screenState(screenId: string): FlowScreenState | null;
-    /**
-     * Forgets a terminal delivery whose external snapshot was evicted. A
-     * running or queued screen keeps its claim and cannot be invalidated.
-     */
-    forgetScreen(screenId: string): boolean;
-    /** True while the session still owes this screen its snapshot. */
-    willDeliver(screenId: string): boolean;
-    /**
-     * True when nothing is queued or walking. Speculative callers read this
-     * before enqueueing: the runner is FIFO, so speculative work queued ahead
-     * of a designer's real request would delay it — speculation may only
-     * enter an empty runner.
-     */
-    isIdle(): boolean;
-    subscribe(listener: () => void): () => void;
-    /**
-     * Drops all session state. Running paths notice the round change at their
-     * next waypoint boundary and stop; their remaining screens re-queue on
-     * the next materialize call.
-     */
-    reset(): void;
-    /** Test/diagnostic snapshot of every tracked screen. */
-    debugScreenStates(): Record<string, FlowScreenState>;
-    /** How many finished walks currently have an instance parked for reuse. */
-    debugWarmInstancesParked(): number;
+export declare function createFlowSessions(deps?: FlowSessionsDeps): {
+    setFlowSessionWarmTtl: (ms: number) => void;
+    __flowSessionWarmDebug: {
+        boots: number;
+        reuses: number;
+        parks: number;
+        evictions: number;
+        /** Warming walks answered by renewing an already-parked instance's lease. */
+        refreshes: number;
+        /** Which supply booted, so a stray second boot is attributable. */
+        bootsByRunner: Record<string, number>;
+    };
+    evictFlowSessionWarmInstances: (ownerLabel?: string, options?: {
+        preservePinned?: boolean;
+    }) => void;
+    warmInstanceServesPath: (path: ResolvedFlowPath) => boolean;
+    warmInstanceAtPathEnd: (path: ResolvedFlowPath) => HTMLIFrameElement | null;
+    createFlowSessionRunner: (options?: FlowSessionRunnerOptions) => {
+        /**
+         * Queues paths for materialization. Screens already delivered, failed, or
+         * claimed by a queued path are skipped — callers re-request freely.
+         */
+        materialize(paths: readonly ResolvedFlowPath[]): number;
+        /**
+         * Applies a path's terminal state on a known live document. The caller
+         * guarantees that this iframe already reached the path's route and base
+         * prefix; all gesture steps are therefore skipped and only the target's
+         * complete desired-state map is prepared. FIFO ordering keeps a document
+         * exposed by the current walk from being mutated until that walk finishes.
+         */
+        materializeOnInstance(path: ResolvedFlowPath, iframe: HTMLIFrameElement): number;
+        /**
+         * Drops queued paths the predicate rejects, releasing their pending
+         * screens so a later materialize can queue them again. Running walks are
+         * untouched. Called when the designer moves to another canvas: the
+         * paths of the canvas they left should not run ahead of the one they
+         * are looking at.
+         */
+        pruneQueue(keep: (path: ResolvedFlowPath) => boolean): number;
+        /** Live instances that may walk at once; takes effect at the next pump. */
+        setConcurrency(next: number): void;
+        /** Session state of one screen, or null when no session claims it. */
+        screenState(screenId: string): FlowScreenState | null;
+        /**
+         * Forgets a terminal delivery whose external snapshot was evicted. A
+         * running or queued screen keeps its claim and cannot be invalidated.
+         */
+        forgetScreen(screenId: string): boolean;
+        /** True while the session still owes this screen its snapshot. */
+        willDeliver(screenId: string): boolean;
+        /**
+         * True when nothing is queued or walking. Speculative callers read this
+         * before enqueueing: the runner is FIFO, so speculative work queued ahead
+         * of a designer's real request would delay it — speculation may only
+         * enter an empty runner.
+         */
+        isIdle(): boolean;
+        subscribe(listener: () => void): () => void;
+        /**
+         * Drops all session state. Running paths notice the round change at their
+         * next waypoint boundary and stop; their remaining screens re-queue on
+         * the next materialize call.
+         */
+        reset(): void;
+        /** Test/diagnostic snapshot of every tracked screen. */
+        debugScreenStates(): Record<string, FlowScreenState>;
+        /** How many finished walks currently have an instance parked for reuse. */
+        debugWarmInstancesParked(): number;
+    };
+    getFlowSessionRunner: () => ReturnType<(options?: FlowSessionRunnerOptions) => {
+        /**
+         * Queues paths for materialization. Screens already delivered, failed, or
+         * claimed by a queued path are skipped — callers re-request freely.
+         */
+        materialize(paths: readonly ResolvedFlowPath[]): number;
+        /**
+         * Applies a path's terminal state on a known live document. The caller
+         * guarantees that this iframe already reached the path's route and base
+         * prefix; all gesture steps are therefore skipped and only the target's
+         * complete desired-state map is prepared. FIFO ordering keeps a document
+         * exposed by the current walk from being mutated until that walk finishes.
+         */
+        materializeOnInstance(path: ResolvedFlowPath, iframe: HTMLIFrameElement): number;
+        /**
+         * Drops queued paths the predicate rejects, releasing their pending
+         * screens so a later materialize can queue them again. Running walks are
+         * untouched. Called when the designer moves to another canvas: the
+         * paths of the canvas they left should not run ahead of the one they
+         * are looking at.
+         */
+        pruneQueue(keep: (path: ResolvedFlowPath) => boolean): number;
+        /** Live instances that may walk at once; takes effect at the next pump. */
+        setConcurrency(next: number): void;
+        /** Session state of one screen, or null when no session claims it. */
+        screenState(screenId: string): FlowScreenState | null;
+        /**
+         * Forgets a terminal delivery whose external snapshot was evicted. A
+         * running or queued screen keeps its claim and cannot be invalidated.
+         */
+        forgetScreen(screenId: string): boolean;
+        /** True while the session still owes this screen its snapshot. */
+        willDeliver(screenId: string): boolean;
+        /**
+         * True when nothing is queued or walking. Speculative callers read this
+         * before enqueueing: the runner is FIFO, so speculative work queued ahead
+         * of a designer's real request would delay it — speculation may only
+         * enter an empty runner.
+         */
+        isIdle(): boolean;
+        subscribe(listener: () => void): () => void;
+        /**
+         * Drops all session state. Running paths notice the round change at their
+         * next waypoint boundary and stop; their remaining screens re-queue on
+         * the next materialize call.
+         */
+        reset(): void;
+        /** Test/diagnostic snapshot of every tracked screen. */
+        debugScreenStates(): Record<string, FlowScreenState>;
+        /** How many finished walks currently have an instance parked for reuse. */
+        debugWarmInstancesParked(): number;
+    }>;
+    setFlowSessionConcurrency: (concurrency: number) => void;
+    resetFlowSessionRunner: () => void;
 };
-export type FlowSessionRunner = ReturnType<typeof createFlowSessionRunner>;
-export declare function getFlowSessionRunner(): FlowSessionRunner;
-/**
- * How many walks the canonical supply runs at once. The host declares it,
- * because only the host knows whether its mocked backends survive two
- * sessions; the default of one is the safe choice.
- */
-export declare function setFlowSessionConcurrency(concurrency: number): void;
-export declare function resetFlowSessionRunner(): void;
+export type FlowSessions = ReturnType<typeof createFlowSessions>;
+export type FlowSessionRunner = ReturnType<FlowSessions['createFlowSessionRunner']>;

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

@@ -34,39 +34,29 @@ export interface FrameInteractionEntryContext {
 export declare function canBeginFrameInteraction({ editMode, tool, hasRoute, liveOriginReady, backgroundOnly, }: FrameInteractionEntryContext): boolean;
 /** Keeps canvas tools authoritative except during selection or live input. */
 export declare function canvasFramePointerEventsEnabled(editMode: boolean, tool: string, interactionActive: boolean): boolean;
-/** Starts a transient live-input session for one code-backed frame. */
-export declare function beginFrameInteraction(frameId: string): void;
-/** Ends the current session. A frame id prevents stale cleanups from ending a newer one. */
-export declare function exitFrameInteraction(frameId?: string): boolean;
-/**
- * Keeps interaction scoped to the selected frame and to view-only/select mode.
- * Returns true when a session was closed.
- */
-export declare function reconcileFrameInteractionScope(activeFrameId: string | null, enabled: boolean): boolean;
-export declare function getFrameInteractionSnapshot(): FrameInteractionSnapshot;
-export declare function subscribeFrameInteraction(listener: () => void): () => void;
-/**
- * Connects the running preview viewport once its declared screen state arrives.
- * The bridge is deliberately imperative: a side panel can read and set scroll
- * without learning whether the running surface is an iframe or another host.
- */
-export declare function connectFrameInteractionViewport(frameId: string, adapter: FrameInteractionViewportAdapter): () => void;
-/**
- * Makes the frozen DOM useful immediately while its live React document warms.
- * The preview is a scroll-only bridge: navigation and form submission stay
- * contained, and the live iframe later replaces it without ending the session.
- */
-export declare function connectFrameInteractionPreview(frameId: string, root: ShadowRoot, contentElement: HTMLElement): () => void;
-/** Scrolls the running frame viewport and immediately republishes its reading. */
-export declare function setFrameInteractionScroll(position: {
-    x?: number;
-    y?: number;
-}): boolean;
 /** Hash and query changes stay in the same screen; another path leaves it. */
 export declare function frameInteractionNavigationStaysInFrame(baselineHref: string, nextHref: string): boolean;
 /** Blocks document navigation while leaving ordinary in-screen events intact. */
 export declare function installFrameInteractionNavigationGuard(view: Window, document: Document): () => void;
-/** Connects a same-origin live iframe, including Escape and nested scroll tracking. */
-export declare function connectFrameInteractionIframe(frameId: string, iframe: HTMLIFrameElement): () => void;
-/** Test seam for independent runtime cases. */
-export declare function resetFrameInteraction(): void;
+/**
+ * The per-runtime live-input session: the frame in live input, its phase and
+ * scroll reading, the connected viewport bridge, and the listeners the shell
+ * and panels subscribe through. The bodies below are the former module-level
+ * functions, closed over instance state instead of module state.
+ */
+export declare function createFrameInteraction(): {
+    beginFrameInteraction: (frameId: string) => void;
+    exitFrameInteraction: (frameId?: string) => boolean;
+    reconcileFrameInteractionScope: (activeFrameId: string | null, enabled: boolean) => boolean;
+    getFrameInteractionSnapshot: () => FrameInteractionSnapshot;
+    subscribeFrameInteraction: (listener: () => void) => () => void;
+    connectFrameInteractionViewport: (frameId: string, adapter: FrameInteractionViewportAdapter) => () => void;
+    connectFrameInteractionPreview: (frameId: string, root: ShadowRoot, contentElement: HTMLElement) => () => void;
+    setFrameInteractionScroll: (position: {
+        x?: number;
+        y?: number;
+    }) => boolean;
+    connectFrameInteractionIframe: (frameId: string, iframe: HTMLIFrameElement) => () => void;
+    resetFrameInteraction: () => void;
+};
+export type FrameInteraction = ReturnType<typeof createFrameInteraction>;

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

@@ -1,4 +1,4 @@
-import type { PageModel } from './store';
+import type { PageModel } from './store.js';
 /**
  * Host-declared presentation of one branch kind.
  *
@@ -97,6 +97,8 @@ export declare const FRAME_LABEL_STYLE: {
     readonly pillSize: 12;
     readonly pillPaddingY: 4;
     readonly pillPaddingX: 10;
+    /** Text of the unclassified-surfaces badge: a warning tint on the dark surface. */
+    readonly unclassified: "#f5c86b";
     /** Bottom margin between the label and its frame. */
     readonly marginBottom: 8;
     readonly surface: "#343441";
@@ -127,7 +129,11 @@ export declare const FRAME_LABEL_OVERLAY_CLEARANCE: number;
  * of sixty frames reads as a coloured structure instead of grey mush.
  */
 export declare const FRAME_LABEL_COMPACT_ZOOM = 0.35;
-export declare function setFrameBranchKinds(defs: readonly FrameBranchKindDef[], labels?: FrameLabelLabels): void;
-export declare function getFrameBranchKinds(): readonly FrameBranchKindDef[];
-export declare function getFrameLabelLabels(): FrameLabelLabels | undefined;
-export declare function frameBranchKindFor(kind: string): FrameBranchKindDef;
+/** One editor's declared frame branch kinds and label labels. */
+export declare function createFrameLabels(): {
+    setFrameBranchKinds: (defs: readonly FrameBranchKindDef[], labels?: FrameLabelLabels) => void;
+    getFrameBranchKinds: () => readonly FrameBranchKindDef[];
+    getFrameLabelLabels: () => FrameLabelLabels | undefined;
+    frameBranchKindFor: (kind: string) => FrameBranchKindDef;
+};
+export type FrameLabels = ReturnType<typeof createFrameLabels>;