@tangle-network/agent-app 0.45.53 → 0.45.55

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

@@ -1,400 +1,22 @@
-import { d as SceneCommand, i as SnapTarget, g as SnapEngine, Z as ZoomPanMath } from '../command-stack-TNPWJCzW.js';
-export { A as ApplySceneResult, a as DesignCanvasMode, D as DesignCanvasProps, b as EditorSceneState, E as ExportTriggerOptions, S as SCENE_COMMAND_HISTORY_LIMIT, e as SceneCommandStack, f as SceneCommandStackWithReapply, h as SnapResult, j as SnapTargetKind, k as SnapTargets, c as createSceneCommandStack } from '../command-stack-TNPWJCzW.js';
-import { a as SceneElement, N as NewPageOptions, c as SceneDocument, b as PageGuides, P as PageBleed, B as Bounds, S as ScenePage } from '../model-DnfO_PdJ.js';
-import { h as SceneAttrsPatch, S as SceneOperation } from '../operations-ByJ6yXOW.js';
-import { d as ExportCropRect, f as ExportPreset } from '../export-presets-mgVulRaV.js';
-export { h as bleedAwareExportBounds, s as scaleForPreset } from '../export-presets-mgVulRaV.js';
-import '../theme/index.js';
-
-/** Define input parameters for adding a scene element with optional index and parent group ID */
-interface AddElementInput {
-    pageId: string;
-    element: SceneElement;
-    /** Insertion z-index within owner; omitted → top. */
-    index?: number;
-    /** Parent group id; omitted → page root. */
-    parentGroupId?: string;
-}
-/** Create a command to add an element to a scene with optional positioning and grouping */
-declare function addElementCommand(input: AddElementInput): SceneCommand;
-/** Define input parameters for setting element attributes within a specific page context */
-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;
-}
-/** Create a command to set attributes on a scene element with undo capability */
-declare function setAttrsCommand(input: SetAttrsInput): SceneCommand;
-/** Define an entry linking page and element IDs with current and prior scene attribute patches */
-interface MultiSetAttrsEntry {
-    pageId: string;
-    elementId: string;
-    attrs: SceneAttrsPatch;
-    priorAttrs: SceneAttrsPatch;
-}
-/** Build a scene command to set multiple attributes on elements across pages */
-declare function multiSetAttrsCommand(entries: MultiSetAttrsEntry[]): SceneCommand;
-/** Define input parameters to reorder an element within a page */
-interface ReorderElementInput {
-    pageId: string;
-    elementId: string;
-    toIndex: number;
-}
-/** Resolve a command to reorder an element within a scene by moving it to a specified index */
-declare function reorderElementCommand(input: ReorderElementInput): SceneCommand;
-/** Define input parameters required to delete an element from a specific page in a document */
-interface DeleteElementInput {
-    document: SceneDocument;
-    pageId: string;
-    elementId: string;
-}
-/** Resolve a command to delete an element from a specified page in the document */
-declare function deleteElementCommand(input: DeleteElementInput): SceneCommand;
-/** Define input parameters for grouping elements within a scene document on a specific page */
-interface GroupElementsInput {
-    document: SceneDocument;
-    pageId: string;
-    elementIds: string[];
-    groupId: string;
-    name?: string;
-}
-/** Create a command to group multiple elements into a single group within a scene */
-declare function groupElementsCommand(input: GroupElementsInput): SceneCommand;
-/** Define input parameters required to ungroup elements within a specific page and group */
-interface UngroupElementInput {
-    document: SceneDocument;
-    pageId: string;
-    groupId: string;
-}
-/** Resolve a command to ungroup a group element into its child elements within a scene */
-declare function ungroupElementCommand(input: UngroupElementInput): SceneCommand;
-/** Define input parameters for adding a new page with optional settings and position index */
-interface AddPageInput {
-    pageId: string;
-    options?: NewPageOptions;
-    index?: number;
-}
-/** Create a command to add a page with optional settings and index in the scene */
-declare function addPageCommand(input: AddPageInput): SceneCommand;
-/** Define input parameters required to duplicate a page within a scene document */
-interface DuplicatePageInput {
-    document: SceneDocument;
-    sourcePageId: string;
-    /** Caller-minted id for the copy. */
-    pageId: string;
-}
-/** Create a command to duplicate a page and prepare its deletion operation in the scene */
-declare function duplicatePageCommand(input: DuplicatePageInput): SceneCommand;
-/** Define input parameters required to delete a page from a scene document */
-interface DeletePageInput {
-    document: SceneDocument;
-    pageId: string;
-}
-/** Delete a page from a document ensuring it is not the last remaining page */
-declare function deletePageCommand(input: DeletePageInput): SceneCommand;
-/** Define input parameters to reorder a page by specifying its ID and target index */
-interface ReorderPageInput {
-    pageId: string;
-    toIndex: number;
-}
-/** Create a command to reorder a page to a specified index within a scene */
-declare function reorderPageCommand(input: ReorderPageInput): SceneCommand;
-/** Define input parameters for setting properties on a specific page within a scene document */
-interface SetPagePropsInput {
-    document: SceneDocument;
-    pageId: string;
-    props: {
-        name?: string;
-        width?: number;
-        height?: number;
-        background?: string;
-        bleed?: PageBleed | null;
-    };
-}
-/** Build a command to update page properties based on the provided input */
-declare function setPagePropsCommand(input: SetPagePropsInput): SceneCommand;
-/** Define input parameters for setting guides on a specific page within a document */
-interface SetPageGuidesInput {
-    document: SceneDocument;
-    pageId: string;
-    guides: PageGuides;
-}
-/** Create a command to update page guides with undo support */
-declare function setPageGuidesCommand(input: SetPageGuidesInput): SceneCommand;
-/** Define input parameters for binding a slot within a scene document element */
-interface BindSlotInput {
-    document: SceneDocument;
-    pageId: string;
-    elementId: string;
-    slot: string | null;
-}
-/** Bind a slot to an element within a page and generate the corresponding scene command */
-declare function bindSlotCommand(input: BindSlotInput): SceneCommand;
-/** Define input parameters for setting the title of a scene document */
-interface SetDocumentTitleInput {
-    document: SceneDocument;
-    title: string;
-}
-/** Resolve a command to rename a document title with undo and redo operations */
-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.
- */
-
-/** Build a SnapEngine instance to manage snapping targets and behavior within an editor scene */
-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.
- */
-
-/**
- * Top-most selectable element whose AABB contains the document-space point, or
- * null when the point is over empty space.
- *
- * This is the authoritative "is the pointer over an element?" test for the
- * pointer-down gesture router. It runs against the scene model in document
- * coordinates rather than Konva's hit-graph canvas, so it is independent of
- * clip groups, listening flags, and hit-canvas redraw timing — all of which
- * could make `stage.getIntersection` misclassify a press as empty space and
- * silently start a marquee instead of an element drag.
- *
- * Z-order: later elements paint on top, so we scan the array in reverse and
- * return the first hit. Groups descend into children (top child wins); a hit on
- * a group child resolves to the group itself, matching drag/selection which
- * operate on the group as a unit. Locked and invisible elements never hit.
- */
-declare function hitTestPoint(page: ScenePage, x: number, y: number): string | null;
-/** Define options to configure marquee selection behavior including containment requirements */
-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[];
-/** Represent horizontal and vertical displacement values for nudging elements */
-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.
- */
-
-/** Define configuration options for minimum and maximum zoom levels in a zoom-pan interface */
-interface ZoomPanConfig {
-    minZoom: number;
-    maxZoom: number;
-}
-/** Create zoom and pan math utilities enforcing valid zoom range constraints */
-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;
-/** Define parameters required to resolve export settings including crop, pixel ratio, type, and quality */
-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;
-/** Hard ceiling for node cache rasterization. Without it a deep zoom (max 32)
- *  on a retina display would rasterize page-size elements into canvases beyond
- *  browser backing-store limits; 4x supersampling covers every realistic
- *  crispness-critical range (fit-page → 200% at dpr 2). */
-declare const NODE_CACHE_PIXEL_RATIO_MAX = 4;
-/**
- * Pixel ratio a Konva node bitmap cache should rasterize at so the cached
- * bitmap matches the screen exactly: the node's absolute scale (content-group
- * zoom) × device pixel ratio. Konva's cache default ignores zoom, so the
- * bitmap is re-scaled at draw time — bilinear-soft at fit-page zooms like
- * 0.47, badly upscaled on zoom-in. ElementNode caches at this ratio and
- * export.ts restores cleared caches at it, keeping one policy in one place.
- */
-declare function resolveNodeCachePixelRatio(absoluteScale: number, devicePixelRatio: number): number;
-/**
- * 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;
-};
-
-/**
- * Pure builders for the human "add element to the canvas" path — the math and
- * `SceneOperation` construction behind {@link CanvasInsertPanel}, separated from
- * the React/DOM layer so every insert is unit-testable without Konva or a
- * browser. The panel calls these to produce `add_element` operations and hands
- * them to the host's `onApplyOperations` (server-validated, undoable) — the same
- * pipeline every other edit flows through.
- *
- * Media boundary: image inserts must pass {@link assertSceneMediaSrc} (remote
- * http(s) or a rooted `/api/` path — never `data:` blobs or sandbox-local
- * files). Builders that take a src assert it up front so a bad url fails here,
- * not deep in the apply layer.
- */
-
-/** Largest dimension (document px) a freshly inserted element is fitted to,
- *  before the page-size cap applies. Keeps a huge upload from filling the page. */
-declare const MAX_INSERT_DIMENSION = 600;
-/** Active page geometry an insert lands into — drives centering and fitting. */
-interface InsertPageGeometry {
-    pageId: string;
-    width: number;
-    height: number;
-    background?: string;
-}
-/** Mint a DOM-safe element id. Prefers `crypto.randomUUID`; falls back to a
- *  time+random id where crypto is unavailable (older runtimes, some test envs). */
-declare function mintElementId(): string;
-/** Fit (naturalW, naturalH) under a max-dimension cap (further bounded by the
- *  page), preserving aspect ratio. Never upscales past natural size. */
-declare function fittedSize(naturalW: number, naturalH: number, pageWidth: number, pageHeight: number): {
-    width: number;
-    height: number;
-};
-/** Top-left position that centers a (width, height) box on the page. */
-declare function centeredPosition(width: number, height: number, pageWidth: number, pageHeight: number): {
-    x: number;
-    y: number;
-};
-/**
- * Build an `add_element` op placing an image, fitted and centered on the page.
- * `naturalSize` is the probed image dimensions (the panel reads them in the
- * browser); pass `{ width: 0, height: 0 }` when unknown to fall back to the cap.
- *
- * Throws (via `assertSceneMediaSrc`) when `src` is not http(s) or a rooted
- * `/api/` path — callers should surface the error, never insert a `data:` src.
- */
-declare function buildInsertImageOp(src: string, naturalSize: {
-    width: number;
-    height: number;
-}, page: InsertPageGeometry): SceneOperation;
-/** A template the insert panel can drop without the agent. `build` is pure and
- *  produces the operations for the active page geometry. */
-interface InsertTemplate {
-    id: string;
-    label: string;
-    build(page: InsertPageGeometry): SceneOperation[];
-}
-/** The built-in starter templates (heading, body text, rectangle, ellipse).
- *  Consumers can pass their own list to {@link CanvasInsertPanel}; this is the
- *  default so every canvas gets a usable set out of the box. */
-declare const DEFAULT_INSERT_TEMPLATES: readonly InsertTemplate[];
-
-export { type AddElementInput, type AddPageInput, type BindSlotInput, DEFAULT_INSERT_TEMPLATES, DUPLICATE_OFFSET, type DeleteElementInput, type DeletePageInput, type DuplicatePageInput, ExportCropRect, ExportPreset, type ExportViewSnapshot, type GroupElementsInput, type InsertPageGeometry, type InsertTemplate, MAX_INSERT_DIMENSION, type MarqueeSelectOptions, type MultiSetAttrsEntry, NODE_CACHE_PIXEL_RATIO_MAX, type NudgeDelta, type ReorderElementInput, type ReorderPageInput, type ResolvedExportParams, SceneCommand, type SetAttrsInput, type SetDocumentTitleInput, type SetPageGuidesInput, type SetPagePropsInput, SnapEngine, SnapTarget, type UngroupElementInput, type ZoomPanConfig, ZoomPanMath, addElementCommand, addPageCommand, bindSlotCommand, buildInsertImageOp, centeredPosition, collectGridTargets, createSnapEngine, createZoomPanMath, deleteElementCommand, deletePageCommand, documentCropToStageCoords, duplicatePageCommand, fittedSize, groupElementsCommand, hitTestPoint, identifyTaintedSrc, isCrossOriginSrc, isExportHiddenNodeName, marqueeSelect, mintElementId, multiSetAttrsCommand, nudgeDelta, reorderElementCommand, reorderPageCommand, resolveExportParams, resolveNodeCachePixelRatio, setAttrsCommand, setDocumentTitleCommand, setPageGuidesCommand, setPagePropsCommand, ungroupElementCommand };
+ * Konva-free core of the design-canvas editor: seam contracts, the command-stack
+ * editing engine, snap/zoom/selection geometry, export math, and insert builders.
+ *
+ * Import this subpath (`@tangle-network/agent-app/design-canvas-react/engine`)
+ * to drive, inspect, or test a scene WITHOUT pulling the Konva renderer (~1.3 MB
+ * of `konva`/`react-konva`) into the bundle — server-side layout, custom
+ * renderers, headless tooling, and unit tests. The full editor lives at the
+ * package root; the code-split handles live at `./design-canvas-react/lazy`.
+ *
+ * Invariant: nothing re-exported here may import `konva`/`react-konva` or touch
+ * the DOM — that is what keeps the subpath shakeable. Adding a Konva import to
+ * any of these modules silently reattaches the renderer to every engine consumer.
+ */
+export * from './contracts';
+export * from './engine/command-stack';
+export * from './engine/commands';
+export * from './engine/snap';
+export * from './engine/selection';
+export * from './engine/zoom-pan';
+export * from './export-math';
+export * from './insert-builders';

package/dist/design-canvas-react/export-math.d.ts

@@ -0,0 +1,104 @@
+/**
+ * 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.
+ */
+import type { ScenePage } from '../design-canvas/model';
+import { bleedAwareExportBounds, scaleForPreset, type ExportCropRect, type ExportPreset } from '../design-canvas/export-presets';
+export type { ExportCropRect, ExportPreset };
+export { bleedAwareExportBounds, scaleForPreset };
+/** 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'. */
+export declare function isExportHiddenNodeName(name: string): boolean;
+/** Define parameters required to resolve export settings including crop, pixel ratio, type, and quality */
+export 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).
+ */
+export declare function resolveExportParams(page: ScenePage, opts: {
+    format: 'png' | 'jpeg';
+    pixelRatio?: number;
+    includeBleed?: boolean;
+    preset?: ExportPreset;
+}): ResolvedExportParams;
+/** Hard ceiling for node cache rasterization. Without it a deep zoom (max 32)
+ *  on a retina display would rasterize page-size elements into canvases beyond
+ *  browser backing-store limits; 4x supersampling covers every realistic
+ *  crispness-critical range (fit-page → 200% at dpr 2). */
+export declare const NODE_CACHE_PIXEL_RATIO_MAX = 4;
+/**
+ * Pixel ratio a Konva node bitmap cache should rasterize at so the cached
+ * bitmap matches the screen exactly: the node's absolute scale (content-group
+ * zoom) × device pixel ratio. Konva's cache default ignores zoom, so the
+ * bitmap is re-scaled at draw time — bilinear-soft at fit-page zooms like
+ * 0.47, badly upscaled on zoom-in. ElementNode caches at this ratio and
+ * export.ts restores cleared caches at it, keeping one policy in one place.
+ */
+export declare function resolveNodeCachePixelRatio(absoluteScale: number, devicePixelRatio: number): number;
+/**
+ * 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.
+ */
+export 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.
+ */
+export declare function isCrossOriginSrc(src: string): boolean;
+/** Minimal snapshot of stage view state that export.ts saves before mutating
+ *  zoom/pan/visibility and restores afterward. */
+export 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.
+ */
+export declare function documentCropToStageCoords(cropRect: ExportCropRect, stageScale: number, stageX: number, stageY: number): {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};

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

@@ -0,0 +1,89 @@
+/**
+ * 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.
+ */
+import type { SceneDocument, ScenePage } from '../design-canvas/model';
+import type { ExportPreset } from '../design-canvas/export-presets';
+interface KonvaNodeLike {
+    name(): string;
+    visible(): boolean;
+    visible(v: boolean): void;
+    getAttr(key: string): unknown;
+    isCached(): boolean;
+    clearCache(): void;
+    cache(config?: {
+        pixelRatio?: number;
+    }): void;
+    getAbsoluteScale(): {
+        x: number;
+        y: number;
+    };
+    /** Konva.Container only — leaf shapes lack it; the cache walk treats its
+     *  absence as "no children". */
+    getChildren?(): KonvaNodeLike[];
+}
+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;
+}
+/** Define options to export a page as a data URL with format, pixel ratio, bleed, and preset settings */
+export 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.
+ */
+export 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.
+ */
+export 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.
+ */
+export declare function downloadDataUrl(dataUrl: string, filename: string): void;
+export {};