@pygmalionjs/pygmalion 0.5.14 → 0.5.16

package/dist-lib/testing.js

@@ -1,4 +1,4 @@
-import { F as s, N as a, e as r, s as i, a as t } from "./FrozenRoutePreview-BR5CBAD3.js";
+import { F as s, N as a, e as r, s as i, a as t } from "./FrozenRoutePreview-CZOpvN6z.js";
 export {
   s as FrozenRoutePreviewView,
   a as NodeModel,

package/dist-lib/types/App.d.ts

@@ -0,0 +1,5 @@
+export interface AppProps {
+    /** The route identity is stable enough to read or produce preview artifacts. */
+    previewIdentityReady?: boolean;
+}
+export declare const App: import("react").FunctionComponent<AppProps>;

package/dist-lib/types/canvas/CameraLayer.d.ts

@@ -0,0 +1,9 @@
+import { type ReactNode } from 'react';
+import type { FrameLodFrame } from '../editor/frameLod';
+/** Diagnostic passthrough for headless debugging of the LOD frame inputs. */
+export declare function __debugReadEditorFrames(): (FrameLodFrame & {
+    memoKey?: string;
+})[];
+export declare function CameraLayer({ children }: {
+    children?: ReactNode;
+}): import("react").JSX.Element;

package/dist-lib/types/canvas/Canvas.d.ts

@@ -0,0 +1,19 @@
+import { type CSSProperties } from 'react';
+import { type NodeModel } from '../editor/store';
+export declare const JUSTIFY_CSS: {
+    readonly start: "flex-start";
+    readonly center: "center";
+    readonly end: "flex-end";
+    readonly between: "space-between";
+};
+export declare const ALIGN_CSS: {
+    readonly start: "flex-start";
+    readonly center: "center";
+    readonly end: "flex-end";
+};
+export declare function sizeStyle(node: NodeModel): CSSProperties;
+import { layoutContextStyle } from './layoutContext';
+export { layoutContextStyle };
+export declare const CanvasNode: import("react").NamedExoticComponent<{
+    node: NodeModel;
+}>;

package/dist-lib/types/canvas/FrameLabelBanner.d.ts

@@ -0,0 +1,7 @@
+import { type PageModel } from '../editor/store';
+export declare const FrameLabelBanner: import("react").FunctionComponent<{
+    page: PageModel;
+    active: boolean;
+    /** Drag-to-move, passed only in edit mode; view-only reads and never grabs. */
+    onLabelDown?: (event: React.MouseEvent) => void;
+}>;

package/dist-lib/types/canvas/FrameView.d.ts

@@ -0,0 +1,9 @@
+import { type PageModel } from '../editor/store';
+export declare const FrameView: import("react").FunctionComponent<{
+    page: PageModel;
+    active: boolean;
+    selected: boolean;
+    backgroundOnly?: boolean;
+    cacheHydrated: boolean;
+    previewIdentityReady: boolean;
+}>;

package/dist-lib/types/canvas/FrozenRoutePreview.d.ts

@@ -0,0 +1,12 @@
+import { type PageModel } from '../editor/store';
+export declare function FrozenRoutePreviewView({ page, snapshot, height, onDocumentReady, onDocumentHeightChange, onReplayIssuesChange, }: {
+    page: PageModel;
+    snapshot: string;
+    height: number;
+    onDocumentReady?: (iframe: HTMLIFrameElement) => void;
+    onDocumentHeightChange?: (height: number) => void;
+    onReplayIssuesChange?: (issues: string[]) => void;
+}): import("react").JSX.Element;
+export declare const FrozenRoutePreview: typeof FrozenRoutePreviewView & {
+    displayName: string;
+};

package/dist-lib/types/canvas/InspectOverlay.d.ts

@@ -0,0 +1,10 @@
+import { type RefObject } from 'react';
+import { type SourceAffectedFrame } from '../editor/inspect';
+export declare function InspectOverlay({ iframeRef, containerRef, affectedFrames, }: {
+    /** route page — when placed over a same-origin iframe. */
+    iframeRef?: RefObject<HTMLIFrameElement | null>;
+    /** fixture page — when placed over a scroll container in the body (same document). */
+    containerRef?: RefObject<HTMLElement | null>;
+    /** Current selection screen. Even before calculating the impact of all same-source frames, at least the current frame is preserved in the operation. */
+    affectedFrames?: readonly SourceAffectedFrame[];
+}): import("react").JSX.Element;

package/dist-lib/types/canvas/LightweightCanvas.d.ts

@@ -0,0 +1,10 @@
+import type { NodeModel } from '../editor/store';
+/**
+ * Real-time DOM renderer for inactive frames.
+ * Leave only one MobX observer per frame and do not create selection/hover/drag handlers.
+ * Therefore, it is lightweight at the level of static capture, but currently uses NodeModel's text/props/style/structure.
+ * Read all, instantly displaying common changes without clicking or activating.
+ */
+export declare const LightweightCanvas: import("react").FunctionComponent<{
+    root: NodeModel;
+}>;

package/dist-lib/types/canvas/ObjectControls.d.ts

@@ -0,0 +1,22 @@
+export type ResizeEdge = 'n' | 'ne' | 'e' | 'se' | 's' | 'sw' | 'w' | 'nw';
+export type Rect = {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+export declare function resizedRect(base: Rect, edge: ResizeEdge, dx: number, dy: number, minWidth: number, minHeight: number): Rect;
+export declare function ObjectControls({ kind, onResize, onDelete, deleteDisabled, status, readOnly, }: {
+    kind: 'frame' | 'section';
+    onResize: (edge: ResizeEdge, e: React.MouseEvent) => void;
+    onDelete: (e: React.MouseEvent) => void;
+    deleteDisabled?: boolean;
+    status?: string;
+    /**
+     * Draws the outline and the size read-out without the grips. View-only
+     * still wants to show WHICH object is being read; it must not offer a
+     * handle to drag or a button to delete, because an affordance is a
+     * promise and this mode cannot keep it.
+     */
+    readOnly?: boolean;
+}): import("react").JSX.Element;

package/dist-lib/types/canvas/Preview.d.ts

@@ -0,0 +1,3 @@
+export declare const PrototypePreview: import("react").FunctionComponent<{
+    onClose: () => void;
+}>;

package/dist-lib/types/canvas/SectionBoxes.d.ts

@@ -0,0 +1,24 @@
+export declare const SECTION_PAD = 28;
+/**
+ * Section bounds on the active canvas — the union of explicit section
+ * rectangles and member frame bboxes. Empty sections are included so a frame
+ * can still be dropped onto one.
+ *
+ * A frame's box is measured to `resolveFrameHeight`, which is the frame
+ * itself; the rendered element is taller because its label banner sits in
+ * flow above it (63 canvas units on this project, font-metric dependent). Do
+ * not widen these bounds to match: they decide which section a dropped frame
+ * joins, the search takes the first section it intersects, and lanes sit 210
+ * apart while sections sit 120 plus the header reserve — so a taller box
+ * would start overlapping its neighbour and reassign frames to the wrong
+ * section. Understating is the safe direction, and nothing is drawn from
+ * these bounds any more that a designer could see the shortfall in.
+ */
+export declare function sectionBounds(): Map<string, {
+    x0: number;
+    y0: number;
+    x1: number;
+    y1: number;
+    explicit: boolean;
+}>;
+export declare const SectionBoxes: import("react").FunctionComponent<object>;

package/dist-lib/types/canvas/ShadowRoutePreview.d.ts

@@ -0,0 +1,14 @@
+import { type RoutePreviewShadowArtifact } from '../editor/routePreview';
+import { type PageModel } from '../editor/store';
+export declare const ShadowRoutePreview: import("react").FunctionComponent<{
+    page: PageModel;
+    snapshot?: string;
+    artifact?: RoutePreviewShadowArtifact;
+    height: number;
+    baseUrl: string;
+    revision: string;
+    /** True when the backing artifact no longer matches the source screen — blocks bootless promotion. */
+    sourceStale?: boolean;
+    onDocumentHeightChange?: (height: number) => void;
+    onReplayIssuesChange?: (issues: string[]) => void;
+}>;

package/dist-lib/types/canvas/StoryboardConnections.d.ts

@@ -0,0 +1,31 @@
+import type { StoryboardGraphViewModel } from '../editor/storyboardGraphView';
+export interface StoryboardFrameGeometry {
+    frameId: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface StoryboardConnectionPath {
+    id: string;
+    sourceFrameId: string;
+    targetFrameId: string;
+    path: string;
+}
+export type StoryboardConnectionMode = 'story' | 'focus' | 'overview';
+export interface StoryboardConnectionPathOptions {
+    mode?: StoryboardConnectionMode;
+    activeFrameId?: string | null;
+}
+/**
+ * Projects graph transitions into world-space paths. The calculation is kept
+ * independent from camera pan and zoom because the SVG lives inside the same
+ * transformed canvas layer as the frames.
+ */
+export declare function createStoryboardConnectionPaths(model: StoryboardGraphViewModel, frames: readonly StoryboardFrameGeometry[], options?: StoryboardConnectionPathOptions): StoryboardConnectionPath[];
+export declare function StoryboardConnections({ model, frames, mode, activeFrameId, }: {
+    model: StoryboardGraphViewModel;
+    frames: readonly StoryboardFrameGeometry[];
+    mode?: StoryboardConnectionMode;
+    activeFrameId?: string | null;
+}): import("react").JSX.Element | null;

package/dist-lib/types/canvas/cameraPlacement.d.ts

@@ -0,0 +1,45 @@
+export interface CameraView {
+    panX: number;
+    panY: number;
+    zoom: number;
+}
+export interface CameraViewport {
+    width: number;
+    height: number;
+    insetLeft?: number;
+    insetRight?: number;
+    insetTop?: number;
+    insetBottom?: number;
+}
+export interface CameraFrameRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** Fixed initial view of the new canvas. It has nothing to do with frame/iframe/viewport geometry. */
+export declare const DEFAULT_CANVAS_CAMERA_VIEW: Readonly<CameraView>;
+/**
+ * The only automatic view decisions allowed when switching canvases:
+ * If there is a previous user view, it is restored. If not, a fixed default value is used.
+ * Because it does not receive asynchronous geometry or viewport as input, ready cannot move the camera.
+ */
+export declare function resolveCanvasCameraView(saved: CameraView | null | undefined): CameraView;
+/**
+ * Camera placement only used when the user explicitly requests movement in the frame list.
+ * Align and center the frame within the viewport, excluding the area covered by the panel.
+ */
+export declare function resolveFrameFocusCameraView(frame: CameraFrameRect, viewport: CameraViewport, options?: {
+    padding?: number;
+    minZoom?: number;
+    maxZoom?: number;
+}): CameraView;
+/**
+ * Reveals a sidebar-selected frame with the smallest possible pan adjustment.
+ * The user's zoom is never changed, and an already visible frame does not move
+ * the camera. Explicit fit commands continue to use resolveFrameFocusCameraView.
+ */
+export declare function resolveFrameRevealCameraView(frame: CameraFrameRect, viewport: CameraViewport, current: CameraView, options?: {
+    padding?: number;
+    tolerance?: number;
+}): CameraView;

package/dist-lib/types/canvas/domTags.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Tags rendered without children.
+ *
+ * Mostly the HTML void elements plus the SVG leaves. `textarea` is not void,
+ * but its content travels as `defaultValue` rather than as children, so React
+ * treats children as a conflict — for rendering purposes it is a leaf too.
+ */
+export declare const DOM_LEAF_TAGS: Set<string>;
+/** Captured document scaffolding that must not render as itself inside a frame. */
+export declare const DOCUMENT_CONTAINER_TAGS: Set<string>;

package/dist-lib/types/canvas/layoutContext.d.ts

@@ -0,0 +1,9 @@
+import type { CSSProperties } from 'react';
+/**
+ * The slice of a collapsed instance's captured styles that keeps it PLACED
+ * exactly as captured — position, box, and formatting context — while the
+ * registered component supplies its own appearance.
+ */
+export declare function layoutContextStyle(node: {
+    domStyle: Record<string, string>;
+}): CSSProperties;

package/dist-lib/types/canvas/useFlowSession.d.ts

@@ -0,0 +1,36 @@
+/**
+ * True while a flow session still owes this screen its snapshot. Frames use
+ * it exactly like the artifact-hydration gate: activation waits for the
+ * session's delivery instead of booting a live app of its own.
+ */
+export declare function useFlowSessionPending(screenId: string): boolean;
+/**
+ * True while a viewport-variant session (committed size change) still owes
+ * this page its snapshot at the given viewport. While pending, the frame
+ * holds its provisional tree instead of live re-measuring — the delivery
+ * mounts as a frozen preview and promotes over the provisional import.
+ */
+export declare function useViewportSessionPending(page: {
+    importPageId?: string;
+    id: string;
+}, viewport: {
+    width: number;
+    height: number;
+}): boolean;
+/**
+ * True while an interactive-state session (a declared axis the frame is held
+ * in, such as a folded sidebar) still owes this page its snapshot. The frame
+ * waits for it instead of booting the app and replaying the whole recipe
+ * itself — the session does that work in one instance the warm pool keeps.
+ */
+export declare function useInteractiveSessionPending(page: {
+    importPageId?: string;
+    id: string;
+    interactiveStateId?: string;
+    interactiveOptionId?: string;
+}): boolean;
+/**
+ * True while this frame holds one of the host's live screen slots, meaning it
+ * renders the running app rather than its frozen capture.
+ */
+export declare function useLiveScreenSlot(pageId: string): boolean;

package/dist-lib/types/canvas/useFrameLod.d.ts

@@ -0,0 +1,35 @@
+import type { FrameLifecycleTier } from '../editor/frameLod';
+/**
+ * The lifecycle tier of one frame, read from the frame LOD controller's keyed
+ * store. Pinned frames (active, selected, preview-intended, or holding a live
+ * preview grant) always read as full — losing their DOM would kill a running
+ * producer or the surface the user is working on. The server snapshot is full
+ * so SSR markup stays the complete preview surface.
+ */
+export declare function useFrameLod(frameId: string, pinned: boolean): FrameLifecycleTier;
+/**
+ * Whether the camera currently draws this frame beyond its screenshot's pixel
+ * density, from the same keyed store as the tier. False on the server — SSR
+ * markup keeps the screenshot surface, and hydration corrects it on the first
+ * recompute if the saved camera is already magnifying.
+ */
+export declare function useFrameMagnification(frameId: string): boolean;
+/**
+ * The URL a frame screenshot should display right now. Native resolution
+ * while the camera magnifies past one device pixel per CSS pixel (or while
+ * the downscale still generates); the CSS-resolution downscale otherwise, so
+ * an overview does not keep every frame's full bitmap decoded. The server
+ * snapshot always uses the native URL.
+ */
+export declare function useScreenshotDisplayUrl(cacheKey: string, screenshot: {
+    dataUrl: string;
+    width: number;
+    height: number;
+} | null, cssWidth: number, cssHeight: number): string | null;
+/**
+ * Dev-only remount cost probe: marks the render that reattaches a detached
+ * frame and measures once the commit's mount effects (including the shadow
+ * preview mount, which flushes before this parent effect) have run. Off in
+ * production builds unless `globalThis.PYGMALION_PROFILE_FRAME_LOD` is true.
+ */
+export declare function useFrameLodRemountProfile(frameId: string, tier: FrameLifecycleTier): void;

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

@@ -0,0 +1,67 @@
+export interface AdaptiveFrameSize {
+    width: number;
+    height: number;
+}
+export interface AdaptiveFramePosition extends AdaptiveFrameSize {
+    x: number;
+    y: number;
+}
+export interface AdaptiveFrameLayout {
+    frames: AdaptiveFramePosition[];
+    width: number;
+    height: number;
+    rowWidth: number;
+}
+export interface AdaptiveFrameLayoutOptions {
+    gap?: number;
+    targetAspectRatio?: number;
+    maxRowWidth?: number;
+}
+export interface LaneInput {
+    laneId: string;
+    frames: readonly AdaptiveFrameSize[];
+}
+export interface LaneBand {
+    laneId: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface LanedFrameLayout {
+    /** Positions in the input order, lanes concatenated. */
+    frames: AdaptiveFramePosition[];
+    bands: LaneBand[];
+    width: number;
+    height: number;
+}
+export interface LaneLayoutOptions {
+    /** Between frames inside one lane — "the next thing in this situation". */
+    gap?: number;
+    /** Between lanes — "a different situation". Wider than gap on purpose. */
+    laneGap?: number;
+    /** Frames per lane row before the lane wraps into a continuation row. */
+    maxFramesPerRow?: number;
+}
+/**
+ * Lays lanes out as rows: one lane is one horizontal run, read left to right,
+ * and lanes stack downward separated by a wider gap.
+ *
+ * Rows are left-aligned rather than column-aligned across lanes. Forcing a
+ * grid would imply a correspondence between, say, the third screen of the
+ * recording run and the third error path, and would punch holes wherever a
+ * lane is shorter — the gap is what carries the grouping, so it does the work
+ * instead.
+ *
+ * A lane longer than `maxFramesPerRow` wraps into continuation rows at the
+ * intra-lane gap, which keeps a whole lane inside one viewport at overview
+ * zoom while still reading as one block.
+ */
+export declare function layoutLaneRows(lanes: readonly LaneInput[], options?: LaneLayoutOptions): LanedFrameLayout;
+/**
+ * Packs ordered frames into a compact storyboard block. The target row width is
+ * derived from total rendered area, so larger stories gain columns gradually
+ * without relying on a fixed column count. Hosts may still provide an explicit
+ * maximum when their canvas has a known horizontal constraint.
+ */
+export declare function layoutAdaptiveFrames(frames: readonly AdaptiveFrameSize[], options?: AdaptiveFrameLayoutOptions): AdaptiveFrameLayout;

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

@@ -0,0 +1,10 @@
+import type { DesignImportAsset, DesignImportKind } from './designImport';
+import type { NodeModel, PageModel } from './store';
+export interface DesignAssetEditRequest {
+    kind: DesignImportKind;
+    asset: DesignImportAsset;
+    pageId: string;
+}
+/** Resolve the implementation layer represented by one inventory asset. */
+export declare function findDesignAssetEditTarget(root: NodeModel, asset: DesignImportAsset): NodeModel | null;
+export declare function pageForDesignAsset(pages: readonly PageModel[], kind: DesignImportKind, asset: DesignImportAsset): PageModel | null;

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

@@ -0,0 +1,18 @@
+/** Palette of the reviewed banner, shared by every density. */
+export declare const BANNER_PALETTE: {
+    readonly surface: "#343441";
+    readonly pillSurface: "#2e2c3a";
+    readonly caption: "#a1a1b3";
+    readonly code: "#ffffff";
+    readonly title: "#e7e7f0";
+    readonly titleMuted: "#a1a1b3";
+    readonly meta: "#bebecb";
+    readonly purpose: "#c4ccd8";
+};
+export declare const HEX_COLOR: RegExp;
+/**
+ * The design pairs a saturated rule with a lighter tint of the same hue for
+ * the pill text (#06b6d4 / #6edcee). Mixing toward white reproduces that
+ * pairing from the one colour a host declares.
+ */
+export declare function lightenHex(hex: string, amount: number): string;

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

@@ -0,0 +1,101 @@
+import { type CSSProperties, type ReactNode } from 'react';
+import type { DesignImportCollection } from './designImport';
+import type { ComponentRegistry, RegistryEntry, RegistryPropValue } from './registry';
+export type DesignCatalogKind = 'icons' | 'design-tokens' | 'atoms' | 'components';
+export interface DesignCatalogItem {
+    id: string;
+    name: string;
+    section: string;
+    sourcePath?: string;
+    codeName?: string;
+    description?: string;
+}
+export interface DesignCatalogPageDescriptor {
+    id: string;
+    name: string;
+    section: string;
+}
+export interface DesignCatalogFrame {
+    width: number;
+    height: number;
+}
+export interface DesignCatalogBuild {
+    registry: ComponentRegistry;
+    collection: DesignImportCollection;
+}
+export interface DesignGalleryCatalogOptions<T extends DesignCatalogItem> {
+    kind: 'icons' | 'design-tokens';
+    items: readonly T[];
+    expectedCount?: number;
+    pageFor: (item: T) => DesignCatalogPageDescriptor;
+    renderPreview: (item: T) => ReactNode;
+    secondaryLabel?: (item: T) => ReactNode;
+    frame?: DesignCatalogFrame | ((page: DesignCatalogPageDescriptor, items: readonly T[]) => DesignCatalogFrame);
+    minimumColumnWidth?: number;
+    registryPrefix?: string;
+}
+export interface DesignComponentCatalogOptions {
+    kind: 'atoms' | 'components';
+    items: readonly DesignCatalogItem[];
+    registry: ComponentRegistry;
+    expectedCount?: number;
+    maxVariantCells?: number;
+    registryPrefix?: string;
+}
+export interface DesignComponentVariantMatrix {
+    row?: readonly [name: string, values: readonly RegistryPropValue[]];
+    column?: readonly [name: string, values: readonly RegistryPropValue[]];
+    fixed: readonly (readonly [name: string, value: RegistryPropValue])[];
+    additional: readonly (readonly [name: string, values: readonly RegistryPropValue[]])[];
+}
+export interface PygmalionCatalogDocumentProps {
+    title: ReactNode;
+    eyebrow?: ReactNode;
+    description?: ReactNode;
+    version?: ReactNode;
+    meta?: ReactNode;
+    children: ReactNode;
+    headerBackground?: string;
+    headerColor?: string;
+    bodyBackground?: string;
+    bodyGap?: number;
+}
+export interface PygmalionCatalogSectionProps {
+    title: ReactNode;
+    itemId?: string;
+    count?: number;
+    description?: ReactNode;
+    children: ReactNode;
+    tone?: 'plain' | 'tinted';
+}
+export interface PygmalionCatalogMatrixProps {
+    rows: readonly RegistryPropValue[];
+    columns: readonly RegistryPropValue[];
+    cornerLabel?: ReactNode;
+    renderCell: (row: RegistryPropValue, column: RegistryPropValue) => ReactNode;
+    renderRowLabel?: (row: RegistryPropValue) => ReactNode;
+    renderColumnLabel?: (column: RegistryPropValue) => ReactNode;
+    boundary?: boolean;
+    cellStyle?: CSSProperties;
+}
+/**
+ * Intrinsically sized catalog document inspired by a design-system source
+ * page. The root is the single content-bounds authority, so hosts never need
+ * to predict a frame width or height from item counts.
+ */
+export declare function PygmalionCatalogDocument({ title, eyebrow, description, version, meta, children, headerBackground, headerColor, bodyBackground, bodyGap, }: PygmalionCatalogDocumentProps): import("react").JSX.Element;
+/**
+ * Neutral grouping surface for token families, component sets, and icon
+ * categories. Its width follows the rendered children instead of a card grid.
+ */
+export declare function PygmalionCatalogSection({ title, itemId, count, description, children, tone, }: PygmalionCatalogSectionProps): import("react").JSX.Element;
+/**
+ * Variant matrix with explicit row and column axes. Cells remain open
+ * design-document content rather than forced equal-size cards.
+ */
+export declare function PygmalionCatalogMatrix({ rows, columns, cornerLabel, renderCell, renderRowLabel, renderColumnLabel, boundary, cellStyle, }: PygmalionCatalogMatrixProps): import("react").JSX.Element;
+export declare function designCatalogKey(value: string): string;
+export declare function designCatalogRegistryName(kind: DesignCatalogKind, id: string, prefix?: string): string;
+export declare function createDesignGalleryCatalog<T extends DesignCatalogItem>(options: DesignGalleryCatalogOptions<T>): DesignCatalogBuild;
+export declare function createDesignComponentVariantMatrix(entry: RegistryEntry | undefined, maxCells?: number): DesignComponentVariantMatrix;
+export declare function createDesignComponentCatalog(options: DesignComponentCatalogOptions): DesignCatalogBuild;

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

@@ -0,0 +1,11 @@
+import type { NodeJSON, NodeModel } from './store';
+export type CodegenNode = NodeModel | NodeJSON;
+export interface CodegenFrameOptions {
+    fill?: string;
+    opacity?: number;
+    radius?: number;
+    clipContent?: boolean;
+}
+export declare function codegen(node: CodegenNode, indent?: number): string;
+/** Generates the built-in target and keeps the historical string API stable. */
+export declare function codegenDocument(root: CodegenNode, frame?: CodegenFrameOptions): string;

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

@@ -0,0 +1,63 @@
+export type DesignConnectionPropertyKind = 'text' | 'boolean' | 'variant' | 'instance' | 'slot';
+export interface DesignComponentReference {
+    /** External design system name. Use "figma" for a Figma library. */
+    provider: string;
+    documentId?: string;
+    nodeId: string;
+    url?: string;
+    name?: string;
+}
+export interface DesignConnectionPropertyDef {
+    designName: string;
+    kind: DesignConnectionPropertyKind;
+    /** Complete vocabulary for a variant property. */
+    values?: readonly string[];
+    defaultValue?: string | boolean;
+    /** Existing code prop. Use "children" for a text or slot child. */
+    codeProperty?: string;
+    /** Exhaustive design-value to code-value mapping. Identity is the default. */
+    valueMap?: Readonly<Record<string, string | boolean>>;
+    /** Makes an intentionally unmapped design property visible to validation. */
+    omitReason?: string;
+}
+export interface DesignComponentConnectionDef {
+    id: string;
+    componentName: string;
+    design: DesignComponentReference;
+    code?: {
+        sourcePath?: string;
+        importPath?: string;
+    };
+    properties?: readonly DesignConnectionPropertyDef[];
+}
+export interface DesignConnectionDiagnostic {
+    severity: 'warning' | 'error';
+    code: string;
+    message: string;
+    connectionId: string;
+    property?: string;
+}
+export interface DesignComponentConnectionCase {
+    id: string;
+    label: string;
+    designValues: Readonly<Record<string, string | boolean>>;
+    codeProps: Readonly<Record<string, string | boolean>>;
+}
+export interface DesignComponentConnectionCases {
+    connectionId: string;
+    cases: readonly DesignComponentConnectionCase[];
+    total: number;
+    truncated: {
+        total: number;
+        limit: number;
+    } | null;
+    diagnostics: readonly DesignConnectionDiagnostic[];
+}
+export declare function setDesignComponentConnections(next: readonly DesignComponentConnectionDef[]): void;
+export declare function getDesignComponentConnections(): readonly DesignComponentConnectionDef[];
+export declare function getDesignComponentConnection(connectionId: string): DesignComponentConnectionDef | undefined;
+export declare function getDesignComponentConnectionForComponent(componentName: string): DesignComponentConnectionDef | undefined;
+export declare function validateDesignComponentConnections(): readonly DesignConnectionDiagnostic[];
+export declare function enumerateDesignComponentConnectionCases(connectionId: string, options?: {
+    limit?: number;
+}): DesignComponentConnectionCases;

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

@@ -0,0 +1,27 @@
+import type { ComponentRegistry, RegistryEntry, RegistryPropValue } from './registry';
+import type { NodeModel, PageModel } from './store';
+/** One controllable component instance found in a page tree. */
+export interface ComponentInstanceSummary {
+    nodeId: string;
+    componentName: string;
+    /** Display label: childrenText, then a distinguishing prop value, then the ordinal. */
+    label: string;
+    /** 1-based position among the same component's instances in the page. */
+    ordinal: number;
+    /** Effective typed prop values — instance props over registry defaults. */
+    props: Record<string, RegistryPropValue>;
+    /** Registry props that are literal-authored on the instance and writable to source. */
+    sourceWritableProps: readonly string[];
+}
+/** All instances of one component in a page, in document order. */
+export interface ComponentInstanceGroup {
+    componentName: string;
+    instances: ComponentInstanceSummary[];
+}
+/** Registry props whose authored JSX literal can safely take a vocabulary value. */
+export declare function sourceWritableRegistryProps(node: Pick<NodeModel, 'sourceProps'>, entry: Pick<RegistryEntry, 'props'> | undefined): string[];
+/**
+ * Enumerates the controllable component instances of a page, grouped by
+ * component in document order.
+ */
+export declare function listComponentInstances(page: Pick<PageModel, 'root'>, registry: ComponentRegistry): ComponentInstanceGroup[];