@canvas-harness/core 0.0.0 → 0.0.2

package/dist/index.d.cts

@@ -71,6 +71,13 @@ type Style = {
      * per-keystroke).
      */
     autoFit?: boolean;
+    /**
+     * Color applied to SVG icons (`node.type === 'icon'`) — substitutes
+     * every `currentColor` occurrence in the SVG markup before
+     * rasterizing. The rasterizer caches by `(markup, iconColor, size)`
+     * so changing this re-keys without invalidating other variants.
+     */
+    iconColor?: string;
 };
 type EdgeStyle = Style & {
     sourceArrowhead?: Arrowhead;
@@ -126,6 +133,28 @@ type Node = {
     style?: Style;
     data?: unknown;
 };
+/**
+ * `node.data` shape for `node.type === 'image'`. `src` is a self-
+ * contained data URI (we don't accept external URLs to keep scenes
+ * portable + CORS-free). `naturalW` / `naturalH` are the post-downscale
+ * dimensions used for aspect-ratio preservation on resize.
+ */
+type ImageNodeData = {
+    src: string;
+    naturalW: number;
+    naturalH: number;
+    alt?: string;
+};
+/**
+ * `node.data` shape for `node.type === 'icon'`. `src` is sanitized
+ * SVG markup (scripts + event handlers stripped at add time). The
+ * recolor knob lives on `style.iconColor`, not here, so theming
+ * flows through the same channel as other style tokens.
+ */
+type IconNodeData = {
+    src: string;
+    alt?: string;
+};
 
 type PathStyle = 'straight' | 'bezier' | 'polyline';
 /**
@@ -1475,6 +1504,55 @@ interface CanvasStore {
      * batch (so one undo restores the node + every edge that pointed to it).
      */
     removeNode(id: NodeId): void;
+    /**
+     * Adds a raster image node. Async because the input may need decoding
+     * + downscaling before storage. Accepts `File` / `Blob` / data URI;
+     * external URLs are rejected to keep scenes self-contained.
+     *
+     * PNG and JPEG only; up to 2 MB. Larger sources throw immediately
+     * (caller should surface the error in UI).
+     *
+     * `w` / `h` default to the natural dimensions clamped to 400 px on
+     * the longer side. Aspect ratio is preserved by default; the resize
+     * gesture locks aspect for image nodes (shift to override).
+     *
+     * @example
+     * const id = await store.addImage({ src: file, x: 100, y: 100 })
+     */
+    addImage(opts: {
+        src: File | Blob | string;
+        x: number;
+        y: number;
+        w?: number;
+        h?: number;
+        /** Longest-side cap after downscale. Default 2048. 0 disables. */
+        maxDimension?: number;
+        alt?: string;
+        style?: Style;
+    }): Promise<NodeId>;
+    /**
+     * Adds an SVG icon node. Markup is sanitized at add time (scripts +
+     * event handlers stripped) and stored on `node.data.src`. The
+     * `iconColor` style token substitutes `currentColor` at rasterize
+     * time so the same SVG renders in multiple tints without re-storage.
+     *
+     * `w` / `h` default to the SVG's intrinsic size (width/height attrs
+     * or viewBox); falls back to 24×24 if neither is present. Aspect
+     * ratio is locked on resize by default.
+     *
+     * @example
+     * const id = await store.addSvg({ src: '<svg ...>', x: 0, y: 0, color: '#3b82f6' })
+     */
+    addSvg(opts: {
+        src: string;
+        x: number;
+        y: number;
+        w?: number;
+        h?: number;
+        color?: string;
+        alt?: string;
+        style?: Style;
+    }): Promise<NodeId>;
     /** Adds an edge. Returns its id. */
     addEdge(edge: Edge): EdgeId;
     /** Patches fields on an existing edge. */
@@ -1944,6 +2022,16 @@ type RendererOptions = {
      * the synced scene). Update at runtime via `Renderer.setBackground`.
      */
     background?: CanvasBackground;
+    /**
+     * Color for all selection chrome: selection outlines, resize +
+     * rotate handles, edge endpoint + midpoint handles, marquee rect,
+     * and the drag-create preview. Defaults to `#3b82f6` (the standard
+     * canvas-app blue). Update at runtime via `Renderer.setSelectionColor`.
+     *
+     * Accepts any CSS color literal (hex, rgb(), named). The marquee
+     * fill tints via globalAlpha — no parsing needed.
+     */
+    selectionColor?: string;
     /**
      * Fires when the set of custom nodes that should be rendered in the DOM
      * overlay changes. Consumers use this to mount/unmount React subtrees
@@ -1965,6 +2053,8 @@ type Renderer = {
     setSize(cssW: number, cssH: number): void;
     /** Update the page background / pattern. Triggers a static repaint. */
     setBackground(bg: CanvasBackground | undefined): void;
+    /** Update the selection chrome color. Triggers an interactive repaint. */
+    setSelectionColor(color: string): void;
     /** Per-frame timing (FPS, lastMs, avgMs, frames). */
     stats(): FrameStats;
     /** Number of items the most recent paint actually drew. */
@@ -2946,6 +3036,102 @@ type AnthropicToolDef = {
  */
 declare const opSchemasAsAnthropicTools: () => AnthropicToolDef[];
 
+/**
+ * Raster image utilities used by `store.addImage` and the renderer's
+ * asset cache.
+ *
+ * Inputs accepted: `File`, `Blob`, or a `data:image/(png|jpeg)` URI.
+ * External URLs are rejected — scenes must be self-contained (no
+ * out-of-document references, no CORS surprises).
+ *
+ * Anything larger than `MAX_IMAGE_BYTES` or not PNG/JPEG is rejected
+ * up front with a clear error so consumers can show a useful message.
+ */
+declare const MAX_IMAGE_BYTES: number;
+/**
+ * Validates that the input is a PNG/JPEG within the size cap. Throws
+ * on rejection — meant for the synchronous prologue of an async
+ * `addImage` call so consumers see the failure immediately, not after
+ * an in-flight load.
+ */
+declare const validateImageInput: (input: File | Blob | string) => void;
+/** Normalize any accepted `addImage` input to a `Blob`. */
+declare const toImageBlob: (input: File | Blob | string) => Promise<Blob>;
+/**
+ * Downscales a blob's image if its longer side exceeds `maxDim`. Returns
+ * the original blob unchanged when no downscale is needed. The output
+ * MIME mirrors the input (PNG stays PNG to preserve alpha; JPEG stays
+ * JPEG with q=0.9).
+ *
+ * `maxDim <= 0` disables downscaling entirely — useful when the caller
+ * wants the original bytes (e.g. they're going to do their own
+ * processing or they need full fidelity).
+ */
+declare const downscaleImageBlob: (blob: Blob, maxDim: number) => Promise<{
+    blob: Blob;
+    naturalW: number;
+    naturalH: number;
+}>;
+/**
+ * Encodes a blob as a `data:` URI. The store persists this string on
+ * `node.data.src` so the node round-trips through serialize/restore
+ * without needing an external asset store.
+ */
+declare const blobToDataUri: (blob: Blob) => Promise<string>;
+
+/**
+ * SVG utilities used by `store.addSvg` and the renderer's asset cache.
+ *
+ * SVG is XML — it can carry `<script>` tags, `on*` event handlers, and
+ * `javascript:` hrefs that execute when the markup is inlined into the
+ * DOM. We rasterize SVGs (so the DOM is never asked to live-render
+ * them as elements), but a defense-in-depth sanitize still runs since
+ * the rasterization itself goes through `<img src=blob:>` and a stray
+ * embedded `<foreignObject>` could host arbitrary HTML.
+ */
+declare const MAX_SVG_BYTES: number;
+/**
+ * Cheap "is this plausibly SVG markup?" check + size cap. Throws on
+ * rejection so consumers see the error immediately.
+ */
+declare const validateSvgMarkup: (markup: string) => void;
+/**
+ * Removes attack surfaces from SVG markup:
+ *   - `<script>` and `<foreignObject>` elements entirely
+ *   - `on*` event-handler attributes
+ *   - `href` / `xlink:href` / `src` attributes whose value starts with
+ *     `javascript:` (case-insensitive)
+ *   - External entity references (`<!DOCTYPE` / `<!ENTITY`) by parsing
+ *     in SVG mode (DOMParser ignores DTDs in SVG context)
+ *
+ * Returns the cleaned markup. Throws if the parser can't make sense
+ * of the input.
+ */
+declare const sanitizeSvg: (markup: string) => string;
+/**
+ * Resolves intended display dimensions for an SVG. Order of preference:
+ *   1. explicit `width` + `height` attributes (numeric, units stripped)
+ *   2. `viewBox` width/height
+ *   3. fallback 24×24
+ *
+ * The result is the SVG's "natural size" — what `addSvg` uses as the
+ * default node dimensions when caller omits `w`/`h`.
+ */
+declare const extractSvgDimensions: (markup: string) => {
+    w: number;
+    h: number;
+};
+/**
+ * Substitutes every `currentColor` occurrence in the markup with the
+ * given color literal. Case-insensitive. Used by the rasterizer cache
+ * to bake the icon's tint into the rendered bitmap.
+ *
+ * Single-color recoloring covers ~95% of real icon libraries (Lucide,
+ * Heroicons, Phosphor, Tabler, etc.) which are designed monochromatic.
+ * Two-tone icons can pre-color their markup and skip this step.
+ */
+declare const applySvgColor: (markup: string, color: string) => string;
+
 /**
  * Extension system — see ARCHITECTURE.md §13.9.
  *
@@ -2974,8 +3160,14 @@ type Extension = {
      * Called when the extension is installed. May return a cleanup
      * function that runs on uninstall (in addition to auto-unsubscribed
      * listeners registered via `api.on`).
+     *
+     * `void` in the union is deliberate — extensions whose installer
+     * does its work via `api.on` (auto-cleaned-up) don't need to return
+     * anything. `undefined | (() => void)` would require an explicit
+     * `return undefined`, which is noise. Biome's noConfusingVoidType
+     * fires on this pattern; the suppression below is intentional.
      */
-    onInstall(api: ExtensionApi): undefined | (() => void);
+    onInstall(api: ExtensionApi): void | (() => void);
 };
 /**
  * Defines an extension. Pure identity — exists for symmetry with
@@ -3021,4 +3213,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 IdGenerator, type InlineType, type InteractionMode, type InteractionState, LINE_HEIGHT_MAP, LINK_COLOR, type LayoutLine, type LayoutOptions, 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, arrowheadLength, asBatchId, asClientId, asEdgeId, asGroupId, asNodeId, attachSync, autoRouteControls, clampEffectiveScale, clampZoom, clearMeasureCache, clearSurface, clearTextBitmapCache, clipSamples, computeAutoFitHeight, computeEdgeGeometry, copy, createCanvasStore, createDefaultTextareaEditor, createFrameLoop, createPalmRejectionState, createRenderer, cubicBezier, cubicBezierTangent, cut, defineExtension, defineNode, deserializeClipboard, detectConflicts, drawArrowhead, drawEdge, drawMinimapViewport, drawShape, drawTextToCanvas, drawWithNodeTransform, edgeAABBFromSamples, edgeLabelBoundsWorld, emptyPresenceState, estimateMarkdownContentHeight, exportSelection, exportSelectionSvg, exportViewport, 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, sceneBounds, screenToWorld, selfLoopGeometry, serializeSelection, setupSurface, shouldAutoFit, shouldRejectTouch, sideNormalLocal, sideOf, sizeSurface, storeToJSON, subscribeFontEpoch, tangentAtArcLength, toSerialized, toggleBold, toggleCode, toggleItalic, toggleStrike, toggleUnderline, tokenize, unionRects, 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 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 };

package/dist/index.d.ts

@@ -71,6 +71,13 @@ type Style = {
      * per-keystroke).
      */
     autoFit?: boolean;
+    /**
+     * Color applied to SVG icons (`node.type === 'icon'`) — substitutes
+     * every `currentColor` occurrence in the SVG markup before
+     * rasterizing. The rasterizer caches by `(markup, iconColor, size)`
+     * so changing this re-keys without invalidating other variants.
+     */
+    iconColor?: string;
 };
 type EdgeStyle = Style & {
     sourceArrowhead?: Arrowhead;
@@ -126,6 +133,28 @@ type Node = {
     style?: Style;
     data?: unknown;
 };
+/**
+ * `node.data` shape for `node.type === 'image'`. `src` is a self-
+ * contained data URI (we don't accept external URLs to keep scenes
+ * portable + CORS-free). `naturalW` / `naturalH` are the post-downscale
+ * dimensions used for aspect-ratio preservation on resize.
+ */
+type ImageNodeData = {
+    src: string;
+    naturalW: number;
+    naturalH: number;
+    alt?: string;
+};
+/**
+ * `node.data` shape for `node.type === 'icon'`. `src` is sanitized
+ * SVG markup (scripts + event handlers stripped at add time). The
+ * recolor knob lives on `style.iconColor`, not here, so theming
+ * flows through the same channel as other style tokens.
+ */
+type IconNodeData = {
+    src: string;
+    alt?: string;
+};
 
 type PathStyle = 'straight' | 'bezier' | 'polyline';
 /**
@@ -1475,6 +1504,55 @@ interface CanvasStore {
      * batch (so one undo restores the node + every edge that pointed to it).
      */
     removeNode(id: NodeId): void;
+    /**
+     * Adds a raster image node. Async because the input may need decoding
+     * + downscaling before storage. Accepts `File` / `Blob` / data URI;
+     * external URLs are rejected to keep scenes self-contained.
+     *
+     * PNG and JPEG only; up to 2 MB. Larger sources throw immediately
+     * (caller should surface the error in UI).
+     *
+     * `w` / `h` default to the natural dimensions clamped to 400 px on
+     * the longer side. Aspect ratio is preserved by default; the resize
+     * gesture locks aspect for image nodes (shift to override).
+     *
+     * @example
+     * const id = await store.addImage({ src: file, x: 100, y: 100 })
+     */
+    addImage(opts: {
+        src: File | Blob | string;
+        x: number;
+        y: number;
+        w?: number;
+        h?: number;
+        /** Longest-side cap after downscale. Default 2048. 0 disables. */
+        maxDimension?: number;
+        alt?: string;
+        style?: Style;
+    }): Promise<NodeId>;
+    /**
+     * Adds an SVG icon node. Markup is sanitized at add time (scripts +
+     * event handlers stripped) and stored on `node.data.src`. The
+     * `iconColor` style token substitutes `currentColor` at rasterize
+     * time so the same SVG renders in multiple tints without re-storage.
+     *
+     * `w` / `h` default to the SVG's intrinsic size (width/height attrs
+     * or viewBox); falls back to 24×24 if neither is present. Aspect
+     * ratio is locked on resize by default.
+     *
+     * @example
+     * const id = await store.addSvg({ src: '<svg ...>', x: 0, y: 0, color: '#3b82f6' })
+     */
+    addSvg(opts: {
+        src: string;
+        x: number;
+        y: number;
+        w?: number;
+        h?: number;
+        color?: string;
+        alt?: string;
+        style?: Style;
+    }): Promise<NodeId>;
     /** Adds an edge. Returns its id. */
     addEdge(edge: Edge): EdgeId;
     /** Patches fields on an existing edge. */
@@ -1944,6 +2022,16 @@ type RendererOptions = {
      * the synced scene). Update at runtime via `Renderer.setBackground`.
      */
     background?: CanvasBackground;
+    /**
+     * Color for all selection chrome: selection outlines, resize +
+     * rotate handles, edge endpoint + midpoint handles, marquee rect,
+     * and the drag-create preview. Defaults to `#3b82f6` (the standard
+     * canvas-app blue). Update at runtime via `Renderer.setSelectionColor`.
+     *
+     * Accepts any CSS color literal (hex, rgb(), named). The marquee
+     * fill tints via globalAlpha — no parsing needed.
+     */
+    selectionColor?: string;
     /**
      * Fires when the set of custom nodes that should be rendered in the DOM
      * overlay changes. Consumers use this to mount/unmount React subtrees
@@ -1965,6 +2053,8 @@ type Renderer = {
     setSize(cssW: number, cssH: number): void;
     /** Update the page background / pattern. Triggers a static repaint. */
     setBackground(bg: CanvasBackground | undefined): void;
+    /** Update the selection chrome color. Triggers an interactive repaint. */
+    setSelectionColor(color: string): void;
     /** Per-frame timing (FPS, lastMs, avgMs, frames). */
     stats(): FrameStats;
     /** Number of items the most recent paint actually drew. */
@@ -2946,6 +3036,102 @@ type AnthropicToolDef = {
  */
 declare const opSchemasAsAnthropicTools: () => AnthropicToolDef[];
 
+/**
+ * Raster image utilities used by `store.addImage` and the renderer's
+ * asset cache.
+ *
+ * Inputs accepted: `File`, `Blob`, or a `data:image/(png|jpeg)` URI.
+ * External URLs are rejected — scenes must be self-contained (no
+ * out-of-document references, no CORS surprises).
+ *
+ * Anything larger than `MAX_IMAGE_BYTES` or not PNG/JPEG is rejected
+ * up front with a clear error so consumers can show a useful message.
+ */
+declare const MAX_IMAGE_BYTES: number;
+/**
+ * Validates that the input is a PNG/JPEG within the size cap. Throws
+ * on rejection — meant for the synchronous prologue of an async
+ * `addImage` call so consumers see the failure immediately, not after
+ * an in-flight load.
+ */
+declare const validateImageInput: (input: File | Blob | string) => void;
+/** Normalize any accepted `addImage` input to a `Blob`. */
+declare const toImageBlob: (input: File | Blob | string) => Promise<Blob>;
+/**
+ * Downscales a blob's image if its longer side exceeds `maxDim`. Returns
+ * the original blob unchanged when no downscale is needed. The output
+ * MIME mirrors the input (PNG stays PNG to preserve alpha; JPEG stays
+ * JPEG with q=0.9).
+ *
+ * `maxDim <= 0` disables downscaling entirely — useful when the caller
+ * wants the original bytes (e.g. they're going to do their own
+ * processing or they need full fidelity).
+ */
+declare const downscaleImageBlob: (blob: Blob, maxDim: number) => Promise<{
+    blob: Blob;
+    naturalW: number;
+    naturalH: number;
+}>;
+/**
+ * Encodes a blob as a `data:` URI. The store persists this string on
+ * `node.data.src` so the node round-trips through serialize/restore
+ * without needing an external asset store.
+ */
+declare const blobToDataUri: (blob: Blob) => Promise<string>;
+
+/**
+ * SVG utilities used by `store.addSvg` and the renderer's asset cache.
+ *
+ * SVG is XML — it can carry `<script>` tags, `on*` event handlers, and
+ * `javascript:` hrefs that execute when the markup is inlined into the
+ * DOM. We rasterize SVGs (so the DOM is never asked to live-render
+ * them as elements), but a defense-in-depth sanitize still runs since
+ * the rasterization itself goes through `<img src=blob:>` and a stray
+ * embedded `<foreignObject>` could host arbitrary HTML.
+ */
+declare const MAX_SVG_BYTES: number;
+/**
+ * Cheap "is this plausibly SVG markup?" check + size cap. Throws on
+ * rejection so consumers see the error immediately.
+ */
+declare const validateSvgMarkup: (markup: string) => void;
+/**
+ * Removes attack surfaces from SVG markup:
+ *   - `<script>` and `<foreignObject>` elements entirely
+ *   - `on*` event-handler attributes
+ *   - `href` / `xlink:href` / `src` attributes whose value starts with
+ *     `javascript:` (case-insensitive)
+ *   - External entity references (`<!DOCTYPE` / `<!ENTITY`) by parsing
+ *     in SVG mode (DOMParser ignores DTDs in SVG context)
+ *
+ * Returns the cleaned markup. Throws if the parser can't make sense
+ * of the input.
+ */
+declare const sanitizeSvg: (markup: string) => string;
+/**
+ * Resolves intended display dimensions for an SVG. Order of preference:
+ *   1. explicit `width` + `height` attributes (numeric, units stripped)
+ *   2. `viewBox` width/height
+ *   3. fallback 24×24
+ *
+ * The result is the SVG's "natural size" — what `addSvg` uses as the
+ * default node dimensions when caller omits `w`/`h`.
+ */
+declare const extractSvgDimensions: (markup: string) => {
+    w: number;
+    h: number;
+};
+/**
+ * Substitutes every `currentColor` occurrence in the markup with the
+ * given color literal. Case-insensitive. Used by the rasterizer cache
+ * to bake the icon's tint into the rendered bitmap.
+ *
+ * Single-color recoloring covers ~95% of real icon libraries (Lucide,
+ * Heroicons, Phosphor, Tabler, etc.) which are designed monochromatic.
+ * Two-tone icons can pre-color their markup and skip this step.
+ */
+declare const applySvgColor: (markup: string, color: string) => string;
+
 /**
  * Extension system — see ARCHITECTURE.md §13.9.
  *
@@ -2974,8 +3160,14 @@ type Extension = {
      * Called when the extension is installed. May return a cleanup
      * function that runs on uninstall (in addition to auto-unsubscribed
      * listeners registered via `api.on`).
+     *
+     * `void` in the union is deliberate — extensions whose installer
+     * does its work via `api.on` (auto-cleaned-up) don't need to return
+     * anything. `undefined | (() => void)` would require an explicit
+     * `return undefined`, which is noise. Biome's noConfusingVoidType
+     * fires on this pattern; the suppression below is intentional.
      */
-    onInstall(api: ExtensionApi): undefined | (() => void);
+    onInstall(api: ExtensionApi): void | (() => void);
 };
 /**
  * Defines an extension. Pure identity — exists for symmetry with
@@ -3021,4 +3213,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 IdGenerator, type InlineType, type InteractionMode, type InteractionState, LINE_HEIGHT_MAP, LINK_COLOR, type LayoutLine, type LayoutOptions, 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, arrowheadLength, asBatchId, asClientId, asEdgeId, asGroupId, asNodeId, attachSync, autoRouteControls, clampEffectiveScale, clampZoom, clearMeasureCache, clearSurface, clearTextBitmapCache, clipSamples, computeAutoFitHeight, computeEdgeGeometry, copy, createCanvasStore, createDefaultTextareaEditor, createFrameLoop, createPalmRejectionState, createRenderer, cubicBezier, cubicBezierTangent, cut, defineExtension, defineNode, deserializeClipboard, detectConflicts, drawArrowhead, drawEdge, drawMinimapViewport, drawShape, drawTextToCanvas, drawWithNodeTransform, edgeAABBFromSamples, edgeLabelBoundsWorld, emptyPresenceState, estimateMarkdownContentHeight, exportSelection, exportSelectionSvg, exportViewport, 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, sceneBounds, screenToWorld, selfLoopGeometry, serializeSelection, setupSurface, shouldAutoFit, shouldRejectTouch, sideNormalLocal, sideOf, sizeSurface, storeToJSON, subscribeFontEpoch, tangentAtArcLength, toSerialized, toggleBold, toggleCode, toggleItalic, toggleStrike, toggleUnderline, tokenize, unionRects, 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 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 };