@pygmalionjs/pygmalion 0.6.34 → 0.7.1

package/dist-lib/types/core/debug.d.ts

@@ -0,0 +1,187 @@
+import { getObserverTree, isObservableProp } from 'mobx';
+import type { EditorRuntime } from './runtime';
+export interface EditorRuntimeDiagnostics {
+    /** Whether the preview identity had settled at the last render. */
+    previewIdentityReady: boolean;
+    /** The preview revision the last render resolved frames against. */
+    resolvedPreviewRevision: string;
+}
+export declare function createEditorDebug(runtime: EditorRuntime): {
+    /** The runtime's store, under the name the first host automation used. */
+    readonly editor: import("../testing").EditorStore;
+    readonly store: import("../testing").EditorStore;
+    readonly host: import("./hostBindings").HostBindings;
+    /** Render inputs the frames were last given, mirrored for headless diagnosis. */
+    diagnostics: EditorRuntimeDiagnostics;
+    getObserverTree: typeof getObserverTree;
+    isObservableProp: typeof isObservableProp;
+    /** Preview-surface introspection for headless diagnosis of frame surfaces. */
+    preview(frameId: string): Promise<{
+        key: string;
+        hasOutcome: boolean;
+        screenshot: {
+            width: number;
+            height: number;
+        } | null;
+        hasShadowArtifact: boolean;
+        hasSnapshot: boolean;
+        keys: {
+            which: "active" | "inactive";
+            sameAsDebugKey: boolean;
+            hasShadowArtifact: boolean;
+            hasSnapshot: boolean;
+        }[];
+        isActivePage: boolean;
+        snapshotShape: {
+            length: number;
+            bodyLength: number;
+            elements: number;
+            basePlaceholderLeft: boolean;
+            baseHref: string | null;
+            head: string;
+        } | null;
+        previewIdentityReady: boolean;
+        seedRevision: string;
+        hostRevision: string;
+        staticSurface: import("../editor/routePreviewStatus").StaticRoutePreviewSurface;
+        tier: import("../editor/frameLod").FrameLifecycleTier;
+        magnified: boolean;
+        promotion: {
+            mounted: boolean;
+            stamped: boolean | null;
+        };
+        lodState: {
+            tiers: [string, import("../editor/frameLod").FrameLifecycleTier][];
+            magnified: [string, boolean][];
+            lastRecompute: {
+                displayDensity?: number;
+                overview?: boolean;
+                frames?: {
+                    id: string;
+                    screenshotDensity: number | null | undefined;
+                    tier: string;
+                }[];
+            };
+        };
+        readFramesNow: (import("../editor/frameLod").FrameLodFrame & {
+            memoKey?: string;
+        }) | undefined;
+    } | null>;
+    /** Flow-session delivery states for headless diagnosis of the captureless supply. */
+    flowSessions(): Promise<{
+        declaredPaths: number;
+        scheduler: {
+            calls: number;
+            lastCanvas: string;
+            lastFlows: number;
+            lastCandidates: number;
+            lastQueued: number;
+        };
+        states: Record<string, import("../editor/flowSessions").FlowScreenState>;
+        viewport: {
+            commit: {
+                requested: number;
+                resolvedNull: number;
+                controllerMissing: number;
+                markerGone: number;
+                editsWon: number;
+                captureNull: number;
+                committed: number;
+            };
+            states: Record<string, unknown>;
+        };
+        interactive: {
+            requests: {
+                requested: number;
+                noPath: number;
+                resolvedNull: number;
+                queued: number;
+                reparkQueued: number;
+                reparkAlreadyParked: number;
+                reparkNoExtraSteps: number;
+            };
+            states: Record<string, unknown>;
+        };
+        warming: {
+            requested: number;
+            noPath: number;
+            resolvedNull: number;
+            alreadyWarm: number;
+            queued: number;
+        };
+        warm: {
+            bootsByRunner: {
+                [x: string]: number;
+            };
+            parked: number;
+            boots: number;
+            reuses: number;
+            parks: number;
+            evictions: number;
+            refreshes: number;
+        };
+    }>;
+    /**
+     * State-switch instrumentation: phase timings of recent flow-session walks
+     * (boot/replay/settle/stability/serialize/publish, per runner label, warm
+     * reuse vs cold boot) plus route-preview producer-gate counters. JSON-safe.
+     */
+    stateSwitchMetrics(): Promise<{
+        walks: {
+            byRunner: {
+                [k: string]: {
+                    count: number;
+                    completed: number;
+                    coldBoots: number;
+                    warmReuses: number;
+                    stabilityTimeouts: number;
+                    phases: Record<import("../editor/stateSwitchMetrics").StateSwitchPhase, import("../editor/stateSwitchMetrics").PhaseAggregate>;
+                };
+            };
+            recent: {
+                totals: {
+                    replayMs: number;
+                    settleMs: number;
+                    stabilityMs: number;
+                    serializeMs: number;
+                    publishMs: number;
+                };
+                waypoints: {
+                    screenId: string;
+                    replayMs: number | null;
+                    settleMs: number | null;
+                    stabilityMs: number | null;
+                    stabilityTimedOut: boolean;
+                    serializeMs: number | null;
+                    publishMs: number | null;
+                }[];
+                runner: string;
+                pathId: string;
+                reused: boolean;
+                completed: boolean;
+                startedAtEpochMs: number;
+                totalMs: number;
+                bootMs: number | null;
+            }[];
+            count: number;
+            completed: number;
+            coldBoots: number;
+            warmReuses: number;
+            stabilityTimeouts: number;
+            phases: Record<import("../editor/stateSwitchMetrics").StateSwitchPhase, import("../editor/stateSwitchMetrics").PhaseAggregate>;
+        };
+        routePreviewProducer: {
+            evaluations: number;
+            allowed: number;
+            suppressed: number;
+            byTrigger: {
+                endpointNotConfigured: number;
+                detailActive: number;
+                previewIntended: number;
+            };
+        };
+    }>;
+    /** Clears the state-switch metrics between headless audit scenarios. */
+    resetStateSwitchMetrics(): Promise<void>;
+};
+export type EditorRuntimeDebug = ReturnType<typeof createEditorDebug>;

package/dist-lib/types/core/defaultRuntime.d.ts

@@ -0,0 +1,3 @@
+import { type EditorRuntime } from './runtime';
+/** @deprecated Create a runtime with `createEditorRuntime()` and pass it to `<PygmalionEditor runtime>`. */
+export declare function getDefaultRuntime(): EditorRuntime;

package/dist-lib/types/core/hostBindings.d.ts

@@ -0,0 +1,90 @@
+import type { ApplyPayload, DesignChangePayload, DesignChangeResult, InspectApplyResult, InspectImpactResult, InspectPreviewResult } from '../editor/host';
+import type { InspectApplyPayload } from '../editor/inspect';
+export type ApplyHandler = (payload: ApplyPayload) => Promise<{
+    branch: string;
+} | void>;
+export type InspectApplyHandler = (payload: InspectApplyPayload) => Promise<InspectApplyResult | void>;
+export type InspectPreviewHandler = (payload: InspectApplyPayload) => Promise<InspectPreviewResult>;
+export type InspectImpactHandler = (componentFiles: string[]) => Promise<InspectImpactResult>;
+export type DesignChangeHandler = (payload: DesignChangePayload) => Promise<DesignChangeResult | void>;
+export type PreviewOpenChangeHandler = (open: boolean) => void;
+/** The six host callbacks, as one immutable object so a render can subscribe to "any of them changed". */
+export interface HostCallbacks {
+    readonly onApply: ApplyHandler | null;
+    readonly onInspectApply: InspectApplyHandler | null;
+    readonly onInspectPreview: InspectPreviewHandler | null;
+    readonly onInspectImpact: InspectImpactHandler | null;
+    readonly onDesignChange: DesignChangeHandler | null;
+    readonly onPreviewOpenChange: PreviewOpenChangeHandler | null;
+}
+export type StaticFrameSurface = 'bitmap' | 'dom';
+export interface HostBindingsInit {
+    appOrigin?: string;
+    artifactOrigin?: string;
+    previewRevision?: string;
+    flowCanvas?: string;
+    staticFrameSurface?: StaticFrameSurface;
+}
+export declare class HostBindings {
+    private appOriginValue;
+    private artifactOriginValue;
+    private previewRevisionValue;
+    private callbacksValue;
+    private callbackVersionValue;
+    private readonly appOriginListeners;
+    private readonly artifactOriginListeners;
+    private readonly previewRevisionListeners;
+    private readonly callbackListeners;
+    /**
+     * The canvas the full-screen preview always plays: entering it from a sheet
+     * or token canvas still opens the application flow. Empty plays the active
+     * page as before.
+     */
+    flowCanvas: string;
+    /**
+     * The default static surface for route frames. `bitmap` renders captured
+     * screenshots and reconstructs frozen DOM only on demand; `dom` mounts the
+     * frozen DOM from the start, which suits per-section canvases where every
+     * activation must be promotion-ready without a mount wait.
+     */
+    staticFrameSurface: StaticFrameSurface;
+    constructor(init?: HostBindingsInit);
+    get appOrigin(): string;
+    setAppOrigin: (origin: string) => void;
+    subscribeAppOrigin: (listener: () => void) => (() => void);
+    /**
+     * Origin a captured snapshot resolves its relative assets against.
+     *
+     * This is not the same question as "where does the live screen run". A
+     * capture is already rendered and needs somewhere to fetch the images and
+     * fonts its markup points at, while a live frame needs the checkout of a
+     * specific revision. The order is most-accurate-first: an origin the host
+     * declared, then the live one once a runtime exists, then the editor's own,
+     * which serves the same application and lets the catalog paint immediately.
+     */
+    get artifactOrigin(): string;
+    setArtifactOrigin: (origin: string) => void;
+    subscribeArtifactOrigin: (listener: () => void) => (() => void);
+    /** Baseline code version of the preview. A change creates a new static screen cache for the same URL. */
+    get previewRevision(): string;
+    setPreviewRevision: (revision: string) => void;
+    subscribePreviewRevision: (listener: () => void) => (() => void);
+    setFlowCanvas: (canvas: string) => void;
+    setStaticFrameSurface: (surface: StaticFrameSurface) => void;
+    get callbacks(): HostCallbacks;
+    get callbackVersion(): number;
+    subscribeCallbacks: (listener: () => void) => (() => void);
+    get onApply(): ApplyHandler | null;
+    get onInspectApply(): InspectApplyHandler | null;
+    get onInspectPreview(): InspectPreviewHandler | null;
+    get onInspectImpact(): InspectImpactHandler | null;
+    get onDesignChange(): DesignChangeHandler | null;
+    get onPreviewOpenChange(): PreviewOpenChangeHandler | null;
+    setOnApply: (callback: ApplyHandler | null) => void;
+    setOnInspectApply: (callback: InspectApplyHandler | null) => void;
+    setOnInspectPreview: (callback: InspectPreviewHandler | null) => void;
+    setOnInspectImpact: (callback: InspectImpactHandler | null) => void;
+    setOnDesignChange: (callback: DesignChangeHandler | null) => void;
+    setOnPreviewOpenChange: (callback: PreviewOpenChangeHandler | null) => void;
+    private setCallback;
+}

package/dist-lib/types/core/runtime.d.ts

@@ -0,0 +1,36 @@
+import { EditorStore } from '../editor/store';
+import { HostBindings, type HostBindingsInit } from './hostBindings';
+import { type EditorRuntimeDebug } from './debug';
+import type { EditorTransport } from '../contract/transport.js';
+export interface EditorRuntimeOptions {
+    /** Initial host values; every one can also be set later through `runtime.host`. */
+    host?: HostBindingsInit;
+    /**
+     * How this editor reaches the Node side. Defaults to the same-origin Vite
+     * transport; pass `createViteTransport({ endpoints, fetch })` to move paths
+     * or stub the network, or another implementation of the interface.
+     */
+    transport?: EditorTransport;
+}
+export interface EditorRuntime {
+    readonly store: EditorStore;
+    readonly host: HostBindings;
+    readonly transport: EditorTransport;
+    /** Headless diagnosis surface, the former module-level `__debug`. */
+    readonly debug: EditorRuntimeDebug;
+    /** Switches to the page with this name, in the editor and the preview alike. */
+    navigate(pageName: string): void;
+    /** Opens the prototype preview, for hosts that place their own entry button. */
+    openPreview(): void;
+    /** Discards unapplied canvas and inspection edits made since the latest source load or apply. */
+    resetCurrentEdits(): boolean;
+    /**
+     * Installs the module-level registrations this runtime needs while an editor
+     * is mounted on it, and returns the function that removes them. Attaching
+     * one runtime from two mounted editors at once is an error.
+     */
+    attach(): () => void;
+    /** Releases what the store holds (reactions, persistence subscriptions). */
+    dispose(): void;
+}
+export declare function createEditorRuntime(options?: EditorRuntimeOptions): EditorRuntime;

package/dist-lib/types/core/runtimeContext.d.ts

@@ -0,0 +1,13 @@
+import type { EditorStore } from '../editor/store';
+import type { HostBindings, HostCallbacks } from './hostBindings';
+import type { EditorRuntime } from './runtime';
+export declare const EditorRuntimeContext: import("react").Context<EditorRuntime | null>;
+export declare function useEditorRuntime(): EditorRuntime;
+export declare function useEditorStore(): EditorStore;
+export declare function useHostBindings(): HostBindings;
+/**
+ * The host callbacks as a render-time value. They are installed from props in
+ * a layout effect, so a component that decides on first paint whether a diff
+ * review is required subscribes here rather than reading a getter once.
+ */
+export declare function useHostCallbacks(): HostCallbacks;

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

@@ -1,9 +1,17 @@
 import { type DesignImportController, type DesignScreenCaptureSpec } from './designImport';
 import type { FlowSessionRunner, ResolvedFlowPath } from './flowSessions';
 import type { ScreenFlowPath } from './screenFlows';
-import { type PageModel } from './store';
+import type { EditorStore, PageModel } from './store';
+/** What the scheduler needs from an editor runtime; `EditorRuntime` satisfies it. */
+export interface FlowSessionRuntime {
+    readonly store: EditorStore;
+    readonly host: {
+        readonly appOrigin: string;
+        readonly previewRevision: string;
+    };
+}
 /** Applies the active frame's own boot condition to a path-specific session. */
-export declare function resolveActivePagePath(resolved: ResolvedFlowPath, path: ScreenFlowPath, page: PageModel): ResolvedFlowPath;
+export declare function resolveActivePagePath(resolved: ResolvedFlowPath, path: ScreenFlowPath, page: PageModel, appOrigin: string): ResolvedFlowPath;
 /** Diagnostic counters for the headless debug surface. */
 export declare const __flowSchedulerDebug: {
     calls: number;
@@ -17,7 +25,7 @@ export declare const __flowSchedulerDebug: {
  * frozen snapshot. Paths delivering the active frame's screen run first.
  * Returns the number of paths queued.
  */
-export declare function materializeCanvasFlows(input: {
+export declare function materializeCanvasFlows(runtime: FlowSessionRuntime, input: {
     canvas: string;
     previewRevision: string;
     /**
@@ -37,7 +45,7 @@ export declare function flowSessionWillDeliverPage(page: {
  * it, unless a parked instance already serves that path. Returns true when a
  * warming walk was queued.
  */
-export declare function warmActiveFrameInstance(page: PageModel, previewRevision: string): boolean;
+export declare function warmActiveFrameInstance(runtime: FlowSessionRuntime, page: PageModel, previewRevision: string): boolean;
 /** Diagnostic counters for activation warming. */
 export declare const __warmingDebug: {
     requested: number;
@@ -53,7 +61,7 @@ export declare const __warmingDebug: {
  * 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(page: PageModel, viewport: {
+export declare function materializePageViewport(runtime: FlowSessionRuntime, page: PageModel, viewport: {
     width: number;
     height: number;
 }, previewRevision: string): boolean;
@@ -103,7 +111,7 @@ export declare function interactiveSessionSurfaceId(page: {
  * Returns false when no flow claims the screen — those frames keep the live
  * boot fallback.
  */
-export declare function materializePageInteractiveState(page: PageModel, previewRevision: string, targetCacheKey?: string): boolean;
+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;
@@ -142,7 +150,7 @@ export declare function interactiveSessionTracksVariant(variantPage: {
  * most one speculative walk is therefore ever queued or running, and a real
  * selection made meanwhile queues behind that single walk at worst.
  */
-export declare function prefetchPageInteractiveVariant(variantPage: PageModel, previewRevision: string): InteractiveVariantPrefetchOutcome;
+export declare function prefetchPageInteractiveVariant(runtime: FlowSessionRuntime, variantPage: PageModel, previewRevision: string): InteractiveVariantPrefetchOutcome;
 /** Diagnostic counters for the interactive-state path. */
 export declare const __interactiveSessionDebug: {
     requested: number;
@@ -170,4 +178,10 @@ export declare const __viewportCommitDebug: {
 };
 /** 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 {};

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

@@ -1,21 +1,21 @@
-import { type PageModel } from './store';
+import type { PageModel } from './store';
 /**
  * The preview environment of one page: its own declared environment, plus the
  * host's preview-environment override when the page is the active one.
  *
- * `active` matters for reactivity, not just for the merge. The default reads
- * `editor.activePageId`, and inside a MobX observer render that read
- * subscribes the component to every selection change — which is how a single
- * click used to re-render all 79 frames. A caller that already knows whether
- * its page is active (FrameView receives it as a prop) must pass `active`
- * explicitly so its render never touches the selection observable.
+ * `active` is required rather than looked up. This module used to default it
+ * to a read of the store's active page, and inside a MobX observer render that
+ * read subscribed the component to every selection change — which is how a
+ * single click once re-rendered all 79 frames. A caller knows whether its page
+ * is active (FrameView receives it as a prop; a store-side caller compares
+ * ids), and passing it keeps the computation free of any store.
  */
-export declare function pagePreviewEnvironment(page: PageModel, active?: boolean): import("./designImport").StoryboardEnvironment | undefined;
+export declare function pagePreviewEnvironment(page: PageModel, active: boolean): import("./designImport").StoryboardEnvironment | undefined;
 /**
  * The recipe cache key of one page. `active` is forwarded to
  * pagePreviewEnvironment — see its note on selection reactivity.
  */
-export declare function routePreviewCacheKey(page: PageModel, previewRevision: string, viewport?: {
+export declare function routePreviewCacheKey(page: PageModel, previewRevision: string, active: boolean, viewport?: {
     width: number;
     height: number;
-}, active?: boolean): string;
+}): string;

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

@@ -93,50 +93,55 @@ export interface DesignChangeResult {
     files?: string[];
     message?: string;
 }
+/** @deprecated Use `runtime.host.setAppOrigin`. */
 export declare function setAppOrigin(origin: string): void;
+/** @deprecated Use `runtime.host.appOrigin`. */
 export declare function getAppOrigin(): string;
+/** @deprecated Use `runtime.host.subscribeAppOrigin`. */
 export declare function subscribeAppOrigin(listener: () => void): () => void;
+/** @deprecated Use `runtime.host.setArtifactOrigin`. */
 export declare function setArtifactOrigin(origin: string): void;
-/**
- * Origin a captured snapshot resolves its relative assets against.
- *
- * This is not the same question as "where does the live screen run". A capture is
- * already rendered — it needs somewhere to fetch the images and fonts its markup
- * still points at — while a live frame needs the checkout of a specific revision.
- * Answering both with one value tied the catalog to a checkout that takes minutes
- * to build, so opening the editor showed a spinner instead of the frames sitting
- * on disk.
- *
- * The order is most-accurate-first: an origin the host declared, then the live
- * one once a runtime exists, then the editor's own — which serves the same
- * application and lets the catalog paint immediately. Assets it cannot resolve
- * are the ones the working tree no longer has; the live origin replaces them the
- * moment it comes up, because these readers re-run when it does.
- */
+/** @deprecated Use `runtime.host.artifactOrigin`; see its documentation for the fallback order. */
 export declare function getArtifactOrigin(): string;
+/** @deprecated Use `runtime.host.subscribeArtifactOrigin`. */
 export declare function subscribeArtifactOrigin(listener: () => void): () => void;
-/** Baseline code version of the preview (dev SHA, etc.). When a change is made, a new static screen cache of the same URL is also created. */
+/** @deprecated Use `runtime.host.setPreviewRevision`. */
 export declare function setPreviewRevision(revision: string): void;
+/** @deprecated Use `runtime.host.previewRevision`. */
 export declare function getPreviewRevision(): string;
+/** @deprecated Use `runtime.host.subscribePreviewRevision`. */
 export declare function subscribePreviewRevision(listener: () => void): () => void;
+/** @deprecated Use `runtime.host.setFlowCanvas`. */
 export declare function setFlowCanvas(canvas: string): void;
+/** @deprecated Use `runtime.host.flowCanvas`. */
 export declare function getFlowCanvas(): string;
+/** @deprecated Use `runtime.host.setStaticFrameSurface`. */
 export declare function setStaticFrameSurface(surface: 'bitmap' | 'dom'): void;
+/** @deprecated Use `runtime.host.staticFrameSurface`. */
 export declare function getStaticFrameSurface(): 'bitmap' | 'dom';
+/** @deprecated Use `runtime.host.setOnApply`. */
 export declare function setOnApply(cb: ((payload: ApplyPayload) => Promise<{
     branch: string;
 } | void>) | null): void;
-export declare function getOnApply(): ((payload: ApplyPayload) => Promise<{
-    branch: string;
-} | void>) | null;
+/** @deprecated Use `runtime.host.onApply`. */
+export declare function getOnApply(): import("../core/hostBindings").ApplyHandler | null;
+/** @deprecated Use `runtime.host.setOnInspectApply`. */
 export declare function setOnInspectApply(cb: ((payload: InspectApplyPayload) => Promise<InspectApplyResult | void>) | null): void;
-export declare function getOnInspectApply(): ((payload: InspectApplyPayload) => Promise<InspectApplyResult | void>) | null;
+/** @deprecated Use `runtime.host.onInspectApply`. */
+export declare function getOnInspectApply(): import("../core/hostBindings").InspectApplyHandler | null;
+/** @deprecated Use `runtime.host.setOnInspectPreview`. */
 export declare function setOnInspectPreview(cb: ((payload: InspectApplyPayload) => Promise<InspectPreviewResult>) | null): void;
-export declare function getOnInspectPreview(): ((payload: InspectApplyPayload) => Promise<InspectPreviewResult>) | null;
+/** @deprecated Use `runtime.host.onInspectPreview`. */
+export declare function getOnInspectPreview(): import("../core/hostBindings").InspectPreviewHandler | null;
+/** @deprecated Use `runtime.host.setOnInspectImpact`. */
 export declare function setOnInspectImpact(cb: ((componentFiles: string[]) => Promise<InspectImpactResult>) | null): void;
-export declare function getOnInspectImpact(): ((componentFiles: string[]) => Promise<InspectImpactResult>) | null;
+/** @deprecated Use `runtime.host.onInspectImpact`. */
+export declare function getOnInspectImpact(): import("../core/hostBindings").InspectImpactHandler | null;
+/** @deprecated Use `runtime.host.setOnDesignChange`. */
 export declare function setOnDesignChange(cb: ((payload: DesignChangePayload) => Promise<DesignChangeResult | void>) | null): void;
-export declare function getOnDesignChange(): ((payload: DesignChangePayload) => Promise<DesignChangeResult | void>) | null;
-/** ▶ Synchronize the preview open status with the host router. */
+/** @deprecated Use `runtime.host.onDesignChange`. */
+export declare function getOnDesignChange(): import("../core/hostBindings").DesignChangeHandler | null;
+/** @deprecated Use `runtime.host.setOnPreviewOpenChange`. */
 export declare function setOnPreviewOpenChange(cb: ((open: boolean) => void) | null): void;
-export declare function getOnPreviewOpenChange(): ((open: boolean) => void) | null;
+/** @deprecated Use `runtime.host.onPreviewOpenChange`. */
+export declare function getOnPreviewOpenChange(): import("../core/hostBindings").PreviewOpenChangeHandler | null;

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

@@ -23,21 +23,7 @@ export interface PreviewArtifactFrameRequest {
     /** The recipe the fingerprint stands for; travels only where a capture may run. */
     recipe?: RoutePreviewFrameRecipe;
 }
-/**
- * Where a capture request sits among captures waiting on the same identity.
- * Smaller runs first. Mirrors `PREVIEW_CAPTURE_PRIORITY` in
- * `node/preview-artifact-plugin.mjs` (browser code cannot import the Node
- * plugin); a shared test pins the pair.
- */
-export declare const PREVIEW_CAPTURE_PRIORITY: Readonly<{
-    /** A frame the designer selected: whatever else is queued waits. */
-    selected: 0;
-    /** The canvas in front of the designer being filled. */
-    canvas: 10;
-    /** A canvas nobody is looking at yet. */
-    background: 20;
-}>;
-export type PreviewCapturePriority = (typeof PREVIEW_CAPTURE_PRIORITY)[keyof typeof PREVIEW_CAPTURE_PRIORITY];
+export { PREVIEW_CAPTURE_PRIORITY, type PreviewCapturePriority } from '../contract/paths.js';
 export interface PreviewArtifactTransportRequest extends PreviewArtifactExpectation {
     /** Frames to fetch. Omitted asks for the whole bundle, as earlier versions did. */
     frames?: readonly PreviewArtifactFrameRequest[];
@@ -242,6 +228,10 @@ export declare function createStoryboardCaptureRecipeIdentity(screen: Storyboard
  * Creates the default same-origin HTTP transport for preview artifacts.
  * Hosts provide only an endpoint; identity query parameters and safe fetch
  * semantics remain owned by Pygmalion.
+ *
+ * An adapter over `createViteTransport().preview.artifact`, kept so a host
+ * that assembled its own transport from an endpoint and a fetcher still can.
+ * An absolute endpoint splits into the transport's origin and path.
  */
 export declare function createPreviewArtifactHttpTransport({ endpoint, fetcher, captureBaseUrl, }: PreviewArtifactHttpTransportOptions): PreviewArtifactTransport;
 /** Resolves frame freshness without downloading or validating snapshot payloads. */

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

@@ -1,4 +1,6 @@
-export declare const PYGMALION_PREVIEW_CAPTURE_PROGRESS_SUFFIX = "/progress";
+import { PYGMALION_PREVIEW_CAPTURE_PROGRESS_SUFFIX } from '../contract/paths.js';
+import type { EditorTransport } from '../contract/transport.js';
+export { PYGMALION_PREVIEW_CAPTURE_PROGRESS_SUFFIX };
 export type PygmalionPreviewCaptureProgressPhase = 'idle' | 'queued' | 'preparing' | 'capturing' | 'retrying' | 'finalizing';
 export interface PygmalionPreviewCaptureProgress {
     active: boolean;
@@ -43,5 +45,8 @@ export declare function mergePreviewCaptureProgress(worker: PygmalionPreviewCapt
  * Reads the local preview worker's current progress from the artifact plugin.
  * Idle polling is deliberately slower; an active capture tightens the interval
  * so a multi-minute job stays legible without holding a streaming connection.
+ *
+ * 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(artifactEndpoint?: string): PygmalionPreviewCaptureProgress;
+export declare function usePygmalionPreviewCaptureProgress(transport?: EditorTransport | null): PygmalionPreviewCaptureProgress;

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

@@ -31,17 +31,30 @@ export interface MirrorGateStatus {
 export interface IdleMirrorSourceStatus extends MirrorGateStatus {
     sourceRef: string | null;
 }
+/** One listed ref whose exact revision can start a lazy checkout. */
+export interface IdleMirrorListedSourceRef {
+    name: string;
+    fullName?: string;
+    sourceRevision?: string;
+}
+/** The ref-list fields needed to resolve an idle named source. */
+export interface IdleMirrorSourceRefs {
+    refs: readonly IdleMirrorListedSourceRef[];
+    defaultRef: string | null;
+    worktreeRef?: string | null;
+}
 /**
  * Returns an immutable source revision that can safely create the first lazy
  * preview demand.
  *
  * An idle mirror has no checked-out `commit` yet. When it was configured with
  * a full Git object id, however, that ref already names the exact revision the
- * catalog endpoint will verify after preparation. Named refs, worktree mode,
- * and abbreviated ids can move or be ambiguous, so they remain pending until
- * the server reports the resolved commit.
+ * catalog endpoint will verify after preparation. A named ref can also create
+ * that first demand when the ref-list endpoint supplies its full object id.
+ * The abbreviated display commit is intentionally ignored: it can be
+ * ambiguous and cannot satisfy the exact source lease.
  */
-export declare function idleMirrorSourceRevision(status: IdleMirrorSourceStatus): string | null;
+export declare function idleMirrorSourceRevision(status: IdleMirrorSourceStatus, sourceRefs?: IdleMirrorSourceRefs): string | null;
 export interface SettleMirrorStatusOptions<S extends MirrorGateStatus> {
     /** Status of the initial request; returned as-is when already settled. */
     initial: S;