@pygmalionjs/pygmalion 0.5.14 → 0.5.15

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

@@ -0,0 +1,34 @@
+export interface ContentBounds {
+    width: number;
+    height: number;
+}
+type ContentBoundsMeasurement = (element: Element) => ContentBounds;
+/**
+ * Measures the actual rendered bounds of a catalog root. Scroll metrics cover
+ * tables and forms that overflow their wrapper; the descendant union covers
+ * positioned content that is not represented by the wrapper's scroll box.
+ */
+export declare function measureContentBounds(element: Element): ContentBounds;
+/**
+ * Measures the authored content root itself instead of its overflow box.
+ *
+ * `data-pygmalion-content-bounds` is an explicit frame boundary. Its layout
+ * border box already grows with normal-flow and max-content children, while
+ * scroll metrics can be polluted by editor-only layers after DOM promotion.
+ * Prefer untransformed layout metrics so canvas zoom never changes the model
+ * frame size.
+ */
+export declare function measureContentBorderBounds(element: Element): ContentBounds;
+/**
+ * Reports stable rendered bounds after layout, font loading, resize, and DOM
+ * mutation. Updates are coalesced through two animation frames so a font or
+ * component layout commit cannot publish an intermediate frame size.
+ */
+export declare function observeContentBounds(element: Element, onBoundsChange: (bounds: ContentBounds) => void, measure?: ContentBoundsMeasurement): () => void;
+/**
+ * Follows the measurable catalog root inside a render host. Catalog components
+ * may mount or be replaced after the frame effect runs, so observing only the
+ * first query result can leave a persisted seed size in place indefinitely.
+ */
+export declare function observeContentBoundsTarget(container: Element, selector: string, onBoundsChange: (bounds: ContentBounds) => void, measure?: ContentBoundsMeasurement): () => void;
+export {};

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

@@ -0,0 +1,100 @@
+import { type CodegenFrameOptions, type CodegenNode } from './codegen';
+import { type NodeJSON } from './store';
+export declare const DESIGN_IR_SCHEMA: "pygmalion.design-ir";
+export declare const DESIGN_IR_VERSION: 1;
+export type DesignCompilePurpose = 'interactive' | 'export';
+export type DesignCompileSeverity = 'info' | 'warning' | 'error';
+export type DesignCompileStage = 'normalize' | 'analyze' | 'generate' | 'resource';
+export type DesignCompileStatus = 'ready' | 'deferred' | 'blocked';
+export interface DesignCompileDiagnostic {
+    severity: DesignCompileSeverity;
+    stage: DesignCompileStage;
+    code: string;
+    message: string;
+    nodeId?: string;
+    nodePath?: string;
+    details?: Readonly<Record<string, string | number | boolean>>;
+}
+export interface DesignIRAsset {
+    id: string;
+    kind: 'image' | 'video' | 'background';
+    source: string;
+    portability: 'embedded' | 'remote' | 'project' | 'ephemeral';
+    nodeIds: readonly string[];
+}
+export interface DesignIRComponent {
+    name: string;
+    importPath: string;
+    registered: boolean;
+    connectionId?: string;
+    sourcePath?: string;
+    design?: {
+        provider: string;
+        documentId?: string;
+        nodeId: string;
+        url?: string;
+    };
+    nodeIds: readonly string[];
+}
+export interface DesignIRMetrics {
+    nodeCount: number;
+    maxDepth: number;
+    hiddenNodeCount: number;
+    componentCount: number;
+    assetCount: number;
+}
+export interface DesignIntermediateDocumentV1 {
+    schema: typeof DESIGN_IR_SCHEMA;
+    version: typeof DESIGN_IR_VERSION;
+    root: NodeJSON;
+    frame?: CodegenFrameOptions;
+    components: readonly DesignIRComponent[];
+    assets: readonly DesignIRAsset[];
+    metrics: DesignIRMetrics;
+}
+export interface DesignCompileLimits {
+    /** Interactive code output pauses above this size until explicitly requested. */
+    previewNodeLimit: number;
+    /** Compilation is blocked instead of silently dropping nodes. */
+    maxNodes: number;
+    maxDepth: number;
+    maxOutputBytes: number;
+}
+export declare const DEFAULT_DESIGN_COMPILE_LIMITS: Readonly<DesignCompileLimits>;
+export interface DesignCodegenAdapterContext {
+    document: DesignIntermediateDocumentV1;
+}
+export interface DesignCodegenAdapterOutput {
+    code: string;
+    diagnostics?: readonly DesignCompileDiagnostic[];
+}
+export interface DesignCodegenAdapter {
+    id: string;
+    label: string;
+    language: string;
+    extension: string;
+    generate(context: DesignCodegenAdapterContext): string | DesignCodegenAdapterOutput;
+}
+export interface DesignCompileOptions {
+    target?: string;
+    purpose?: DesignCompilePurpose;
+    force?: boolean;
+    frame?: CodegenFrameOptions;
+    limits?: Partial<DesignCompileLimits>;
+}
+export interface DesignCompileResult {
+    target: string;
+    status: DesignCompileStatus;
+    code: string;
+    language?: string;
+    extension?: string;
+    document: DesignIntermediateDocumentV1;
+    diagnostics: readonly DesignCompileDiagnostic[];
+    metrics: DesignIRMetrics & {
+        outputBytes: number;
+    };
+}
+export declare function createDesignIntermediateDocument(root: CodegenNode, frame?: CodegenFrameOptions): DesignIntermediateDocumentV1;
+export declare function registerDesignCodegenAdapter(adapter: DesignCodegenAdapter): () => void;
+export declare function getDesignCodegenAdapters(): readonly DesignCodegenAdapter[];
+export declare function compileDesignDocument(root: CodegenNode, options?: DesignCompileOptions): DesignCompileResult;

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

@@ -0,0 +1,448 @@
+import { type DomImportOptions, type DomImportResult } from './domImport';
+import type { DesignFrameHeightMode } from './frameHeight';
+import type { ComponentRegistry } from './registry';
+import type { TokenDef } from './tokens';
+export declare const DESIGN_IMPORT_KINDS: readonly ["icons", "design-tokens", "atoms", "components", "screens"];
+export type DesignImportKind = (typeof DESIGN_IMPORT_KINDS)[number];
+export type DesignFrameSizeMode = 'fixed' | 'content';
+export type { DesignFrameHeightMode } from './frameHeight';
+/** Individual assets discovered at source. Connect to which designer sheet it can be viewed using pageId. */
+export interface DesignImportAsset {
+    id: string;
+    name: string;
+    section: string;
+    pageId: string;
+    sourcePath?: string;
+    codeName?: string;
+    /** Metadata that describes the user flow/QA catalog when it is a screen asset. */
+    flow?: string;
+    scenarioId?: string;
+    description?: string;
+}
+export type DesignScreenInteractionAction = 'click' | 'focus' | 'fill' | 'check' | 'press' | 'wait' | 'storage';
+/**
+ * A critical step to capture the actual app screen after putting it in a specific user flow state.
+ * A CSS selector is used first, and if text is present, the selector candidates are narrowed down to the display string.
+ */
+export interface DesignScreenInteraction {
+    action: DesignScreenInteractionAction;
+    label: string;
+    selector?: string;
+    text?: string;
+    exact?: boolean;
+    index?: number;
+    /** A wait step observes visible elements by default. Use attached to wait for DOM insertion only. */
+    waitState?: 'visible' | 'attached';
+    value?: string;
+    key?: string;
+    storage?: 'local' | 'session';
+    timeoutMs?: number;
+    settleMs?: number;
+    optional?: boolean;
+}
+/** A JSON-compatible value that conveys host-specific meaning without Pygmalion interpreting it. */
+export type DesignSerializable = string | number | boolean | null | readonly DesignSerializable[] | {
+    readonly [key: string]: DesignSerializable;
+};
+/**
+ * A deterministic environment that the host must recreate before capture.
+ * Example: { role, api, host, timers, device, microphone }.
+ * The meaning of keys and values ​​is entirely owned by the host adapter.
+ */
+export type DesignScreenPreset = Readonly<Record<string, DesignSerializable>>;
+export type StoryboardPermissionState = 'granted' | 'denied' | 'prompt';
+export type StoryboardMediaFailure = 'not-allowed' | 'not-found' | 'not-readable' | 'overconstrained';
+export interface StoryboardMediaDevice {
+    kind: 'audioinput' | 'audiooutput' | 'videoinput';
+    deviceId: string;
+    groupId?: string;
+    label?: string;
+}
+/**
+ * Browser-owned state that must exist before application modules execute.
+ * Unlike a host preset, these keys have portable semantics and are installed
+ * by the Pygmalion preview runtime before the route application mounts.
+ */
+export interface StoryboardEnvironment {
+    localStorage?: Readonly<Record<string, string | null>>;
+    sessionStorage?: Readonly<Record<string, string | null>>;
+    permissions?: Readonly<Record<string, StoryboardPermissionState>>;
+    mediaDevices?: {
+        devices?: readonly StoryboardMediaDevice[];
+        getUserMedia?: 'passthrough' | StoryboardMediaFailure;
+    };
+    /**
+     * 'sandbox' virtualizes the whole origin storage for the document: reads
+     * of undeclared keys see a pristine profile and writes never reach the
+     * shared storage. Hidden preview instances set it so persisted UI state
+     * from one walk cannot poison sibling instances or the designer's tab.
+     */
+    storageIsolation?: 'sandbox';
+    /**
+     * Host screen preset installed as `window.__PYGMALION_SCREEN_PRESET__`
+     * before application modules execute — parity with the Node capture
+     * runtime's init script for fixtures that read the preset at module or
+     * mount time.
+     */
+    screenPreset?: Readonly<Record<string, unknown>>;
+    /**
+     * Request outcomes, applied by patching fetch and XMLHttpRequest before
+     * application modules execute.
+     *
+     * A failed request, an empty result, a slow response — these are states the
+     * product spends real time in and a storyboard almost never shows, because
+     * reaching one is not something a designer can click. Hosts used to reproduce
+     * them by inventing a flag per state and branching their own mock layer,
+     * which costs enough that most were never declared at all. The mechanism is
+     * generic, so it belongs here: the host says which request, not how to fake
+     * it.
+     */
+    network?: StoryboardNetwork;
+}
+export type StoryboardRequestOutcome = 
+/** Reject the request the way an offline or 5xx call rejects. */
+{
+    kind: 'fail';
+    status?: number;
+    message?: string;
+}
+/** Resolve with a well-formed but empty body, for empty-state screens. */
+ | {
+    kind: 'empty';
+    status?: number;
+    body?: string;
+}
+/** Resolve normally, late — the loading state, held still for capture. */
+ | {
+    kind: 'slow';
+    delayMs: number;
+};
+export interface StoryboardRequestCondition {
+    /**
+     * Matched against the request URL as a substring, so a host can name an
+     * endpoint without knowing the origin a preview boots on.
+     */
+    match: string;
+    method?: string;
+    outcome: StoryboardRequestOutcome;
+}
+export interface StoryboardNetwork {
+    conditions?: readonly StoryboardRequestCondition[];
+}
+export type DesignScreenAssertionVisibility = 'visible' | 'hidden';
+export interface DesignScreenAttributeAssertion {
+    name: string;
+    /** If omitted, the existence of the attribute itself is checked. */
+    value?: string;
+    match?: 'equals' | 'contains';
+    /** If false, there should be no attribute. Default true. */
+    present?: boolean;
+}
+/** An end condition that is checked immediately before capturing the DOM after an interaction. */
+export interface DesignScreenAssertion {
+    label: string;
+    selector: string;
+    index?: number;
+    /** If false, the selector should not exist. Default true. */
+    exists?: boolean;
+    text?: string;
+    exact?: boolean;
+    attribute?: DesignScreenAttributeAssertion;
+    visibility?: DesignScreenAssertionVisibility;
+    timeoutMs?: number;
+    optional?: boolean;
+}
+/** The page whose assets will be rendered into the actual DOM. One page can contain multiple icon/token assets. */
+export interface DesignImportPage {
+    id: string;
+    name: string;
+    section: string;
+    componentName?: string;
+    gallery?: string[];
+    route?: string;
+    path?: string;
+    publish?: boolean;
+    width?: number;
+    height?: number;
+    /**
+     * `content` replaces the 1×1 measurement seed with the rendered catalog
+     * root's actual DOM bounds. The default keeps the configured frame size.
+     */
+    frameSizeMode?: DesignFrameSizeMode;
+    /** `document` expands the frame to the rendered document height. The default remains a fixed viewport. */
+    heightMode?: DesignFrameHeightMode;
+    /** Safety limit used only by document-height frames. Defaults to 12,000px and is capped at 32,000px. */
+    maxHeight?: number;
+    /** User flow hierarchy and status that designers use when organizing screens. */
+    flow?: string;
+    scenario?: string;
+    state?: string;
+    /** Host-declared kind of the state branch (overlay, badge, layout, ...). */
+    stateKind?: string;
+    /** Host-declared situation group the canvas arranges the frame into. */
+    lane?: string;
+    scenarioId?: string;
+    /**
+     * Every scenario this screen demonstrates. Coverage is the whole set; the
+     * canonical `scenarioId` is only the one a reviewer is sent to first, and a
+     * screen may declare the set without naming a canonical one.
+     */
+    scenarioIds?: readonly string[];
+    interactions?: readonly DesignScreenInteraction[];
+    environment?: StoryboardEnvironment;
+    preset?: DesignScreenPreset;
+    assertions?: readonly DesignScreenAssertion[];
+    /**
+     * Names a group of screens that one running application can serve.
+     *
+     * A declared state is reached by switching state, so screens in the same group
+     * share a booted instance — capture reuses a warm page, and the editor reuses
+     * a warm preview. Set it only when the declaration is the complete state; a
+     * screen whose result depends on how it was entered must leave it unset.
+     * Screens with interactions never share an instance, because only the screen
+     * knows how to undo what a click opened.
+     */
+    session?: string;
+}
+export interface DesignImportCollection {
+    assets: readonly DesignImportAsset[];
+    pages: readonly DesignImportPage[];
+    /** Number of original code scans. If it is different from assets.length, it is judged as stale/missing. */
+    expectedCount: number;
+}
+/** User scenarios discovered in host code. This is the input ledger for screen case classification. */
+export interface DesignScenarioSource {
+    id: string;
+    name?: string;
+    section: string;
+    flow?: string;
+    sourcePath?: string;
+    codeName?: string;
+    description?: string;
+}
+/** A single visual state that is recreated in the actual app for designers to review. */
+export interface DesignScreenCase extends DesignImportPage {
+    scenarioIds?: readonly string[];
+    sourcePath?: string;
+    codeName?: string;
+    /** The code route that this visual state represents. Used when reproducing the route guard state with a component fixture. */
+    coverageRoutes?: readonly string[];
+}
+/** Operational scenarios such as network, storage, bridge, etc. without separate visual state. */
+export interface DesignBehaviorScenario {
+    id: string;
+    reason: string;
+}
+export interface DesignScenarioCoverage {
+    total: number;
+    screen: number;
+    behavior: number;
+    missing: readonly string[];
+    complete: boolean;
+}
+export interface DesignScreenCollectionResult {
+    collection: DesignImportCollection;
+    coverage: DesignScenarioCoverage;
+}
+/** A portable viewport variant used to render the same authored screen recipe responsively. */
+export interface DesignScreenViewport {
+    id: string;
+    label: string;
+    width: number;
+    height: number;
+    heightMode?: DesignFrameHeightMode;
+    maxHeight?: number;
+}
+export type DesignScreenViewportPagePatch = Partial<Omit<DesignImportPage, 'id' | 'name' | 'section' | 'width' | 'height'>>;
+export interface DesignScreenViewportExpansionOptions {
+    include?: (page: DesignImportPage, viewport: DesignScreenViewport) => boolean;
+    /**
+     * Adapts viewport-specific reproduction details such as interactions,
+     * assertions, presets, or document-height behavior. Identity, grouping, and
+     * viewport dimensions are still owned by the expansion contract.
+     */
+    transformPage?: (page: DesignImportPage, viewport: DesignScreenViewport) => DesignScreenViewportPagePatch | undefined;
+    createPageId?: (page: DesignImportPage, viewport: DesignScreenViewport) => string;
+    createPageName?: (page: DesignImportPage, viewport: DesignScreenViewport) => string;
+    createSection?: (page: DesignImportPage, viewport: DesignScreenViewport) => string;
+}
+export interface DesignImportManifest {
+    sourceSha?: string;
+    registry: ComponentRegistry;
+    tokens: readonly TokenDef[];
+    collections: Record<DesignImportKind, DesignImportCollection>;
+}
+export interface DesignImportInitialPage {
+    name: string;
+    canvas: string;
+    section?: string;
+    componentName?: string;
+    gallery?: string[];
+    route?: string;
+    path?: string;
+    publish?: boolean;
+    width?: number;
+    height?: number;
+    frameSizeMode?: DesignFrameSizeMode;
+    heightMode?: DesignFrameHeightMode;
+    maxHeight?: number;
+    /** If true, the entire actual DOM is replaced with an editable layer tree immediately after the first render. */
+    importLayers?: boolean;
+    /** Original manifest page id and asset type. */
+    importPageId?: string;
+    importKind?: DesignImportKind;
+    /** The actual code assets and source files that this edit frame represents. */
+    assetIds?: string[];
+    sourcePaths?: string[];
+    flow?: string;
+    scenario?: string;
+    state?: string;
+    stateKind?: string;
+    lane?: string;
+    scenarioId?: string;
+    interactions?: DesignScreenInteraction[];
+    environment?: StoryboardEnvironment;
+    preset?: DesignScreenPreset;
+    assertions?: DesignScreenAssertion[];
+}
+export interface DesignImportCoverageItem {
+    expected: number;
+    imported: number;
+    pages: number;
+    missing: number;
+}
+export type DesignImportCoverage = Record<DesignImportKind, DesignImportCoverageItem> & {
+    sourceSha?: string;
+    complete: boolean;
+};
+export interface DesignScreenInteractionReport {
+    complete: boolean;
+    completed: number;
+    total: number;
+    failedLabel?: string;
+    error?: string;
+}
+export type DesignScreenCaptureFailureStage = 'preset' | 'interaction' | 'assertion';
+export type DesignScreenCaptureFailureCode = 'preset_executor_missing' | 'preset_rejected' | 'preset_error' | 'interaction_failed' | 'invalid_selector' | 'existence_mismatch' | 'text_mismatch' | 'attribute_mismatch' | 'visibility_mismatch';
+export interface DesignScreenCaptureFailure {
+    stage: DesignScreenCaptureFailureStage;
+    code: DesignScreenCaptureFailureCode;
+    message: string;
+    label?: string;
+    index?: number;
+    selector?: string;
+    expected?: DesignSerializable;
+    actual?: DesignSerializable;
+}
+export interface DesignScreenAssertionReport {
+    complete: boolean;
+    completed: number;
+    total: number;
+    failures: DesignScreenCaptureFailure[];
+}
+export interface DesignScreenCaptureReport {
+    complete: boolean;
+    presetApplied: boolean;
+    interactions: DesignScreenInteractionReport;
+    assertions: DesignScreenAssertionReport;
+    failures: DesignScreenCaptureFailure[];
+    /** First failure summary compatible with existing screen error UI. */
+    failedLabel?: string;
+    error?: string;
+}
+/**
+ * Rejects a rendered route state when its authored reproduction recipe did not
+ * finish. Call this before serializing or caching a live preview so a base
+ * route cannot silently replace the requested interaction state.
+ */
+export declare function assertScreenCaptureComplete(report: DesignScreenCaptureReport | null | undefined): void;
+/** Serializable preset transport. The iframe is delivered only to a separate local execution context. */
+export interface DesignScreenPresetRequest {
+    pageId: string;
+    route?: string;
+    preset: DesignScreenPreset;
+}
+export interface DesignScreenPresetContext {
+    iframe: HTMLIFrameElement;
+}
+export interface DesignScreenPresetExecutionResult {
+    complete: boolean;
+    message?: string;
+    details?: DesignSerializable;
+}
+export type DesignScreenPresetExecutor = (request: DesignScreenPresetRequest, context: DesignScreenPresetContext) => Promise<DesignScreenPresetExecutionResult | void> | DesignScreenPresetExecutionResult | void;
+export interface DesignScreenCaptureSpec {
+    pageId: string;
+    route?: string;
+    preset?: DesignScreenPreset;
+    interactions?: readonly DesignScreenInteraction[];
+    assertions?: readonly DesignScreenAssertion[];
+}
+export interface DesignScreenCaptureDefaults {
+    preset?: DesignScreenPreset;
+    assertions?: readonly DesignScreenAssertion[];
+}
+/** Host opt-in guard to block missing contracts in large catalogs before starting the editor. */
+export interface DesignScreenCaptureRequirements {
+    preset?: boolean;
+    assertions?: boolean;
+}
+export interface DesignImportController {
+    readonly sourceSha?: string;
+    getRegistry(): ComponentRegistry;
+    getTokens(): TokenDef[];
+    getAssets(kind?: DesignImportKind): DesignImportAsset[];
+    getInitialPages(): DesignImportInitialPage[];
+    getCoverage(): DesignImportCoverage;
+    assertComplete(): void;
+    captureElement(element: Element, win?: Window, options?: DomImportOptions): DomImportResult | null;
+    captureIframe(iframe: HTMLIFrameElement, options?: DomImportOptions): DomImportResult | null;
+    captureIframeWhenStable(iframe: HTMLIFrameElement, options?: DomImportOptions & {
+        settleMs?: number;
+        timeoutMs?: number;
+        minElementCount?: number;
+    }): Promise<DomImportResult | null>;
+    runScreenInteractions(iframe: HTMLIFrameElement, interactions: readonly DesignScreenInteraction[]): Promise<DesignScreenInteractionReport>;
+    prepareScreenCapture(iframe: HTMLIFrameElement, spec: DesignScreenCaptureSpec): Promise<DesignScreenCaptureReport>;
+}
+export interface CreateDesignImportOptions {
+    /** Default budget for full layer mode. The host can explicitly increase it according to the screen size. */
+    layerOptions?: DomImportOptions;
+    /** The only boundary that enforces the host-specific semantics of the preset. The package does not interpret the payload. */
+    executeScreenPreset?: DesignScreenPresetExecutor;
+    /**
+     * How screen pages spread across canvases. `single` (default) keeps every
+     * screen on one canvas. `section` gives each section its own canvas
+     * (`<screens canvas> · <section>`): only the active section's frames
+     * materialize, so the camera, the LOD budget, and decoded previews scale
+     * with a section instead of the whole catalog. Cross-canvas activation
+     * already switches canvases (EditorStore.switchPage).
+     */
+    screensCanvasPartition?: 'single' | 'section';
+}
+/** Creates responsive variants of authored cases without reclassifying source scenarios. */
+export declare function expandDesignScreenCasesViewports(cases: readonly DesignScreenCase[], viewports: readonly DesignScreenViewport[], options?: DesignScreenViewportExpansionOptions): DesignScreenCase[];
+/**
+ * Expands a canonical screen collection into deterministic responsive frames.
+ *
+ * Scenario coverage is intentionally calculated before this step. Responsive
+ * frames are alternate renderings of the same authored recipe, not duplicate
+ * scenario assignments.
+ */
+export declare function expandDesignScreenCollectionViewports(collection: DesignImportCollection, viewports: readonly DesignScreenViewport[], options?: DesignScreenViewportExpansionOptions): DesignImportCollection;
+/**
+ * Classify every code scenario once as either a screen case or a non-visual operation.
+ * Silent omissions, duplicate classifications, and non-existent scenario/frame references are blocked before opening the editor.
+ */
+export declare function createDesignScreenCollection({ cases, scenarios, behaviorScenarios, captureDefaults, captureRequirements, }: {
+    cases: readonly DesignScreenCase[];
+    scenarios: readonly DesignScenarioSource[];
+    behaviorScenarios?: readonly DesignBehaviorScenario[];
+    captureDefaults?: DesignScreenCaptureDefaults;
+    captureRequirements?: DesignScreenCaptureRequirements;
+}): DesignScreenCollectionResult;
+/** Host basic environment + override for each case. Objects are recursively merged and arrays/primitives are replaced by cases. */
+export declare function mergeScreenPresets(defaults?: DesignScreenPreset, override?: DesignScreenPreset): DesignScreenPreset;
+export declare function createDesignImportController(manifest: DesignImportManifest, options?: CreateDesignImportOptions): DesignImportController;
+export declare function setDesignImportController(controller: DesignImportController | null): void;
+export declare function getDesignImportController(): DesignImportController | null;

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

@@ -0,0 +1,28 @@
+import type { EditorStore } from './store';
+type SyncStatus = 'idle' | 'saving' | 'saved' | 'error';
+declare class DesignSyncState {
+    status: SyncStatus;
+    pending: number;
+    message: string;
+    constructor();
+    setPending(pending: number): void;
+    setStatus(status: SyncStatus, message: string): void;
+}
+/** General purpose status to show code autosave status in right panel. */
+export declare const designSyncState: DesignSyncState;
+/**
+ * It observes the entire edited document, but only sends the final state of changed elements to the host.
+ * Continuous typing/dragging and undo/redo are combined with the same element key, so the save history and edit history are separated.
+ */
+export declare function startDocumentSync(editor: EditorStore): () => void;
+/** Tokens also use the same element change queue as canvas documents. */
+export declare function queueTokenDesignChange(tokens: {
+    name: string;
+    value: string;
+}[]): void;
+/**
+ * Clear all remaining debounce/asynchronous storage just before final reflection.
+ * Save failures are propagated to the caller, and any saved pendings are retried on the next flush.
+ */
+export declare function flushDesignChanges(): Promise<void>;
+export {};

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

@@ -0,0 +1,58 @@
+import type { InstanceHit, InstanceResolver } from './fiberMap';
+import type { NodeJSON } from './store';
+/** Keeps a real 0 — the value that hides hover-only affordances. */
+export declare function clampOpacity(value: string): number;
+export interface DomImportDiagnostic {
+    severity: 'warning';
+    stage: 'capture';
+    code: 'max-nodes' | 'max-depth';
+    message: string;
+    limit: number;
+    actual: number;
+}
+export interface DomImportMetrics {
+    nodeCount: number;
+    maxDepth: number;
+}
+export interface DomImportOptions {
+    /** fiberMap resolver — Promotes the registry instance root to a component node, if present. */
+    resolveInstance?: InstanceResolver;
+    /**
+     * Overrides the `file#localName` CSS-module source lookup for an element.
+     * Defaults to the live-realm sourceTargetOf mapping; frozen previews swap in
+     * a resolver that reads the stamped data-pygmalion-source-style attribute.
+     */
+    resolveSourceStyle?: (el: Element) => string;
+    /** collapse=component 1 node, expand=component boundary name+entire child DOM, ignore=pure DOM. */
+    instanceMode?: 'collapse' | 'expand' | 'ignore';
+    /**
+     * Hybrid collapse for 'expand' mode: a resolved hit this predicate accepts is
+     * imported as one component node exactly like instanceMode 'collapse', while
+     * rejected hits and unresolved DOM keep expanding. Ignored in other modes.
+     */
+    collapseInstance?: (hit: InstanceHit) => boolean;
+    /** Exclude instance matching registry name — to prevent the fixture being disassembled from being re-captured in its entirety. */
+    exclude?: ReadonlySet<string>;
+    /** CSS transform scale (canvas zoom) — getBoundingClientRect is converted to model px because the transform is reflected. */
+    scale?: number;
+    /** Recursion depth/node budget. truncated=true when exceeded. */
+    maxDepth?: number;
+    maxNodes?: number;
+    /** display:none/visibility:hidden layers are also kept hidden. */
+    includeHidden?: boolean;
+    /** Structural layers of size 0 are also preserved. */
+    includeZeroSize?: boolean;
+    /** placeholder=one box of media, layers=svg/path/picture recursively down to the lower DOM. */
+    mediaMode?: 'placeholder' | 'layers';
+}
+export interface DomImportResult {
+    root: NodeJSON;
+    count: number;
+    truncated: boolean;
+    diagnostics: readonly DomImportDiagnostic[];
+    metrics: DomImportMetrics;
+}
+/** Transformation entry point starting from Element in the same document (or iframe document) — win is the window to which el belongs. */
+export declare function importDomFromElement(el: Element, win: Window, opts?: DomImportOptions): DomImportResult | null;
+/** Convert the body of the same-origin iframe to a node tree. null if cross-origin. */
+export declare function importDomFromIframe(iframe: HTMLIFrameElement, opts?: DomImportOptions): DomImportResult | null;