@pygmalionjs/pygmalion 0.7.4 → 0.8.0

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

@@ -1,5 +1,5 @@
 import type { RoutePreviewArtifactBundle } from './routePreview.js';
-import type { DesignScreenCase, StoryboardEnvironment } from './designImport';
+import type { DesignScreenCase, StoryboardEnvironment } from './designImport.js';
 export interface PreviewRecipeIdentity {
     id: string;
     recipe: unknown;
@@ -143,17 +143,6 @@ export declare function createPreviewFrameFingerprint(screen: StoryboardCaptureR
 }, options?: {
     dependencyDigest?: string;
 }): string;
-/**
- * Per-route content digests published by the storyboard scan.
- *
- * A source revision remains the provenance boundary. Within that boundary, the
- * route digest makes an edited screen move without invalidating unrelated ones.
- */
-export declare function setPreviewDependencyDigests(routes: readonly {
-    path?: string;
-    dependencyDigest?: string;
-}[] | null): void;
-export declare function previewDependencyDigest(route: string): string | undefined;
 export interface PreviewFramePage {
     canonicalId: string;
     route: string;
@@ -187,8 +176,6 @@ export interface RoutePreviewFrameRecipe {
     interactions?: unknown;
     assertions?: unknown;
 }
-/** The recipe behind createRoutePreviewFrameFingerprint, for the same page. */
-export declare function routePreviewFrameRecipe(page: PreviewFramePage, baselineEnvironment?: StoryboardEnvironment): RoutePreviewFrameRecipe;
 /**
  * Resolves the page identity a returned frame must seed.
  *
@@ -200,14 +187,6 @@ export declare function routePreviewFrameRecipe(page: PreviewFramePage, baseline
 export declare function resolveRoutePreviewFrameRequestPage(request: PreviewArtifactFrameRequest, authored?: PreviewFramePage): (PreviewFramePage & {
     fingerprint?: string;
 }) | null;
-/**
- * Identity of one frame's capture, derived the same way wherever it is needed.
- *
- * The revision is folded in until a dependency-closure digest replaces it, so a
- * frame is invalidated no less often than before; what changes is that a consumer
- * now captures per frame instead of demanding the whole catalog up front.
- */
-export declare function createRoutePreviewFrameFingerprint(page: PreviewFramePage, previewRevision: string, baselineEnvironment?: StoryboardEnvironment): string;
 /** The reproducible capture recipe, kept separate from changing source content. */
 export declare function createRoutePreviewFrameRecipeFingerprint(page: PreviewFramePage, baselineEnvironment?: StoryboardEnvironment): string;
 export declare function createPreviewCacheNamespace({ sourceRevision, recipes, recipeVersion, scope, }: PreviewCacheNamespaceOptions): string;
@@ -260,3 +239,14 @@ export declare function bootstrapPreviewArtifact({ namespace, sourceRevision, tr
     generate?: boolean;
     priority?: number;
 }): Promise<PreviewArtifactBootstrapResult>;
+/** The route dependency digests the host declared for one editor's previews. */
+export declare function createPreviewDependencyDigests(): {
+    setPreviewDependencyDigests: (routes: readonly {
+        path?: string;
+        dependencyDigest?: string;
+    }[] | null) => void;
+    previewDependencyDigest: (route: string) => string | undefined;
+    routePreviewFrameRecipe: (page: PreviewFramePage, baselineEnvironment?: StoryboardEnvironment) => RoutePreviewFrameRecipe;
+    createRoutePreviewFrameFingerprint: (page: PreviewFramePage, previewRevision: string, baselineEnvironment?: StoryboardEnvironment) => string;
+};
+export type PreviewDependencyDigests = ReturnType<typeof createPreviewDependencyDigests>;

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

@@ -1,5 +1,5 @@
 import { PYGMALION_PREVIEW_CAPTURE_PROGRESS_SUFFIX } from '../contract/paths.js';
-import type { EditorTransport } from '../contract/transport.js';
+import type { EditorRuntime } from '../core/runtime.js';
 export { PYGMALION_PREVIEW_CAPTURE_PROGRESS_SUFFIX };
 export type PygmalionPreviewCaptureProgressPhase = 'idle' | 'queued' | 'preparing' | 'capturing' | 'retrying' | 'finalizing';
 export interface PygmalionPreviewCaptureProgress {
@@ -25,10 +25,6 @@ export interface PygmalionPreviewCaptureCatalogProgress {
     jobCount: number;
     updatedAt?: number;
 }
-export declare function getPreviewCaptureCatalogProgress(): PygmalionPreviewCaptureCatalogProgress;
-export declare function subscribePreviewCaptureCatalogProgress(listener: () => void): () => void;
-export declare function publishPreviewCaptureCatalogProgress(value: PygmalionPreviewCaptureCatalogProgress): void;
-export declare function resetPreviewCaptureCatalogProgress(): void;
 export declare function previewCaptureProgressEndpoint(artifactEndpoint: string): string;
 export declare function normalizePreviewCaptureProgress(value: unknown): PygmalionPreviewCaptureProgress | null;
 export interface PreviewCaptureProgressMergeState {
@@ -49,4 +45,12 @@ export declare function mergePreviewCaptureProgress(worker: PygmalionPreviewCapt
  * Polls the given transport, or the mounted editor's when rendered inside
  * one, and only while that transport has a progress endpoint configured.
  */
-export declare function usePygmalionPreviewCaptureProgress(transport?: EditorTransport | null): PygmalionPreviewCaptureProgress;
+export declare function usePygmalionPreviewCaptureProgress(runtime: EditorRuntime): PygmalionPreviewCaptureProgress;
+/** One editor's catalog capture progress channel, published by the canvas probe. */
+export declare function createPreviewCaptureProgress(): {
+    getPreviewCaptureCatalogProgress: () => PygmalionPreviewCaptureCatalogProgress;
+    subscribePreviewCaptureCatalogProgress: (listener: () => void) => () => void;
+    publishPreviewCaptureCatalogProgress: (value: PygmalionPreviewCaptureCatalogProgress) => void;
+    resetPreviewCaptureCatalogProgress: () => void;
+};
+export type PreviewCaptureProgress = ReturnType<typeof createPreviewCaptureProgress>;

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

@@ -1,4 +1,4 @@
-import type { StoryboardEnvironment } from './designImport';
+import type { StoryboardEnvironment } from './designImport.js';
 /** A host-declared value for a portable browser condition such as color scheme. */
 export interface PreviewEnvironmentControlOptionDef {
     value: string;
@@ -17,19 +17,16 @@ export interface PreviewEnvironmentControlDef {
     defaultValue: string;
     options: readonly PreviewEnvironmentControlOptionDef[];
 }
-/** Configure the inspector controls once from the host application. */
-export declare function setPreviewEnvironmentControls(next: readonly PreviewEnvironmentControlDef[]): void;
-export declare function getPreviewEnvironmentControls(): readonly PreviewEnvironmentControlDef[];
-/** Explicit choices only; defaults stay implicit so they do not alter identity. */
-export declare function getPreviewEnvironmentControlSelections(): Readonly<Record<string, string>>;
-export declare function getPreviewEnvironmentControlValue(controlId: string): string | undefined;
-/**
- * Selects a condition. Defaults are visually selected but remain inert until a
- * user changes a control, preserving existing exact preview artifact identities.
- */
-export declare function setPreviewEnvironmentControlValue(controlId: string, value: string): void;
-export declare function clearPreviewEnvironmentControlValues(): void;
-/** Merged explicit override for the active frame, if the user selected one. */
-export declare function getPreviewEnvironmentOverride(): StoryboardEnvironment | undefined;
-export declare function subscribePreviewEnvironmentControls(listener: () => void): () => void;
-export declare function getPreviewEnvironmentControlRevision(): number;
+/** One editor's declared preview environment controls and their selections. */
+export declare function createPreviewEnvironmentControls(): {
+    setPreviewEnvironmentControls: (next: readonly PreviewEnvironmentControlDef[]) => void;
+    getPreviewEnvironmentControls: () => readonly PreviewEnvironmentControlDef[];
+    getPreviewEnvironmentControlSelections: () => Readonly<Record<string, string>>;
+    getPreviewEnvironmentControlValue: (controlId: string) => string | undefined;
+    setPreviewEnvironmentControlValue: (controlId: string, value: string) => void;
+    clearPreviewEnvironmentControlValues: () => void;
+    getPreviewEnvironmentOverride: () => StoryboardEnvironment | undefined;
+    subscribePreviewEnvironmentControls: (listener: () => void) => () => void;
+    getPreviewEnvironmentControlRevision: () => number;
+};
+export type PreviewEnvironmentControls = ReturnType<typeof createPreviewEnvironmentControls>;

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

@@ -1,17 +1,12 @@
 export declare const PREVIEW_INTENT_LIMIT = 2;
-/** Marks a frame as likely to be opened next. Returns true when the slot set changed. */
-export declare function notePreviewIntent(pageId: string, limit?: number): boolean;
-/**
- * Drops preparation for a frame.
- *
- * Leaving a frame is not a reason to drop it — the work is already paid for and
- * the designer often comes back. This exists for frames that stop being
- * previewable at all, such as one whose layers have been imported.
- */
-export declare function releasePreviewIntent(pageId: string): void;
-export declare function hasPreviewIntent(pageId: string): boolean;
-export declare function getPreviewIntentSlots(): readonly string[];
-export declare function subscribePreviewIntent(listener: () => void): () => void;
-/** Fires only when this page enters or leaves the intent slots. */
-export declare function subscribePreviewIntentFor(pageId: string, listener: () => void): () => void;
-export declare function resetPreviewIntent(): void;
+/** One editor's preview intent slots: the frames a reader means to see next. */
+export declare function createPreviewIntent(): {
+    notePreviewIntent: (pageId: string, limit?: number) => boolean;
+    releasePreviewIntent: (pageId: string) => void;
+    hasPreviewIntent: (pageId: string) => boolean;
+    getPreviewIntentSlots: () => readonly string[];
+    subscribePreviewIntent: (listener: () => void) => () => void;
+    subscribePreviewIntentFor: (pageId: string, listener: () => void) => () => void;
+    resetPreviewIntent: () => void;
+};
+export type PreviewIntent = ReturnType<typeof createPreviewIntent>;

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

@@ -124,6 +124,10 @@ export interface PreviewSweeper {
 }
 export declare const SWEEP_INTERACTION_CHUNK_SIZE = 8;
 export declare const SWEEP_INTERACTION_REQUEST_CAP = 32;
-export declare function getPreviewSweepStatus(): PreviewSweepStatus;
-export declare function subscribePreviewSweep(listener: () => void): () => void;
-export declare function createPreviewSweeper(deps: PreviewSweeperDeps, options?: PreviewSweeperOptions): PreviewSweeper;
+/** One editor's sweep status channel and the sweeper factory that publishes into it. */
+export declare function createPreviewSweepChannel(): {
+    getPreviewSweepStatus: () => PreviewSweepStatus;
+    subscribePreviewSweep: (listener: () => void) => () => void;
+    createPreviewSweeper: (deps: PreviewSweeperDeps, options?: PreviewSweeperOptions) => PreviewSweeper;
+};
+export type PreviewSweepChannel = ReturnType<typeof createPreviewSweepChannel>;

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

@@ -1,7 +1,9 @@
-import type { StoryboardEnvironment } from './designImport';
-import { type DesignFrameHeightMode } from './frameHeight';
-import { type LivePreviewInstances } from './livePreviewInstances';
-import type { StoryboardGraph } from './storyboardGraph';
+import type { StoryboardEnvironment } from './designImport.js';
+import { type DesignFrameHeightMode } from './frameHeight.js';
+import { type LivePreviewInstances } from './livePreviewInstances.js';
+import { type PreviewIntent } from './previewIntent.js';
+import type { StoryboardGraph } from './storyboardGraph.js';
+import type { StoryboardGraphRuntime } from './storyboardGraphRuntime.js';
 /** The page facts warmup planning reads; a store PageModel satisfies it. */
 export interface PreviewWarmupPage {
     id: string;
@@ -55,8 +57,6 @@ export interface StartPreviewWarmupOptions {
     getPages: () => readonly PreviewWarmupPage[];
     appOrigin: string;
     baselineEnvironment?: StoryboardEnvironment;
-    /** Test seam — defaults to the shared pool. */
-    instances?: Pick<LivePreviewInstances, 'warm'>;
     /** Test seam — defaults to the published storyboard graph. */
     getGraph?: () => StoryboardGraph | null;
     /** Test seam — defaults to navigator.deviceMemory. */
@@ -66,6 +66,10 @@ export interface StartPreviewWarmupOptions {
  * Warms the top instance group once and, from then on, prepares the
  * storyboard successors of whichever screen becomes active.
  *
+ * `livePreviews` is the pool of the runtime this warmup serves — the one its
+ * frames lease from, so the first real lease of a warmed group finds the
+ * running document.
+ *
  * Returns a dispose function that stops the selection reaction. Warm boots
  * already in flight finish on their own; the pool treats them as ordinary
  * instances afterwards.
@@ -75,4 +79,12 @@ export interface StartPreviewWarmupOptions {
  * because both end in an offscreen application document the device cannot
  * spare (see the module comment for the measured cost).
  */
-export declare function startPreviewWarmup(options: StartPreviewWarmupOptions): () => void;
+/** What a warmup needs from the runtime it serves. */
+export interface PreviewWarmupRuntime {
+    readonly schedulers: {
+        readonly livePreviews: LivePreviewInstances;
+        readonly previewIntent: PreviewIntent;
+    };
+    readonly declarations: Pick<StoryboardGraphRuntime, 'getStoryboardGraph'>;
+}
+export declare function startPreviewWarmup(runtime: PreviewWarmupRuntime, options: StartPreviewWarmupOptions): () => void;

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

@@ -1,7 +1,7 @@
 import type { EditorTransport } from '../contract/transport.js';
 import type { PygmalionDesignSessionStatus, PygmalionDevMirrorStatus, PygmalionRevertResult, PygmalionSourceRefs } from '../contract/types.js';
-import type { InspectApplyPayload } from './inspect';
-import type { InspectApplyResult, InspectImpactResult, InspectPreviewResult } from './host';
+import type { InspectApplyPayload } from './inspect.js';
+import type { InspectApplyResult, InspectImpactResult, InspectPreviewResult } from './host.js';
 export type { PygmalionDesignSessionStatus, PygmalionDevMirrorStatus, PygmalionIntegrationState, PygmalionRevertResult, PygmalionSessionOperation, PygmalionSourceRef, PygmalionSourceRefs, PygmalionVisualOperation, PygmalionVisualRevertOperation, } from '../contract/types.js';
 export interface PygmalionProjectRuntimeOptions {
     /**

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

@@ -34,5 +34,9 @@ export interface RegistryEntry {
     };
 }
 export type ComponentRegistry = Record<string, RegistryEntry>;
-export declare function setComponentRegistry(r: ComponentRegistry): void;
-export declare function getRegistry(): ComponentRegistry;
+/** One editor's component registry: the components the host declared. */
+export declare function createRegistry(): {
+    setComponentRegistry: (r: ComponentRegistry) => void;
+    getRegistry: () => ComponentRegistry;
+};
+export type Registry = ReturnType<typeof createRegistry>;

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

@@ -1,24 +1,24 @@
-import type { DesignComponentConnectionDef } from './componentConnections';
+import type { DesignComponentConnectionDef } from './componentConnections.js';
 import { TransportError } from '../contract/errors.js';
 import type { EditorTransport } from '../contract/transport.js';
-import type { DesignCodegenProjectManifest } from './designCompiler';
-import type { DesignImportAsset, DesignImportInitialPage, DesignScenarioSource } from './designImport';
-import type { FrameBranchKindDef, FrameLabelLabels } from './frameLabels';
-import type { ScreenLaneDef } from './frameLanes';
-import { type ScreenStateAxisDef } from './interactiveStates';
-import type { PreviewEnvironmentControlDef } from './previewEnvironmentControls';
-import type { RegistryEntry } from './registry';
-import type { ScenarioCoverageClaim } from './scenarioCoverage';
-import type { ScreenCardDef } from './screenCards';
-import type { ScreenDimensionDef } from './screenDimensions';
-import type { ScreenFlowPath } from './screenFlows';
-import type { ScreenListDef } from './screenLists';
-import type { SectionHeaderDef, SectionHeaderLabels } from './sectionHeaders';
-import type { SessionPresetDef } from './sessionPresets';
-import type { StoryboardDefinition } from './storyboardGraph';
-import type { SurfaceClassification } from './surfaceDemands';
-import type { TokenDef } from './tokens';
-import type { ViewportPresetDef } from './viewportPresets';
+import type { DesignCodegenProjectManifest } from './designCompiler.js';
+import type { DesignImportAsset, DesignImportInitialPage, DesignScenarioSource } from './designImport.js';
+import type { FrameBranchKindDef, FrameLabelLabels } from './frameLabels.js';
+import type { ScreenLaneDef } from './frameLanes.js';
+import { type ScreenStateAxisDef } from './interactiveStates.js';
+import type { PreviewEnvironmentControlDef } from './previewEnvironmentControls.js';
+import type { RegistryEntry } from './registry.js';
+import type { ScenarioCoverageClaim } from './scenarioCoverage.js';
+import type { ScreenCardDef } from './screenCards.js';
+import type { ScreenDimensionDef } from './screenDimensions.js';
+import type { ScreenFlowPath } from './screenFlows.js';
+import type { ScreenListDef } from './screenLists.js';
+import type { SectionHeaderDef, SectionHeaderLabels } from './sectionHeaders.js';
+import type { SessionPresetDef } from './sessionPresets.js';
+import type { StoryboardDefinition } from './storyboardGraph.js';
+import type { SurfaceClassification } from './surfaceDemands.js';
+import type { TokenDef } from './tokens.js';
+import type { ViewportPresetDef } from './viewportPresets.js';
 export declare const PYGMALION_REVISION_CATALOG_VERSION: 1;
 /** A routed page whose identity is complete at the JSON boundary. */
 export interface PygmalionRevisionScreenPage extends DesignImportInitialPage {

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

@@ -1,19 +1,20 @@
-import { type DesignComponentConnectionDef } from './componentConnections';
-import { type FrameBranchKindDef, type FrameLabelLabels } from './frameLabels';
-import { type ScreenLaneDef } from './frameLanes';
-import { type ScreenStateAxisDef } from './interactiveStates';
-import { type PreviewEnvironmentControlDef } from './previewEnvironmentControls';
-import { type ComponentRegistry, type RegistryEntry } from './registry';
-import { type ScenarioCoverageClaim } from './scenarioCoverage';
-import { type ScreenCardDef } from './screenCards';
-import { type ScreenDimensionDef } from './screenDimensions';
-import { type ScreenFlowPath } from './screenFlows';
-import { type ScreenListDef } from './screenLists';
-import { type SectionHeaderDef, type SectionHeaderLabels } from './sectionHeaders';
-import { type SessionPresetDef } from './sessionPresets';
-import { type SurfaceClassification } from './surfaceDemands';
-import { type TokenDef } from './tokens';
-import { type ViewportPresetDef } from './viewportPresets';
+import type { EditorDeclarations } from './declarations.js';
+import type { DesignComponentConnectionDef } from './componentConnections.js';
+import type { FrameBranchKindDef, FrameLabelLabels } from './frameLabels.js';
+import type { ScreenLaneDef } from './frameLanes.js';
+import type { ScreenStateAxisDef } from './interactiveStates.js';
+import type { PreviewEnvironmentControlDef } from './previewEnvironmentControls.js';
+import type { ComponentRegistry, RegistryEntry } from './registry.js';
+import type { ScenarioCoverageClaim } from './scenarioCoverage.js';
+import type { ScreenCardDef } from './screenCards.js';
+import type { ScreenDimensionDef } from './screenDimensions.js';
+import type { ScreenFlowPath } from './screenFlows.js';
+import type { ScreenListDef } from './screenLists.js';
+import type { SectionHeaderDef, SectionHeaderLabels } from './sectionHeaders.js';
+import type { SessionPresetDef } from './sessionPresets.js';
+import type { SurfaceClassification } from './surfaceDemands.js';
+import type { TokenDef } from './tokens.js';
+import type { ViewportPresetDef } from './viewportPresets.js';
 /**
  * Mutable declaration singletons that must move with one revision catalog.
  * The component implementations remain supplied by the host bundle; the
@@ -59,4 +60,4 @@ export declare function bindRevisionComponentRegistry(manifest: Readonly<Record<
  * restore it if a declaration installer or the page commit rejects. A failed
  * revision therefore never remains half-installed for the next render.
  */
-export declare function installRevisionCatalogSnapshot(declarations: RevisionCatalogDeclarations, pageCommit: (() => void) | RevisionCatalogPageCommit): void;
+export declare function installRevisionCatalogSnapshot(declarations: EditorDeclarations, next: RevisionCatalogDeclarations, pageCommit: (() => void) | RevisionCatalogPageCommit): void;

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

@@ -1,8 +1,10 @@
 import { type RoutePreviewArtifactBundleV2 } from './routePreviewArtifactV2.js';
 import { type RoutePreviewArtifactBundleV3, type RoutePreviewArtifactV3Diagnostic, type RoutePreviewArtifactV3Status } from './routePreviewArtifactV3.js';
-import type { StoryboardEnvironment } from './designImport';
-import type { RoutePreviewFrameRecipe } from './previewBootstrap';
-import { type InstanceResolver } from './fiberMap';
+import type { StoryboardEnvironment } from './designImport.js';
+import type { RoutePreviewFrameRecipe } from './previewBootstrap.js';
+import { type InstanceResolver } from './fiberMap.js';
+import { type StateSwitchMetrics } from './stateSwitchMetrics.js';
+import { type EditorDeclarations } from './declarations.js';
 type SlotRelease = () => void;
 export interface RoutePreviewRecipe {
     namespace?: string;
@@ -142,38 +144,6 @@ export declare function recommendedRoutePreviewConcurrency(capabilities?: {
     hardwareConcurrency?: number;
     deviceMemory?: number;
 }): number;
-/** Coalesces keyed notifications; nested batches flush once at the outermost end. */
-export declare function beginSnapshotNotificationBatch(): void;
-export declare function endSnapshotNotificationBatch(): void;
-export declare function subscribeRoutePreviewSnapshots(listener: () => void): () => void;
-export declare function getRoutePreviewSnapshotRevision(): number;
-/** Fires for writes, hydration verdicts, and evictions of exactly this key. */
-export declare function subscribeRoutePreviewSnapshotKey(key: string, listener: () => void): () => void;
-/** Changes when this key's channel fires or a whole-store event bumps the epoch. */
-export declare function getRoutePreviewSnapshotKeyVersion(key: string): number;
-export declare function subscribeRoutePreviewArtifactKey(cacheKey: string, listener: () => void): () => void;
-export declare function getRoutePreviewArtifactKeyVersion(cacheKey: string): number;
-/** Artifact resolutions live in the frame-identity key space, not the recipe one. */
-export declare function subscribeRoutePreviewArtifactIdentity(id: string, fingerprint: string | undefined, listener: () => void): () => void;
-export declare function getRoutePreviewArtifactIdentityVersion(id: string, fingerprint?: string): number;
-/** Pairs with getActiveRoutePreviewCount; slot events never reach the snapshot channel. */
-export declare function subscribeRoutePreviewSlotCount(listener: () => void): () => void;
-export declare function getActiveRoutePreviewCount(): number;
-export declare function hasRoutePreviewSnapshot(key: string): boolean;
-/** A last-known stale artifact is drawable, but it is not a current warm hit. */
-export declare function hasExactRoutePreviewSnapshot(key: string): boolean;
-export declare function getRoutePreviewArtifactOutcome(key: string): RoutePreviewArtifactOutcome | null;
-/**
- * Artifact outcomes change only when a bundle is seeded or cleared, so frames
- * subscribe to this instead of the per-snapshot revision. Reading the outcome
- * without it leaves memoized frames on a replaced bundle forever.
- */
-export declare function getRoutePreviewArtifactRevision(): number;
-export declare function subscribeRoutePreviewArtifacts(listener: () => void): () => void;
-export declare function getRoutePreviewArtifactResolution(id: string, fingerprint?: string): RoutePreviewArtifactResolution;
-/** Publishes cache-probe state for one or more exact frame identities. */
-export declare function setRoutePreviewArtifactResolution(frames: readonly RoutePreviewArtifactFrameIdentity[], resolution: RoutePreviewArtifactResolution): void;
-export declare function isRoutePreviewSnapshotHydrated(key: string): boolean;
 /**
  * Persistent cache identity excluding random mirror ports.
  * By normalizing the object key order, the same screen recipe always uses the same key.
@@ -183,18 +153,6 @@ export interface RoutePreviewFrameRequestOptions {
     priority?: number;
 }
 type RoutePreviewFrameRequester = (frames: readonly RoutePreviewArtifactFrameIdentity[], options?: RoutePreviewFrameRequestOptions) => RoutePreviewArtifactFrameRequestResult | Promise<RoutePreviewArtifactFrameRequestResult> | void;
-/** Installed by the host adapter, which owns the transport. */
-export declare function setRoutePreviewArtifactFrameRequester(requester: RoutePreviewFrameRequester | null): () => void;
-/**
- * When an exact artifact endpoint exists, background cache misses stay cheap:
- * only an active or deliberately hovered frame may boot the live application.
- */
-export declare function setRoutePreviewArtifactEndpointConfigured(configured: boolean): void;
-export declare function isRoutePreviewArtifactEndpointConfigured(): boolean;
-export declare function shouldStartRoutePreviewProducer({ detailActive, previewIntended, }: {
-    detailActive: boolean;
-    previewIntended: boolean;
-}): boolean;
 /** A persisted exact frozen snapshot already satisfies the active editor frame. */
 export declare function shouldRequestRoutePreviewArtifactFrame({ cacheHydrated, detailActive, hasRoute, layersImported, hasExactArtifact, hasExactSnapshot, hasFingerprint, }: {
     cacheHydrated: boolean;
@@ -205,97 +163,7 @@ export declare function shouldRequestRoutePreviewArtifactFrame({ cacheHydrated,
     hasExactSnapshot: boolean;
     hasFingerprint: boolean;
 }): boolean;
-/**
- * Asks for one frame's capture, once per identity.
- *
- * Called when a frame becomes visible, which is why the editor no longer needs
- * every screen captured before it can show anything. A changed fingerprint is a
- * new identity, so an edited screen is requested again.
- */
-export declare function requestRoutePreviewArtifactFrame(id: string, fingerprint?: string, options?: {
-    retry?: boolean;
-    recipeFingerprint?: string;
-    recipe?: RoutePreviewFrameRecipe;
-    priority?: number;
-}): Promise<RoutePreviewArtifactResolution> | null;
-/**
- * Asks for many frames' captures in one requester call.
- *
- * A canvas being filled and the background sweep both name frames in chunks,
- * and a chunk must not fan out into one transport round trip per frame — nor
- * into one capture job per frame, which is what left the worker's lanes idle.
- * Identities already resolved exactly, already generating, or already failed
- * are skipped (an error is retried only on request); the remaining frames
- * share a single requester call and a single resolution, and each identity
- * joins the same in-flight dedupe map the single-frame request uses. Each
- * frame's recipe travels with it, so a generator can reproduce a variant
- * instead of re-capturing what the host declared for the id.
- */
-export declare function requestRoutePreviewArtifactFrames(frames: readonly RoutePreviewArtifactFrameIdentity[], options?: {
-    retry?: boolean;
-    priority?: number;
-}): Promise<RoutePreviewArtifactResolution> | null;
-export declare function createRoutePreviewRecipeKey(recipe: RoutePreviewRecipe): string;
-/**
- * Returns the compact body plus pooled style input without reconstructing a
- * complete HTML snapshot for every frame.
- */
-export declare function getRoutePreviewShadowArtifact(key: string): RoutePreviewShadowArtifact | null;
-/**
- * Extracts the artifact source SHA from a runtime previewRevision.
- * Runtime revisions are `<sourceSha>:<sessionRevision>`, while artifact bundles
- * are stamped with the source SHA alone. Every identity comparison and every
- * artifact request must go through this so both sides agree.
- */
-export declare function routePreviewSourceRevision(previewRevision: string): string;
-/**
- * Synchronously inject build-time snapshots into the memory cache before mounting the app.
- * IndexedDB storage uses the existing setRoutePreviewSnapshot write-through as is.
- */
-export declare function seedRoutePreviewArtifacts(bundle: RoutePreviewArtifactBundle | null | undefined, options: {
-    namespace: string;
-    previewRevision: string;
-    appOrigin: string;
-    baselineEnvironment?: StoryboardEnvironment;
-    allowStaleIdentity?: boolean;
-    /** Endpoint-validated v3 subsets may prove freshness by frame fingerprint. */
-    allowMatchingFrameIdentity?: boolean;
-    pages: readonly RoutePreviewArtifactPage[];
-}): RoutePreviewArtifactSeedResult;
-export declare function setRoutePreviewCacheNamespace(namespace: string | null | undefined): void;
-export declare function getRoutePreviewCacheNamespace(): string;
 export declare function routePreviewPruneKeys(records: readonly Pick<RoutePreviewPersistentRecord, 'key' | 'bytes' | 'lastAccess'>[]): string[];
-/** Persistence seam for node testing. It is not exposed to public package entrypoint. */
-export declare function setRoutePreviewPersistenceForTests(persistence: RoutePreviewPersistence | null | undefined): void;
-/**
- * Several iframes are prepared in parallel, but computed style → NodeModel conversion is performed in parallel.
- * Limited to 2-lane dedicated to main thread. Requests for the same screen are combined into one.
- */
-export declare function scheduleRouteLayerCapture<T>(key: string, priority: number, task: () => Promise<T>): Promise<T>;
-/** Limits the number of actual app iframes that will boot simultaneously across the entire editor. */
-export declare function acquireRoutePreviewSlot(priority?: number): RoutePreviewSlotTicket;
-export declare function setRoutePreviewConcurrency(value: number): void;
-export declare function getRoutePreviewSnapshot(key: string): string | null;
-/** Immediately records to memory and writes through to IndexedDB. */
-export declare function setRoutePreviewSnapshot(key: string, snapshot: string): boolean;
-/**
- * Raise persistent hits to memory LRU. miss/corrupt does not resolve until judgment is complete
- * It is possible to prevent a race in which the caller acquires the live iframe slot first.
- */
-export declare function hydrateRoutePreviewSnapshot(key: string): Promise<string | null>;
-/** Hydrates multiple screen recipes in parallel to fill the memory cache before the first paint. */
-export declare function prehydrateRoutePreviewSnapshots(keys: readonly string[]): Promise<Map<string, string>>;
-export declare function clearRoutePreviewSnapshots(namespace?: string): void;
-/**
- * Asynchronous operations with the same preview key share one slot and promise.
- * The caller must complete the actual iframe preparation and serialization within the task.
- */
-export declare function scheduleRoutePreviewTask<T>(key: string, priority: number, task: () => Promise<T>): Promise<T>;
-/**
- * High-level scheduling API that uses snapshot cache and in-flight dedupe together.
- * The caller should only express priority as to whether or not it is nearViewport, and the call itself should not be blocked.
- */
-export declare function scheduleRoutePreviewSnapshot(key: string, priority: number, task: () => Promise<string | null>, runtimeKey?: string): Promise<string | null>;
 /** Maps live elements to their source metadata for stamping (docs/perf-contracts.md). */
 export interface RoutePreviewSourceAnnotator {
     /** Resolves the registry component instance rooted at an element. */
@@ -306,7 +174,85 @@ export interface RoutePreviewSourceAnnotator {
 export interface SerializeRoutePreviewOptions {
     annotate?: RoutePreviewSourceAnnotator;
 }
-/** Fix the running app document as a script-less srcDoc and terminate the API, timer, and React runtime. */
-export declare function serializeRoutePreview(iframe: HTMLIFrameElement, fallbackUrl: string, options?: SerializeRoutePreviewOptions): string | null;
 export declare function waitForRoutePreviewSettle(ms?: number): Promise<void>;
+/**
+ * The per-runtime preview cache: snapshots and their persistence, artifact
+ * frames and outcomes, capture slots and the layer-capture queue, the frame
+ * requester, and the per-key invalidation channels components subscribe to.
+ * The bodies below are the former module-level functions, closed over
+ * instance state instead of module state.
+ */
+export interface RoutePreviewCacheOptions {
+    /** Where producer decisions are counted; the runtime passes its own metrics. */
+    metrics?: Pick<StateSwitchMetrics, 'recordRoutePreviewProducerDecision'>;
+    /** The host declarations this cache keys and installs against; the runtime passes its own. */
+    declarations?: EditorDeclarations;
+}
+export declare function createRoutePreviewCache(options?: RoutePreviewCacheOptions): {
+    beginSnapshotNotificationBatch: () => void;
+    endSnapshotNotificationBatch: () => void;
+    subscribeRoutePreviewSnapshots: (listener: () => void) => () => void;
+    getRoutePreviewSnapshotRevision: () => number;
+    subscribeRoutePreviewSnapshotKey: (key: string, listener: () => void) => () => void;
+    getRoutePreviewSnapshotKeyVersion: (key: string) => number;
+    subscribeRoutePreviewArtifactKey: (cacheKey: string, listener: () => void) => () => void;
+    getRoutePreviewArtifactKeyVersion: (cacheKey: string) => number;
+    subscribeRoutePreviewArtifactIdentity: (id: string, fingerprint: string | undefined, listener: () => void) => () => void;
+    getRoutePreviewArtifactIdentityVersion: (id: string, fingerprint?: string) => number;
+    subscribeRoutePreviewSlotCount: (listener: () => void) => () => void;
+    getActiveRoutePreviewCount: () => number;
+    hasRoutePreviewSnapshot: (key: string) => boolean;
+    hasExactRoutePreviewSnapshot: (key: string) => boolean;
+    getRoutePreviewArtifactOutcome: (key: string) => RoutePreviewArtifactOutcome | null;
+    getRoutePreviewArtifactRevision: () => number;
+    subscribeRoutePreviewArtifacts: (listener: () => void) => () => void;
+    getRoutePreviewArtifactResolution: (id: string, fingerprint?: string) => RoutePreviewArtifactResolution;
+    setRoutePreviewArtifactResolution: (frames: readonly RoutePreviewArtifactFrameIdentity[], resolution: RoutePreviewArtifactResolution) => void;
+    isRoutePreviewSnapshotHydrated: (key: string) => boolean;
+    setRoutePreviewArtifactFrameRequester: (requester: RoutePreviewFrameRequester | null) => () => void;
+    setRoutePreviewArtifactEndpointConfigured: (configured: boolean) => void;
+    isRoutePreviewArtifactEndpointConfigured: () => boolean;
+    shouldStartRoutePreviewProducer: ({ detailActive, previewIntended, }: {
+        detailActive: boolean;
+        previewIntended: boolean;
+    }) => boolean;
+    requestRoutePreviewArtifactFrame: (id: string, fingerprint?: string, options?: {
+        retry?: boolean;
+        recipeFingerprint?: string;
+        recipe?: RoutePreviewFrameRecipe;
+        priority?: number;
+    }) => Promise<RoutePreviewArtifactResolution> | null;
+    requestRoutePreviewArtifactFrames: (frames: readonly RoutePreviewArtifactFrameIdentity[], options?: {
+        retry?: boolean;
+        priority?: number;
+    }) => Promise<RoutePreviewArtifactResolution> | null;
+    createRoutePreviewRecipeKey: (recipe: RoutePreviewRecipe) => string;
+    getRoutePreviewShadowArtifact: (key: string) => RoutePreviewShadowArtifact | null;
+    routePreviewSourceRevision: (previewRevision: string) => string;
+    seedRoutePreviewArtifacts: (bundle: RoutePreviewArtifactBundle | null | undefined, options: {
+        namespace: string;
+        previewRevision: string;
+        appOrigin: string;
+        baselineEnvironment?: StoryboardEnvironment;
+        allowStaleIdentity?: boolean;
+        /** Endpoint-validated v3 subsets may prove freshness by frame fingerprint. */
+        allowMatchingFrameIdentity?: boolean;
+        pages: readonly RoutePreviewArtifactPage[];
+    }) => RoutePreviewArtifactSeedResult;
+    setRoutePreviewCacheNamespace: (namespace: string | null | undefined) => void;
+    getRoutePreviewCacheNamespace: () => string;
+    setRoutePreviewPersistenceForTests: (persistence: RoutePreviewPersistence | null | undefined) => void;
+    scheduleRouteLayerCapture: <T>(key: string, priority: number, task: () => Promise<T>) => Promise<T>;
+    acquireRoutePreviewSlot: (priority?: number) => RoutePreviewSlotTicket;
+    setRoutePreviewConcurrency: (value: number) => void;
+    getRoutePreviewSnapshot: (key: string) => string | null;
+    setRoutePreviewSnapshot: (key: string, snapshot: string) => boolean;
+    hydrateRoutePreviewSnapshot: (key: string) => Promise<string | null>;
+    prehydrateRoutePreviewSnapshots: (keys: readonly string[]) => Promise<Map<string, string>>;
+    clearRoutePreviewSnapshots: (namespace?: string) => void;
+    scheduleRoutePreviewTask: <T>(key: string, priority: number, task: () => Promise<T>) => Promise<T>;
+    scheduleRoutePreviewSnapshot: (key: string, priority: number, task: () => Promise<string | null>, runtimeKey?: string) => Promise<string | null>;
+    serializeRoutePreview: (iframe: HTMLIFrameElement, fallbackUrl: string, options?: SerializeRoutePreviewOptions) => string | null;
+};
+export type RoutePreviewCache = ReturnType<typeof createRoutePreviewCache>;
 export {};