@pygmalionjs/pygmalion 0.5.14 → 0.5.15

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

@@ -0,0 +1,77 @@
+import type { StoryboardEnvironment } from './designImport';
+import { type DesignFrameHeightMode } from './frameHeight';
+import { type LivePreviewInstances } from './livePreviewInstances';
+import type { StoryboardGraph } from './storyboardGraph';
+/** The page facts warmup planning reads; a store PageModel satisfies it. */
+export interface PreviewWarmupPage {
+    id: string;
+    importPageId?: string;
+    session?: string;
+    route?: string | null;
+    width?: number;
+    height?: number;
+    heightMode?: DesignFrameHeightMode;
+    maxHeight?: number;
+    resolvedDocumentHeight?: number;
+    environment?: StoryboardEnvironment;
+    interactions?: readonly unknown[];
+    layersImported?: boolean;
+}
+export interface PreviewWarmupTarget {
+    key: string;
+    url: string;
+    width: number;
+    height: number;
+}
+/** How many groups are warmed on open. One on purpose: each warm boot is a full app document (see module comment). */
+export declare const PREVIEW_WARMUP_GROUP_LIMIT = 1;
+/** Below this reported device memory (GB), warming is skipped entirely. */
+export declare const PREVIEW_WARMUP_MIN_DEVICE_MEMORY_GB = 4;
+/**
+ * Picks the instance groups worth booting before any frame asks.
+ *
+ * Pool-eligible pages are grouped by their shared-instance key; groups are
+ * ranked by member count because one boot amortizes across every member, and
+ * ties keep page order so the plan is deterministic. The key mirrors what
+ * FrameView computes for an inactive frame — page environment only — while the
+ * boot URL carries the baseline-merged environment, exactly like a lease boot.
+ */
+export declare function planLivePreviewWarmup(pages: readonly PreviewWarmupPage[], appOrigin: string, baselineEnvironment?: StoryboardEnvironment, groupLimit?: number): PreviewWarmupTarget[];
+/**
+ * Frame ids of the storyboard successors of the active page.
+ *
+ * A successor node is represented by one frame — its canonical screen when
+ * that frame exists, otherwise the first declared alias — and only frames the
+ * hover-intent path would accept qualify: a route is present and the layers
+ * were not imported.
+ */
+export declare function storyboardSuccessorPageIds(graph: StoryboardGraph | null, pages: readonly PreviewWarmupPage[], activePageId: string): string[];
+export interface StartPreviewWarmupOptions {
+    /** The observable selection source; only activePageId is tracked. */
+    editor: {
+        activePageId: string;
+    };
+    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. */
+    deviceMemoryGb?: number;
+}
+/**
+ * Warms the top instance group once and, from then on, prepares the
+ * storyboard successors of whichever screen becomes active.
+ *
+ * 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.
+ *
+ * On devices reporting less than PREVIEW_WARMUP_MIN_DEVICE_MEMORY_GB of
+ * memory the whole feature is inert: no pool boot and no successor intents,
+ * 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;

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

@@ -0,0 +1,45 @@
+/**
+ * How long the client keeps polling a mirror that answers 'syncing'.
+ * Must outlast the server's own worst case: 180s shared-lock wait + 180s
+ * capture-lease wait + checkout materialization (git switch, dependency
+ * install, preview boot). 420s gives that chain a minute of headroom.
+ */
+export declare const MIRROR_SYNC_POLL_TIMEOUT_MS = 420000;
+/** Poll cadence while the mirror reports 'syncing'. */
+export declare const MIRROR_SYNC_POLL_INTERVAL_MS = 500;
+/** First automatic boot-retry delay after a failed refresh. */
+export declare const MIRROR_BOOT_RETRY_BASE_MS = 5000;
+/** Ceiling for the boot-retry backoff. */
+export declare const MIRROR_BOOT_RETRY_MAX_MS = 30000;
+/** Delay before automatic boot retry `attempt` (0-based): 5s, 10s, 20s, then 30s forever. */
+export declare function mirrorBootRetryDelayMs(attempt: number): number;
+/** The slice of the mirror status the gate decides on. */
+export interface MirrorGateStatus {
+    state: string;
+}
+export interface SettleMirrorStatusOptions<S extends MirrorGateStatus> {
+    /** Status of the initial request; returned as-is when already settled. */
+    initial: S;
+    /** One GET of the mirror status endpoint. */
+    fetchStatus: () => Promise<S>;
+    /** One POST to the mirror refresh endpoint; resolves with the post-sync status. */
+    requestResync: () => Promise<S>;
+    timeoutMs?: number;
+    intervalMs?: number;
+    /** Test seams. */
+    now?: () => number;
+    sleep?: (ms: number) => Promise<void>;
+}
+/**
+ * Settles the mirror status a boot can act on.
+ *
+ * 'syncing' is polled through — the server is alive and working, and its own
+ * lock waits exceed two minutes, so giving up earlier than MIRROR_SYNC_POLL_-
+ * TIMEOUT_MS misreads a busy server as a dead one. 'drifted' asks the server
+ * to resync exactly once: drift means another server moved the shared
+ * checkout, and one refresh re-materializes the ref this server serves.
+ *
+ * Returns the first status that is neither, or the last observed status when
+ * the window closes. The caller decides whether that status is fatal.
+ */
+export declare function settleMirrorStatus<S extends MirrorGateStatus>(options: SettleMirrorStatusOptions<S>): Promise<S>;

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

@@ -0,0 +1,138 @@
+import type { InspectApplyPayload } from './inspect';
+import type { InspectApplyResult, InspectImpactResult, InspectPreviewResult } from './host';
+export type PygmalionIntegrationState = 'up_to_date' | 'auto_merged' | 'review_required' | 'conflict' | 'offline';
+export interface PygmalionDevMirrorStatus {
+    /** 'drifted' means another server moved the shared mirror checkout; a refresh resyncs it. */
+    state: 'idle' | 'syncing' | 'ready' | 'error' | 'drifted';
+    commit: string | null;
+    shortCommit: string | null;
+    /** Git ref the mirror is tracking, or null when it follows the source branch. */
+    sourceRef: string | null;
+    syncedAt: string | null;
+    updated: boolean;
+    warning: string | null;
+    error: string | null;
+    appOrigin: string | null;
+}
+/** One revision the mirror can be repointed at. */
+export interface PygmalionSourceRef {
+    name: string;
+    commit: string;
+    fullName: string;
+    kind: 'local' | 'remote';
+}
+/** Revisions available to `switchSource`, listed from the mirror repository. */
+export interface PygmalionSourceRefs {
+    refs: readonly PygmalionSourceRef[];
+    /** Revision followed when none is pinned. */
+    defaultRef: string | null;
+    /** Ref that renders uncommitted work. */
+    worktreeRef: string | null;
+}
+export interface PygmalionVisualOperation {
+    id: string;
+    revision: number;
+    kind: 'visual';
+    createdAt: string;
+    commitSha: string;
+    files: string[];
+    integrationState: PygmalionIntegrationState;
+}
+export interface PygmalionVisualRevertOperation {
+    id: string;
+    revision: number;
+    kind: 'visual-revert';
+    createdAt: string;
+    commitSha: string;
+    revertsOperationId: string;
+    revertsRevision: number;
+    revertsCommitSha: string;
+    recordedCommitSha: string;
+    files: string[];
+    integrationState: PygmalionIntegrationState;
+}
+export type PygmalionSessionOperation = PygmalionVisualOperation | PygmalionVisualRevertOperation;
+export interface PygmalionDesignSessionStatus {
+    id: string;
+    createdAt: string;
+    updatedAt: string;
+    createdFromSha: string;
+    baseDevSha: string;
+    branchName: string | null;
+    headSha: string | null;
+    revision: number;
+    integration: {
+        state: PygmalionIntegrationState;
+        latestDevSha: string;
+        checkedAt: string;
+        affectedFiles: string[];
+        conflictFiles: string[];
+        error?: string;
+    };
+    lastOperation: PygmalionSessionOperation | null;
+    canRevert: boolean;
+    lastRevertableOperation: PygmalionVisualOperation | null;
+    lastRevert: PygmalionVisualRevertOperation | null;
+    appOrigin: string | null;
+    previewError: string | null;
+}
+export interface PygmalionRevertResult {
+    reverted: true;
+    operation: PygmalionVisualRevertOperation;
+    session: PygmalionDesignSessionStatus;
+}
+export interface PygmalionProjectEndpoints {
+    mirror: string;
+    sessions: string;
+    inspect: string;
+}
+export interface PygmalionProjectRuntimeOptions {
+    endpoints?: Partial<PygmalionProjectEndpoints>;
+    sessionId?: string;
+    sessionStorageKey?: string;
+    autoStart?: boolean;
+    fetcher?: typeof fetch;
+    formatApplyMessage?: (session: PygmalionDesignSessionStatus, applied: number) => string | undefined;
+    /** Compare the canonical impact screen before and after application using the host Playwright capture endpoint. */
+    visualQa?: {
+        endpoint?: string;
+        eligibleFrameIds: readonly string[];
+    };
+}
+export interface PygmalionProjectRuntime {
+    mirror: PygmalionDevMirrorStatus;
+    session: PygmalionDesignSessionStatus | null;
+    ready: boolean;
+    appOrigin: string | null;
+    previewRevision: string;
+    /**
+     * Source SHA of previewRevision, without the session mutation counter.
+     * Artifact bundles are stamped with this, so hosts must build artifact cache
+     * namespaces from it instead of parsing previewRevision themselves.
+     */
+    previewSourceRevision: string;
+    refresh(manual?: boolean, sourceRef?: string): Promise<void>;
+    /**
+     * Repoints the mirror at another git ref without restarting the dev server.
+     * Pass PYGMALION_WORKTREE_SOURCE_REF to preview uncommitted work.
+     * The artifact cache is keyed by source SHA, so a switch invalidates it.
+     */
+    switchSource(sourceRef: string, options?: {
+        discardEdits?: boolean;
+    }): Promise<void>;
+    /**
+     * Revisions `switchSource` can be given. Empty until listed, so a host can
+     * offer a choice instead of asking for a ref string.
+     */
+    sourceRefs: PygmalionSourceRefs;
+    loadSourceRefs(): Promise<PygmalionSourceRefs>;
+    previewVisual(payload: InspectApplyPayload): Promise<InspectPreviewResult>;
+    inspectImpact(componentFiles: string[]): Promise<InspectImpactResult>;
+    applyVisual(payload: InspectApplyPayload): Promise<InspectApplyResult>;
+    revertLastVisual(): Promise<PygmalionRevertResult>;
+}
+/**
+ * A general-purpose browser runtime that consumes the Vite plugin's dev mirror and design session API.
+ * The host only provides the route/fixture catalog and display text, and the Git·preview life cycle is left to this hook.
+ */
+export declare function usePygmalionProject(options?: PygmalionProjectRuntimeOptions): PygmalionProjectRuntime;

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

@@ -0,0 +1,38 @@
+import type { ComponentType } from 'react';
+/** Literal prop values that can be previewed, serialized, and written back safely. */
+export type RegistryPropValue = string | number | boolean;
+export interface RegistryEntry {
+    component: ComponentType<any>;
+    /** Previewable props. Boolean vocabularies become On/Off controls; other values become selects. */
+    props?: Record<string, readonly RegistryPropValue[]>;
+    /** Optional human-readable labels for preview controls. */
+    propLabels?: Readonly<Record<string, string>>;
+    /** Default props on insert. */
+    defaultProps?: Record<string, RegistryPropValue>;
+    /** Default string children to use when inserting into the component palette. */
+    defaultChildren?: string;
+    /** 'text' = Edit children as a string (button label) · 'nodes' = Place canvas nodes as children (container components such as Card). */
+    children?: 'text' | 'none' | 'nodes';
+    /**
+     * Whether a captured screen subtree may be REPLACED by this entry when a
+     * screen is imported. Only declare it for entries that render the real
+     * component from literal props: a catalog demo or a fixture-seeded adapter
+     * draws its own sample content, so collapsing into it swaps the captured
+     * screen for that sample (five distinct records became five copies of one
+     * fixture record). Default false — the captured DOM is kept, and a
+     * designer can still adopt a node into an instance on demand.
+     */
+    collapsible?: boolean;
+    /** Path for generating codegen import statements. */
+    importPath?: string;
+    /** In inspection mode, only actually valid dynamic cases are exposed. */
+    casePreview?: {
+        /** Whether the text varies in length at runtime, such as user input/API response. */
+        text?: boolean;
+        /** A preview of what states the component actually supports. */
+        states?: readonly ('selected' | 'disabled' | 'loading')[];
+    };
+}
+export type ComponentRegistry = Record<string, RegistryEntry>;
+export declare function setComponentRegistry(r: ComponentRegistry): void;
+export declare function getRegistry(): ComponentRegistry;

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

@@ -0,0 +1,285 @@
+import { type RoutePreviewArtifactBundleV2 } from './routePreviewArtifactV2.js';
+import { type RoutePreviewArtifactBundleV3, type RoutePreviewArtifactV3Diagnostic, type RoutePreviewArtifactV3Status } from './routePreviewArtifactV3.js';
+import type { StoryboardEnvironment } from './designImport';
+import { type InstanceResolver } from './fiberMap';
+type SlotRelease = () => void;
+export interface RoutePreviewRecipe {
+    namespace?: string;
+    previewRevision?: string;
+    route: string;
+    width: number;
+    height: number;
+    environment?: unknown;
+    preset?: unknown;
+    interactions?: unknown;
+    assertions?: unknown;
+}
+export interface RoutePreviewArtifactBundleV1 {
+    version: 1;
+    namespace: string;
+    /** Source SHA at the time of creation. It must match the value before the first ':' of runtime previewRevision. */
+    sourceRevision?: string;
+    snapshots: Record<string, string>;
+}
+export type RoutePreviewArtifactBundle = RoutePreviewArtifactBundleV1 | RoutePreviewArtifactBundleV2 | RoutePreviewArtifactBundleV3;
+export interface RoutePreviewArtifactOutcome {
+    status: RoutePreviewArtifactV3Status;
+    diagnostics: readonly RoutePreviewArtifactV3Diagnostic[];
+    /** The snapshot is a last-known preview shown while an exact revision is loading. */
+    stale?: boolean;
+    screenshot: {
+        mediaType: 'image/png' | 'image/webp';
+        width: number;
+        height: number;
+        dataUrl: string;
+    } | null;
+}
+export interface RoutePreviewShadowArtifact {
+    bodyHtml: string;
+    bodyAttributes: string;
+    htmlAttributes: string;
+    sharedStylesheets: readonly {
+        key: string;
+        cssText: string;
+    }[];
+    stylesheetLinksHtml: string;
+}
+export interface RoutePreviewArtifactPage {
+    canonicalId: string;
+    route: string;
+    /** What this page's capture must have come from. Compared per frame. */
+    fingerprint?: string;
+    width?: number;
+    height?: number;
+    environment?: StoryboardEnvironment;
+    preset?: unknown;
+    interactions?: unknown;
+    assertions?: unknown;
+}
+export interface RoutePreviewArtifactSeedResult {
+    accepted: number;
+    rejected: number;
+    reason?: 'invalid-bundle' | 'namespace-mismatch' | 'revision-mismatch';
+}
+export interface RoutePreviewArtifactFrameIdentity {
+    id: string;
+    fingerprint?: string;
+}
+/** Lifecycle of resolving one frame against an exact artifact endpoint. */
+export type RoutePreviewArtifactResolution = {
+    status: 'idle';
+} | {
+    status: 'checking';
+} | {
+    status: 'outdated';
+    message?: string;
+} | {
+    status: 'generating';
+} | {
+    status: 'error';
+    reason: 'unavailable' | 'rejected';
+    message: string;
+} | {
+    status: 'exact';
+};
+export type RoutePreviewArtifactFrameRequestResult = {
+    status: 'accepted';
+} | {
+    status: 'unavailable';
+    message?: string;
+} | {
+    status: 'rejected';
+    message: string;
+};
+export type RoutePreviewState = 'hydrating' | 'live' | 'cached' | 'detailed' | 'placeholder';
+export declare function resolveRoutePreviewState(input: {
+    hasRoute: boolean;
+    layersImported: boolean;
+    cacheHydrated: boolean;
+    hasSnapshot: boolean;
+    liveGranted: boolean;
+}): RoutePreviewState;
+export declare function routePreviewRetryDelay(failedAttempt: number, options?: {
+    maxAttempts?: number;
+    baseDelayMs?: number;
+}): number | null;
+export interface RoutePreviewPersistentRecord {
+    version: number;
+    key: string;
+    namespace: string;
+    snapshot: string;
+    bytes: number;
+    lastAccess: number;
+}
+export interface RoutePreviewPersistence {
+    read(key: string): Promise<unknown>;
+    readMany?(keys: readonly string[]): Promise<Map<string, unknown>>;
+    write(record: RoutePreviewPersistentRecord): Promise<void>;
+    remove(key: string): Promise<void>;
+    clear(namespace?: string): Promise<void>;
+}
+export interface RoutePreviewSlotTicket {
+    promise: Promise<SlotRelease>;
+    cancel: () => void;
+    updatePriority: (priority: number) => void;
+}
+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.
+ */
+type RoutePreviewFrameRequester = (frames: readonly RoutePreviewArtifactFrameIdentity[]) => 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 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;
+    detailActive: boolean;
+    hasRoute: boolean;
+    layersImported: boolean;
+    hasExactArtifact: boolean;
+    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;
+}): Promise<RoutePreviewArtifactResolution> | null;
+/**
+ * Asks for many frames' captures in one requester call.
+ *
+ * The background sweep delegates its interaction screens in chunks, and a
+ * chunk must not fan out into one transport round trip per frame. 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.
+ */
+export declare function requestRoutePreviewArtifactFrames(frames: readonly RoutePreviewArtifactFrameIdentity[], options?: {
+    retry?: boolean;
+}): 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. */
+    resolveInstance?: InstanceResolver;
+    /** Resolves the `file#localName` CSS-module source of an element. */
+    resolveStyle?: (el: Element) => string | null;
+}
+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>;
+export {};

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

@@ -0,0 +1,34 @@
+export type RoutePreviewArtifactV2Hash = `sha256-${string}`;
+export interface RoutePreviewArtifactV2HeadReference {
+    readonly kind: 'head' | 'stylesheet';
+    readonly hash: RoutePreviewArtifactV2Hash;
+}
+export interface RoutePreviewArtifactV2Document {
+    readonly doctype: string;
+    readonly htmlAttributes: string;
+    readonly headAttributes: string;
+    readonly bodyAttributes: string;
+}
+export interface RoutePreviewArtifactV2Frame {
+    readonly document: RoutePreviewArtifactV2Document;
+    readonly head: readonly RoutePreviewArtifactV2HeadReference[];
+    readonly body: string;
+}
+export interface RoutePreviewArtifactBundleV2 {
+    readonly version: 2;
+    readonly namespace: string;
+    readonly sourceRevision?: string;
+    readonly assets: {
+        readonly head: Readonly<Record<RoutePreviewArtifactV2Hash, string>>;
+        readonly stylesheets: Readonly<Record<RoutePreviewArtifactV2Hash, string>>;
+    };
+    readonly frames: Readonly<Record<string, RoutePreviewArtifactV2Frame>>;
+}
+export interface RoutePreviewArtifactV2ValidationResult {
+    valid: boolean;
+    errors: string[];
+    bytes: number;
+}
+export declare function isSafeFrozenRoutePreviewSnapshotV2(snapshot: unknown): snapshot is string;
+export declare function validateRoutePreviewArtifactV2Browser(value: unknown): RoutePreviewArtifactV2ValidationResult;
+export declare function reconstructRoutePreviewArtifactSnapshotV2(value: unknown, frameId: string): string | null;