@pygmalionjs/pygmalion 0.5.14 → 0.5.15

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

@@ -0,0 +1,17 @@
+/** Explains a control that is inert because the editor is in view-only. */
+export declare const VIEW_ONLY_REASON = "View only \u2014 switch to Editing to change this.";
+interface ModeKeyEvent {
+    key: string;
+    code?: string;
+    metaKey?: boolean;
+    ctrlKey?: boolean;
+    shiftKey?: boolean;
+    altKey?: boolean;
+}
+/**
+ * True when this keystroke would change the design and the editor is not in
+ * edit mode. Selection, zoom, panning, tool switching and copy are absent
+ * from the lists above by design — reading a canvas needs all of them.
+ */
+export declare function viewOnlyBlocksKey(editMode: boolean, event: ModeKeyEvent): boolean;
+export {};

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

@@ -0,0 +1,16 @@
+import type { ComponentRegistry, RegistryPropValue } from './registry';
+export interface InstanceHit {
+    /** Registry key. */
+    name: string;
+    /** Registry importPath. If not present, name — Identifies the same implementation source across multiple screens. */
+    sourceId: string;
+    /** Only safe literal props are retained (functions, objects, and ReactElement are discarded). */
+    props: Record<string, RegistryPropValue>;
+    /** It is used by the source editor to safely create AST operations by preserving the original literal type. */
+    primitiveProps: Record<string, string | number | boolean>;
+    /** only if memoizedProps.children is string. */
+    childrenText: string;
+}
+export type InstanceResolver = (el: Element, exclude?: ReadonlySet<string>) => InstanceHit | null;
+/** Create a resolver that creates a registry reverse map (component → name) once and closes it — does not rebuild it on each call. */
+export declare function createInstanceResolver(registry: ComponentRegistry): InstanceResolver;

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

@@ -0,0 +1,97 @@
+import { type PageModel } from './store';
+/** Diagnostic counters for the headless debug surface. */
+export declare const __flowSchedulerDebug: {
+    calls: number;
+    lastCanvas: string;
+    lastFlows: number;
+    lastCandidates: number;
+    lastQueued: number;
+};
+/**
+ * Materializes the flow-declared screens of one canvas that still lack a
+ * frozen snapshot. Paths delivering the active frame's screen run first.
+ * Returns the number of paths queued.
+ */
+export declare function materializeCanvasFlows(input: {
+    canvas: string;
+    previewRevision: string;
+}): number;
+/** Session delivery state for one page, keyed by its catalog screen id. */
+export declare function flowSessionWillDeliverPage(page: {
+    importPageId?: string;
+    id: string;
+}): boolean;
+/**
+ * Walks an instance to the active frame's screen in the background and parks
+ * it, unless a parked instance already serves that path. Returns true when a
+ * warming walk was queued.
+ */
+export declare function warmActiveFrameInstance(page: PageModel, previewRevision: string): boolean;
+/** Diagnostic counters for activation warming. */
+export declare const __warmingDebug: {
+    requested: number;
+    noPath: number;
+    resolvedNull: number;
+    alreadyWarm: number;
+    queued: number;
+};
+/**
+ * Materializes one screen at an explicit viewport through its flow path.
+ * Prefix waypoints walk as pass-through (steps only); the target publishes
+ * under the page's recipe key at that viewport — the key its frame reads
+ * after the size change commits. Returns false when no flow claims the
+ * screen (the live re-import fallback stays for those).
+ */
+export declare function materializePageViewport(page: PageModel, viewport: {
+    width: number;
+    height: number;
+}, previewRevision: string): boolean;
+/** True while a viewport-variant session still owes this page's snapshot. */
+export declare function viewportSessionWillDeliver(page: {
+    importPageId?: string;
+    id: string;
+}, viewport: {
+    width: number;
+    height: number;
+}): boolean;
+/** Subscribe to viewport-variant delivery changes. */
+export declare function subscribeViewportSessions(listener: () => void): () => void;
+/**
+ * Materializes one screen in its declared interactive state through the
+ * screen's flow path. The prefix walks as pass-through; the target publishes
+ * under the page's own recipe key, which already includes the option's steps
+ * (the store appends them to the recipe, and resolvePath replays them).
+ * Returns false when no flow claims the screen — those frames keep the live
+ * boot fallback.
+ */
+export declare function materializePageInteractiveState(page: PageModel, previewRevision: string): boolean;
+/** True while an interactive-state session still owes this page its snapshot. */
+export declare function interactiveSessionWillDeliver(page: {
+    importPageId?: string;
+    id: string;
+    interactiveStateId?: string;
+    interactiveOptionId?: string;
+}): boolean;
+/** Subscribe to interactive-state delivery changes. */
+export declare function subscribeInteractiveSessions(listener: () => void): () => void;
+/** Diagnostic counters for the interactive-state path. */
+export declare const __interactiveSessionDebug: {
+    requested: number;
+    noPath: number;
+    resolvedNull: number;
+    queued: number;
+};
+/** Interactive-runner delivery states for the headless debug surface. */
+export declare function __debugInteractiveSessionStates(): Record<string, unknown>;
+/** Diagnostic counters for the viewport-commit path. */
+export declare const __viewportCommitDebug: {
+    requested: number;
+    resolvedNull: number;
+    controllerMissing: number;
+    markerGone: number;
+    editsWon: number;
+    captureNull: number;
+    committed: number;
+};
+/** Viewport-runner delivery states for the headless debug surface. */
+export declare function __debugViewportSessionStates(): Record<string, unknown>;

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

@@ -0,0 +1,137 @@
+import type { DesignScreenAssertion, DesignScreenCaptureReport, DesignScreenInteraction, DesignScreenPreset } from './designImport';
+export interface ResolvedFlowWaypoint {
+    screenId: string;
+    /**
+     * Route-preview store key the snapshot publishes under. An empty key marks
+     * a pass-through waypoint: its steps advance the instance so LATER
+     * waypoints stay reachable, but nothing publishes and no delivery status
+     * is tracked (viewport-variant paths walk their prefix this way).
+     */
+    cacheKey: string;
+    /** Viewport of this waypoint's frame; the instance resizes when it differs. */
+    width: number;
+    height: number;
+    steps: readonly DesignScreenInteraction[];
+    /** The waypoint's own capture assertions, checked after its steps settle. */
+    assertions?: readonly DesignScreenAssertion[];
+    /**
+     * Runs against the settled live instance after the snapshot publishes,
+     * while the iframe is still mounted. Viewport-variant deliveries commit
+     * their layer import here: the walk iframe is a TRUE viewport, so width
+     * media queries hold — unlike canvas shadow mounts, which evaluate them
+     * against the editor window.
+     */
+    afterSerialize?: (iframe: HTMLIFrameElement) => Promise<void>;
+}
+export interface ResolvedFlowPath {
+    id: string;
+    /** Boot URL with route and declarative environment already encoded. */
+    url: string;
+    /** Authored route, forwarded to the capture-preparation spec. */
+    route: string;
+    /**
+     * Shared screen preset of every waypoint on this path (mock APIs, identity,
+     * timers). Applied through the host executor with the FIRST waypoint's
+     * preparation; the instance keeps it for the rest of the walk.
+     */
+    preset?: DesignScreenPreset;
+    waypoints: readonly ResolvedFlowWaypoint[];
+}
+export type FlowScreenStatus = 'pending' | 'running' | 'delivered' | 'failed';
+export interface FlowScreenState {
+    status: FlowScreenStatus;
+    pathId: string;
+    /** Failure reason, present only for failed screens. */
+    reason?: string;
+}
+export interface FlowSessionRunnerOptions {
+    /**
+     * Concurrent live instances. The default is 1: mocked app backends
+     * (STT sockets, summary generators) are commonly single-session, and two
+     * concurrent walks contending for them time out deterministically. Raise
+     * it only for apps whose fixtures are proven concurrency-safe.
+     */
+    concurrency?: number;
+    /** Names this supply in the boot counters, so a stray boot is attributable. */
+    label?: string;
+    createIframe?: () => HTMLIFrameElement;
+    resolveContainer?: () => (Node & {
+        appendChild(node: Node): unknown;
+    }) | null;
+    /** Navigates the instance and resolves when the document loaded. */
+    boot?: (iframe: HTMLIFrameElement, url: string) => Promise<void>;
+    /**
+     * Prepares one waypoint on the instance: preset (host executor) ->
+     * interactions -> assertions, exactly the capture pipeline's contract.
+     * Defaults to the design-import controller's prepareScreenCapture.
+     */
+    prepare?: (iframe: HTMLIFrameElement, spec: {
+        pageId: string;
+        route?: string;
+        preset?: DesignScreenPreset;
+        interactions?: readonly DesignScreenInteraction[];
+        assertions?: readonly DesignScreenAssertion[];
+    }) => Promise<DesignScreenCaptureReport>;
+    /** Extra settle before serializing a waypoint (fonts, trailing paints). */
+    settle?: (iframe: HTMLIFrameElement, ms: number) => Promise<void>;
+    /** Layout-stability wait before serializing. Defaults to waitForGeometryStability. */
+    waitForStability?: (iframe: HTMLIFrameElement) => Promise<void>;
+    serialize?: (iframe: HTMLIFrameElement, fallbackUrl: string) => string | null;
+    /** Writes one waypoint snapshot into the route preview store. */
+    publish?: (cacheKey: string, snapshot: string) => boolean;
+    onError?: (pathId: string, error: unknown) => void;
+}
+/**
+ * Resolves when the document's layout stops moving: two consecutive
+ * animation frames with an identical element-geometry hash. JS-driven
+ * entrance animations (rAF springs writing inline transforms) are invisible
+ * to the frozen stylesheet's animation:none — serializing mid-flight pins
+ * intermediate rects as overlapping boxes, so the walk waits them out.
+ * Perpetual animations hit the timeout and serialize best-effort.
+ */
+export declare function waitForGeometryStability(iframe: HTMLIFrameElement, timeoutMs?: number): Promise<void>;
+export declare function createFlowSessionIframe(): HTMLIFrameElement;
+/** Test/tuning hook for how long a parked instance stays claimable. */
+export declare function setFlowSessionWarmTtl(ms: number): void;
+/** Warm-pool counters for the headless debug surface. */
+export declare const __flowSessionWarmDebug: {
+    boots: number;
+    reuses: number;
+    parks: number;
+    evictions: number;
+    /** Which supply booted, so a stray second boot is attributable. */
+    bootsByRunner: Record<string, number>;
+};
+/** Drops every parked instance — identity change, canvas change, teardown. */
+export declare function evictFlowSessionWarmInstances(): void;
+/**
+ * True when a walk of this path would resume on a parked instance. Activation
+ * warming reads it to decide whether the frame already has a resumable
+ * instance or one has to be walked in the background.
+ */
+export declare function warmInstanceServesPath(path: ResolvedFlowPath): boolean;
+export declare function createFlowSessionRunner(options?: FlowSessionRunnerOptions): {
+    /**
+     * Queues paths for materialization. Screens already delivered, failed, or
+     * claimed by a queued path are skipped — callers re-request freely.
+     */
+    materialize(paths: readonly ResolvedFlowPath[]): number;
+    /** Session state of one screen, or null when no session claims it. */
+    screenState(screenId: string): FlowScreenState | null;
+    /** True while the session still owes this screen its snapshot. */
+    willDeliver(screenId: string): boolean;
+    subscribe(listener: () => void): () => void;
+    /**
+     * Drops all session state. Running paths notice the round change at their
+     * next waypoint boundary and stop; their remaining screens re-queue on
+     * the next materialize call.
+     */
+    reset(): void;
+    /** Test/diagnostic snapshot of every tracked screen. */
+    debugScreenStates(): Record<string, FlowScreenState>;
+    /** How many finished walks currently have an instance parked for reuse. */
+    debugWarmInstancesParked(): number;
+};
+export type FlowSessionRunner = ReturnType<typeof createFlowSessionRunner>;
+export declare function getFlowSessionRunner(): FlowSessionRunner;
+export declare function resetFlowSessionRunner(): void;

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

@@ -0,0 +1,14 @@
+export type DesignFrameHeightMode = 'fixed' | 'document';
+export declare const DEFAULT_DOCUMENT_FRAME_MAX_HEIGHT = 12000;
+export declare const ABSOLUTE_DOCUMENT_FRAME_MAX_HEIGHT = 32000;
+interface FrameHeightInput {
+    height?: number;
+    heightMode?: DesignFrameHeightMode;
+    maxHeight?: number;
+    resolvedDocumentHeight?: number;
+}
+export declare function documentFrameHeightLimit(viewportHeight: number, maxHeight?: number): number;
+export declare function resolveFrameHeight(page: FrameHeightInput): number;
+export declare function measurePreviewDocumentHeight(root: Document | ShadowRoot): number;
+export declare function observePreviewDocumentHeight(root: Document | ShadowRoot, onHeightChange: (height: number) => void): () => void;
+export {};

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

@@ -0,0 +1,9 @@
+/**
+ * Source inventory and QA use the stable host-owned screen id, while the editor
+ * keeps its own unique page id for selection, layout, and navigation.
+ */
+export interface FrameIdentitySource {
+    id: string;
+    importPageId?: string;
+}
+export declare function canonicalFrameId(page: FrameIdentitySource): string;

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

@@ -0,0 +1,124 @@
+import type { PageModel } from './store';
+/**
+ * Host-declared presentation of one branch kind.
+ *
+ * `kind` matches either a `stateKind` a case declares, or one of the two kinds
+ * the core derives on its own: `step` for a plain screen and `variant` for a
+ * numbered branch that declares no state kind.
+ */
+export interface FrameBranchKindDef {
+    kind: string;
+    /** Word shown in the pill. */
+    label: string;
+    /** Accent colour for the rule and the pill text. */
+    accent: string;
+}
+/**
+ * Words for the facts the core counts. Defaults are English; a host renders
+ * its own language by declaring them, so the core carries no product copy.
+ */
+export interface FrameLabelLabels {
+    /** Unit for the layer count. Default "layers". */
+    layers?: string;
+    /** Shown when a screen frame claims no scenario at all. Default "no scenario". */
+    noScenario?: string;
+    /** Shown when the import dropped nodes. Default "some omissions". */
+    omissions?: string;
+    /** Shown when the import failed. Default "check flow". */
+    checkFlow?: string;
+}
+export declare function resolveFrameLabelLabels(labels: FrameLabelLabels | undefined): Required<FrameLabelLabels>;
+/** Branch kinds the core derives when a frame declares no state kind. */
+export declare const FRAME_BRANCH_STEP = "step";
+export declare const FRAME_BRANCH_VARIANT = "variant";
+/** Neutral accent for a kind the host has not described. */
+export declare const FRAME_BRANCH_FALLBACK_ACCENT = "#8b8b9e";
+export interface FrameBranchKindDiagnostic {
+    severity: 'error' | 'warning';
+    kind: string;
+    message: string;
+}
+export declare function validateFrameBranchKinds(defs: readonly FrameBranchKindDef[], context?: {
+    stateKinds?: readonly string[];
+}): FrameBranchKindDiagnostic[];
+/** Every scenario a page claims: the whole declared set, or its canonical id. */
+export declare function pageScenarioIds(page: PageModel): readonly string[];
+/**
+ * A screen frame with nothing to say about coverage. Catalog sheets are not
+ * screens and are not expected to claim scenarios, so only routed frames
+ * count as a hole.
+ */
+export declare function pageMissesScenario(page: PageModel): boolean;
+export declare function framesMissingScenario(pages: readonly PageModel[]): readonly PageModel[];
+/**
+ * Branch kind of a frame.
+ *
+ * A declared state kind wins, because the host said what the branch is. Absent
+ * one, a case number with a third segment (`02.02.2` beside `02.02`) is the
+ * catalog's own way of saying "branch of the screen before it" — the same
+ * convention the fold groups read.
+ */
+export declare function frameBranchKind(page: PageModel): string;
+/** Leading case number of a frame name, or null when it has none. */
+export declare function frameLabelCode(page: PageModel): string | null;
+export interface FrameLabelParts {
+    /** Case number, or null for a frame that is not numbered. */
+    code: string | null;
+    /** Title after the flow prefix, e.g. "recording error". */
+    title: string;
+    /** Secondary clause: the state this branch is in. */
+    state?: string;
+}
+/**
+ * Splits a frame name into the banner's slots.
+ *
+ * Catalog names carry `<code> <flow> / <title>`; the flow is already the
+ * section, so repeating it in the title would spend the widest slot on the
+ * thing the section band above it already says.
+ */
+export declare function frameLabelParts(page: PageModel): FrameLabelParts;
+/**
+ * The counted line, in the order a reviewer scans it. An import that failed or
+ * dropped nodes says so first — it changes whether the frame can be trusted at
+ * all — and a screen claiming no scenario says that rather than staying quiet,
+ * which is how fourteen uncovered screens went unnoticed.
+ */
+export declare function frameLabelFacts(page: PageModel, labels: Required<FrameLabelLabels>): string;
+export declare const FRAME_LABEL_STYLE: {
+    readonly radius: 10;
+    readonly pillRadius: 999;
+    readonly ruleWidth: 6;
+    readonly gap: 14;
+    readonly paddingY: 10;
+    readonly paddingRight: 16;
+    readonly codeSize: 32;
+    readonly titleSize: 20;
+    readonly metaSize: 14;
+    readonly pillSize: 12;
+    readonly pillPaddingY: 4;
+    readonly pillPaddingX: 10;
+    /** Bottom margin between the label and its frame. */
+    readonly marginBottom: 8;
+    readonly surface: "#343441";
+    readonly pillSurface: "#2e2c3a";
+    readonly caption: "#a1a1b3";
+    readonly code: "#ffffff";
+    readonly title: "#e7e7f0";
+    readonly titleMuted: "#a1a1b3";
+    readonly meta: "#bebecb";
+    readonly purpose: "#c4ccd8";
+};
+/**
+ * Below this zoom the label keeps only its rule and code.
+ *
+ * At overview zoom the label is a few pixels tall: a 20px title renders at 5px
+ * and is noise, while a 32px code renders at 8px and still parses, and colour
+ * survives any scale at all. So the overview tier spends everything on the two
+ * signals that keep working — which branch kind, which number — and a canvas
+ * of sixty frames reads as a coloured structure instead of grey mush.
+ */
+export declare const FRAME_LABEL_COMPACT_ZOOM = 0.35;
+export declare function setFrameBranchKinds(defs: readonly FrameBranchKindDef[], labels?: FrameLabelLabels): void;
+export declare function getFrameBranchKinds(): readonly FrameBranchKindDef[];
+export declare function getFrameLabelLabels(): FrameLabelLabels | undefined;
+export declare function frameBranchKindFor(kind: string): FrameBranchKindDef;

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

@@ -0,0 +1,62 @@
+/** A situation group within one section. Declaration order is lane order. */
+export interface ScreenLaneDef {
+    /** Unique within its section. */
+    id: string;
+    /** Human-readable, in the host's language — drawn as the lane caption. */
+    label: string;
+    /** The section this lane belongs to, matched against `page.section`. */
+    section: string;
+    /** Caption rule colour. Defaults to the neutral caption colour. */
+    accent?: string;
+}
+export interface ScreenLaneDiagnostic {
+    severity: 'error' | 'warning';
+    laneId: string;
+    message: string;
+}
+export declare const LANE_CAPTION_STYLE: {
+    /** Rule width and the gap between rule and text. */
+    readonly ruleWidth: 4;
+    readonly gap: 10;
+    /** Caption band height, and the space between caption and the first label. */
+    readonly height: 26;
+    readonly marginBottom: 14;
+    readonly fontSize: 17;
+    readonly fontWeight: 700;
+    readonly color: "#6b6b76";
+    readonly accent: "#b8b8c2";
+    readonly countColor: "#a1a1b3";
+    readonly countSize: 14;
+};
+/**
+ * Lane layout constants. `maxFramesPerRow` is what a designer can take in
+ * without panning at overview zoom — six 1280px screens is about one viewport
+ * — so a longer lane wraps into continuation rows rather than running off.
+ */
+export declare const LANE_LAYOUT: {
+    readonly gap: 80;
+    readonly laneGap: 210;
+    readonly maxFramesPerRow: 6;
+};
+/** The implicit lane that collects frames no declaration placed. */
+export declare const UNDECLARED_LANE_ID = "";
+export declare function validateScreenLanes(lanes: readonly ScreenLaneDef[], context?: {
+    sections?: readonly string[];
+}): ScreenLaneDiagnostic[];
+export declare function setScreenLanes(lanes: readonly ScreenLaneDef[] | undefined): void;
+export declare function getScreenLanes(): readonly ScreenLaneDef[];
+/** Declared lanes of one section, in declaration order. */
+export declare function lanesForSection(section: string): ScreenLaneDef[];
+export declare function laneCaptionFor(section: string, laneId: string): ScreenLaneDef | null;
+/**
+ * Groups frames into lanes in declaration order, appending the implicit lane
+ * last. A frame tagged with a lane the section did not declare counts as
+ * undeclared rather than creating a lane of its own, so a typo shows up as a
+ * frame that fell out of its situation instead of as a phantom row.
+ */
+export declare function groupByLane<T extends {
+    lane?: string;
+}>(section: string, frames: readonly T[]): {
+    laneId: string;
+    frames: T[];
+}[];

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

@@ -0,0 +1,123 @@
+export type FrameLifecycleTier = 'full' | 'contained' | 'detached';
+export interface FrameLodRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface FrameLodCamera {
+    panX: number;
+    panY: number;
+    zoom: number;
+}
+export interface FrameLodViewport {
+    width: number;
+    height: number;
+}
+export interface FrameLodConfig {
+    /** Distance below which a contained or detached frame promotes to full. */
+    fullEnter: number;
+    /** Distance above which a full frame demotes to contained. */
+    fullExit: number;
+    /** Distance beyond which a contained frame may detach after the dwell. */
+    detachEnter: number;
+    /** Distance below which a detached frame reattaches as contained. */
+    detachExit: number;
+    /**
+     * How long a frame must have held its contained tier before it may detach.
+     * Counted from the tier-entry timestamp, so a pan that sweeps a frame out
+     * and back within the dwell never pays a remount.
+     */
+    dwellMs: number;
+    /** Slack factor when testing whether the frame union fits the viewport. */
+    overviewFitSlack: number;
+    /** Frames intersecting the viewport at once that force overview mode. */
+    overviewVisibleCount: number;
+}
+export declare const DEFAULT_FRAME_LOD_CONFIG: FrameLodConfig;
+export interface FrameLodFrame {
+    id: string;
+    rect: FrameLodRect;
+    /** Pinned frames (active, selected, preview-intended, live) stay full. */
+    pinned: boolean;
+    /** Retained snapshot weight proxy: serialized snapshot length times two. */
+    weightBytes: number;
+    /**
+     * Screenshot bitmap pixels stored per frame CSS pixel; null or absent when
+     * the frame has no captured screenshot. Input to the magnification signal.
+     */
+    screenshotDensity?: number | null;
+}
+export interface FrameLodTierState {
+    tier: FrameLifecycleTier;
+    /** Timestamp at which the frame entered its current tier. */
+    since: number;
+}
+/**
+ * Screen-space gap between a frame and the viewport, normalized by the
+ * viewport diagonal. A frame intersecting the viewport is at distance zero;
+ * one whole viewport diagonal away is at distance one.
+ */
+export declare function frameViewportDistance(frameRect: FrameLodRect, camera: FrameLodCamera, viewport: FrameLodViewport): number;
+/**
+ * An overview camera sees the storyboard as a whole: either the union of all
+ * frames roughly fits the viewport, or many frames intersect it at once. In
+ * overview every frame legitimately needs pixels, so tier demotion is off and
+ * the imperative camera writer alone pays for the pan.
+ */
+export declare function isOverviewCamera(frames: readonly FrameLodRect[], camera: FrameLodCamera, viewport: FrameLodViewport, config?: FrameLodConfig): boolean;
+/**
+ * True when the camera draws a frame above its screenshot's pixel density —
+ * the bitmap would visibly blur, so the frame should trade its screenshot for
+ * the frozen DOM surface. Gated on the `full` tier: at magnifying zoom levels
+ * only a handful of frames are near the viewport, which keeps simultaneous
+ * DOM reconstruction bounded.
+ *
+ * An overview camera never magnifies. Overview marks every frame `full`
+ * because they all need pixels at once — and a low-density bitmap (a legacy
+ * 1x capture on a 2x display) can sit "past its density" at overview zoom,
+ * which would reconstruct the whole storyboard's frozen DOM in one pass.
+ */
+export declare function frameMagnifiedPastBitmap(tier: FrameLifecycleTier, displayDensity: number, screenshotDensity: number | null | undefined, overview: boolean): boolean;
+/**
+ * Whether frame screenshots should display at their native (2x) resolution.
+ * Below one device pixel per CSS pixel a half-scale bitmap is
+ * indistinguishable, and an overview showing every frame at native capture
+ * resolution keeps gigabytes of decoded bitmap resident — the canvas pans
+ * like it is buffering. The display density is camera-global, so this is one
+ * signal, not a per-frame one; the ±5% band keeps a zoom hovering at the
+ * boundary from flapping between decodes.
+ */
+export declare function resolveBitmapFullSignal(previous: boolean, displayDensity: number): boolean;
+export declare const FRAME_LOD_BUDGET_BYTES_PER_GB: number;
+export declare const FRAME_LOD_BUDGET_MIN_BYTES: number;
+export declare const FRAME_LOD_BUDGET_MAX_BYTES: number;
+export declare const FRAME_LOD_BUDGET_MIN_BYTES_PER_FRAME: number;
+/**
+ * Total attached-preview weight allowed before the governor demotes the
+ * farthest unpinned frames. Scales with device memory, clamped, and never
+ * drops below a small per-frame allowance so a large storyboard is not forced
+ * into a wall of placeholders on a small device.
+ */
+export declare function resolveFrameLodBudget({ deviceMemoryGb, frameCount, }: {
+    deviceMemoryGb?: number;
+    frameCount: number;
+}): number;
+/**
+ * Resolves the lifecycle tier for every frame. Rules, in order: an overview
+ * camera keeps everything full; pinned frames are always full; otherwise the
+ * hysteresis step above applies; finally the memory governor demotes the
+ * farthest unpinned attached frames (skipping weightless ones — demoting them
+ * frees nothing) until the attached weight fits the budget. Governor
+ * demotion is allowed to bypass the dwell: it exists to cap memory, not to
+ * smooth pans.
+ */
+export declare function resolveFrameLodTiers({ frames, camera, viewport, previous, now, config, budget, }: {
+    frames: readonly FrameLodFrame[];
+    camera: FrameLodCamera;
+    viewport: FrameLodViewport;
+    previous: ReadonlyMap<string, FrameLodTierState>;
+    now: number;
+    config?: FrameLodConfig;
+    budget: number;
+}): Map<string, FrameLifecycleTier>;

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

@@ -0,0 +1,64 @@
+import { type FrameLifecycleTier, type FrameLodCamera, type FrameLodConfig, type FrameLodFrame, type FrameLodViewport } from './frameLod';
+/** Frames the controller has not classified render at full detail. */
+export declare const DEFAULT_FRAME_LOD_TIER: FrameLifecycleTier;
+export declare function getFrameTier(frameId: string): FrameLifecycleTier;
+/**
+ * True when the camera currently draws this frame beyond its screenshot's
+ * pixel density. Published from the same recompute as the tiers, over the
+ * same per-frame channels, so only frames whose flag flips re-render.
+ */
+export declare function getFrameMagnification(frameId: string): boolean;
+/**
+ * Whether screenshots should display at native capture resolution right now.
+ * Camera-global: below one device pixel per CSS pixel every frame's
+ * half-scale bitmap is indistinguishable and far cheaper to keep decoded.
+ */
+export declare function getFrameBitmapFull(): boolean;
+export declare function subscribeFrameBitmapScale(listener: () => void): () => void;
+/** Diagnostic view of the published LOD state, for headless debugging. */
+export declare function __debugFrameLodState(): {
+    tiers: [string, FrameLifecycleTier][];
+    magnified: [string, boolean][];
+    lastRecompute: {
+        displayDensity?: number;
+        overview?: boolean;
+        frames?: {
+            id: string;
+            screenshotDensity: number | null | undefined;
+            tier: string;
+        }[];
+    };
+};
+export declare function subscribeFrameLod(frameId: string, listener: () => void): () => void;
+/**
+ * Total live tier listeners across all frames. A diagnostic seam for leak
+ * tests: after any number of mount/unmount cycles the count must return to
+ * what it was before them, because every subscribeFrameLod cleanup removes
+ * its listener and drops the frame's empty set.
+ */
+export declare function countFrameLodListeners(): number;
+export interface FrameLodCameraSample extends FrameLodCamera {
+    /** Tracked so a canvas switch retriggers the reaction; unused by the math. */
+    canvas?: string;
+}
+export interface FrameLodControllerOptions {
+    /** Read inside the MobX reaction — its observable reads drive recomputes. */
+    readCamera(): FrameLodCameraSample;
+    /** Read untracked at compute time. */
+    readFrames(): readonly FrameLodFrame[];
+    readViewport(): FrameLodViewport;
+    /** Throttle for camera-driven recomputes. Defaults to requestAnimationFrame. */
+    schedule?(recompute: () => void): () => void;
+    now?(): number;
+    config?: FrameLodConfig;
+    resolveBudget?(frames: readonly FrameLodFrame[]): number;
+    /** Screen device pixels per CSS pixel. Defaults to window.devicePixelRatio. */
+    readDevicePixelRatio?(): number;
+}
+export interface FrameLodController {
+    start(): void;
+    stop(): void;
+    /** Runs the tier computation immediately (initial mount and tests). */
+    recompute(): void;
+}
+export declare function createFrameLodController(options: FrameLodControllerOptions): FrameLodController;