@tangle-network/agent-app 0.12.0 → 0.13.0

package/dist/design-canvas-react/index.d.ts

@@ -0,0 +1,916 @@
+import { c as SceneDocument, d as SceneElement, B as Bounds, N as NewPageOptions, a as PageGuides, P as PageBleed, g as ScenePage } from '../model-BHLN208Z.js';
+import { n as SceneOperation, m as SceneAttrsPatch, h as ExportCropRect, j as ExportPreset } from '../export-presets-Dl5Aa5xj.js';
+export { v as bleedAwareExportBounds, F as scaleForPreset } from '../export-presets-Dl5Aa5xj.js';
+import * as react from 'react';
+import Konva from 'konva';
+
+/**
+ * Seams between the design-canvas editor's engine and components, mirroring
+ * the sequences-react pattern: interface-only so layers build independently.
+ *
+ * Persistence: the command stack executes optimistically against local state
+ * and emits `SceneOperation[]` through `DesignCanvasProps.onApplyOperations`.
+ * The host's apply returns the new revision (and the server document when it
+ * re-minted ids); a rejected promise rolls the command back. Drag gestures
+ * coalesce: pointer moves mutate volatile state, ONE command (final attrs,
+ * inverse = pre-gesture attrs) executes on release — undo is per-gesture,
+ * never per-pixel.
+ */
+
+interface EditorSceneState {
+    document: SceneDocument;
+    activePageId: string;
+    selectedElementIds: string[];
+    /** Pixels per document px. */
+    zoom: number;
+    panX: number;
+    panY: number;
+    gridEnabled: boolean;
+    /** Document px between grid lines. */
+    gridSize: number;
+    snapEnabled: boolean;
+    showRulers: boolean;
+    showBleed: boolean;
+}
+interface SceneCommand {
+    label: string;
+    execute(state: EditorSceneState): EditorSceneState;
+    undo(state: EditorSceneState): EditorSceneState;
+    operations(): SceneOperation[];
+    /**
+     * The inverse operation sequence for server-side persistence of an undo.
+     * Most commands return an exact inverse (e.g. set_attrs → prior set_attrs,
+     * add_element → delete_element). deletePageCommand returns add_page +
+     * per-element add_element ops restoring the full page snapshot.
+     */
+    inverseOperations(): SceneOperation[];
+}
+interface SceneCommandStack {
+    execute(command: SceneCommand): void;
+    /** Apply the top-of-done-stack inverse and return the command (callers use
+     *  `command.inverseOperations()` to persist the undo to the server). */
+    undo(): SceneCommand;
+    /** Re-execute the top-of-redo-stack and return the command (callers use
+     *  `command.operations()` to persist the redo to the server). */
+    redo(): SceneCommand;
+    canUndo(): boolean;
+    canRedo(): boolean;
+    subscribe(listener: () => void): () => void;
+    getState(): EditorSceneState;
+    /** Update volatile view state (zoom/pan/selection/toggles) without touching
+     *  history — view changes are never undo steps. */
+    setView(patch: Partial<Omit<EditorSceneState, 'document'>>): void;
+    /** Rebase onto a server refresh WITHOUT clearing history (history holds
+     *  operations, not snapshots). */
+    reset(document: SceneDocument): void;
+    /**
+     * Remove a specific command from the undo stack and apply its inverse to
+     * the current state. Called by the persistence layer when a save rejects
+     * AFTER the user may have made further edits.
+     *
+     * Invariant: for commands that operate on disjoint attributes, rollback is
+     * identity for all commands executed after the rolled-back one — their net
+     * effect is preserved. For overlapping attr edits (same element, same field)
+     * the result is defined but not guaranteed to be semantically correct; the
+     * caller should trigger an onResyncRequired fetch in that case.
+     *
+     * If `command` is not found in the undo stack (stale or double-fire
+     * rejection handler), this is a safe no-op.
+     */
+    rollback(command: SceneCommand): void;
+}
+type SnapTargetKind = 'grid' | 'element-edge' | 'element-center' | 'page-edge' | 'page-center' | 'guide';
+interface SnapTarget {
+    /** Page-coordinate position of the snap line. */
+    position: number;
+    kind: SnapTargetKind;
+}
+interface SnapTargets {
+    vertical: SnapTarget[];
+    horizontal: SnapTarget[];
+}
+interface SnapResult {
+    x: number;
+    y: number;
+    /** Lines to render while the gesture holds the snap. */
+    activeVertical: SnapTarget | null;
+    activeHorizontal: SnapTarget | null;
+}
+interface SnapEngine {
+    /** Collect targets for a gesture: other elements' edges/centers, page
+     *  edges/center, saved guides, and grid lines when enabled. `excludeIds`
+     *  removes the dragged elements' own geometry. */
+    collectTargets(state: EditorSceneState, excludeIds: string[]): SnapTargets;
+    /** Snap a moving AABB. Threshold is SCREEN pixels, divided by zoom. */
+    apply(bounds: Bounds, targets: SnapTargets, thresholdPx: number, zoom: number): SnapResult;
+}
+interface ZoomPanMath {
+    minZoom: number;
+    maxZoom: number;
+    /** Zoom about a screen point so the document point under the cursor stays
+     *  fixed (wheel-zoom-to-cursor). Returns the clamped new view. */
+    zoomAtPoint(state: {
+        zoom: number;
+        panX: number;
+        panY: number;
+    }, factor: number, screenX: number, screenY: number): {
+        zoom: number;
+        panX: number;
+        panY: number;
+    };
+    /** Fit the active page into a viewport with padding. */
+    fitPage(page: {
+        width: number;
+        height: number;
+    }, viewport: {
+        width: number;
+        height: number;
+    }, paddingPx?: number): {
+        zoom: number;
+        panX: number;
+        panY: number;
+    };
+    documentToScreen(state: {
+        zoom: number;
+        panX: number;
+        panY: number;
+    }, x: number, y: number): {
+        x: number;
+        y: number;
+    };
+    screenToDocument(state: {
+        zoom: number;
+        panX: number;
+        panY: number;
+    }, x: number, y: number): {
+        x: number;
+        y: number;
+    };
+}
+interface ApplySceneResult {
+    rev: number;
+    /** Present when the server re-minted ids or normalized the document; the
+     *  editor rebases onto it. */
+    document?: SceneDocument;
+}
+interface DesignCanvasProps {
+    document: SceneDocument;
+    /** Revision the document was loaded at; threaded through saves. */
+    rev: number;
+    canWrite: boolean;
+    /** Persist operations. Resolve with the new revision; reject to roll back.
+     *  A stale-revision failure should resolve AFTER refetch with the fresh
+     *  document so the editor rebases instead of fighting. */
+    onApplyOperations(operations: SceneOperation[]): Promise<ApplySceneResult>;
+    onSelectionChange?(elements: SceneElement[]): void;
+    /** Host panels: agent chat (right), asset/template browser (left). */
+    renderAgentPanel?(ctx: {
+        selectedElements: SceneElement[];
+        activePageId: string;
+    }): React.ReactNode;
+    renderSidePanel?(): React.ReactNode;
+    /** Export hook — host persists the rendered blob (upload → asset row). */
+    onExport?(result: {
+        pageId: string;
+        format: 'png' | 'jpeg';
+        dataUrl: string;
+        pixelRatio: number;
+    }): Promise<void>;
+    className?: string;
+}
+
+/**
+ * Undo/redo command stack over immutable `EditorSceneState`.
+ *
+ * History entries hold COMMANDS (state transforms + durable operations
+ * captured at construction), never snapshots. Rebasing the document via
+ * `reset()` therefore cannot stale the history: a later undo re-applies the
+ * inverse transform to whatever document is current. If the rebase removed an
+ * element a historical command targets, that transform throws (fail loud)
+ * rather than silently editing the wrong element.
+ *
+ * `setView` updates volatile view state (zoom/pan/selection/toggles) without
+ * touching history — view changes are never undo steps.
+ */
+
+/** Oldest entries are dropped past this bound; redo stack is cleared on execute. */
+declare const SCENE_COMMAND_HISTORY_LIMIT = 200;
+declare function createSceneCommandStack(document: SceneDocument, activePageId: string): SceneCommandStack;
+
+interface AddElementInput {
+    pageId: string;
+    element: SceneElement;
+    /** Insertion z-index within owner; omitted → top. */
+    index?: number;
+    /** Parent group id; omitted → page root. */
+    parentGroupId?: string;
+}
+declare function addElementCommand(input: AddElementInput): SceneCommand;
+interface SetAttrsInput {
+    pageId: string;
+    elementId: string;
+    /** Final attribute values after the gesture. */
+    attrs: SceneAttrsPatch;
+    /** Attribute values BEFORE the gesture began — inverse is built from these. */
+    priorAttrs: SceneAttrsPatch;
+}
+declare function setAttrsCommand(input: SetAttrsInput): SceneCommand;
+interface MultiSetAttrsEntry {
+    pageId: string;
+    elementId: string;
+    attrs: SceneAttrsPatch;
+    priorAttrs: SceneAttrsPatch;
+}
+declare function multiSetAttrsCommand(entries: MultiSetAttrsEntry[]): SceneCommand;
+interface ReorderElementInput {
+    pageId: string;
+    elementId: string;
+    toIndex: number;
+}
+declare function reorderElementCommand(input: ReorderElementInput): SceneCommand;
+interface DeleteElementInput {
+    document: SceneDocument;
+    pageId: string;
+    elementId: string;
+}
+declare function deleteElementCommand(input: DeleteElementInput): SceneCommand;
+interface GroupElementsInput {
+    document: SceneDocument;
+    pageId: string;
+    elementIds: string[];
+    groupId: string;
+    name?: string;
+}
+declare function groupElementsCommand(input: GroupElementsInput): SceneCommand;
+interface UngroupElementInput {
+    document: SceneDocument;
+    pageId: string;
+    groupId: string;
+}
+declare function ungroupElementCommand(input: UngroupElementInput): SceneCommand;
+interface AddPageInput {
+    pageId: string;
+    options?: NewPageOptions;
+    index?: number;
+}
+declare function addPageCommand(input: AddPageInput): SceneCommand;
+interface DuplicatePageInput {
+    document: SceneDocument;
+    sourcePageId: string;
+    /** Caller-minted id for the copy. */
+    pageId: string;
+}
+declare function duplicatePageCommand(input: DuplicatePageInput): SceneCommand;
+interface DeletePageInput {
+    document: SceneDocument;
+    pageId: string;
+}
+declare function deletePageCommand(input: DeletePageInput): SceneCommand;
+interface ReorderPageInput {
+    pageId: string;
+    toIndex: number;
+}
+declare function reorderPageCommand(input: ReorderPageInput): SceneCommand;
+interface SetPagePropsInput {
+    document: SceneDocument;
+    pageId: string;
+    props: {
+        name?: string;
+        width?: number;
+        height?: number;
+        background?: string;
+        bleed?: PageBleed | null;
+    };
+}
+declare function setPagePropsCommand(input: SetPagePropsInput): SceneCommand;
+interface SetPageGuidesInput {
+    document: SceneDocument;
+    pageId: string;
+    guides: PageGuides;
+}
+declare function setPageGuidesCommand(input: SetPageGuidesInput): SceneCommand;
+interface BindSlotInput {
+    document: SceneDocument;
+    pageId: string;
+    elementId: string;
+    slot: string | null;
+}
+declare function bindSlotCommand(input: BindSlotInput): SceneCommand;
+interface SetDocumentTitleInput {
+    document: SceneDocument;
+    title: string;
+}
+declare function setDocumentTitleCommand(input: SetDocumentTitleInput): SceneCommand;
+
+/**
+ * 2-axis snap engine for the design-canvas editor. Targets come from element
+ * AABBs (edges + centers), page edges + center, saved guides, and grid lines
+ * near the moving bounds. Grid lines are generated lazily in the neighborhood
+ * of the moving element, not the full page — avoids allocating thousands of
+ * targets on large pages with fine grids.
+ *
+ * Threshold is a SCREEN distance (pixels), divided by zoom to convert to
+ * document units — what "feels close" is a screen distance.
+ *
+ * Tie-breaking: non-grid kinds beat grid on equal distance; among equals of
+ * the same priority the first in iteration order wins.
+ */
+
+declare function createSnapEngine(): SnapEngine;
+/** Generate grid line targets within a neighborhood around the moving bounds.
+ *  Call this and append to `SnapTargets.vertical`/`horizontal` before
+ *  passing to `apply()` when `state.gridEnabled`. */
+declare function collectGridTargets(bounds: Bounds, gridSize: number, page: ScenePage, thresholdDocPx: number): {
+    vertical: SnapTarget[];
+    horizontal: SnapTarget[];
+};
+
+/**
+ * Selection math for the design-canvas editor: marquee hit-tests, keyboard
+ * nudge deltas, and the duplicate offset constant. Pure functions — no DOM, no
+ * Konva, no React.
+ *
+ * Marquee inclusion: by default any element whose AABB intersects the marquee
+ * rect is included (the "touch" model). Pass `requireFullContainment: true` for
+ * the "surround" model where the marquee must fully contain the element. Locked
+ * and invisible elements are never selected regardless.
+ */
+
+interface MarqueeSelectOptions {
+    /** When true, the element's AABB must be fully inside the marquee; default is
+     *  intersection (any overlap selects). */
+    requireFullContainment?: boolean;
+}
+/** Returns the ids of selectable elements on `page` whose AABB intersects (or
+ *  is contained by) `rect`. Locked and invisible elements are excluded. */
+declare function marqueeSelect(page: ScenePage, rect: Bounds, opts?: MarqueeSelectOptions): string[];
+interface NudgeDelta {
+    dx: number;
+    dy: number;
+}
+/** Map an arrow key to a document-px delta. `shift` engages the 10× step.
+ *  Throws on unknown keys so callers handle only real nudge keys. */
+declare function nudgeDelta(key: 'ArrowLeft' | 'ArrowRight' | 'ArrowUp' | 'ArrowDown', shift: boolean): NudgeDelta;
+/** Document-px offset applied to duplicated elements so the copy is visually
+ *  separated from the original (matching common design-tool convention). */
+declare const DUPLICATE_OFFSET: NudgeDelta;
+
+/**
+ * Zoom + pan coordinate math for the design-canvas editor. Zoom is pixels-per-
+ * document-px (e.g. 2 = 200% magnification). The key invariant for wheel-zoom
+ * is that the document point under the cursor stays fixed in screen space:
+ *
+ *   docPoint = (screenPoint - pan) / zoom
+ *   newPan   = screenPoint - docPoint * newZoom
+ *
+ * This module is pure math — no DOM, no Konva, no React.
+ */
+
+interface ZoomPanConfig {
+    minZoom: number;
+    maxZoom: number;
+}
+declare function createZoomPanMath(config: ZoomPanConfig): ZoomPanMath;
+
+/**
+ * Pure export math for the design-canvas surface — no Konva, no DOM, no React.
+ *
+ * All stage-interaction code (save/restore, node visibility, toDataURL) lives
+ * in export.ts and delegates the decision math here so it can be tested
+ * without a canvas environment.
+ */
+
+/** Returns true for any Konva node that must be hidden during export. Nodes
+ *  whose names start with 'overlay:' are editor-only chrome (snap lines,
+ *  selection indicators, rulers, bleed guides). The transformer node is
+ *  identified by its canonical name 'Transformer'. */
+declare function isExportHiddenNodeName(name: string): boolean;
+interface ResolvedExportParams {
+    cropRect: ExportCropRect;
+    pixelRatio: number;
+    mimeType: 'image/png' | 'image/jpeg';
+    quality: number | undefined;
+}
+/**
+ * Resolve the full set of toDataURL params from a page, format, pixel ratio,
+ * bleed flag, and optional preset. When a preset is supplied it overrides
+ * `pixelRatio` and `includeBleed` — the explicit args are ignored for those
+ * two values so the preset is the single source of truth.
+ *
+ * `quality` is set to 0.92 for jpeg, undefined for png (Konva ignores it).
+ */
+declare function resolveExportParams(page: ScenePage, opts: {
+    format: 'png' | 'jpeg';
+    pixelRatio?: number;
+    includeBleed?: boolean;
+    preset?: ExportPreset;
+}): ResolvedExportParams;
+/**
+ * Walk image nodes to find the src of any that may have caused a SecurityError
+ * when the stage called toDataURL. Returns the first offending src found, or
+ * null if none can be identified.
+ *
+ * `imageSrcs` is a flat list of { name, src } records collected from all image
+ * nodes on the stage before calling toDataURL — export.ts builds it before
+ * attempting the export so that if the SecurityError fires we have the data.
+ */
+declare function identifyTaintedSrc(imageSrcs: ReadonlyArray<{
+    name: string;
+    src: string;
+}>): string | null;
+/**
+ * Heuristic: a src is potentially cross-origin when it is an absolute http(s)
+ * URL. Same-origin relative paths (/api/...) and data: blobs are safe.
+ * This is intentionally conservative — the taint check runs only after a
+ * SecurityError fires, so a false positive is "blamed" without being silently
+ * ignored. NOTE: same-origin https:// assets will also match; if a
+ * SecurityError fires, the cross-origin culprit may be a different image than
+ * the one this function flags first.
+ */
+declare function isCrossOriginSrc(src: string): boolean;
+/** Minimal snapshot of stage view state that export.ts saves before mutating
+ *  zoom/pan/visibility and restores afterward. */
+interface ExportViewSnapshot {
+    /** Stage scale factor before export. */
+    scaleX: number;
+    scaleY: number;
+    /** Stage translation before export. */
+    x: number;
+    y: number;
+    /** node name → prior visibility, for the nodes that were hidden. */
+    hiddenNodeNames: string[];
+}
+/**
+ * Build the toDataURL crop rect translated to stage output coordinates.
+ * Konva's `stage.toDataURL({ x, y, width, height })` takes STAGE OUTPUT
+ * coordinates, not document coordinates. When the stage has been scaled to fit
+ * (zoom × stageScale), the crop rect in document px must be multiplied by the
+ * combined scale to land on the right pixels.
+ *
+ * `stageScale` is the stage's current uniform scale (scaleX == scaleY);
+ * `pixelRatio` is separate and handed directly to toDataURL — Konva multiplies
+ * it internally when rendering to the backing canvas, so we must NOT include
+ * it in the stage-coordinate rect.
+ */
+declare function documentCropToStageCoords(cropRect: ExportCropRect, stageScale: number, stageX: number, stageY: number): {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+
+/**
+ * Client-side export for design-canvas pages: raster (PNG/JPEG via Konva
+ * stage.toDataURL) and JSON (document serialisation).
+ *
+ * The heavy lifting — crop math, pixel ratio resolution, CORS taint detection
+ * — lives in export-math.ts where it can be unit-tested without a canvas
+ * context. This file is the thin Konva-wiring layer: hide overlays, call
+ * toDataURL, restore, handle the SecurityError.
+ *
+ * Konva is an OPTIONAL peer. Import this file only from browser-context code
+ * that has konva wired in. The types are written against a minimal structural
+ * interface so the file compiles even when konva's types are absent.
+ */
+
+interface KonvaNodeLike {
+    name(): string;
+    visible(): boolean;
+    visible(v: boolean): void;
+    getAttr(key: string): unknown;
+}
+interface KonvaLayerLike {
+    getChildren(): KonvaNodeLike[];
+}
+interface KonvaStageLike {
+    scaleX(): number;
+    scaleY(): number;
+    x(): number;
+    y(): number;
+    getLayers(): KonvaLayerLike[];
+    toDataURL(params: {
+        mimeType: string;
+        quality?: number;
+        pixelRatio: number;
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    }): string;
+}
+interface ExportPageDataUrlOptions {
+    format: 'png' | 'jpeg';
+    pixelRatio?: number;
+    includeBleed?: boolean;
+    preset?: ExportPreset;
+}
+/**
+ * Render a single page to a data URL.
+ *
+ * The function temporarily hides every node whose name starts with 'overlay:'
+ * plus any Transformer node, computes the crop rect and pixel ratio from the
+ * page model and options, calls stage.toDataURL, then restores all prior view
+ * state exactly — zoom, pan, and node visibility.
+ *
+ * Rejects with a descriptive error when a CORS-tainted image source causes
+ * the SecurityError, naming the offending src so the caller can surface it.
+ *
+ * The `stage` argument must be the Konva stage with the page content already
+ * rendered. The caller is responsible for ensuring all async image loads have
+ * settled before calling this function.
+ */
+declare function exportPageDataUrl(stage: KonvaStageLike, page: ScenePage, opts: ExportPageDataUrlOptions): Promise<string>;
+/**
+ * Serialize a scene document to pretty-printed JSON with schemaVersion
+ * asserted. Throws when the document's schemaVersion does not match
+ * SCENE_SCHEMA_VERSION — the caller must not smuggle stale documents through.
+ */
+declare function exportDocumentJson(document: SceneDocument): string;
+/**
+ * Trigger a browser download for a data URL. Safe to import in SSR — the
+ * function is a no-op when `document` is not defined (e.g. server-side render
+ * or test environment without a DOM). The integrator must not rely on the
+ * download executing in those contexts.
+ */
+declare function downloadDataUrl(dataUrl: string, filename: string): void;
+
+/** Callers inject a workspace renderer so this chrome stays Konva-free. The
+ *  workspace occupies the scrollable area between the rulers and the bottom bar. */
+interface DesignCanvasFullProps extends DesignCanvasProps {
+    /**
+     * Render the Konva canvas workspace into the slot this shell provides.
+     * The shell passes viewport dimensions, view-state, and the shared command
+     * stack so `WorkspaceView` can commit gestures through the same stack the
+     * chrome uses for undo/redo and layers-panel selection.
+     *
+     * `onFitRef` is a ref the workspace fills with a fit-page callback; the
+     * shell calls it when the user presses F or clicks the Fit button.
+     */
+    renderWorkspace(ctx: {
+        document: SceneDocument;
+        activePageId: string;
+        selectedElementIds: string[];
+        zoom: number;
+        panX: number;
+        panY: number;
+        gridEnabled: boolean;
+        gridSize: number;
+        snapEnabled: boolean;
+        showBleed: boolean;
+        canWrite: boolean;
+        /** The chrome's command stack. Pass to WorkspaceView so gestures, undo,
+         *  and layers-panel selection share a single state machine. */
+        stack: ReturnType<typeof createSceneCommandStack>;
+        activePage: SceneDocument['pages'][number] | undefined;
+        onFitRef: React.MutableRefObject<(() => void) | null>;
+        onZoomChange(zoom: number): void;
+        onPanChange(panX: number, panY: number): void;
+        onSelectElements(ids: string[], additive: boolean): void;
+    }): React.ReactNode;
+    /**
+     * Generates page thumbnails for the PagesStrip. Injected by the integrator
+     * (who has Konva access) so the chrome doesn't import Konva directly.
+     */
+    renderThumbnail(page: SceneDocument['pages'][number]): Promise<string | null>;
+}
+declare function DesignCanvas({ document: initialDocument, rev: initialRev, canWrite, onApplyOperations, onSelectionChange, renderAgentPanel, renderSidePanel, onExport, className, renderWorkspace, renderThumbnail, }: DesignCanvasFullProps): react.JSX.Element;
+
+/**
+ * Mount this component to get the full editor: toolbar, rulers, layers panel,
+ * pages strip, zoom controls, and the Konva canvas — all sharing one command
+ * stack so undo/redo and selection are coherent across every surface.
+ */
+declare function DesignCanvasEditor(props: DesignCanvasProps): react.JSX.Element;
+
+interface WorkspaceViewProps {
+    /** The command stack this view commits gestures through. Must be the same
+     *  instance the chrome (DesignCanvasEditor) owns so undo/redo and layers-
+     *  panel selection are coherent. */
+    stack: ReturnType<typeof createSceneCommandStack>;
+    /** Active page resolved before render — WorkspaceView has no conditional
+     *  hook guards; the caller ensures this is never null. */
+    activePage: ScenePage;
+    canWrite: boolean;
+    onApplyOperations: DesignCanvasProps['onApplyOperations'];
+    onSelectionChange?: DesignCanvasProps['onSelectionChange'];
+    renderAgentPanel?: DesignCanvasProps['renderAgentPanel'];
+    renderSidePanel?: DesignCanvasProps['renderSidePanel'];
+    className?: string;
+    /** Ref the chrome fills with a fit-page callback. The chrome calls it on F /
+     *  Fit button; when injected via DesignCanvasEditor the ref is shared. */
+    onFitRef?: React.MutableRefObject<(() => void) | null>;
+}
+declare function WorkspaceView({ canWrite, onApplyOperations, onSelectionChange, renderAgentPanel, renderSidePanel, className, stack, activePage, onFitRef, }: WorkspaceViewProps): react.JSX.Element;
+/**
+ * Self-contained Konva workspace that creates its own command stack. Mount
+ * this when you want the canvas without the toolbar/rulers/pages-strip chrome.
+ *
+ * Products that want the full editor (chrome + workspace sharing one stack)
+ * should mount `DesignCanvasEditor` instead.
+ */
+declare function Workspace(props: DesignCanvasProps): react.JSX.Element | null;
+
+interface SelectionLayerProps {
+    /** Konva stage reference to look up selected nodes by name. */
+    stageRef: React.RefObject<Konva.Stage | null>;
+    /** Selected element ids from editor state. */
+    selectedIds: string[];
+    /** The model elements corresponding to selectedIds (pre-gesture snapshot). */
+    selectedElements: SceneElement[];
+    /** Whether the canvas is writable. False → transformer renders but is not interactive. */
+    canWrite: boolean;
+    /** Emitted when a transform gesture completes with final attrs per element. */
+    onTransformEnd(entries: MultiSetAttrsEntry[]): void;
+    /** Active page id — every entry in onTransformEnd carries this. */
+    pageId: string;
+}
+declare function SelectionLayer({ stageRef, selectedIds, selectedElements, canWrite, onTransformEnd, pageId, }: SelectionLayerProps): react.JSX.Element;
+
+interface PagesStripProps {
+    pages: ScenePage[];
+    activePageId: string;
+    canWrite: boolean;
+    /**
+     * The host provides this to generate thumbnail data-URLs. The strip calls it
+     * on mount and debounces re-calls on document changes. Returns null when the
+     * thumbnail is not yet available (the strip renders a placeholder instead).
+     */
+    renderThumbnail(page: ScenePage): Promise<string | null>;
+    onSelectPage(pageId: string): void;
+    onAddPage(): void;
+    onDuplicatePage(pageId: string): void;
+    onDeletePage(pageId: string): void;
+    onReorderPage(pageId: string, toIndex: number): void;
+}
+declare function PagesStrip({ pages, activePageId, canWrite, renderThumbnail, onSelectPage, onAddPage, onDuplicatePage, onDeletePage, onReorderPage, }: PagesStripProps): react.JSX.Element;
+
+interface LayersPanelProps {
+    page: ScenePage;
+    selectedElementIds: string[];
+    canWrite: boolean;
+    /** Emit a set_attrs command for the given element. */
+    onSetAttrs(elementId: string, attrs: Partial<Pick<SceneElement, 'name' | 'visible' | 'locked'>>): void;
+    /** Emit a reorder_element command. */
+    onReorder(elementId: string, toIndex: number): void;
+    onSelect(elementId: string, additive: boolean): void;
+}
+declare function LayersPanel({ page, selectedElementIds, canWrite, onSetAttrs, onReorder, onSelect }: LayersPanelProps): react.JSX.Element;
+
+interface ToolbarProps {
+    page: ScenePage;
+    selectedElements: SceneElement[];
+    canWrite: boolean;
+    canUndo: boolean;
+    canRedo: boolean;
+    gridEnabled: boolean;
+    snapEnabled: boolean;
+    showRulers: boolean;
+    showBleed: boolean;
+    onUndo(): void;
+    onRedo(): void;
+    onToggleGrid(): void;
+    onToggleSnap(): void;
+    onToggleRulers(): void;
+    onToggleBleed(): void;
+    /** Emit attrs patch for each selected element. */
+    onSetAttrs(elementId: string, attrs: SceneAttrsPatch): void;
+    onSetPageProps(props: {
+        name?: string;
+        width?: number;
+        height?: number;
+        background?: string;
+        bleed?: PageBleed | null;
+    }): void;
+    onSetPageGuides(guides: {
+        vertical: number[];
+        horizontal: number[];
+    }): void;
+    onReorder(elementId: string, toIndex: number, ownerLength: number, direction: 'front' | 'back' | 'forward' | 'backward'): void;
+    onGroup(elementIds: string[]): void;
+    onUngroup(groupId: string): void;
+    onDelete(elementIds: string[]): void;
+    onBindSlot(elementId: string, slot: string | null): void;
+}
+declare function Toolbar({ page, selectedElements, canWrite, canUndo, canRedo, gridEnabled, snapEnabled, showRulers, showBleed, onUndo, onRedo, onToggleGrid, onToggleSnap, onToggleRulers, onToggleBleed, onSetAttrs, onSetPageProps, onSetPageGuides, onReorder, onGroup, onUngroup, onDelete, onBindSlot, }: ToolbarProps): react.JSX.Element;
+
+/**
+ * Canvas zoom controls: fit-to-page, 100%, zoom-out/in buttons, and a percent
+ * readout. Stateless — zoom lives in the editor's view state, updated through
+ * onZoom.
+ */
+interface ZoomControlsProps {
+    zoom: number;
+    onZoom(zoom: number): void;
+    onFit(): void;
+}
+declare function ZoomControls({ zoom, onZoom, onFit }: ZoomControlsProps): react.JSX.Element;
+
+interface ElementNodeProps {
+    element: SceneElement;
+    isSelected: boolean;
+    zoom: number;
+    onClick?(elementId: string): void;
+    onDragStart?(elementId: string): void;
+    onDragMove?(elementId: string, dx: number, dy: number): void;
+    onDragEnd?(elementId: string, finalX: number, finalY: number): void;
+    onDoubleClick?(elementId: string): void;
+}
+declare function ElementNode(props: ElementNodeProps): react.JSX.Element | null;
+
+/**
+ * Grid overlay rendered beneath page content. Uses Konva.Layer with Konva.Line
+ * nodes at `gridSize` document-px spacing, scaled by zoom. Grid lines are
+ * skipped entirely when they would be closer than 4 screen pixels apart —
+ * below that density the grid becomes visual noise rather than guidance.
+ *
+ * All nodes carry the name prefix 'overlay:' so export logic can exclude this
+ * layer from rasterization.
+ */
+interface GridLayerProps {
+    /** Page width in document px. */
+    pageWidth: number;
+    /** Page height in document px. */
+    pageHeight: number;
+    /** Document px between grid lines. */
+    gridSize: number;
+    /** Screen px per document px. */
+    zoom: number;
+    /** Grid line color. */
+    color?: string;
+    /** Grid line opacity (0–1). */
+    opacity?: number;
+}
+declare function GridLayer({ pageWidth, pageHeight, gridSize, zoom, color, opacity, }: GridLayerProps): react.JSX.Element | null;
+
+interface RulersProps {
+    /** Page width in document px. */
+    pageWidth: number;
+    /** Page height in document px. */
+    pageHeight: number;
+    zoom: number;
+    /** How many doc-px of the canvas are scrolled off-screen left/top. */
+    scrollLeft: number;
+    scrollTop: number;
+    showRulers: boolean;
+    guides: PageGuides;
+    /** Emitted when the user drops a guide or deletes one back into the ruler. */
+    onGuidesChange(guides: PageGuides): void;
+}
+declare function Rulers({ pageWidth, pageHeight, zoom, scrollLeft, scrollTop, showRulers, guides, onGuidesChange }: RulersProps): react.JSX.Element | null;
+
+/**
+ * Pure layer-tree helpers: flatten a page's element array into an ordered list
+ * for the LayersPanel, preserving group nesting. Extracted so render order,
+ * depth, and selection math can be unit-tested independently of React.
+ */
+
+interface LayerRow {
+    element: SceneElement;
+    depth: number;
+    /** True when this row is a group whose children follow it in the list. */
+    isGroup: boolean;
+    /** Index within its owner (page.elements or group.children). */
+    ownerIndex: number;
+    /** Length of the owner array — needed for z-order bound math. */
+    ownerLength: number;
+    /** Id of the containing group, or null for page-root elements. */
+    parentGroupId: string | null;
+}
+/**
+ * Flatten `page.elements` into display order for the layers panel.
+ *
+ * Z-order is bottom→top in the element array; the layers panel shows
+ * top→bottom (highest z-index first). A group row precedes its children
+ * (the group is "above" its children in the panel, reflecting that the group
+ * node itself paints last in Konva when empty; children paint inside it).
+ *
+ * Depth increases by 1 for each group level, starting at 0 for page-root
+ * elements. Groups are expanded; collapsed state is a view concern the caller
+ * tracks separately.
+ */
+declare function flattenLayerTree(page: ScenePage): LayerRow[];
+/** The maximum number of rows the layers panel renders before truncating. */
+declare const LAYERS_PANEL_ROW_LIMIT = 500;
+
+/**
+ * Pure geometry helpers extracted from component drag/transform logic so
+ * every interactive math path is unit-testable without Konva or a DOM.
+ *
+ * Invariants:
+ * - All inputs and outputs are in document-coordinate pixels unless noted.
+ * - Rotation angles are degrees, clockwise, matching the Konva + model convention.
+ * - "Baking" scale into width/height resets Konva's scaleX/scaleY to 1; that
+ *   is required so the model's width/height always reflects true size, never a
+ *   scaled-but-uncollapsed state.
+ */
+interface TransformerNode {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    /** Konva's scale after the transformer gesture; 1 when already baked. */
+    scaleX: number;
+    scaleY: number;
+    rotation: number;
+}
+interface BakedNodeAttrs {
+    x: number;
+    y: number;
+    /** True pixel size after scale is collapsed into dimensions. */
+    width: number;
+    height: number;
+    rotation: number;
+}
+/**
+ * Collapse Konva scaleX/scaleY into width/height so the model always stores
+ * true pixel dimensions. The transformer mutates scale on drag; we bake it
+ * once at dragend/transformend and emit width/height — scale resets to 1
+ * implicitly (the emitted attrs do not include scale, so the next render
+ * starts from scaleX=1).
+ *
+ * Konva rotates about the top-left origin and also shifts x/y to compensate
+ * for scale — the transformer gives us the post-rotation, post-scale x/y
+ * directly, so no further rotation math is needed here.
+ */
+declare function bakeRectTransform(node: TransformerNode): BakedNodeAttrs;
+/**
+ * Lines store points as a flat [x0, y0, x1, y1, ...] array relative to the
+ * line element's (x, y). When the transformer scales the group containing the
+ * line, we bake scaleX into every x-component of points and scaleY into every
+ * y-component, then reset scale to 1. The element x/y is the Konva group
+ * origin and is taken directly from the transformer output.
+ */
+declare function bakeLineTransform(node: TransformerNode & {
+    points: number[];
+}): BakedNodeAttrs & {
+    points: number[];
+};
+/**
+ * Text nodes have a fixed wrap width; scaling that width is what the
+ * transformer controls. Height is content-derived and is NOT baked here —
+ * it re-derives from text content at render time via estimateTextHeight.
+ * Only scaleX is baked into width; scaleY into fontSize so text scales
+ * proportionally when the user resizes with keepRatio.
+ */
+declare function bakeTextTransform(node: TransformerNode & {
+    fontSize: number;
+}): BakedNodeAttrs & {
+    fontSize: number;
+};
+
+/**
+ * Pure ruler tick-step and label math for the canvas rulers. Nothing here
+ * touches React or the DOM — all interaction geometry is extracted so it can
+ * be unit-tested without a browser.
+ *
+ * Canvas rulers show document-coordinate values (CSS px). Tick density adapts
+ * to the current zoom so major ticks never sit closer than `minMajorSpacingPx`
+ * screen pixels apart. The step table covers typical design zoom ranges; beyond
+ * the table the step grows by doubling the last candidate.
+ */
+interface TickStep {
+    /** Document-coordinate step between major ticks. */
+    major: number;
+    /** Document-coordinate step between minor ticks (major / 5). */
+    minor: number;
+    /** True when minor ticks should be drawn (they sit ≥ minMinorSpacingPx apart). */
+    drawMinor: boolean;
+}
+/**
+ * Select the major tick step that keeps major ticks ≥ minMajorSpacingPx apart
+ * at the given zoom. Minor ticks are rendered when they'd clear minMinorSpacingPx.
+ *
+ * Both spacing thresholds are SCREEN pixels — the caller provides `zoom` (screen
+ * px per document px) so the result is zoom-independent.
+ */
+declare function selectTickStep(input: {
+    zoom: number;
+    minMajorSpacingPx?: number;
+    minMinorSpacingPx?: number;
+}): TickStep;
+interface RulerTick {
+    /** Position in document coordinates. */
+    position: number;
+    /** Label text, or null for a minor tick. */
+    label: string | null;
+}
+/**
+ * Generate all ticks visible in a ruler of `documentLength` document-px,
+ * given the current tick step. The caller clips to the viewport; this produces
+ * all ticks for the full document extent so the ruler can be rendered
+ * declaratively without a separate clipping pass.
+ */
+declare function buildRulerTicks(input: {
+    documentLength: number;
+    step: TickStep;
+}): RulerTick[];
+/** Format a document-px position as a compact label: integers stay whole,
+ *  decimals are rounded to 1 place. Values ≥ 1000 are compacted to "1k" etc. */
+declare function formatRulerLabel(value: number): string;
+
+/** Batteries-included editor: chrome + workspace on one shared stack. */
+declare const DesignCanvasLazy: react.LazyExoticComponent<typeof DesignCanvasEditor>;
+/** Raw chrome only — use when supplying a custom renderWorkspace/renderThumbnail. */
+declare const DesignCanvasChromeLazy: react.LazyExoticComponent<typeof DesignCanvas>;
+
+export { type AddElementInput, type AddPageInput, type ApplySceneResult, type BakedNodeAttrs, type BindSlotInput, DUPLICATE_OFFSET, type DeleteElementInput, type DeletePageInput, DesignCanvas, DesignCanvasChromeLazy, DesignCanvasEditor, type DesignCanvasFullProps, DesignCanvasLazy, type DesignCanvasProps, type DuplicatePageInput, type EditorSceneState, ElementNode, type ElementNodeProps, ExportCropRect, type ExportPageDataUrlOptions, ExportPreset, type ExportViewSnapshot, GridLayer, type GridLayerProps, type GroupElementsInput, LAYERS_PANEL_ROW_LIMIT, type LayerRow, LayersPanel, type LayersPanelProps, type MarqueeSelectOptions, type MultiSetAttrsEntry, type NudgeDelta, PagesStrip, type PagesStripProps, type ReorderElementInput, type ReorderPageInput, type ResolvedExportParams, type RulerTick, Rulers, type RulersProps, SCENE_COMMAND_HISTORY_LIMIT, type SceneCommand, type SceneCommandStack, SelectionLayer, type SelectionLayerProps, type SetAttrsInput, type SetDocumentTitleInput, type SetPageGuidesInput, type SetPagePropsInput, type SnapEngine, type SnapResult, type SnapTarget, type SnapTargetKind, type SnapTargets, type TickStep, Toolbar, type ToolbarProps, type TransformerNode, type UngroupElementInput, Workspace, WorkspaceView, type WorkspaceViewProps, ZoomControls, type ZoomControlsProps, type ZoomPanConfig, type ZoomPanMath, addElementCommand, addPageCommand, bakeLineTransform, bakeRectTransform, bakeTextTransform, bindSlotCommand, buildRulerTicks, collectGridTargets, createSceneCommandStack, createSnapEngine, createZoomPanMath, deleteElementCommand, deletePageCommand, documentCropToStageCoords, downloadDataUrl, duplicatePageCommand, exportDocumentJson, exportPageDataUrl, flattenLayerTree, formatRulerLabel, groupElementsCommand, identifyTaintedSrc, isCrossOriginSrc, isExportHiddenNodeName, marqueeSelect, multiSetAttrsCommand, nudgeDelta, reorderElementCommand, reorderPageCommand, resolveExportParams, selectTickStep, setAttrsCommand, setDocumentTitleCommand, setPageGuidesCommand, setPagePropsCommand, ungroupElementCommand };