@canvas-harness/core 0.0.5 → 0.1.1

package/dist/index.d.cts

@@ -922,7 +922,14 @@ declare const defineNode: (opts: NodeTypeDefOptions) => NodeTypeDef;
  * nesting, no escapes — single-pass regex tokenization keeps layout
  * fast at scale. See ARCHITECTURE.md §8.
  */
-type InlineType = 'text' | 'bold' | 'italic' | 'underline' | 'strike' | 'highlight' | 'code' | 'link';
+type InlineType = 'text' | 'bold' | 'italic' | 'underline' | 'strike' | 'highlight' | 'code' | 'link'
+/**
+ * LaTeX math expression, content is the source between `$...$` (no
+ * leading/trailing whitespace, no line breaks). Rendered via MathJax
+ * SVG output and rasterized to an inline bitmap at paint time. See
+ * `text/math/`.
+ */
+ | 'math';
 type Token = {
     type: InlineType;
     content: string;
@@ -963,6 +970,12 @@ type LayoutOptions = {
     fontFamily: FontFamily;
     fontSize: FontSize;
     textStyle: TextStyle;
+    /**
+     * Used to key the math bitmap cache. Both layout (for measured dims)
+     * and paint (for the actual bitmap) need to query the same cache
+     * entry. Defaults to `#000000` for estimate-only callers.
+     */
+    textColor?: string;
 };
 /**
  * Turns tokens into drawable lines. Output consumed by the canvas paint pass.
@@ -1037,6 +1050,97 @@ declare const subscribeFontEpoch: (listener: (epoch: number) => void) => (() =>
  */
 declare const getFontEpoch: () => number;
 
+/**
+ * Lazy loader for MathJax — same pattern as `render/rough/loader.ts`.
+ *
+ * MathJax is ~600KB and only useful for scenes with LaTeX math. We
+ * defer loading until the first `$...$` token requests a compile,
+ * then convert LaTeX → SVG strings off the main rAF path.
+ *
+ * Loaded from jsDelivr CDN rather than bundled because the v4
+ * tex-svg.js bundle uses `importScripts('sre/speech-worker.js')` for
+ * accessibility; the relative URL resolves wrong when served from a
+ * dev bundler's node_modules. The CDN serves sibling files at
+ * predictable paths so the bundle finds its workers. Self-host by
+ * pointing `VENDOR_URL` at your own copy of the v4 component files.
+ *
+ * Notes:
+ *   - MathJax's `tex-svg.js` bundle attaches itself to `window.MathJax`
+ *     when loaded. This is the documented v4 browser API.
+ *   - If a consumer also uses MathJax, they should configure the
+ *     global *before* canvas-harness's first math node loads.
+ */
+type MathJaxLike = {
+    tex2svgPromise(source: string, opts?: {
+        display?: boolean;
+        em?: number;
+        ex?: number;
+        containerWidth?: number;
+    }): Promise<MathJaxSvgElement>;
+    startup: {
+        /**
+         * The "lite adaptor" used by the SVG output in browser context.
+         * `serializeXML` returns standalone-valid SVG markup with
+         * namespaces intact (which `outerHTML` does not always do).
+         */
+        adaptor: {
+            serializeXML?(el: MathJaxSvgElement): string;
+            outerHTML(el: MathJaxSvgElement): string;
+        };
+    };
+};
+/**
+ * MathJax returns a "lite element" virtual-DOM node, not a real SVG
+ * element. We only need to serialize it via the adaptor.
+ */
+type MathJaxSvgElement = unknown;
+declare global {
+    var MathJax: unknown;
+}
+/**
+ * Returns the configured MathJax instance if loaded, else `null` and
+ * triggers the lazy import on first call. Subscribers via `onMathJaxReady`
+ * are notified when the import resolves.
+ */
+declare const getMathJax: () => MathJaxLike | null;
+/**
+ * Registers a callback that fires once when MathJax becomes available.
+ * No-op if already loaded — caller should check `getMathJax() !== null`
+ * first. Used to trigger a re-paint of math-bearing text nodes.
+ */
+declare const onMathJaxReady: (cb: () => void) => void;
+
+/** Result of a successful math compile + raster. */
+type MathBitmap = {
+    bitmap: ImageBitmap;
+    /** Width in logical CSS pixels at the requested font size. */
+    width: number;
+    /** Height in logical CSS pixels at the requested font size. */
+    height: number;
+    /**
+     * Baseline offset in CSS pixels (positive = bitmap top sits ABOVE
+     * the text baseline; the bottom dips below by `height - baseline`).
+     * Parsed from MathJax's `vertical-align: -Nex` style attribute.
+     */
+    baselineOffset: number;
+};
+declare const getMathEpoch: () => number;
+declare const subscribeMathEpoch: (cb: () => void) => (() => void);
+/**
+ * Look up a math bitmap or kick off compilation. Returns the cached
+ * bitmap if ready, `null` if still loading / queued (caller should
+ * paint a placeholder this frame). Triggers a math-epoch bump when
+ * the formula resolves.
+ *
+ * `sizePx` is the on-screen height in logical px (typically the line
+ * height of the surrounding text × DPR).
+ */
+declare const getMathBitmap: (source: string, color: string, sizePx: number) => MathBitmap | null;
+/** Test / debug aid. */
+declare const clearMathCache: () => void;
+/** Test / debug aid. */
+declare const getMathCacheSize: () => number;
+
 /**
  * Buckets zoom to avoid cache churn from sub-1%-zoom changes.
  */
@@ -1495,14 +1599,21 @@ interface CanvasStore {
      * Adds a node. Returns its id. If `node.style.autoFit !== false` and
      * `node.content` is set, height is grown to fit.
      *
+     * `z` is optional — omit to land on top of the current stack (uses
+     * the internal `topZ` counter). Pass a literal value (incl. `0` or
+     * negative) to place the node at that exact z.
+     *
      * @example
+     * // Omit z → goes on top of the current stack.
      * const id = store.addNode({
      *   id: asNodeId(store.generateId()),
      *   type: 'rect', x: 0, y: 0, w: 200, h: 100,
-     *   angle: 0, z: 0, groups: [],
+     *   angle: 0, groups: [],
      * })
      */
-    addNode(node: Node): NodeId;
+    addNode(node: Omit<Node, 'z'> & {
+        z?: number;
+    }): NodeId;
     /**
      * Patches fields on an existing node. Captures the previous slice on
      * the op so undo is free. Autofit re-runs when `content` or font
@@ -1566,8 +1677,13 @@ interface CanvasStore {
         alt?: string;
         style?: Style;
     }): Promise<NodeId>;
-    /** Adds an edge. Returns its id. */
-    addEdge(edge: Edge): EdgeId;
+    /**
+     * Adds an edge. Returns its id. `z` is optional — same auto-top
+     * semantics as {@link CanvasStore.addNode}.
+     */
+    addEdge(edge: Omit<Edge, 'z'> & {
+        z?: number;
+    }): EdgeId;
     /** Patches fields on an existing edge. */
     updateEdge(id: EdgeId, patch: Partial<Edge>): void;
     /** Removes an edge. */
@@ -3252,4 +3368,4 @@ declare const installedExtensions: (store: CanvasStore) => string[];
  */
 declare const VERSION = "0.0.0";
 
-export { type AnthropicToolDef, type Arrowhead, BEZIER_SEGMENTS, type BatchId, type BitmapCacheEntry, type BitmapCacheRequest, type BuiltInNodeType, CODE_BG_COLOR, CODE_BLOCK_MARGIN_Y, CODE_BLOCK_PADDING_X, CONTENT_HEIGHT_BUFFER, CONTENT_PADDING, type CameraState, type CanvasBackground, type CanvasBackgroundPattern, type CanvasStore, type CanvasSurface, type ClientId, type ClipResult, type ConflictRecord, type ContextEdge, type ContextNode, DEFAULT_BACKGROUND, DEFAULT_CAMERA, DEFAULT_HIGHLIGHT_COLOR, DEFAULT_HIGHLIGHT_COLOR_DARK, DEFAULT_MINIMAP_MAX_NODES, DEFAULT_STYLE, DEFAULT_TEXT_COLOR, type DeserializeOptions, type DragOriginal, type DrawTextOptions, EDGE_HANDLE_SLOP_PX, EDGE_HIT_SLOP_PX, type Edge, type EdgeEnd, type EdgeGeometry, EdgeGeometryCache, type EdgeHit, type EdgeId, type EdgeStyle, type EditorAdapter, type EditorAdapterFactory, type EditorAdapterMountOptions, type EstimateOptions, type ExportOptions, type Extension, type ExtensionApi, FONT_FAMILY_MAP, FONT_SIZE_MAP, type FontFamily, type FontSize, type FrameLoop, type FrameStats, type GetContextOptions, type Group, type GroupId, type Hit, type IconNodeData, type IdGenerator, type ImageNodeData, type InlineType, type InteractionMode, type InteractionState, LINE_HEIGHT_MAP, LINK_COLOR, type LayoutLine, type LayoutOptions, MAX_IMAGE_BYTES, MAX_SVG_BYTES, MAX_ZOOM, MIN_ZOOM, type Migrator, type MinimapContentOptions, type Node, type NodeHit, type NodeId, type NodeType, type NodeTypeDef, type NodeTypeDefOptions, type Op, type OpBatch, type OpOrigin, PALM_REJECTION_GRACE_MS, type PalmRejectionState, type PathStyle, type PointerInfo, type PresenceEvent, type PresencePatch, type PresenceSlice, type PresenceState, type PrimitiveType, RESIZE_HANDLES, RESIZE_HANDLE_SIZE_PX, ROTATE_HANDLE_OFFSET_PX, ROTATE_HANDLE_RADIUS_PX, type RenderEnv, type Renderer, type RendererOptions, type ResizeHandle, SCHEMA_VERSION, type Scene, type SceneContextJson, type SchemaVersion, type SerializedClipboard, type SerializedScene, type Side, type SnapshotEnv, type SpatialId, type SpatialQuery, type SpatialResult, type StoreEventHandler, type StoreEventName, type StoreEvents, type StoreOptions, type StrokeStyle, type Style, type StyledRun, type SvgExportOptions, type SyncAdapter, type SyncAdapterCapabilities, type TextAlign, type TextStyle, type ThemeResolver, type Token, type Transform, UniformGrid, type Unsubscribe, VERSION, type Vec2, type WorldRect, applyCameraTransform, applySvgColor, arrowheadLength, asBatchId, asClientId, asEdgeId, asGroupId, asNodeId, attachSync, autoRouteControls, blobToDataUri, clampEffectiveScale, clampZoom, clearMeasureCache, clearSurface, clearTextBitmapCache, clipSamples, computeAutoFitHeight, computeEdgeGeometry, copy, createCanvasStore, createDefaultTextareaEditor, createFrameLoop, createPalmRejectionState, createRenderer, cubicBezier, cubicBezierTangent, cut, defineExtension, defineNode, deserializeClipboard, detectConflicts, downscaleImageBlob, drawArrowhead, drawEdge, drawMinimapViewport, drawShape, drawTextToCanvas, drawWithNodeTransform, edgeAABBFromSamples, edgeLabelBoundsWorld, emptyPresenceState, estimateMarkdownContentHeight, exportSelection, exportSelectionSvg, exportViewport, extractSvgDimensions, fromSerialized, fullVisibleClipResult, getCanvasFont, getContentHeight, getContext, getDpr, getFontEpoch, getMarkdownLineHeightPx, getOrRenderTextBitmap, getPointAndTangentAtArcLength, getTextBitmapCacheSize, handleEnter, handleWorldPositions, hitTestAny, hitTestEdge, hitTestHandles, hitTestPoint, hitTestRotateHandle, idleInteractionState, inflateRect, insertLink, installExtension, installedExtensions, inverseBatch, inverseOp, isAttached, isCanvasHarnessClipboard, isDrawablePrimitive, isMoving, isNodeRemoteEditing, layoutTokens, makeIdGenerator, marqueeNodes, measureText, midpointToCubicControls, minimapScreenToWorld, nodeAABB, nodeIntersectsRect, nodeLocalToWorld, notePenActive, notePenInactive, opSchemas, opSchemasAsAnthropicTools, paintBackground, panByScreen, paste, pointInNode, projectEndToWorld, projectToNodeBoundary, quantizeDpr, quantizeZoom, randomClientId, rectContainsPoint, rectFromPoints, rectsIntersect, registerMigrator, renderMinimapContent, resolveColor, resolveOpacity, resolveRenderScale, resolveStrokeWidth, rotateHandleWorldPosition, rotateVecByAngle, sampleBezier, sampleSelfLoop, samplesFor, sanitizeSvg, sceneBounds, screenToWorld, selfLoopGeometry, serializeSelection, setupSurface, shouldAutoFit, shouldRejectTouch, sideNormalLocal, sideOf, sizeSurface, storeToJSON, subscribeFontEpoch, tangentAtArcLength, toImageBlob, toSerialized, toggleBold, toggleCode, toggleItalic, toggleStrike, toggleUnderline, tokenize, unionRects, validateImageInput, validateSvgMarkup, viewportWorldRect, withAutoFitHeight, worldToNodeLocal, worldToScreen, worldViewport, worldViewportFromCamera, zoomAtScreenPoint };
+export { type AnthropicToolDef, type Arrowhead, BEZIER_SEGMENTS, type BatchId, type BitmapCacheEntry, type BitmapCacheRequest, type BuiltInNodeType, CODE_BG_COLOR, CODE_BLOCK_MARGIN_Y, CODE_BLOCK_PADDING_X, CONTENT_HEIGHT_BUFFER, CONTENT_PADDING, type CameraState, type CanvasBackground, type CanvasBackgroundPattern, type CanvasStore, type CanvasSurface, type ClientId, type ClipResult, type ConflictRecord, type ContextEdge, type ContextNode, DEFAULT_BACKGROUND, DEFAULT_CAMERA, DEFAULT_HIGHLIGHT_COLOR, DEFAULT_HIGHLIGHT_COLOR_DARK, DEFAULT_MINIMAP_MAX_NODES, DEFAULT_STYLE, DEFAULT_TEXT_COLOR, type DeserializeOptions, type DragOriginal, type DrawTextOptions, EDGE_HANDLE_SLOP_PX, EDGE_HIT_SLOP_PX, type Edge, type EdgeEnd, type EdgeGeometry, EdgeGeometryCache, type EdgeHit, type EdgeId, type EdgeStyle, type EditorAdapter, type EditorAdapterFactory, type EditorAdapterMountOptions, type EstimateOptions, type ExportOptions, type Extension, type ExtensionApi, FONT_FAMILY_MAP, FONT_SIZE_MAP, type FontFamily, type FontSize, type FrameLoop, type FrameStats, type GetContextOptions, type Group, type GroupId, type Hit, type IconNodeData, type IdGenerator, type ImageNodeData, type InlineType, type InteractionMode, type InteractionState, LINE_HEIGHT_MAP, LINK_COLOR, type LayoutLine, type LayoutOptions, MAX_IMAGE_BYTES, MAX_SVG_BYTES, MAX_ZOOM, MIN_ZOOM, type MathBitmap, type Migrator, type MinimapContentOptions, type Node, type NodeHit, type NodeId, type NodeType, type NodeTypeDef, type NodeTypeDefOptions, type Op, type OpBatch, type OpOrigin, PALM_REJECTION_GRACE_MS, type PalmRejectionState, type PathStyle, type PointerInfo, type PresenceEvent, type PresencePatch, type PresenceSlice, type PresenceState, type PrimitiveType, RESIZE_HANDLES, RESIZE_HANDLE_SIZE_PX, ROTATE_HANDLE_OFFSET_PX, ROTATE_HANDLE_RADIUS_PX, type RenderEnv, type Renderer, type RendererOptions, type ResizeHandle, SCHEMA_VERSION, type Scene, type SceneContextJson, type SchemaVersion, type SerializedClipboard, type SerializedScene, type Side, type SnapshotEnv, type SpatialId, type SpatialQuery, type SpatialResult, type StoreEventHandler, type StoreEventName, type StoreEvents, type StoreOptions, type StrokeStyle, type Style, type StyledRun, type SvgExportOptions, type SyncAdapter, type SyncAdapterCapabilities, type TextAlign, type TextStyle, type ThemeResolver, type Token, type Transform, UniformGrid, type Unsubscribe, VERSION, type Vec2, type WorldRect, applyCameraTransform, applySvgColor, arrowheadLength, asBatchId, asClientId, asEdgeId, asGroupId, asNodeId, attachSync, autoRouteControls, blobToDataUri, clampEffectiveScale, clampZoom, clearMathCache, clearMeasureCache, clearSurface, clearTextBitmapCache, clipSamples, computeAutoFitHeight, computeEdgeGeometry, copy, createCanvasStore, createDefaultTextareaEditor, createFrameLoop, createPalmRejectionState, createRenderer, cubicBezier, cubicBezierTangent, cut, defineExtension, defineNode, deserializeClipboard, detectConflicts, downscaleImageBlob, drawArrowhead, drawEdge, drawMinimapViewport, drawShape, drawTextToCanvas, drawWithNodeTransform, edgeAABBFromSamples, edgeLabelBoundsWorld, emptyPresenceState, estimateMarkdownContentHeight, exportSelection, exportSelectionSvg, exportViewport, extractSvgDimensions, fromSerialized, fullVisibleClipResult, getCanvasFont, getContentHeight, getContext, getDpr, getFontEpoch, getMarkdownLineHeightPx, getMathBitmap, getMathCacheSize, getMathEpoch, getMathJax, getOrRenderTextBitmap, getPointAndTangentAtArcLength, getTextBitmapCacheSize, handleEnter, handleWorldPositions, hitTestAny, hitTestEdge, hitTestHandles, hitTestPoint, hitTestRotateHandle, idleInteractionState, inflateRect, insertLink, installExtension, installedExtensions, inverseBatch, inverseOp, isAttached, isCanvasHarnessClipboard, isDrawablePrimitive, isMoving, isNodeRemoteEditing, layoutTokens, makeIdGenerator, marqueeNodes, measureText, midpointToCubicControls, minimapScreenToWorld, nodeAABB, nodeIntersectsRect, nodeLocalToWorld, notePenActive, notePenInactive, onMathJaxReady, opSchemas, opSchemasAsAnthropicTools, paintBackground, panByScreen, paste, pointInNode, projectEndToWorld, projectToNodeBoundary, quantizeDpr, quantizeZoom, randomClientId, rectContainsPoint, rectFromPoints, rectsIntersect, registerMigrator, renderMinimapContent, resolveColor, resolveOpacity, resolveRenderScale, resolveStrokeWidth, rotateHandleWorldPosition, rotateVecByAngle, sampleBezier, sampleSelfLoop, samplesFor, sanitizeSvg, sceneBounds, screenToWorld, selfLoopGeometry, serializeSelection, setupSurface, shouldAutoFit, shouldRejectTouch, sideNormalLocal, sideOf, sizeSurface, storeToJSON, subscribeFontEpoch, subscribeMathEpoch, tangentAtArcLength, toImageBlob, toSerialized, toggleBold, toggleCode, toggleItalic, toggleStrike, toggleUnderline, tokenize, unionRects, validateImageInput, validateSvgMarkup, viewportWorldRect, withAutoFitHeight, worldToNodeLocal, worldToScreen, worldViewport, worldViewportFromCamera, zoomAtScreenPoint };

package/dist/index.d.ts

@@ -922,7 +922,14 @@ declare const defineNode: (opts: NodeTypeDefOptions) => NodeTypeDef;
  * nesting, no escapes — single-pass regex tokenization keeps layout
  * fast at scale. See ARCHITECTURE.md §8.
  */
-type InlineType = 'text' | 'bold' | 'italic' | 'underline' | 'strike' | 'highlight' | 'code' | 'link';
+type InlineType = 'text' | 'bold' | 'italic' | 'underline' | 'strike' | 'highlight' | 'code' | 'link'
+/**
+ * LaTeX math expression, content is the source between `$...$` (no
+ * leading/trailing whitespace, no line breaks). Rendered via MathJax
+ * SVG output and rasterized to an inline bitmap at paint time. See
+ * `text/math/`.
+ */
+ | 'math';
 type Token = {
     type: InlineType;
     content: string;
@@ -963,6 +970,12 @@ type LayoutOptions = {
     fontFamily: FontFamily;
     fontSize: FontSize;
     textStyle: TextStyle;
+    /**
+     * Used to key the math bitmap cache. Both layout (for measured dims)
+     * and paint (for the actual bitmap) need to query the same cache
+     * entry. Defaults to `#000000` for estimate-only callers.
+     */
+    textColor?: string;
 };
 /**
  * Turns tokens into drawable lines. Output consumed by the canvas paint pass.
@@ -1037,6 +1050,97 @@ declare const subscribeFontEpoch: (listener: (epoch: number) => void) => (() =>
  */
 declare const getFontEpoch: () => number;
 
+/**
+ * Lazy loader for MathJax — same pattern as `render/rough/loader.ts`.
+ *
+ * MathJax is ~600KB and only useful for scenes with LaTeX math. We
+ * defer loading until the first `$...$` token requests a compile,
+ * then convert LaTeX → SVG strings off the main rAF path.
+ *
+ * Loaded from jsDelivr CDN rather than bundled because the v4
+ * tex-svg.js bundle uses `importScripts('sre/speech-worker.js')` for
+ * accessibility; the relative URL resolves wrong when served from a
+ * dev bundler's node_modules. The CDN serves sibling files at
+ * predictable paths so the bundle finds its workers. Self-host by
+ * pointing `VENDOR_URL` at your own copy of the v4 component files.
+ *
+ * Notes:
+ *   - MathJax's `tex-svg.js` bundle attaches itself to `window.MathJax`
+ *     when loaded. This is the documented v4 browser API.
+ *   - If a consumer also uses MathJax, they should configure the
+ *     global *before* canvas-harness's first math node loads.
+ */
+type MathJaxLike = {
+    tex2svgPromise(source: string, opts?: {
+        display?: boolean;
+        em?: number;
+        ex?: number;
+        containerWidth?: number;
+    }): Promise<MathJaxSvgElement>;
+    startup: {
+        /**
+         * The "lite adaptor" used by the SVG output in browser context.
+         * `serializeXML` returns standalone-valid SVG markup with
+         * namespaces intact (which `outerHTML` does not always do).
+         */
+        adaptor: {
+            serializeXML?(el: MathJaxSvgElement): string;
+            outerHTML(el: MathJaxSvgElement): string;
+        };
+    };
+};
+/**
+ * MathJax returns a "lite element" virtual-DOM node, not a real SVG
+ * element. We only need to serialize it via the adaptor.
+ */
+type MathJaxSvgElement = unknown;
+declare global {
+    var MathJax: unknown;
+}
+/**
+ * Returns the configured MathJax instance if loaded, else `null` and
+ * triggers the lazy import on first call. Subscribers via `onMathJaxReady`
+ * are notified when the import resolves.
+ */
+declare const getMathJax: () => MathJaxLike | null;
+/**
+ * Registers a callback that fires once when MathJax becomes available.
+ * No-op if already loaded — caller should check `getMathJax() !== null`
+ * first. Used to trigger a re-paint of math-bearing text nodes.
+ */
+declare const onMathJaxReady: (cb: () => void) => void;
+
+/** Result of a successful math compile + raster. */
+type MathBitmap = {
+    bitmap: ImageBitmap;
+    /** Width in logical CSS pixels at the requested font size. */
+    width: number;
+    /** Height in logical CSS pixels at the requested font size. */
+    height: number;
+    /**
+     * Baseline offset in CSS pixels (positive = bitmap top sits ABOVE
+     * the text baseline; the bottom dips below by `height - baseline`).
+     * Parsed from MathJax's `vertical-align: -Nex` style attribute.
+     */
+    baselineOffset: number;
+};
+declare const getMathEpoch: () => number;
+declare const subscribeMathEpoch: (cb: () => void) => (() => void);
+/**
+ * Look up a math bitmap or kick off compilation. Returns the cached
+ * bitmap if ready, `null` if still loading / queued (caller should
+ * paint a placeholder this frame). Triggers a math-epoch bump when
+ * the formula resolves.
+ *
+ * `sizePx` is the on-screen height in logical px (typically the line
+ * height of the surrounding text × DPR).
+ */
+declare const getMathBitmap: (source: string, color: string, sizePx: number) => MathBitmap | null;
+/** Test / debug aid. */
+declare const clearMathCache: () => void;
+/** Test / debug aid. */
+declare const getMathCacheSize: () => number;
+
 /**
  * Buckets zoom to avoid cache churn from sub-1%-zoom changes.
  */
@@ -1495,14 +1599,21 @@ interface CanvasStore {
      * Adds a node. Returns its id. If `node.style.autoFit !== false` and
      * `node.content` is set, height is grown to fit.
      *
+     * `z` is optional — omit to land on top of the current stack (uses
+     * the internal `topZ` counter). Pass a literal value (incl. `0` or
+     * negative) to place the node at that exact z.
+     *
      * @example
+     * // Omit z → goes on top of the current stack.
      * const id = store.addNode({
      *   id: asNodeId(store.generateId()),
      *   type: 'rect', x: 0, y: 0, w: 200, h: 100,
-     *   angle: 0, z: 0, groups: [],
+     *   angle: 0, groups: [],
      * })
      */
-    addNode(node: Node): NodeId;
+    addNode(node: Omit<Node, 'z'> & {
+        z?: number;
+    }): NodeId;
     /**
      * Patches fields on an existing node. Captures the previous slice on
      * the op so undo is free. Autofit re-runs when `content` or font
@@ -1566,8 +1677,13 @@ interface CanvasStore {
         alt?: string;
         style?: Style;
     }): Promise<NodeId>;
-    /** Adds an edge. Returns its id. */
-    addEdge(edge: Edge): EdgeId;
+    /**
+     * Adds an edge. Returns its id. `z` is optional — same auto-top
+     * semantics as {@link CanvasStore.addNode}.
+     */
+    addEdge(edge: Omit<Edge, 'z'> & {
+        z?: number;
+    }): EdgeId;
     /** Patches fields on an existing edge. */
     updateEdge(id: EdgeId, patch: Partial<Edge>): void;
     /** Removes an edge. */
@@ -3252,4 +3368,4 @@ declare const installedExtensions: (store: CanvasStore) => string[];
  */
 declare const VERSION = "0.0.0";
 
-export { type AnthropicToolDef, type Arrowhead, BEZIER_SEGMENTS, type BatchId, type BitmapCacheEntry, type BitmapCacheRequest, type BuiltInNodeType, CODE_BG_COLOR, CODE_BLOCK_MARGIN_Y, CODE_BLOCK_PADDING_X, CONTENT_HEIGHT_BUFFER, CONTENT_PADDING, type CameraState, type CanvasBackground, type CanvasBackgroundPattern, type CanvasStore, type CanvasSurface, type ClientId, type ClipResult, type ConflictRecord, type ContextEdge, type ContextNode, DEFAULT_BACKGROUND, DEFAULT_CAMERA, DEFAULT_HIGHLIGHT_COLOR, DEFAULT_HIGHLIGHT_COLOR_DARK, DEFAULT_MINIMAP_MAX_NODES, DEFAULT_STYLE, DEFAULT_TEXT_COLOR, type DeserializeOptions, type DragOriginal, type DrawTextOptions, EDGE_HANDLE_SLOP_PX, EDGE_HIT_SLOP_PX, type Edge, type EdgeEnd, type EdgeGeometry, EdgeGeometryCache, type EdgeHit, type EdgeId, type EdgeStyle, type EditorAdapter, type EditorAdapterFactory, type EditorAdapterMountOptions, type EstimateOptions, type ExportOptions, type Extension, type ExtensionApi, FONT_FAMILY_MAP, FONT_SIZE_MAP, type FontFamily, type FontSize, type FrameLoop, type FrameStats, type GetContextOptions, type Group, type GroupId, type Hit, type IconNodeData, type IdGenerator, type ImageNodeData, type InlineType, type InteractionMode, type InteractionState, LINE_HEIGHT_MAP, LINK_COLOR, type LayoutLine, type LayoutOptions, MAX_IMAGE_BYTES, MAX_SVG_BYTES, MAX_ZOOM, MIN_ZOOM, type Migrator, type MinimapContentOptions, type Node, type NodeHit, type NodeId, type NodeType, type NodeTypeDef, type NodeTypeDefOptions, type Op, type OpBatch, type OpOrigin, PALM_REJECTION_GRACE_MS, type PalmRejectionState, type PathStyle, type PointerInfo, type PresenceEvent, type PresencePatch, type PresenceSlice, type PresenceState, type PrimitiveType, RESIZE_HANDLES, RESIZE_HANDLE_SIZE_PX, ROTATE_HANDLE_OFFSET_PX, ROTATE_HANDLE_RADIUS_PX, type RenderEnv, type Renderer, type RendererOptions, type ResizeHandle, SCHEMA_VERSION, type Scene, type SceneContextJson, type SchemaVersion, type SerializedClipboard, type SerializedScene, type Side, type SnapshotEnv, type SpatialId, type SpatialQuery, type SpatialResult, type StoreEventHandler, type StoreEventName, type StoreEvents, type StoreOptions, type StrokeStyle, type Style, type StyledRun, type SvgExportOptions, type SyncAdapter, type SyncAdapterCapabilities, type TextAlign, type TextStyle, type ThemeResolver, type Token, type Transform, UniformGrid, type Unsubscribe, VERSION, type Vec2, type WorldRect, applyCameraTransform, applySvgColor, arrowheadLength, asBatchId, asClientId, asEdgeId, asGroupId, asNodeId, attachSync, autoRouteControls, blobToDataUri, clampEffectiveScale, clampZoom, clearMeasureCache, clearSurface, clearTextBitmapCache, clipSamples, computeAutoFitHeight, computeEdgeGeometry, copy, createCanvasStore, createDefaultTextareaEditor, createFrameLoop, createPalmRejectionState, createRenderer, cubicBezier, cubicBezierTangent, cut, defineExtension, defineNode, deserializeClipboard, detectConflicts, downscaleImageBlob, drawArrowhead, drawEdge, drawMinimapViewport, drawShape, drawTextToCanvas, drawWithNodeTransform, edgeAABBFromSamples, edgeLabelBoundsWorld, emptyPresenceState, estimateMarkdownContentHeight, exportSelection, exportSelectionSvg, exportViewport, extractSvgDimensions, fromSerialized, fullVisibleClipResult, getCanvasFont, getContentHeight, getContext, getDpr, getFontEpoch, getMarkdownLineHeightPx, getOrRenderTextBitmap, getPointAndTangentAtArcLength, getTextBitmapCacheSize, handleEnter, handleWorldPositions, hitTestAny, hitTestEdge, hitTestHandles, hitTestPoint, hitTestRotateHandle, idleInteractionState, inflateRect, insertLink, installExtension, installedExtensions, inverseBatch, inverseOp, isAttached, isCanvasHarnessClipboard, isDrawablePrimitive, isMoving, isNodeRemoteEditing, layoutTokens, makeIdGenerator, marqueeNodes, measureText, midpointToCubicControls, minimapScreenToWorld, nodeAABB, nodeIntersectsRect, nodeLocalToWorld, notePenActive, notePenInactive, opSchemas, opSchemasAsAnthropicTools, paintBackground, panByScreen, paste, pointInNode, projectEndToWorld, projectToNodeBoundary, quantizeDpr, quantizeZoom, randomClientId, rectContainsPoint, rectFromPoints, rectsIntersect, registerMigrator, renderMinimapContent, resolveColor, resolveOpacity, resolveRenderScale, resolveStrokeWidth, rotateHandleWorldPosition, rotateVecByAngle, sampleBezier, sampleSelfLoop, samplesFor, sanitizeSvg, sceneBounds, screenToWorld, selfLoopGeometry, serializeSelection, setupSurface, shouldAutoFit, shouldRejectTouch, sideNormalLocal, sideOf, sizeSurface, storeToJSON, subscribeFontEpoch, tangentAtArcLength, toImageBlob, toSerialized, toggleBold, toggleCode, toggleItalic, toggleStrike, toggleUnderline, tokenize, unionRects, validateImageInput, validateSvgMarkup, viewportWorldRect, withAutoFitHeight, worldToNodeLocal, worldToScreen, worldViewport, worldViewportFromCamera, zoomAtScreenPoint };
+export { type AnthropicToolDef, type Arrowhead, BEZIER_SEGMENTS, type BatchId, type BitmapCacheEntry, type BitmapCacheRequest, type BuiltInNodeType, CODE_BG_COLOR, CODE_BLOCK_MARGIN_Y, CODE_BLOCK_PADDING_X, CONTENT_HEIGHT_BUFFER, CONTENT_PADDING, type CameraState, type CanvasBackground, type CanvasBackgroundPattern, type CanvasStore, type CanvasSurface, type ClientId, type ClipResult, type ConflictRecord, type ContextEdge, type ContextNode, DEFAULT_BACKGROUND, DEFAULT_CAMERA, DEFAULT_HIGHLIGHT_COLOR, DEFAULT_HIGHLIGHT_COLOR_DARK, DEFAULT_MINIMAP_MAX_NODES, DEFAULT_STYLE, DEFAULT_TEXT_COLOR, type DeserializeOptions, type DragOriginal, type DrawTextOptions, EDGE_HANDLE_SLOP_PX, EDGE_HIT_SLOP_PX, type Edge, type EdgeEnd, type EdgeGeometry, EdgeGeometryCache, type EdgeHit, type EdgeId, type EdgeStyle, type EditorAdapter, type EditorAdapterFactory, type EditorAdapterMountOptions, type EstimateOptions, type ExportOptions, type Extension, type ExtensionApi, FONT_FAMILY_MAP, FONT_SIZE_MAP, type FontFamily, type FontSize, type FrameLoop, type FrameStats, type GetContextOptions, type Group, type GroupId, type Hit, type IconNodeData, type IdGenerator, type ImageNodeData, type InlineType, type InteractionMode, type InteractionState, LINE_HEIGHT_MAP, LINK_COLOR, type LayoutLine, type LayoutOptions, MAX_IMAGE_BYTES, MAX_SVG_BYTES, MAX_ZOOM, MIN_ZOOM, type MathBitmap, type Migrator, type MinimapContentOptions, type Node, type NodeHit, type NodeId, type NodeType, type NodeTypeDef, type NodeTypeDefOptions, type Op, type OpBatch, type OpOrigin, PALM_REJECTION_GRACE_MS, type PalmRejectionState, type PathStyle, type PointerInfo, type PresenceEvent, type PresencePatch, type PresenceSlice, type PresenceState, type PrimitiveType, RESIZE_HANDLES, RESIZE_HANDLE_SIZE_PX, ROTATE_HANDLE_OFFSET_PX, ROTATE_HANDLE_RADIUS_PX, type RenderEnv, type Renderer, type RendererOptions, type ResizeHandle, SCHEMA_VERSION, type Scene, type SceneContextJson, type SchemaVersion, type SerializedClipboard, type SerializedScene, type Side, type SnapshotEnv, type SpatialId, type SpatialQuery, type SpatialResult, type StoreEventHandler, type StoreEventName, type StoreEvents, type StoreOptions, type StrokeStyle, type Style, type StyledRun, type SvgExportOptions, type SyncAdapter, type SyncAdapterCapabilities, type TextAlign, type TextStyle, type ThemeResolver, type Token, type Transform, UniformGrid, type Unsubscribe, VERSION, type Vec2, type WorldRect, applyCameraTransform, applySvgColor, arrowheadLength, asBatchId, asClientId, asEdgeId, asGroupId, asNodeId, attachSync, autoRouteControls, blobToDataUri, clampEffectiveScale, clampZoom, clearMathCache, clearMeasureCache, clearSurface, clearTextBitmapCache, clipSamples, computeAutoFitHeight, computeEdgeGeometry, copy, createCanvasStore, createDefaultTextareaEditor, createFrameLoop, createPalmRejectionState, createRenderer, cubicBezier, cubicBezierTangent, cut, defineExtension, defineNode, deserializeClipboard, detectConflicts, downscaleImageBlob, drawArrowhead, drawEdge, drawMinimapViewport, drawShape, drawTextToCanvas, drawWithNodeTransform, edgeAABBFromSamples, edgeLabelBoundsWorld, emptyPresenceState, estimateMarkdownContentHeight, exportSelection, exportSelectionSvg, exportViewport, extractSvgDimensions, fromSerialized, fullVisibleClipResult, getCanvasFont, getContentHeight, getContext, getDpr, getFontEpoch, getMarkdownLineHeightPx, getMathBitmap, getMathCacheSize, getMathEpoch, getMathJax, getOrRenderTextBitmap, getPointAndTangentAtArcLength, getTextBitmapCacheSize, handleEnter, handleWorldPositions, hitTestAny, hitTestEdge, hitTestHandles, hitTestPoint, hitTestRotateHandle, idleInteractionState, inflateRect, insertLink, installExtension, installedExtensions, inverseBatch, inverseOp, isAttached, isCanvasHarnessClipboard, isDrawablePrimitive, isMoving, isNodeRemoteEditing, layoutTokens, makeIdGenerator, marqueeNodes, measureText, midpointToCubicControls, minimapScreenToWorld, nodeAABB, nodeIntersectsRect, nodeLocalToWorld, notePenActive, notePenInactive, onMathJaxReady, opSchemas, opSchemasAsAnthropicTools, paintBackground, panByScreen, paste, pointInNode, projectEndToWorld, projectToNodeBoundary, quantizeDpr, quantizeZoom, randomClientId, rectContainsPoint, rectFromPoints, rectsIntersect, registerMigrator, renderMinimapContent, resolveColor, resolveOpacity, resolveRenderScale, resolveStrokeWidth, rotateHandleWorldPosition, rotateVecByAngle, sampleBezier, sampleSelfLoop, samplesFor, sanitizeSvg, sceneBounds, screenToWorld, selfLoopGeometry, serializeSelection, setupSurface, shouldAutoFit, shouldRejectTouch, sideNormalLocal, sideOf, sizeSurface, storeToJSON, subscribeFontEpoch, subscribeMathEpoch, tangentAtArcLength, toImageBlob, toSerialized, toggleBold, toggleCode, toggleItalic, toggleStrike, toggleUnderline, tokenize, unionRects, validateImageInput, validateSvgMarkup, viewportWorldRect, withAutoFitHeight, worldToNodeLocal, worldToScreen, worldViewport, worldViewportFromCamera, zoomAtScreenPoint };