@canvas-harness/core 0.0.0

package/dist/index.d.ts

@@ -0,0 +1,3024 @@
+/**
+ * Branded ID types so node/edge/group ids never accidentally cross.
+ */
+type NodeId = string & {
+    readonly __brand: 'NodeId';
+};
+type EdgeId = string & {
+    readonly __brand: 'EdgeId';
+};
+type GroupId = string & {
+    readonly __brand: 'GroupId';
+};
+type ClientId = string & {
+    readonly __brand: 'ClientId';
+};
+type BatchId = string & {
+    readonly __brand: 'BatchId';
+};
+declare const asNodeId: (s: string) => NodeId;
+declare const asEdgeId: (s: string) => EdgeId;
+declare const asGroupId: (s: string) => GroupId;
+declare const asClientId: (s: string) => ClientId;
+declare const asBatchId: (s: string) => BatchId;
+/**
+ * A point in world coordinates.
+ */
+type Vec2 = {
+    x: number;
+    y: number;
+};
+/**
+ * An axis-aligned rectangle in world coordinates.
+ * x/y is the top-left; w/h extend toward +x/+y.
+ */
+type WorldRect = {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+};
+declare const SCHEMA_VERSION: 1;
+type SchemaVersion = typeof SCHEMA_VERSION;
+
+/**
+ * Style tokens — see ARCHITECTURE.md §3.4. All fields optional;
+ * missing values fall back to theme resolver, then built-in defaults.
+ */
+type StrokeStyle = 'solid' | 'dashed' | 'dotted';
+type FontFamily = 'handwriting' | 'sans-serif' | 'serif' | 'monospace' | 'informal';
+type FontSize = 'S' | 'M' | 'L' | 'XL';
+type TextAlign = 'left' | 'center' | 'right';
+type TextStyle = 'normal' | 'bold' | 'italic';
+type Arrowhead = 'none' | 'arrow' | 'barb' | 'arrow-filled';
+type Style = {
+    strokeColor?: string;
+    strokeWidth?: number;
+    strokeStyle?: StrokeStyle;
+    backgroundColor?: string;
+    roughness?: number;
+    roundness?: number;
+    opacity?: number;
+    fontFamily?: FontFamily;
+    fontSize?: FontSize;
+    textAlign?: TextAlign;
+    textColor?: string;
+    textStyle?: TextStyle;
+    /**
+     * When true, the node's height auto-adjusts to fit `content` on add /
+     * edit-commit / resize-commit. Defaults to true for any node type.
+     * See ARCHITECTURE.md §8 (autofit lives on commit boundaries, never
+     * per-keystroke).
+     */
+    autoFit?: boolean;
+};
+type EdgeStyle = Style & {
+    sourceArrowhead?: Arrowhead;
+    targetArrowhead?: Arrowhead;
+    /**
+     * Position of `edge.content` (the edge label) along the polyline,
+     * expressed as arc-length `[0..1]`. Default `0.5` (midpoint).
+     */
+    labelArcLength?: number;
+    /**
+     * When true, the label rotates to follow the tangent of the edge at
+     * its anchor. Default false — labels stay upright. See
+     * ARCHITECTURE.md §6.11.
+     */
+    labelFollowsTangent?: boolean;
+    /**
+     * Background color of the edge-label chip. `'transparent'` or
+     * `'none'` skips the chip entirely (text renders directly on the
+     * edge). Falls through to `theme('edge.label.background')` if unset,
+     * then to white. Per-edge override of the theme default.
+     */
+    labelBackground?: string;
+};
+
+/**
+ * Built-in node types — see ARCHITECTURE.md §3.5.
+ * Custom node types are arbitrary strings registered via defineNode.
+ */
+type BuiltInNodeType = 'rect' | 'ellipse' | 'diamond' | 'tag' | 'capsule' | 'thought-cloud' | 'layered-rect' | 'layered-ellipse' | 'layered-diamond' | 'text' | 'image' | 'icon' | 'frame';
+type NodeType = BuiltInNodeType | (string & {
+    readonly __nodeType?: never;
+});
+/**
+ * Scene node — see ARCHITECTURE.md §3.2.
+ *
+ * Coordinates are top-left world coords pre-rotation; `angle` is radians
+ * around node center. `content` is lite-markdown for text-bearing built-in
+ * shapes; `data` is type-specific payload for everything else.
+ */
+type Node = {
+    id: NodeId;
+    type: NodeType;
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    angle: number;
+    z: number;
+    groups: GroupId[];
+    locked?: boolean;
+    hidden?: boolean;
+    content?: string;
+    style?: Style;
+    data?: unknown;
+};
+
+type PathStyle = 'straight' | 'bezier' | 'polyline';
+/**
+ * Edge endpoint — see ARCHITECTURE.md §6.1.
+ *
+ * Attached: `localOffset` is in the node's pre-rotation local frame,
+ *   top-left origin, absolute pixels. Endpoint follows the node
+ *   automatically via projection at render time.
+ * Free-floating: `worldPoint` is in world coordinates.
+ */
+type EdgeEnd = {
+    nodeId: NodeId;
+    localOffset: Vec2;
+} | {
+    worldPoint: Vec2;
+};
+declare const isAttached: (e: EdgeEnd) => e is {
+    nodeId: NodeId;
+    localOffset: Vec2;
+};
+/**
+ * Scene edge — see ARCHITECTURE.md §3.3.
+ */
+type Edge = {
+    id: EdgeId;
+    source: EdgeEnd;
+    target: EdgeEnd;
+    pathStyle: PathStyle;
+    control?: Vec2[];
+    z: number;
+    groups: GroupId[];
+    locked?: boolean;
+    hidden?: boolean;
+    content?: string;
+    style?: EdgeStyle;
+    data?: unknown;
+};
+
+/**
+ * Group metadata — see ARCHITECTURE.md §3.6.
+ *
+ * Membership is NOT stored here; each node/edge has its own `groups: GroupId[]`.
+ * A Group is just optional name/color metadata for the id.
+ */
+type Group = {
+    id: GroupId;
+    name?: string;
+    color?: string;
+};
+
+/**
+ * Camera state — see ARCHITECTURE.md §4 and §13.4 camera API.
+ *
+ * x/y is the world-space coord that maps to the top-left of the viewport.
+ * z is the zoom factor (1 = 1px world per 1px screen).
+ */
+type CameraState = {
+    x: number;
+    y: number;
+    z: number;
+};
+/**
+ * In-memory scene shape. Records keyed by id for O(1) lookup.
+ * Wire format swaps records for arrays at the codec boundary (see §3.8).
+ */
+type Scene = {
+    schemaVersion: SchemaVersion;
+    nodes: Record<NodeId, Node>;
+    edges: Record<EdgeId, Edge>;
+    groups: Record<GroupId, Group>;
+    camera: CameraState;
+    selection: (NodeId | EdgeId)[];
+};
+/**
+ * On-the-wire serialized form. Arrays gzip smaller and have predictable iteration order.
+ * Camera + selection are unchanged.
+ */
+type SerializedScene = {
+    schemaVersion: SchemaVersion;
+    nodes: Node[];
+    edges: Edge[];
+    groups: Group[];
+    camera: CameraState;
+    selection: (NodeId | EdgeId)[];
+};
+
+/**
+ * Operations — see ARCHITECTURE.md §10.2.
+ *
+ * Every committed scene mutation is one Op. `prev` slices capture the
+ * fields touched by an update so undo can apply the inverse without a diff.
+ */
+type Op = {
+    type: 'node.add';
+    node: Node;
+} | {
+    type: 'node.update';
+    id: NodeId;
+    patch: Partial<Node>;
+    prev: Partial<Node>;
+} | {
+    type: 'node.remove';
+    node: Node;
+} | {
+    type: 'edge.add';
+    edge: Edge;
+} | {
+    type: 'edge.update';
+    id: EdgeId;
+    patch: Partial<Edge>;
+    prev: Partial<Edge>;
+} | {
+    type: 'edge.remove';
+    edge: Edge;
+} | {
+    type: 'group.upsert';
+    group: Group;
+    prev?: Group;
+} | {
+    type: 'group.remove';
+    group: Group;
+};
+/**
+ * A batch is the atomic unit of mutation (also the unit of undo/redo and sync).
+ */
+type OpBatch = {
+    id: BatchId;
+    clientId: ClientId;
+    ts: number;
+    origin: 'local' | 'remote' | 'history';
+    ops: Op[];
+};
+
+/**
+ * Canvas background — see ARCHITECTURE.md §4 (rendering pipeline).
+ *
+ * Local-only render-time config (not part of the synced scene). Drives
+ * the page color plus an optional infinite dot / grid pattern that
+ * helps spatial orientation while panning.
+ *
+ * Patterns are world-space: dots/lines are anchored to the world
+ * origin, so panning moves *through* them rather than dragging them
+ * along.
+ */
+type CanvasBackgroundPattern = 'none' | 'dots' | 'grid';
+type CanvasBackground = {
+    /** Page background color. Default `'#f8fafc'`. */
+    color?: string;
+    /** Pattern overlay on top of the color. Default `'none'`. */
+    pattern?: CanvasBackgroundPattern;
+    /** World units between adjacent dots / grid lines. Default `20`. */
+    gap?: number;
+    /** Color of the dots / grid lines. Default `'#cbd5e1'`. */
+    patternColor?: string;
+    /**
+     * Hide the pattern when `camera.z < minZoom`. Useful to declutter
+     * zoomed-out views and skip the per-frame pattern paint cost. Default
+     * `0` (no minimum — pattern shows at any zoom, subject to the LOD
+     * skip when individual cells would be sub-2px).
+     */
+    minZoom?: number;
+    /**
+     * Hide the pattern when `camera.z > maxZoom`. Default `Infinity` (no
+     * maximum). Most consumers won't need this; useful if you want the
+     * pattern to disappear when zoomed in past a "detail" threshold.
+     */
+    maxZoom?: number;
+};
+declare const DEFAULT_BACKGROUND: Required<CanvasBackground>;
+
+/**
+ * ID generation — see ARCHITECTURE.md §10.8.
+ *
+ * Default scheme: `${clientId}-${counter}`. Collision-free across clients
+ * without coordination, human-readable in dev tools, monotonic per client.
+ *
+ * Consumers may override via `createCanvasStore({ idGenerator })`.
+ */
+
+type IdGenerator = () => string;
+/**
+ * Generates a random short client id like "u-7f3a".
+ * Used when no `clientId` is passed and no `sync` adapter is attached.
+ */
+declare const randomClientId: () => ClientId;
+/**
+ * Builds an id generator that prefixes a stable client id with an
+ * incrementing counter. Each call returns a fresh, never-recycled id.
+ */
+declare const makeIdGenerator: (clientId: ClientId) => IdGenerator;
+
+/**
+ * Camera math — see ARCHITECTURE.md §4.3 and §13.4.
+ *
+ * The camera maps world coordinates to screen coordinates via:
+ *   screen = (world - camera.{x,y}) * camera.z
+ *   world  = screen / camera.z + camera.{x,y}
+ *
+ * camera.{x,y} is the world-space point shown at screen (0,0).
+ * camera.z is the zoom factor (1 = identity).
+ */
+
+declare const DEFAULT_CAMERA: CameraState;
+declare const MIN_ZOOM = 0.05;
+declare const MAX_ZOOM = 16;
+/**
+ * Converts a screen-space point to world coords given the current camera.
+ */
+declare const screenToWorld: (screen: Vec2, camera: CameraState) => Vec2;
+/**
+ * Converts a world-space point to screen coords given the current camera.
+ */
+declare const worldToScreen: (world: Vec2, camera: CameraState) => Vec2;
+/**
+ * Computes the world-space rect currently visible inside a viewport of the
+ * given screen-space size. Used for viewport culling queries.
+ */
+declare const viewportWorldRect: (camera: CameraState, viewportW: number, viewportH: number) => WorldRect;
+/**
+ * Clamps a zoom factor to the supported range.
+ */
+declare const clampZoom: (z: number) => number;
+/**
+ * Applies a zoom delta keeping the world point under `screenAnchor` stationary.
+ * Useful for wheel-zoom and pinch-zoom — keeps focus where the user looks.
+ */
+declare const zoomAtScreenPoint: (camera: CameraState, newZoom: number, screenAnchor: Vec2) => CameraState;
+/**
+ * Pans the camera by a screen-space delta (e.g. from a drag gesture).
+ */
+declare const panByScreen: (camera: CameraState, deltaScreen: Vec2) => CameraState;
+
+/**
+ * AABB utilities. Rectangles are { x, y, w, h } in world space.
+ */
+declare const rectContainsPoint: (r: WorldRect, p: Vec2) => boolean;
+declare const rectsIntersect: (a: WorldRect, b: WorldRect) => boolean;
+/**
+ * Inflate rect by a uniform world-space amount on all sides.
+ */
+declare const inflateRect: (r: WorldRect, amount: number) => WorldRect;
+/**
+ * Smallest AABB containing two points.
+ */
+declare const rectFromPoints: (a: Vec2, b: Vec2) => WorldRect;
+/**
+ * Smallest AABB containing all given rects. Returns null for empty input.
+ */
+declare const unionRects: (rects: WorldRect[]) => WorldRect | null;
+
+type SpatialId = string;
+declare class UniformGrid {
+    private readonly cellSize;
+    private readonly cells;
+    private readonly bounds;
+    constructor(cellSize?: number);
+    get size(): number;
+    /**
+     * Inserts or replaces an entry. Removes previous cell membership if the id existed.
+     */
+    insert(id: SpatialId, aabb: WorldRect): void;
+    /**
+     * Removes an entry. No-op if id is unknown.
+     */
+    remove(id: SpatialId): void;
+    /**
+     * Returns the stored AABB for an id, if any.
+     */
+    getAABB(id: SpatialId): WorldRect | undefined;
+    /**
+     * Returns ids whose AABB intersects the query rect.
+     * Broad-phase only — callers do narrow-phase per id.
+     */
+    queryRect(rect: WorldRect): SpatialId[];
+    /**
+     * Returns ids whose AABB contains the point.
+     */
+    queryPoint(p: Vec2): SpatialId[];
+    /**
+     * Empties the index. O(1) on the bookkeeping; the GC handles the rest.
+     */
+    clear(): void;
+    /**
+     * Yields the cell keys that an AABB covers.
+     */
+    private cellKeysFor;
+    private removeFromCells;
+}
+
+/**
+ * Compute world-space AABB for a (possibly rotated) node.
+ *
+ * For axis-aligned nodes (angle === 0): the AABB is the node rect itself.
+ * For rotated nodes: enclose the 4 rotated corners.
+ */
+
+declare const nodeAABB: (node: Node) => WorldRect;
+
+/**
+ * Auto-routing for bezier edges — see ARCHITECTURE.md §6.6.
+ *
+ * Computes cubic-bezier control points by projecting outward from each
+ * endpoint along the attachment-side normal. Rotation-aware: a node
+ * rotated 30° gets a normal rotated 30° too, so edges leave perpendicular
+ * to the rotated side.
+ */
+
+type Side = 'n' | 's' | 'e' | 'w';
+/**
+ * Picks the side of a node's local rect closest to the given local offset.
+ * Used to determine which way a bezier should leave the node.
+ */
+declare const sideOf: (node: Node, localX: number, localY: number) => Side;
+/**
+ * Outward-pointing unit vector for a given side, in the node's pre-rotation
+ * local frame.
+ */
+declare const sideNormalLocal: (side: Side) => Vec2;
+/**
+ * Rotates a local-frame vector into world coordinates by the node's angle.
+ */
+declare const rotateVecByAngle: (v: Vec2, angle: number) => Vec2;
+/**
+ * Computes auto-routed control points for a cubic bezier between
+ * sourceWorld and targetWorld. Each control point is offset along the
+ * outward normal of its endpoint's attached node (if any).
+ *
+ * For free-floating endpoints (no node), the control aligns with the
+ * source→target direction so the curve degenerates gracefully toward a
+ * straight line.
+ */
+declare const autoRouteControls: (sourceWorld: Vec2, targetWorld: Vec2, sourceNormalWorld: Vec2 | null, targetNormalWorld: Vec2 | null) => {
+    c1: Vec2;
+    c2: Vec2;
+};
+
+/**
+ * Result of clipping the polyline against the two attached-node rects.
+ * `startIndex` / `endIndex` are sample indices; the visible polyline is
+ * `[startPoint, samples[startIndex+1..endIndex-1], endPoint]`.
+ * If both ends are free-floating (no attached node), returns the full range.
+ */
+type ClipResult = {
+    startIndex: number;
+    endIndex: number;
+    startPoint: Vec2;
+    endPoint: Vec2;
+    visible: boolean;
+};
+declare const fullVisibleClipResult: (samples: Vec2[]) => ClipResult;
+/**
+ * Clips a polyline against (up to) two attached-node rects.
+ * `sourceNode` / `targetNode` are the nodes the source/target endpoints
+ * attach to (null for free-floating endpoints).
+ */
+declare const clipSamples: (samples: Vec2[], sourceNode: Node | null, targetNode: Node | null) => ClipResult;
+
+type EdgeGeometry = {
+    /** Endpoint world positions (post-projection, pre-clip). */
+    source: Vec2;
+    target: Vec2;
+    /** Polyline samples for paint / hit-test / clip. */
+    samples: Vec2[];
+    /** AABB enclosing samples (padded for arrowheads). */
+    aabb: WorldRect;
+    /** Whether the edge is a self-loop (source.nodeId === target.nodeId). */
+    isSelfLoop: boolean;
+    /** Source/target attached node IDs (or null). Used by paint to clip. */
+    sourceNodeId: NodeId | null;
+    targetNodeId: NodeId | null;
+};
+/**
+ * Computes edge geometry from current node state. No caching — callers
+ * memoize on a version key (see makeEdgeVersion).
+ */
+declare const computeEdgeGeometry: (edge: Edge, getNode: (id: NodeId) => Node | undefined) => EdgeGeometry | null;
+/**
+ * Cache wrapper: stores last-computed geometry per edge id, keyed by an
+ * integer version supplied by the caller. The store maintains the version
+ * counter and bumps it on geometry-affecting mutations (edge.update or
+ * incident node moves), so this cache becomes a pure integer-compare.
+ *
+ * Earlier versions of this file used a `toFixed(2)`-built string version
+ * to detect changes implicitly. That allocated ~14 strings per edge per
+ * paint and cost ~5-8ms at 2k visible edges. Explicit integer versioning
+ * eliminates that entirely.
+ */
+declare class EdgeGeometryCache {
+    private readonly entries;
+    /**
+     * Returns the cached geometry if `version` matches the cache entry;
+     * otherwise recomputes via `computeEdgeGeometry`, stores, and returns.
+     * Caller is responsible for passing the current store-managed version.
+     */
+    get(edge: Edge, version: number, getNode: (id: NodeId) => Node | undefined): EdgeGeometry | null;
+    delete(id: EdgeId): void;
+    clear(): void;
+}
+
+/**
+ * Edge AABB from samples — see ARCHITECTURE.md §6.12.
+ *
+ * Phase-1 had a crude AABB based on raw endpoint positions. Phase 4
+ * computes the actual sample bounds + padding for arrowheads and labels,
+ * which is what the spatial index needs for correct hit-testing.
+ */
+
+declare const edgeAABBFromSamples: (samples: Vec2[]) => WorldRect;
+
+/**
+ * Returns `{ point, tangent }` at fractional arc-length `t ∈ [0..1]`
+ * along a sample polyline.
+ *
+ * Walks the polyline summing segment lengths until the target is
+ * reached; linearly interpolates inside the last segment. The tangent
+ * is the unit direction of that segment.
+ *
+ * Used by edge-label placement (see ARCHITECTURE.md §6.11) — labels at
+ * arc-length 0.5 sit at the geometric midpoint regardless of curve
+ * shape, and the tangent lets a label rotate to follow the edge.
+ *
+ * @example
+ * const { point, tangent } = getPointAndTangentAtArcLength(geom.samples, 0.5)
+ * ctx.translate(point.x, point.y)
+ */
+declare const getPointAndTangentAtArcLength: (samples: readonly Vec2[], t: number) => {
+    point: Vec2;
+    tangent: Vec2;
+};
+
+/**
+ * Converts a single midpoint `P` (the point the user dragged the
+ * bezier midpoint handle to) into a pair of cubic control points
+ * `(c1, c2)` such that the resulting cubic **passes through `P` at
+ * t = 0.5**.
+ *
+ * Math: a cubic Bezier with endpoints S, T and controls c1, c2 has
+ *
+ *   B(0.5) = (1/8) · S + (3/8) · c1 + (3/8) · c2 + (1/8) · T
+ *
+ * Solving for c1 + c2 when B(0.5) = P:
+ *
+ *   c1 + c2 = (8P − S − T) / 3
+ *
+ * One equation, two unknowns. The convention here: split symmetrically
+ * (c1 = c2). That keeps the curve smooth and predictable for the user.
+ * A two-handle form (c1 / c2 draggable independently) is the v1.x
+ * follow-up.
+ */
+declare const midpointToCubicControls: (source: Vec2, midpoint: Vec2, target: Vec2) => {
+    c1: Vec2;
+    c2: Vec2;
+};
+
+/**
+ * Arrowheads — see ARCHITECTURE.md §6.5 + §3.4 (4 styles).
+ *
+ * The arrowhead sits at the clipped endpoint of the edge; its direction
+ * comes from the curve's tangent at that arc-length position. We draw
+ * in world coords so the strokeWidth follows the camera transform —
+ * scale of strokeWidth/scale gives a constant-screen-px width.
+ */
+
+/**
+ * Draws an arrowhead at the given world tip, pointing toward `tipDir`
+ * (the unit tangent direction at that point — pointing FROM the curve
+ * INTO the tip).
+ */
+declare const drawArrowhead: (ctx: CanvasRenderingContext2D, kind: Arrowhead, tip: Vec2, tipDir: Vec2, strokeColor: string, strokeWidth: number) => void;
+/**
+ * World-space length added to the visible arrowhead at a given stroke
+ * width. Used to know how much to shorten the curve's visible portion
+ * so the line tail doesn't poke through the arrowhead tip.
+ */
+declare const arrowheadLength: (kind: Arrowhead, strokeWidth: number) => number;
+
+/**
+ * Built-in style defaults — see ARCHITECTURE.md §3.4.
+ *
+ * Each render call resolves style via:
+ *   1. node.style[token] if set
+ *   2. theme(token) if a theme resolver is provided
+ *   3. the value here
+ */
+
+declare const DEFAULT_STYLE: Required<Pick<Style, 'strokeColor' | 'strokeWidth' | 'strokeStyle' | 'backgroundColor' | 'opacity' | 'roundness'>>;
+/**
+ * Resolves a style field with the precedence above.
+ * `theme` lookup is optional and returns `undefined` if no override.
+ *
+ * Stable token catalog (consumer maps these to its design system):
+ *   - `strokeColor`            edge + shape stroke
+ *   - `strokeWidth`            shape + edge stroke width
+ *   - `backgroundColor`        shape fill
+ *   - `textColor`              shape text color
+ *   - `opacity`                shape opacity (0-100)
+ *   - `selection.outline`      selection outline color (overlay)
+ *   - `handle.fill`            resize/rotate handle fill
+ *   - `handle.stroke`          resize/rotate handle stroke
+ *   - `text.highlight`         markdown ==highlight== chip color
+ *   - `text.codeBackground`    markdown `code` chip color
+ *
+ * Tokens not in this list are passed through unchanged; consumers can
+ * extend with their own (e.g. `node.shadow.color`).
+ */
+type ThemeResolver = (token: string) => string | number | undefined;
+declare const resolveColor: (style: Style | undefined, key: "strokeColor" | "backgroundColor" | "textColor", fallback: string, theme?: ThemeResolver) => string;
+declare const resolveStrokeWidth: (style: Style | undefined, theme?: ThemeResolver) => number;
+declare const resolveOpacity: (style: Style | undefined, theme?: ThemeResolver) => number;
+
+/**
+ * Edge paint entry. `scale` is the world → device factor (camera.z ×
+ * dpr) — kept for back-compat with PNG export and tests. `opts.zoom`,
+ * `opts.dpr`, `opts.isMoving` control the label bitmap-cache LOD; if
+ * omitted, derived from `scale` (zoom = scale, dpr = 1, idle).
+ */
+declare const drawEdge: (ctx: CanvasRenderingContext2D, edge: Edge, geom: EdgeGeometry, sourceNode: Node | null, targetNode: Node | null, scale: number, theme?: ThemeResolver, opts?: {
+    roughEnabled?: boolean;
+    zoom?: number;
+    dpr?: number;
+    isMoving?: boolean;
+}) => void;
+/**
+ * World-space label bounding box. Used by the hit-test (see
+ * `hitTestEdge`). Returns `null` when the edge has no content.
+ */
+declare const edgeLabelBoundsWorld: (edge: Edge, geom: EdgeGeometry) => {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+} | null;
+
+/**
+ * Resolves an EdgeEnd to its current world coordinates.
+ * Returns null when the endpoint is attached to a node that no longer exists.
+ */
+declare const projectEndToWorld: (end: EdgeEnd, getNode: (id: NodeId) => Node | undefined) => Vec2 | null;
+/**
+ * Transforms a point in a node's pre-rotation local frame (top-left origin)
+ * into world coordinates.
+ */
+declare const nodeLocalToWorld: (local: Vec2, node: Node) => Vec2;
+/**
+ * Transforms a world point into the node's pre-rotation local frame.
+ * Used by auto-clip and by edge-creation snap-to-boundary logic.
+ */
+declare const worldToNodeLocal: (world: Vec2, node: Node) => Vec2;
+/**
+ * Given a world point and a node, returns the local-frame coords of the
+ * nearest point on the node's rect boundary. If the world point is inside
+ * the rect, projects to the nearest edge; if outside, clamps to the
+ * containing edge / corner.
+ *
+ * Used by the edge-creation gesture to snap endpoints to the node boundary.
+ */
+declare const projectToNodeBoundary: (world: Vec2, node: Node) => Vec2;
+
+/**
+ * Curve sampling — see ARCHITECTURE.md §6.6 / §6.9.
+ *
+ * The polyline samples are the load-bearing data for everything edge-related:
+ * paint, auto-clip, hit testing all walk the same array. Caching is in
+ * cache.ts; this module is pure geometry.
+ */
+
+/** Default number of intermediate samples for a bezier (cubic). 32 is
+ * indistinguishable from 64 at typical zoom; halve the array size. */
+declare const BEZIER_SEGMENTS = 32;
+/**
+ * Evaluates a cubic bezier at parameter t ∈ [0, 1].
+ */
+declare const cubicBezier: (p0: Vec2, c1: Vec2, c2: Vec2, p1: Vec2, t: number) => Vec2;
+/**
+ * Tangent (unit vector) to a cubic bezier at parameter t.
+ * Used for arrowhead orientation.
+ */
+declare const cubicBezierTangent: (p0: Vec2, c1: Vec2, c2: Vec2, p1: Vec2, t: number) => Vec2;
+/**
+ * Samples a cubic bezier into BEZIER_SEGMENTS+1 evenly-spaced points
+ * (in parameter space — not arc-length).
+ */
+declare const sampleBezier: (p0: Vec2, c1: Vec2, c2: Vec2, p1: Vec2, segments?: number) => Vec2[];
+/**
+ * Returns the polyline sample list for an edge given its path style,
+ * world-projected endpoints, and (for bezier) control points or (for
+ * polyline) midpoints. Straight = 2-point polyline.
+ */
+declare const samplesFor: (pathStyle: PathStyle, source: Vec2, target: Vec2, controls: Vec2[] | undefined) => Vec2[];
+/**
+ * Tangent at parameter t along the sampled polyline (arc-length-ish).
+ * Used for arrowhead orientation when we don't have analytic curve info.
+ * For straight/polyline this returns the segment direction; for bezier
+ * we approximate by the direction between adjacent samples around the
+ * target t.
+ */
+declare const tangentAtArcLength: (samples: Vec2[], t: number) => Vec2;
+
+/**
+ * Returns world-space (source, target, control1, control2) for a self-loop
+ * on the given node. The loop exits from the top edge and re-enters via
+ * the right edge.
+ */
+declare const selfLoopGeometry: (node: Node) => {
+    source: Vec2;
+    target: Vec2;
+    controls: [Vec2, Vec2];
+};
+/**
+ * Samples a self-loop given its node. Convenience wrapper that produces
+ * the polyline samples auto-clip/hit-test/paint all consume.
+ */
+declare const sampleSelfLoop: (node: Node) => Vec2[];
+
+/**
+ * Custom node type definitions — see ARCHITECTURE.md §5.
+ *
+ * `defineNode` creates a registerable NodeTypeDef. The core doesn't know
+ * about React; the `view` field is typed as `unknown` so the React layer
+ * (or the playground for phase 5) can stash a component reference there
+ * without coupling the core package to React.
+ *
+ * The library reads:
+ *   - kind: 'canvas' | 'react' — which render path applies
+ *   - renderCanvas / drawPlaceholder — canvas paint functions
+ *   - getSnapshot — optional bitmap fallback for LOD / motion
+ *   - hitTest / getOutline — interaction hooks
+ *   - lod — zoom thresholds
+ *   - lifecycle hooks
+ *
+ * Consumers register types via `createCanvasStore({ nodeTypes: [...] })`.
+ */
+
+type RenderEnv = {
+    zoom: number;
+    isMoving: boolean;
+    isSelected: boolean;
+    isHovered: boolean;
+    isEditing: boolean;
+    theme(token: string): string | number | undefined;
+};
+type SnapshotEnv = {
+    width: number;
+    height: number;
+    dpr: number;
+};
+type NodeTypeDefOptions = {
+    /** Unique type id, e.g. 'chart-card'. */
+    type: string;
+    renderCanvas?: (ctx: CanvasRenderingContext2D, node: Node, env: RenderEnv) => void;
+    drawPlaceholder?: (ctx: CanvasRenderingContext2D, node: Node, env: RenderEnv) => void;
+    /**
+     * The React view component reference. Stored as `unknown` here because the
+     * core package is framework-agnostic. The React layer reads this field
+     * when it needs to mount a custom node in the DOM overlay.
+     */
+    view?: unknown;
+    lod?: {
+        /** Below this zoom, prefer drawPlaceholder over the React view. Default 0.7. */
+        minZoomForReact?: number;
+        /** Below this zoom, skip the node entirely. Default 0.3. */
+        minZoomForPlaceholder?: number;
+        /** ms; default Infinity. After this age, the snapshot is regenerated. */
+        snapshotMaxAge?: number;
+    };
+    /**
+     * Author-provided rasterized fallback. Library calls this when it needs a
+     * fast paint (motion, low zoom) and uses `drawImage` to blit. Returns null
+     * to fall back to `drawPlaceholder`.
+     */
+    getSnapshot?: (node: Node, env: SnapshotEnv) => CanvasImageSource | null | Promise<CanvasImageSource | null>;
+    /**
+     * Custom hit-test. Receives the world point pre-transformed into the node's
+     * pre-rotation local frame, origin top-left. Default: AABB.
+     */
+    hitTest?: (node: Node, localPoint: Vec2) => boolean;
+    /**
+     * Custom outline polygon (in node-local coords). Default: rect AABB.
+     * Used by the edge auto-clip system when an edge attaches to this node.
+     */
+    getOutline?: (node: Node) => Vec2[] | null;
+    /** Called when the node enters the viewport / mounts a live React view. */
+    onEnter?: (node: Node) => void;
+    /** Called when the node exits the viewport / unmounts. */
+    onExit?: (node: Node) => void;
+    /**
+     * If true, the React view stays mounted (hidden via visibility:hidden) when
+     * off-screen instead of unmounting. Use sparingly — defeats viewport culling.
+     * Default false.
+     */
+    keepMounted?: boolean;
+    /** Validation / migration on scene load. */
+    parse?: (raw: unknown) => Node['data'];
+    migrate?: (data: unknown, fromVersion: number) => Node['data'];
+};
+/**
+ * Normalized form of a node type definition. The `kind` field is derived
+ * from which render paths are provided so the renderer dispatch is one
+ * `switch` away.
+ */
+type NodeTypeDef = NodeTypeDefOptions & {
+    kind: 'canvas-only' | 'react-only' | 'mixed' | 'invalid';
+    lod: {
+        minZoomForReact: number;
+        minZoomForPlaceholder: number;
+        snapshotMaxAge: number;
+    };
+};
+/**
+ * Defines a custom node type. Register the returned def via
+ * `createCanvasStore({ nodeTypes: [myDef, ...] })`; then any `Node`
+ * with `type === opts.type` will be dispatched to your renderers + hit
+ * test + lifecycle hooks.
+ *
+ * A type must supply at least one render path: `renderCanvas` (paints
+ * via the 2D context), `view` (React component reference — used by
+ * `<Canvas renderCustomNodeView>`), or both (`mixed` — canvas at low
+ * zoom, React at high zoom).
+ *
+ * @example
+ * // Canvas-only — fastest path, paints with the 2D context.
+ * export const sparklineDef = defineNode({
+ *   type: 'sparkline',
+ *   renderCanvas(ctx, node, env) {
+ *     ctx.strokeStyle = env.theme('node.stroke') as string ?? '#000'
+ *     // ...draw a sparkline...
+ *   },
+ *   hitTest: (node, p) => p.x >= 0 && p.x <= node.w && p.y >= 0 && p.y <= node.h,
+ * })
+ *
+ * @example
+ * // React view — full UI; library mounts it in the DOM overlay above
+ * // the canvas at high zoom, falls back to drawPlaceholder below.
+ * export const chartCardDef = defineNode({
+ *   type: 'chart-card',
+ *   view: ChartCardComponent,
+ *   drawPlaceholder(ctx, node) {
+ *     ctx.fillStyle = '#e0e7ff'
+ *     ctx.fillRect(0, 0, node.w, node.h)
+ *   },
+ *   lod: { minZoomForReact: 0.7, minZoomForPlaceholder: 0.3 },
+ * })
+ */
+declare const defineNode: (opts: NodeTypeDefOptions) => NodeTypeDef;
+
+/**
+ * Lite-markdown tokenizer — ported verbatim from
+ * `dim0/webui/src/components/markdown/canvas-lite-markdown.tsx`.
+ *
+ * The vocabulary is deliberately small: bold, italic, underline, strike,
+ * highlight, inline code, links, fenced code blocks, hr lines. No
+ * 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 Token = {
+    type: InlineType;
+    content: string;
+} | {
+    type: 'code-block';
+    content: string;
+} | {
+    type: 'br';
+} | {
+    type: 'hr';
+} | {
+    type: 'hr-double';
+};
+/**
+ * Full markdown tokenizer with fenced code-block support. Code blocks
+ * are display-only (no language badge / syntax highlighting).
+ */
+declare const tokenize: (input: string) => Token[];
+
+type StyledRun = {
+    text: string;
+    type: InlineType;
+};
+type LayoutLine = {
+    kind: 'text';
+    runs: StyledRun[];
+} | {
+    kind: 'code-block';
+    runs: StyledRun[];
+    isFirst: boolean;
+    isLast: boolean;
+} | {
+    kind: 'rule';
+    double: boolean;
+};
+type LayoutOptions = {
+    width: number;
+    fontFamily: FontFamily;
+    fontSize: FontSize;
+    textStyle: TextStyle;
+};
+/**
+ * Turns tokens into drawable lines. Output consumed by the canvas paint pass.
+ */
+declare const layoutTokens: (tokens: Token[], opts: LayoutOptions) => LayoutLine[];
+
+/**
+ * Font + line-height defaults — matches `dim0/webui/.../canvas-lite-markdown.tsx`
+ * and `dim0/backend/topix/datatypes/note/style.py`.
+ *
+ * The maps below are the canonical contract between consumer style tokens
+ * and concrete typography. Custom fonts live in the consumer's @font-face;
+ * the library only renames them.
+ */
+
+/**
+ * Mirrors the font stacks defined in dim0's index.css so canvas measurement
+ * matches DOM text. Custom fonts must be loaded by the consumer (via
+ * @font-face / Google Fonts); the font-epoch reactivity (see font-epoch.ts)
+ * invalidates the bitmap cache when fonts finish loading.
+ */
+declare const FONT_FAMILY_MAP: Record<FontFamily, string>;
+declare const FONT_SIZE_MAP: Record<FontSize, number>;
+declare const LINE_HEIGHT_MAP: Record<FontSize, number>;
+declare const CODE_BLOCK_PADDING_X = 6;
+declare const CODE_BLOCK_MARGIN_Y = 4;
+declare const CONTENT_HEIGHT_BUFFER = 4;
+declare const CONTENT_PADDING = 6;
+declare const DEFAULT_TEXT_COLOR = "#1f2937";
+declare const DEFAULT_HIGHLIGHT_COLOR = "#fde047";
+declare const DEFAULT_HIGHLIGHT_COLOR_DARK = "#6b5a23";
+declare const LINK_COLOR = "#2563eb";
+declare const CODE_BG_COLOR = "rgba(148, 163, 184, 0.18)";
+
+/**
+ * Returns the canvas `font` string for a given run.
+ */
+declare const getCanvasFont: (opts: {
+    type: InlineType;
+    fontFamily: FontFamily;
+    fontSize: FontSize;
+    textStyle: TextStyle;
+}) => string;
+/**
+ * Memoized width measurement. Cache key includes font (so different
+ * fonts/sizes/styles get separate entries).
+ *
+ * Falls back to a heuristic when no canvas is available (SSR / Node tests).
+ */
+declare const measureText: (opts: {
+    text: string;
+    type: InlineType;
+    fontFamily: FontFamily;
+    fontSize: FontSize;
+    textStyle: TextStyle;
+}) => number;
+/**
+ * Clears all cached measurements. Called by the font-epoch system on
+ * font load — fallback metrics returned before fonts settle would be
+ * wrong, so we re-measure everything once they're ready.
+ */
+declare const clearMeasureCache: () => void;
+
+/**
+ * Subscribe to font-epoch bumps. Lazy-initializes the document.fonts
+ * listeners on first call. Returns an unsubscribe.
+ */
+declare const subscribeFontEpoch: (listener: (epoch: number) => void) => (() => void);
+/**
+ * Current epoch — included in bitmap-cache keys so they invalidate when
+ * custom fonts settle.
+ */
+declare const getFontEpoch: () => number;
+
+/**
+ * Buckets zoom to avoid cache churn from sub-1%-zoom changes.
+ */
+declare const quantizeZoom: (value: number) => number;
+/**
+ * Buckets DPR to keep cache keys stable across tiny devicePixelRatio
+ * variance (e.g. when a window crosses a mixed-DPR monitor boundary).
+ */
+declare const quantizeDpr: (value: number) => number;
+/**
+ * Chooses a render scale from a base scale, the current zoom bucket,
+ * and whether the camera (or shape) is in motion. While moving, drop
+ * quality for throughput; on idle, snap back to full quality.
+ */
+declare const resolveRenderScale: (baseScale: number, zoom: number, isMoving: boolean) => number;
+/**
+ * Applies the absolute backing-store size cap so very-wide / very-tall
+ * shapes don't blow up memory at high zoom.
+ */
+declare const clampEffectiveScale: (baseScale: number, width: number, height: number) => number;
+
+type DrawTextOptions = {
+    text: string;
+    width: number;
+    height: number;
+    align: TextAlign;
+    fontFamily: FontFamily;
+    fontSize: FontSize;
+    textStyle: TextStyle;
+    textColor: string;
+    highlightColor: string;
+};
+/**
+ * Paints `text` (markdown) into the canvas at (0..width, 0..height) using
+ * the laid-out lines and styled runs. Background chips for inline code +
+ * highlight, vertical centering when content shorter than height, dashed
+ * decorations for underline/strike/link.
+ */
+declare const drawTextToCanvas: (ctx: CanvasRenderingContext2D, opts: DrawTextOptions) => void;
+
+type EstimateOptions = {
+    text: string;
+    width: number;
+    fontFamily?: FontFamily;
+    fontSize?: FontSize;
+    textStyle?: TextStyle;
+};
+declare const getContentHeight: (lines: LayoutLine[], lineHeight: number) => number;
+declare const estimateMarkdownContentHeight: ({ text, width, fontFamily, fontSize, textStyle, }: EstimateOptions) => number;
+declare const getMarkdownLineHeightPx: (fontSize: FontSize) => number;
+
+type BitmapCacheRequest = {
+    /** Stable id for the source — typically the node id. */
+    id: string;
+    text: string;
+    /** Logical CSS pixels of the destination rect. */
+    width: number;
+    height: number;
+    zoom: number;
+    dpr: number;
+    isMoving: boolean;
+    align: TextAlign;
+    fontFamily: FontFamily;
+    fontSize: FontSize;
+    textStyle: TextStyle;
+    textColor: string;
+    highlightColor: string;
+};
+type BitmapCacheEntry = {
+    /** Backing-store canvas — pass to ctx.drawImage. */
+    canvas: HTMLCanvasElement;
+    /** Logical (CSS) target width — what the caller should draw at. */
+    width: number;
+    /** Logical (CSS) target height. */
+    height: number;
+};
+/**
+ * Lookup-or-build. Always returns a non-null entry as long as `text` is
+ * non-empty — on miss it draws synchronously and stores. Same call site
+ * for hit and miss.
+ *
+ * Returns null only when the input is empty/whitespace.
+ */
+declare const getOrRenderTextBitmap: (req: BitmapCacheRequest) => BitmapCacheEntry | null;
+/** Test / debug aid. */
+declare const clearTextBitmapCache: () => void;
+/** Test / debug aid. */
+declare const getTextBitmapCacheSize: () => number;
+
+/**
+ * Auto-fit policy — see ARCHITECTURE.md §8 and IMPLEMENTATION.md Phase 7.
+ *
+ * Height of a content-bearing node is recomputed on **commit boundaries**:
+ *   - `store.addNode` (when creating a node with content)
+ *   - `store.commitEdit` (when the user finishes editing)
+ *   - resize-commit (when a width-resize ends; new wrap → new height)
+ *
+ * NEVER per-keystroke. The textarea-editor grows its own DOM textarea
+ * during typing; the canvas catches up once on commit.
+ */
+/**
+ * Should this node auto-fit its height to its content?
+ *
+ * Default: true for all node types — matches tldraw/excalidraw behavior
+ * where a sticky / shape grows to fit whatever you type. Set
+ * `style.autoFit: false` to opt out.
+ */
+declare const shouldAutoFit: (node: Node) => boolean;
+/**
+ * Returns the height this node *would* have if its content laid out at its
+ * current width and style. For empty content, returns one line-height so a
+ * shape with the empty-content placeholder isn't zero-sized.
+ */
+declare const computeAutoFitHeight: (node: Node) => number;
+/**
+ * Pure: returns a copy of `node` with `h` adjusted to fit `content`, if
+ * the node opts into autofit. Otherwise returns the input unchanged.
+ *
+ * Pure-by-design so it can run inside `addNode` before the op is enqueued
+ * (avoids a double op: add + update-height).
+ */
+declare const withAutoFitHeight: (node: Node) => Node;
+
+/**
+ * Editor markdown shortcuts — see IMPLEMENTATION.md Phase 7.
+ *
+ * Pure string-transform helpers, framework-agnostic. The default DOM
+ * textarea editor wires these to keyboard events; consumers using a
+ * custom adapter (Lexical / ProseMirror) can ignore this module.
+ *
+ * Each transform takes `(value, selStart, selEnd)` and returns the new
+ * value + new selection so the editor can update its DOM textarea in
+ * one pass.
+ */
+type Transform = {
+    value: string;
+    selStart: number;
+    selEnd: number;
+};
+declare const toggleBold: (v: string, s: number, e: number) => Transform;
+declare const toggleItalic: (v: string, s: number, e: number) => Transform;
+declare const toggleUnderline: (v: string, s: number, e: number) => Transform;
+declare const toggleStrike: (v: string, s: number, e: number) => Transform;
+declare const toggleCode: (v: string, s: number, e: number) => Transform;
+/**
+ * Inserts `[selection](url)`. If `url` is empty the cursor lands inside
+ * the parens so the user can type the URL.
+ */
+declare const insertLink: (value: string, selStart: number, selEnd: number, url: string) => Transform;
+/**
+ * Auto-list — when the user presses Enter inside a `- ` (or `* `, or
+ * `1. ` etc.) line, the next line gets the same prefix prepended.
+ * Two consecutive Enters on an empty list line exit the list.
+ *
+ * Returns a transform when an auto-list rule fires, else null. The
+ * editor should fall back to the textarea's default Enter behavior in
+ * the null case.
+ */
+declare const handleEnter: (value: string, selStart: number, selEnd: number) => Transform | null;
+
+/**
+ * EditorAdapter — see ARCHITECTURE.md §8 (edit mode pluggability).
+ *
+ * Pluggable contract for the in-place editor. The default is a plain
+ * `<textarea>` overlay (see `default-textarea-editor.ts`). Consumers can
+ * swap in a Lexical / ProseMirror / TipTap subtree by implementing this
+ * interface and passing it to the renderer.
+ *
+ * The adapter is created **per edit session** — `mount` runs on
+ * `beginEdit`, `destroy` runs on `commit`/`cancel`.
+ */
+type EditorAdapterMountOptions = {
+    /** The node being edited. Use its style for font-family / size / align. */
+    node: Node;
+    /** The host DOM container the adapter should append its element into. */
+    container: HTMLElement;
+    /**
+     * Current camera. The adapter is responsible for positioning its
+     * element so it overlaps the node in screen-space.
+     */
+    camera: CameraState;
+    /** Device pixel ratio at edit time. Used for crisp positioning. */
+    dpr: number;
+    /** Called when the user commits (Esc / blur / Cmd+Enter). */
+    onCommit: (text: string) => void;
+    /** Called when the user cancels (no content change). */
+    onCancel: () => void;
+};
+type EditorAdapter = {
+    /** Focus the editor (after mount). */
+    focus(): void;
+    /** Read the current draft text. */
+    getValue(): string;
+    /** Replace the draft text (rare; mostly used by undo or programmatic). */
+    setValue(text: string): void;
+    /** Tear down the editor and remove its DOM. */
+    destroy(): void;
+};
+type EditorAdapterFactory = (opts: EditorAdapterMountOptions) => EditorAdapter;
+
+/**
+ * Default in-place editor — a plain `<textarea>` positioned over the
+ * editing node. See Phase 7 plan.
+ *
+ * - Auto-sizes its height to its scrollHeight (DOM-native).
+ * - Font matches the node's style so what you type roughly matches what
+ *   you'll see on commit.
+ * - Cmd+B/I/U/Shift+X/E/K: bold/italic/underline/strike/code/link.
+ * - Enter inside a `- ` line continues the bullet; double-Enter exits.
+ * - Esc / Cmd+Enter / blur: commit. (cancel is wired by the renderer.)
+ */
+declare const createDefaultTextareaEditor: EditorAdapterFactory;
+
+/**
+ * Resize-handle hit testing — see ARCHITECTURE.md §11.6.
+ *
+ * Handles are drawn at constant screen size (e.g. 8px), so their world-space
+ * bounds change with camera zoom. They sit at the 8 cardinal points of the
+ * node's bounding rect; for rotated nodes the handle positions rotate with
+ * the node so a "north-east" handle is actually at the rotated NE corner.
+ */
+
+type ResizeHandle = 'nw' | 'n' | 'ne' | 'e' | 'se' | 's' | 'sw' | 'w';
+declare const RESIZE_HANDLES: ResizeHandle[];
+/**
+ * Screen-pixel size of a resize-handle hit target. Visual size matches.
+ * Sized for touch reach (~14px) without being intrusive on desktop;
+ * tldraw uses a similar value.
+ */
+declare const RESIZE_HANDLE_SIZE_PX = 14;
+/**
+ * Screen-pixel distance from the top edge of the node to the rotation
+ * handle center. Visual + hit-target match.
+ */
+declare const ROTATE_HANDLE_OFFSET_PX = 24;
+/** Screen-pixel radius of the rotation-handle hit target. */
+declare const ROTATE_HANDLE_RADIUS_PX = 9;
+/**
+ * World-space centers of all 8 resize handles for the given node.
+ * Rotation-aware: handles rotate with the node so they sit on the corners
+ * and edge midpoints of the rotated rect (not the rotated AABB).
+ */
+declare const handleWorldPositions: (node: Node) => Record<ResizeHandle, Vec2>;
+/**
+ * Returns the handle hit by a world point, or null. `cameraZ` lets us map
+ * the constant screen-size handle box to its current world-space footprint.
+ */
+declare const hitTestHandles: (node: Node, worldPoint: Vec2, cameraZ: number) => ResizeHandle | null;
+/**
+ * World-space position of the rotation handle — sits a constant 22px
+ * (screen) above the node's top edge midpoint, perpendicular to the
+ * rotated top edge.
+ */
+declare const rotateHandleWorldPosition: (node: Node, cameraZ: number) => Vec2;
+/**
+ * Returns true if `worldPoint` is over the rotation handle for the node.
+ */
+declare const hitTestRotateHandle: (node: Node, worldPoint: Vec2, cameraZ: number) => boolean;
+
+type InteractionMode = 'idle' | 'panning' | 'zooming' | 'dragging' | 'resizing' | 'rotating' | 'marqueeing' | 'creating-shape' | 'creating-edge' | 'reconnecting-edge' | 'editing';
+type PointerInfo = {
+    worldX: number;
+    worldY: number;
+    screenX: number;
+    screenY: number;
+    pointerType: 'mouse' | 'touch' | 'pen';
+    pressure?: number;
+};
+/**
+ * The frozen geometry of a node at drag-start, used to compute the
+ * uncommitted display position during drag (= original + delta).
+ */
+type DragOriginal = {
+    id: NodeId;
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    angle: number;
+};
+type InteractionState = {
+    mode: InteractionMode;
+    pointer: PointerInfo | null;
+    draggedIds: NodeId[];
+    dragOriginals: DragOriginal[];
+    /** World-space delta from drag start; renderer applies this to draw the dragged set. */
+    dragDelta: Vec2;
+    resizeHandle: ResizeHandle | null;
+    /** Whether the user is holding Shift during a resize (aspect-lock). */
+    resizeLockAspect: boolean;
+    /** Whether the user is holding Alt during a resize (resize from center). */
+    resizeFromCenter: boolean;
+    marqueeRect: WorldRect | null;
+    /** Whether the marquee should add to (true, shift held) or replace selection. */
+    marqueeAdditive: boolean;
+    draftEdge: {
+        source: EdgeEnd;
+        target: EdgeEnd;
+        /** When reconnecting an existing edge, the id; null for new edges. */
+        reconnectingId: EdgeId | null;
+        /** Snap candidate (a node id the target endpoint is hovering over). */
+        snapTargetNodeId: NodeId | null;
+    } | null;
+    editingTarget: EditTarget | null;
+    createDraftRect: WorldRect | null;
+    createTool: string | null;
+};
+/** Identifies what's currently being edited — a node (text content) or
+ *  an edge (label content). See `store.beginEdit`. */
+type EditTarget = {
+    kind: 'node';
+    id: NodeId;
+} | {
+    kind: 'edge';
+    id: EdgeId;
+};
+declare const idleInteractionState: () => InteractionState;
+/**
+ * Convenience: any of panning/zooming/dragging/resizing/rotating is "moving".
+ */
+declare const isMoving: (state: InteractionState) => boolean;
+
+/**
+ * Per-client awareness state that other clients see in real time.
+ * Synced over the {@link SyncAdapter}; never in the op log; never
+ * persisted by `toJSON`.
+ *
+ * Set the local copy via `store.presence.setLocal({...})`. Read the
+ * remote copy via `usePresence()` / `usePresence(clientId)` (React) or
+ * `store.presence.get(...)` / `store.presence.getAll()`.
+ */
+type PresenceState = {
+    /** Stable id of the owning client. */
+    clientId: ClientId;
+    /** Cursor world position; null when the cursor has left the surface. */
+    cursor: Vec2 | null;
+    /** Ids the remote client has selected — for shared-awareness highlights. */
+    selection: (NodeId | EdgeId)[];
+    /** Node id the remote client is currently editing (or null). */
+    editing: NodeId | null;
+    /** Display color (hex). Used for remote cursors + selection outlines. */
+    color: string;
+    /** Display name. */
+    name: string;
+};
+declare const emptyPresenceState: (clientId: ClientId) => PresenceState;
+type PresencePatch = Partial<Omit<PresenceState, 'clientId'>>;
+/**
+ * Returns true if any remote presence has this node currently open in
+ * edit mode. Used to enforce the exclusive edit-lock when a SyncAdapter
+ * is attached (see ARCHITECTURE.md §9 collab edit semantics).
+ */
+declare const isNodeRemoteEditing: (remote: ReadonlyMap<ClientId, PresenceState>, nodeId: NodeId) => boolean;
+
+type StoreOptions = {
+    initial?: Scene;
+    clientId?: ClientId;
+    idGenerator?: IdGenerator;
+    /**
+     * Custom node type registry. Each entry created via `defineNode`. The
+     * renderer consults this to decide between built-in shapes, canvas
+     * custom paint, and React-overlay views. See ARCHITECTURE.md §5.
+     */
+    nodeTypes?: NodeTypeDef[];
+};
+/**
+ * Origin of an applied op — drives sync + undo behavior.
+ *
+ * Phase 1 only uses 'local'; remote/history wire up in phase 8.
+ */
+type OpOrigin = 'local' | 'remote' | 'history';
+/**
+ * Presence change event payload. `removed: true` signals a remote client
+ * has left. Local-presence changes carry the full new state.
+ */
+type PresenceEvent = {
+    state: PresenceState;
+    removed?: false;
+} | {
+    clientId: ClientId;
+    removed: true;
+};
+type StoreEvents = {
+    /** Fires once per committed OpBatch (one batch per mutation or per `batch()` call). */
+    change: OpBatch;
+    /** Camera state changed (any field). */
+    camera: CameraState;
+    /** Selection changed. */
+    selection: (NodeId | EdgeId)[];
+    /** Interaction state changed (mode / pointer / drag / marquee / resize / edit). */
+    interaction: InteractionState;
+    /** Local or remote presence changed. Subscribers compare clientId to filter. */
+    presence: PresenceEvent;
+    /**
+     * LWW conflict detected when applying a remote batch — `prev` slice
+     * didn't match local current value. The op was still applied (last
+     * writer wins); the event fires for telemetry / consumer UX.
+     */
+    conflict: {
+        batch: OpBatch;
+        conflicts: {
+            op: Op;
+            field: string;
+        }[];
+    };
+};
+/** Public presence slice on the store. */
+interface PresenceSlice {
+    /** Patch this client's presence; emits a 'presence' event + forwards via SyncAdapter. */
+    setLocal(patch: PresencePatch): void;
+    /** Current local presence. */
+    getLocal(): PresenceState;
+    /** Snapshot of a remote client's presence, or undefined. */
+    get(clientId: ClientId): PresenceState | undefined;
+    /** Snapshot of all remote presences. */
+    getAll(): ReadonlyMap<ClientId, PresenceState>;
+    /**
+     * Adapter-facing: apply a remote client's presence patch. `state === null`
+     * removes the remote client (they've left). Emits a 'presence' event so
+     * consumers can update overlay UI.
+     *
+     * @internal — used by `attachSync`. Not meant for app code.
+     */
+    applyRemote(clientId: ClientId, state: PresenceState | null): void;
+}
+type StoreEventName = keyof StoreEvents;
+type StoreEventHandler<E extends StoreEventName> = (payload: StoreEvents[E]) => void;
+type Unsubscribe = () => void;
+type SpatialQuery = {
+    rect?: WorldRect;
+    point?: Vec2;
+};
+type SpatialResult = {
+    nodes: NodeId[];
+    edges: EdgeId[];
+};
+/**
+ * The single source of truth for one canvas. Mutations go through
+ * typed ops (collab-ready + undoable), reads are imperative, and
+ * change events drive React hooks + sync adapters.
+ *
+ * Created via `createCanvasStore(opts)`. See ARCHITECTURE.md §10.
+ */
+interface CanvasStore {
+    /** Stable id for *this* client. Generated ids embed it. */
+    readonly clientId: ClientId;
+    /**
+     * Mints a new globally-unique id. Embeds `clientId` so ids generated
+     * concurrently across peers don't collide.
+     *
+     * @example
+     * const id = asNodeId(store.generateId())
+     */
+    generateId(): string;
+    /**
+     * Adds a node. Returns its id. If `node.style.autoFit !== false` and
+     * `node.content` is set, height is grown to fit.
+     *
+     * @example
+     * const id = store.addNode({
+     *   id: asNodeId(store.generateId()),
+     *   type: 'rect', x: 0, y: 0, w: 200, h: 100,
+     *   angle: 0, z: 0, groups: [],
+     * })
+     */
+    addNode(node: Node): 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
+     * style fields change.
+     *
+     * @example
+     * store.updateNode(id, { x: 100, style: { backgroundColor: '#fef9c3' } })
+     */
+    updateNode(id: NodeId, patch: Partial<Node>): void;
+    /**
+     * Removes a node and cascade-removes its incident edges in the same
+     * batch (so one undo restores the node + every edge that pointed to it).
+     */
+    removeNode(id: NodeId): void;
+    /** Adds an edge. Returns its id. */
+    addEdge(edge: Edge): EdgeId;
+    /** Patches fields on an existing edge. */
+    updateEdge(id: EdgeId, patch: Partial<Edge>): void;
+    /** Removes an edge. */
+    removeEdge(id: EdgeId): void;
+    upsertGroup(group: Group): void;
+    removeGroup(id: GroupId): void;
+    /**
+     * Z-order: bring the given nodes/edges to the top of the paint
+     * order (and the top of the hit-test priority for overlapping
+     * shapes). Mixed node/edge selections are supported. Each entity
+     * gets a fresh top-of-stack z; relative order among the targets
+     * is preserved (first-passed stays on top).
+     *
+     * Batched as one OpBatch — single undo step.
+     */
+    bringToFront(ids: (NodeId | EdgeId)[]): void;
+    /** Symmetric: send to the bottom of the stack. */
+    sendToBack(ids: (NodeId | EdgeId)[]): void;
+    /** Step each target above the next-higher non-target sibling. */
+    bringForward(ids: (NodeId | EdgeId)[]): void;
+    /** Step each target below the next-lower non-target sibling. */
+    sendBackward(ids: (NodeId | EdgeId)[]): void;
+    /**
+     * Collapses every mutation inside `fn` into a single `OpBatch` — one
+     * undo step, one change event, one sync send.
+     *
+     * @example
+     * store.batch(() => {
+     *   for (const id of selection) store.removeNode(id as NodeId)
+     * })
+     */
+    batch(fn: () => void): void;
+    /**
+     * Low-level op application — usually called by sync adapters or
+     * tool-use AI agents that generate ops directly.
+     * `opts.origin` defaults to `'local'`. Remote/history origins skip
+     * the undo stack.
+     *
+     * @example
+     * // Apply an AI-generated op:
+     * store.applyOp({ type: 'node.add', node: aiNode })
+     */
+    applyOp(op: Op, opts?: {
+        origin?: OpOrigin;
+    }): void;
+    /** Apply an entire batch (origin lives on the batch). */
+    applyBatch(batch: OpBatch): void;
+    /** True when there's something to undo. */
+    canUndo(): boolean;
+    /** True when there's something to redo. */
+    canRedo(): boolean;
+    /**
+     * Pops the most recent local batch and applies its inverse. Returns
+     * true if anything was undone.
+     *
+     * @example
+     * if (e.metaKey && e.key === 'z') store.undo()
+     */
+    undo(): boolean;
+    /** Re-applies a previously-undone batch. */
+    redo(): boolean;
+    /** Drops both undo and redo stacks. Call after `fromJSON` / scene reset. */
+    clearHistory(): void;
+    /**
+     * Per-client *synced* state — cursor / selection / editing / color /
+     * name. Distinct from `getInteractionState()` (which is local-only).
+     *
+     * @example
+     * store.presence.setLocal({ name: 'Alice', color: '#ef4444' })
+     */
+    presence: PresenceSlice;
+    /** O(1) lookup; undefined if not found or removed. */
+    getNode(id: NodeId): Node | undefined;
+    /** O(1) lookup. */
+    getEdge(id: EdgeId): Edge | undefined;
+    /** O(1) lookup. */
+    getGroup(id: GroupId): Group | undefined;
+    /** O(n) — materializes the full list. Use sparingly. */
+    getAllNodes(): Node[];
+    /** O(n) — materializes the full list. */
+    getAllEdges(): Edge[];
+    /** O(n) — materializes the full list. */
+    getAllGroups(): Group[];
+    /** O(1) count without materializing the list. */
+    getNodeCount(): number;
+    /** O(1) count. */
+    getEdgeCount(): number;
+    /** O(1) count. */
+    getGroupCount(): number;
+    /**
+     * Spatial query — ids of nodes + edges that intersect a rect or
+     * contain a point. Backed by a uniform grid for sub-millisecond
+     * queries at 10k+ entities.
+     *
+     * @example
+     * const visible = store.querySpatial({ rect: viewport })
+     */
+    querySpatial(q: SpatialQuery): SpatialResult;
+    /**
+     * Cached edge geometry — sample polyline, AABB, attached-node ids,
+     * self-loop flag. Lazily recomputed when any input changes.
+     */
+    getEdgeGeometry(id: EdgeId): EdgeGeometry | undefined;
+    /**
+     * Ids of every edge attached to this node (either endpoint). O(1) —
+     * maintained as an inverted index internally.
+     */
+    getIncidentEdges(id: NodeId): EdgeId[];
+    /**
+     * The registered `NodeTypeDef` for a type id, or `undefined` for
+     * built-in shapes. See `defineNode`.
+     */
+    getNodeTypeDef(type: string): NodeTypeDef | undefined;
+    getCamera(): CameraState;
+    /**
+     * Set camera fields (partial patch). Clamped to legal zoom range.
+     *
+     * @example
+     * store.setCamera({ z: 1.5 })
+     */
+    setCamera(patch: Partial<CameraState>): void;
+    getSelection(): (NodeId | EdgeId)[];
+    /** Replace the selection. Pass `[]` to deselect everything. */
+    setSelection(ids: (NodeId | EdgeId)[]): void;
+    /** Current interaction state — mode, drag delta, marquee rect, etc. */
+    getInteractionState(): InteractionState;
+    /** Patch fields on interaction state. Emits a 'interaction' event. */
+    setInteractionState(patch: Partial<InteractionState>): void;
+    /** Reset to idle (clears drag / marquee / draft edge / edit mode). */
+    resetInteractionState(): void;
+    /**
+     * Enter edit mode for `id`. Polymorphic — `id` may be a {@link NodeId}
+     * (to edit `node.content`) or an {@link EdgeId} (to edit
+     * `edge.content`, the edge label). Flips interaction mode to
+     * `'editing'`; the library's `EditorMount` picks up the change and
+     * mounts the configured editor adapter at the right anchor.
+     *
+     * @example
+     * // Double-click a node body or an edge label to edit:
+     * onDoubleClick={e => {
+     *   const hit = hitTestAny(store, e.world, camera.z)
+     *   if (hit?.kind === 'body' && 'nodeId' in hit) store.beginEdit(hit.nodeId)
+     *   if (hit?.kind === 'label') store.beginEdit(hit.edgeId)
+     * }}
+     */
+    beginEdit(id: NodeId | EdgeId): void;
+    /**
+     * Write the new content + apply autofit (if opted in) + exit edit
+     * mode. No-op when not editing.
+     */
+    commitEdit(content: string): void;
+    /** Exit edit mode without writing content. */
+    cancelEdit(): void;
+    /**
+     * Subscribe to a store event. Returns an unsubscribe function.
+     * Events fire synchronously; subscribers must not throw.
+     *
+     * Events:
+     *   - `'change'` — any committed batch (local / remote / history)
+     *   - `'camera'` — pan or zoom
+     *   - `'selection'` — selection change
+     *   - `'interaction'` — interaction state change (frequent during drag)
+     *   - `'presence'` — local or remote presence update
+     *   - `'conflict'` — LWW conflict detected when applying a remote batch
+     *
+     * @example
+     * const unsub = store.subscribe('change', batch => save(batch))
+     */
+    subscribe<E extends StoreEventName>(event: E, cb: StoreEventHandler<E>): Unsubscribe;
+}
+
+declare const createCanvasStore: (opts?: StoreOptions) => CanvasStore;
+
+/**
+ * Op inversion — see ARCHITECTURE.md §10.2.
+ *
+ * Every committed `Op` carries enough state (full snapshot for add/remove,
+ * `prev` slice for updates) to derive its inverse with no diffing. Undo
+ * applies `inverseBatch(batch)` with `origin: 'history'`; redo re-applies
+ * the original batch.
+ *
+ * Inverse rules:
+ *   - add ↔ remove (full snapshot retained)
+ *   - update.patch ↔ update.prev
+ *   - group.upsert with `prev` ↔ group.upsert with prev fields swapped; if
+ *     `prev` is absent, the upsert was a fresh insert → invert to remove.
+ */
+
+declare const inverseOp: (op: Op) => Op;
+/**
+ * Inverse batch: reverse op order, invert each op. Reversing preserves
+ * "later ops depended on earlier ones" semantics — e.g. a batch that
+ * (1) adds a node and (2) updates it must undo (2) first, then (1).
+ */
+declare const inverseBatch: (batch: OpBatch) => Op[];
+
+/**
+ * LWW conflict detection — see ARCHITECTURE.md §10.6.
+ *
+ * For remote `node.update` / `edge.update` ops, the `prev` slice
+ * captures what the *remote* client thought the value was before its
+ * change. If our local current value differs, two clients touched the
+ * same field concurrently: LWW says higher `batch.ts` wins (we still
+ * apply the remote op), but we surface a 'conflict' event for
+ * telemetry / consumer UX (e.g. "your background color was just
+ * overwritten by Alice").
+ */
+type ConflictRecord = {
+    op: Op;
+    field: string;
+};
+type GetCurrentNode = (id: Node['id']) => Node | undefined;
+type GetCurrentEdge = (id: Edge['id']) => Edge | undefined;
+/**
+ * Walks a remote OpBatch and returns the set of `(op, field)` pairs
+ * where the local current value disagrees with the op's `prev` slice.
+ * No state is mutated.
+ */
+declare const detectConflicts: (batch: OpBatch, getNode: GetCurrentNode, getEdge: GetCurrentEdge) => ConflictRecord[];
+
+/**
+ * SyncAdapter — see ARCHITECTURE.md §10.6.
+ *
+ * Pluggable transport contract for collab. The library never ships a
+ * concrete adapter (transport is consumer territory: WebSocket, Yjs,
+ * Automerge, BroadcastChannel, …). v1 ships:
+ *
+ *   - This interface
+ *   - `attachSync(store, adapter)` — wires local commits → adapter and
+ *     remote batches → store with `origin: 'remote'`
+ *   - A separate package `@canvas-harness/sync-broadcast` providing a
+ *     BroadcastChannel-backed adapter for single-machine demos
+ *
+ * **v1 sync is experimental.** Conflict semantics assume causally-ordered
+ * op delivery from the adapter. Adapters without causal ordering must
+ * advertise `capabilities.crdt: true` and own merge themselves.
+ */
+type SyncAdapterCapabilities = {
+    /**
+     * Adapter guarantees ops arrive in the same causal order all clients
+     * see. Required for the default LWW path.
+     */
+    causalOrdering?: boolean;
+    /**
+     * Adapter merges via CRDT (Yjs / Automerge / ...). Skips library-side
+     * LWW because the adapter has already resolved conflicts.
+     */
+    crdt?: boolean;
+};
+/**
+ * Pluggable collab transport. Implementations forward op batches +
+ * presence patches between peers. The library is transport-agnostic;
+ * see `@canvas-harness/sync-broadcast` for a reference adapter using
+ * `BroadcastChannel`.
+ *
+ * Authors typically wrap a WebSocket / Yjs / Automerge instance.
+ *
+ * @example
+ * const myAdapter: SyncAdapter = {
+ *   capabilities: { causalOrdering: true },
+ *   sendBatch: b => ws.send(JSON.stringify({ kind: 'op', batch: b })),
+ *   sendPresence: p => ws.send(JSON.stringify({ kind: 'presence', patch: p })),
+ *   onBatch(cb) {
+ *     const h = (e: MessageEvent) => { const m = JSON.parse(e.data); if (m.kind === 'op') cb(m.batch) }
+ *     ws.addEventListener('message', h)
+ *     return () => ws.removeEventListener('message', h)
+ *   },
+ *   onPresence(cb) { … },
+ *   destroy() { ws.close() },
+ * }
+ * const detach = attachSync(store, myAdapter)
+ */
+type SyncAdapter = {
+    capabilities: SyncAdapterCapabilities;
+    /** Send a locally-committed (or history) batch to peers. */
+    sendBatch(batch: OpBatch): void;
+    /** Send a local presence patch to peers. */
+    sendPresence(patch: PresencePatch): void;
+    /** Receive remote batches. Subscription persists until `destroy()`. */
+    onBatch(cb: (batch: OpBatch) => void): Unsubscribe;
+    /**
+     * Receive remote presence patches. `state === null` means the remote
+     * client has left and should be removed from the presence map.
+     */
+    onPresence(cb: (clientId: ClientId, state: PresenceState | null) => void): Unsubscribe;
+    /** Optional teardown — closes sockets, clears buffers, etc. */
+    destroy?(): void;
+};
+/**
+ * Wires a {@link SyncAdapter} to a {@link CanvasStore}. Returns a
+ * `detach()` function that disconnects everything (including the
+ * adapter's own `destroy()`).
+ *
+ * Throws if the adapter advertises neither `causalOrdering` nor
+ * `crdt` — the default LWW path requires causal order.
+ *
+ * After attach:
+ *   - Local + history batches forward to peers via `adapter.sendBatch`.
+ *   - Local presence updates forward via `adapter.sendPresence`.
+ *   - Remote batches apply to the store with `origin: 'remote'`
+ *     (don't enter undo stack; conflict event fires on `prev` mismatch).
+ *   - Remote presence updates merge into `store.presence`.
+ *
+ * @example
+ * import { createBroadcastSyncAdapter } from '@canvas-harness/sync-broadcast'
+ * const adapter = createBroadcastSyncAdapter({
+ *   channelName: 'my-board',
+ *   clientId: store.clientId,
+ * })
+ * const detach = attachSync(store, adapter)
+ * // ...later, on unmount:
+ * detach()
+ */
+declare const attachSync: (store: CanvasStore, adapter: SyncAdapter) => Unsubscribe;
+
+/**
+ * Palm-rejection helper — see IMPLEMENTATION.md Phase 11.
+ *
+ * When a stylus is actively touching the surface, mobile/tablet OSes
+ * sometimes mis-route palm contacts as `pointerType: 'touch'`. The
+ * heuristic: when a pen pointer is down (or has just lifted), drop all
+ * incoming `touch` pointers for a short grace period.
+ *
+ * Pure state holder + helpers. The `<Canvas>` gesture hooks call
+ * `notePenActive` / `notePenInactive` on pen pointer events, and
+ * `shouldRejectTouch` before processing a touch event.
+ */
+type PalmRejectionState = {
+    /** True while at least one pen pointer is currently down. */
+    penActive: boolean;
+    /** Timestamp (ms since epoch) at which the most recent pen pointer lifted. */
+    lastPenUpAt: number;
+};
+declare const PALM_REJECTION_GRACE_MS = 300;
+declare const createPalmRejectionState: () => PalmRejectionState;
+declare const notePenActive: (state: PalmRejectionState) => void;
+declare const notePenInactive: (state: PalmRejectionState, now: number) => void;
+/**
+ * Returns true if this touch event should be ignored because a pen is
+ * active (or just lifted within the grace window).
+ */
+declare const shouldRejectTouch: (state: PalmRejectionState, now: number) => boolean;
+
+type Migrator = (raw: unknown) => unknown;
+/**
+ * Register a migrator that runs when loading data at version `fromVersion`.
+ * The migrator should return data shaped for `fromVersion + 1`.
+ */
+declare const registerMigrator: (fromVersion: number, fn: Migrator) => void;
+/**
+ * Serializes a scene to its wire form.
+ */
+declare const toSerialized: (scene: Scene) => SerializedScene;
+/**
+ * Deserializes from wire form into the in-memory Scene shape.
+ * Runs migrators if the version is older than current.
+ */
+declare const fromSerialized: (raw: SerializedScene | unknown) => Scene;
+/**
+ * Convenience: dump a store's current state to wire form.
+ */
+declare const storeToJSON: (store: CanvasStore) => SerializedScene;
+
+type CanvasSurface = {
+    canvas: HTMLCanvasElement;
+    ctx: CanvasRenderingContext2D;
+    /** Logical CSS pixels (the size you set in JS / read with getBoundingClientRect). */
+    cssWidth: number;
+    cssHeight: number;
+    /** Device pixels — backing-store size. */
+    dpr: number;
+};
+declare const getDpr: () => number;
+/**
+ * Builds a managed canvas surface. Caller pins the canvas element; we size
+ * it and reset the 2d context's transform to logical-pixel space.
+ *
+ * Subsequent calls to `setSize` re-allocate the backing store if the new
+ * `cssW × cssH × DPR` differs from the current.
+ */
+declare const setupSurface: (canvas: HTMLCanvasElement) => CanvasSurface;
+/**
+ * Resizes the surface to a new CSS-pixel size, picking up the current DPR.
+ * Returns true if anything changed (caller should redraw).
+ */
+declare const sizeSurface: (surface: CanvasSurface, cssW: number, cssH: number) => boolean;
+/**
+ * Clears the entire backing store. Call before setting the camera transform.
+ */
+declare const clearSurface: (surface: CanvasSurface) => void;
+
+/**
+ * rAF-driven frame loop — see ARCHITECTURE.md §4.3.
+ *
+ * The renderer marks layers dirty via `requestFrame()`; the loop coalesces
+ * multiple requests into one paint per rAF tick. Idle frames cost nothing
+ * because we only schedule when something is dirty.
+ *
+ * Per-frame timing is captured so consumers can drive perf overlays.
+ */
+type FrameStats = {
+    /** Most recent frame duration in ms (drawFn + overhead). */
+    lastMs: number;
+    /** Running average over the last `historySize` frames. */
+    avgMs: number;
+    /** Number of frames painted since start. */
+    frames: number;
+    /** Frames drawn in the last 1000ms (FPS measurement). */
+    fps: number;
+};
+type FrameLoop = {
+    start(): void;
+    stop(): void;
+    requestFrame(): void;
+    stats(): FrameStats;
+};
+type Opts = {
+    draw: () => void;
+    historySize?: number;
+};
+declare const createFrameLoop: ({ draw, historySize }: Opts) => FrameLoop;
+
+/**
+ * Generic primitive paint pass.
+ *
+ * The renderer applies camera + node transforms (translate to node center,
+ * rotate, translate back to top-left) before calling this. The drawer
+ * just builds a local-space path and fills/strokes it with resolved style.
+ *
+ * `scale` is the current camera × DPR factor (world-units → device-pixels).
+ * Callers compute it once per frame and pass it in so each drawShape call
+ * doesn't allocate a DOMMatrix via ctx.getTransform().
+ */
+
+/**
+ * Atomic single-path primitives. Composites paint multiple of these.
+ * Thought-cloud is atomic — its union geometry is one continuous path
+ * so the rough wobble unifies the silhouette.
+ */
+type AtomicPrimitive = 'rect' | 'ellipse' | 'diamond' | 'tag' | 'thought-cloud';
+/**
+ * Composite primitives built from multiple atomic sub-shapes. Capsule
+ * is intentionally composite — the visible seam between the accent
+ * circle and the rect body reads as two stacked hand-drawn shapes
+ * (medicine-pill aesthetic), which we want to keep.
+ */
+type CompositePrimitive = 'capsule' | 'layered-rect' | 'layered-ellipse' | 'layered-diamond';
+type PrimitiveType = AtomicPrimitive | CompositePrimitive;
+/** Returns true if `node.type` is one of the built-ins drawShape can render. */
+declare const isDrawablePrimitive: (type: string) => type is PrimitiveType;
+declare const drawShape: (ctx: CanvasRenderingContext2D, node: Node, scale: number, theme?: ThemeResolver, opts?: {
+    skipStroke?: boolean;
+}) => void;
+
+type RendererOptions = {
+    store: CanvasStore;
+    staticCanvas: HTMLCanvasElement;
+    interactiveCanvas: HTMLCanvasElement;
+    theme?: ThemeResolver;
+    /** Initial CSS-pixel size. Use `setSize()` to update on resize. */
+    width: number;
+    height: number;
+    /**
+     * Optional page background + dot/grid pattern. Local-only (not in
+     * the synced scene). Update at runtime via `Renderer.setBackground`.
+     */
+    background?: CanvasBackground;
+    /**
+     * Fires when the set of custom nodes that should be rendered in the DOM
+     * overlay changes. Consumers use this to mount/unmount React subtrees
+     * (or whatever framework). See ARCHITECTURE.md §5.2 lifecycle.
+     *
+     * The callback receives the FULL current set, not a delta — consumers
+     * compute the mount/unmount diff themselves.
+     */
+    onOverlayChange?: (mountedIds: NodeId[]) => void;
+};
+type Renderer = {
+    /** Begin the rAF loop. Idempotent. */
+    start(): void;
+    /** Stop the rAF loop. Idempotent. */
+    stop(): void;
+    /** Force a static repaint on the next rAF tick. */
+    invalidate(): void;
+    /** Resize both canvases to a new CSS-pixel viewport. */
+    setSize(cssW: number, cssH: number): void;
+    /** Update the page background / pattern. Triggers a static repaint. */
+    setBackground(bg: CanvasBackground | undefined): void;
+    /** Per-frame timing (FPS, lastMs, avgMs, frames). */
+    stats(): FrameStats;
+    /** Number of items the most recent paint actually drew. */
+    lastDrawCount(): number;
+    /** Current overlay-mounted custom-node ids. */
+    getOverlaySet(): NodeId[];
+    /** Detach event listeners. The store is left untouched. */
+    dispose(): void;
+};
+declare const createRenderer: (opts: RendererOptions) => Renderer;
+
+/**
+ * Page background + optional infinite dot / grid pattern.
+ *
+ * Called inside `paintStatic` after the camera transform is applied,
+ * before nodes. Dots / grid lines are drawn in world coordinates so
+ * they anchor to the world origin — panning moves the user *through*
+ * the pattern, zooming changes visual density.
+ *
+ * LOD: when `gap × zoom` drops below `MIN_PATTERN_SCREEN_PX`, the
+ * effective gap doubles in octaves so the pattern stays roughly the
+ * same on-screen density. Below `MIN_VISIBLE_PATTERN_PX` the pattern
+ * is omitted entirely (sub-pixel would be unreadable mush + waste).
+ */
+type PaintBackgroundOptions = {
+    /** Visible world rect (after viewport-overscan). */
+    viewport: WorldRect;
+    /** camera.z — used for LOD octave selection + screen-px conversion. */
+    zoom: number;
+    background?: CanvasBackground;
+};
+declare const paintBackground: (ctx: CanvasRenderingContext2D, opts: PaintBackgroundOptions) => void;
+
+/**
+ * Minimap rendering — see IMPROVEMENTS.md (UX) and the React layer's
+ * `<Minimap />` component.
+ *
+ * Splits into two paths consumers can compose independently:
+ *
+ *   - `renderMinimapContent(ctx, store, ...)` — paints every node as a
+ *     plain `fillRect` at its scaled AABB. Edge bodies are skipped
+ *     (not useful at this scale and would multiply cost). Run on
+ *     committed scene change ONLY; cache the result as an
+ *     OffscreenCanvas/HTMLCanvasElement and blit.
+ *
+ *   - `drawMinimapViewport(ctx, camera, sceneBounds, mapSize)` — paints
+ *     a tiny rectangle showing the visible viewport. Cheap; run on
+ *     every camera change.
+ *
+ * Cost model:
+ *   - content render: O(N) — only fires on committed mutations.
+ *   - viewport overlay: O(1) per frame.
+ *
+ * Hard cap (`maxNodes`) — above which the content render skips
+ * entirely and the consumer is expected to show a "minimap disabled"
+ * placeholder. Default 5000.
+ */
+declare const DEFAULT_MINIMAP_MAX_NODES = 5000;
+type MinimapContentOptions = {
+    /** Hard upper bound on node count; above this, content is skipped. */
+    maxNodes?: number;
+    /** Override fill color for nodes (used when node has no style.backgroundColor). */
+    defaultNodeColor?: string;
+    /** Background color drawn first inside the minimap rect. */
+    backgroundColor?: string;
+};
+/**
+ * Returns the world-space bounding rect that encloses every visible
+ * node, or `null` if the scene is empty. Used to scale the minimap so
+ * the entire scene fits inside it.
+ */
+declare const sceneBounds: (store: CanvasStore) => WorldRect | null;
+/**
+ * Paints the scene's nodes into the minimap canvas's logical pixel
+ * space. Caller has already cleared the target. Returns true on
+ * success, false when skipped (empty scene or over the node cap).
+ */
+declare const renderMinimapContent: (ctx: CanvasRenderingContext2D, store: CanvasStore, mapWidth: number, mapHeight: number, opts?: MinimapContentOptions) => boolean;
+/**
+ * Paints the camera viewport rectangle on top of the cached minimap
+ * content. Cheap; consumers call this on every camera tick.
+ *
+ * `sceneRect` should be the same bounds used by `renderMinimapContent`
+ * for the current cache. `viewportWorld` is the visible world rect
+ * (caller derives from camera + screen size).
+ */
+declare const drawMinimapViewport: (ctx: CanvasRenderingContext2D, viewportWorld: WorldRect, sceneRect: WorldRect, mapWidth: number, mapHeight: number, color?: string) => void;
+/**
+ * Inverse mapping for click-to-pan: a screen point inside the minimap
+ * rect → the world point it corresponds to. Returns null when the
+ * scene is empty (no bounds to scale against).
+ */
+declare const minimapScreenToWorld: (store: CanvasStore, screenX: number, screenY: number, mapWidth: number, mapHeight: number) => {
+    x: number;
+    y: number;
+} | null;
+/**
+ * World-space viewport rect from the camera + a screen size. Pass to
+ * `drawMinimapViewport`. Caller's responsibility to supply the
+ * canvas/CSS pixel dimensions.
+ */
+declare const worldViewportFromCamera: (camera: CameraState, screenW: number, screenH: number) => WorldRect;
+
+/**
+ * Sets the 2d transform so subsequent draw calls take world coords.
+ *
+ *   screen.x = (world.x - camera.x) * camera.z * dpr
+ *   screen.y = (world.y - camera.y) * camera.z * dpr
+ */
+declare const applyCameraTransform: (surface: CanvasSurface, camera: CameraState) => void;
+/**
+ * The world rect currently visible inside the surface.
+ */
+declare const worldViewport: (surface: CanvasSurface, camera: CameraState) => WorldRect;
+/**
+ * Wraps a draw callback in the local-frame transform for one node:
+ * translates to the node's center, rotates by node.angle, then translates
+ * back to the node's top-left so the drawer can build paths in (0..w, 0..h).
+ */
+declare const drawWithNodeTransform: (ctx: CanvasRenderingContext2D, node: Node, fn: () => void) => void;
+
+/**
+ * Node hit testing — see ARCHITECTURE.md §6.9 (parallels edge hit testing
+ * structure for phase 4).
+ *
+ * For axis-aligned nodes: a fast AABB check.
+ * For rotated nodes: transform the world point into node-local pre-rotation
+ * coords (collapsing the rotation problem to AABB).
+ */
+
+/**
+ * Returns true if the world-space point is inside the (possibly rotated) node.
+ */
+declare const pointInNode: (point: Vec2, node: Node) => boolean;
+/**
+ * Returns true if the node's rotated rect intersects the given AABB.
+ * For axis-aligned nodes this collapses to two AABB ranges; for rotated
+ * nodes we test all 4 corners + 4 axis projections (SAT).
+ */
+declare const nodeIntersectsRect: (node: Node, rect: WorldRect) => boolean;
+
+/** Hit-slop in screen pixels for the edge body. */
+declare const EDGE_HIT_SLOP_PX = 8;
+/** Hit-slop in screen pixels for endpoint / arrowhead handles. */
+declare const EDGE_HANDLE_SLOP_PX = 12;
+type EdgeHit = {
+    kind: 'body';
+    edgeId: EdgeId;
+    distance: number;
+    arcLength: number;
+} | {
+    kind: 'source-handle';
+    edgeId: EdgeId;
+    distance: number;
+} | {
+    kind: 'target-handle';
+    edgeId: EdgeId;
+    distance: number;
+} | {
+    kind: 'midpoint-handle';
+    edgeId: EdgeId;
+} | {
+    kind: 'label';
+    edgeId: EdgeId;
+};
+/**
+ * Returns the topmost edge hit by a world point, or null.
+ * `selectedEdges` enables endpoint-handle detection (handles only show
+ * when the edge is selected).
+ */
+declare const hitTestEdge: (store: CanvasStore, worldPoint: Vec2, cameraZ: number, selectedEdges?: ReadonlySet<EdgeId>) => EdgeHit | null;
+
+/**
+ * Higher-level hit queries that combine the spatial index with per-shape
+ * narrow-phase tests. Returns the topmost hit by z, or all hits inside a
+ * marquee rect.
+ */
+
+type NodeHit = {
+    kind: 'body';
+    nodeId: NodeId;
+} | {
+    kind: 'resize-handle';
+    nodeId: NodeId;
+    handle: ResizeHandle;
+} | {
+    kind: 'rotate-handle';
+    nodeId: NodeId;
+};
+/** A hit covers either a node or an edge sub-region. */
+type Hit = NodeHit | EdgeHit;
+/**
+ * Returns the topmost node hit by a world-space point, plus the part hit
+ * (body or resize handle). Handles are tested before bodies (interactive
+ * elements always win over background — see ARCHITECTURE.md §7).
+ *
+ * If `selectedIds` is provided, only those nodes' handles are considered
+ * — handles only display when the node is selected.
+ */
+declare const hitTestPoint: (store: CanvasStore, worldPoint: Vec2, cameraZ: number, selectedIds?: ReadonlySet<NodeId>) => NodeHit | null;
+/**
+ * Combined node + edge hit testing. Order: node handles > edge endpoint
+ * handles > node bodies > edge bodies.
+ *
+ * Node bodies take priority over edge bodies because clicking ON a node
+ * shouldn't accidentally select the edge passing behind it.
+ */
+declare const hitTestAny: (store: CanvasStore, worldPoint: Vec2, cameraZ: number, selectedNodes?: ReadonlySet<NodeId>, selectedEdges?: ReadonlySet<EdgeId>) => Hit | null;
+/**
+ * Returns ids of all nodes whose (rotated) rect intersects the given rect.
+ * Used for marquee selection.
+ */
+declare const marqueeNodes: (store: CanvasStore, rect: WorldRect) => NodeId[];
+
+/**
+ * Clipboard serialization — see ARCHITECTURE.md §13 (copy/paste).
+ *
+ * Captures the selected nodes plus the edges *between* them (edges
+ * crossing the selection are dropped — same rule as tldraw/excalidraw).
+ * Pure functions; no clipboard-API I/O. The store wraps these with
+ * `navigator.clipboard.{write,read}` calls.
+ */
+type SerializedClipboard = {
+    /** Schema version stamped at copy time. */
+    v: number;
+    /** Source clientId — diagnostic only; not used for paste. */
+    clientId: string;
+    /** Tagged so we can tell our payload apart from arbitrary JSON. */
+    kind: 'canvas-harness/clipboard';
+    nodes: Node[];
+    edges: Edge[];
+};
+/**
+ * Builds a clipboard payload from the store's current selection. Pure
+ * — no I/O, no clipboard API. Useful for programmatic copy-paste
+ * (snapshots, AI-driven duplication, drag-from-sidebar, ...).
+ *
+ * Edges crossing the selection boundary (only one endpoint in the
+ * selection) are dropped. Edges with `worldPoint` endpoints are kept.
+ *
+ * @example
+ * const clip = serializeSelection(store)
+ * localStorage.setItem('clipboard', JSON.stringify(clip))
+ */
+declare const serializeSelection: (store: CanvasStore) => SerializedClipboard;
+type DeserializeOptions = {
+    /** World-space offset applied to all pasted nodes. Default (20, 20). */
+    offset?: Vec2;
+    /** Override the selection on the store after applying. Default true. */
+    select?: boolean;
+};
+/**
+ * Applies a clipboard payload to the store. New ids are minted; edge
+ * endpoints are rewired; offset defaults to `(20, 20)` world units;
+ * the resulting nodes + edges become the new selection by default.
+ *
+ * One `store.batch` — one undo step.
+ *
+ * @example
+ * // Restore from localStorage:
+ * const clip = JSON.parse(localStorage.getItem('clipboard')!)
+ * if (isCanvasHarnessClipboard(clip)) deserializeClipboard(store, clip)
+ */
+declare const deserializeClipboard: (store: CanvasStore, clip: SerializedClipboard, opts?: DeserializeOptions) => NodeId[];
+/**
+ * Type guard — verifies a parsed JSON blob is a clipboard payload from
+ * this library, not arbitrary JSON pasted from elsewhere.
+ */
+declare const isCanvasHarnessClipboard: (raw: unknown) => raw is SerializedClipboard;
+
+/**
+ * Copies the current selection to the system clipboard. Writes both a
+ * native MIME (`application/x-canvas-harness+json`) and a `text/plain`
+ * fallback (concatenated node contents) so paste works in non-canvas
+ * destinations too.
+ *
+ * The `<Canvas>` component already wires this to Cmd/Ctrl+C — call
+ * directly only if you're building a custom copy button.
+ *
+ * @example
+ * <button onClick={() => copy(store)}>Copy</button>
+ */
+declare const copy: (store: CanvasStore) => Promise<SerializedClipboard>;
+/**
+ * Copy + remove the selection in one undoable batch. Same as
+ * Cmd/Ctrl+X.
+ *
+ * @example
+ * <button onClick={() => cut(store)}>Cut</button>
+ */
+declare const cut: (store: CanvasStore) => Promise<SerializedClipboard>;
+/**
+ * Paste from the system clipboard (or a supplied payload). Every node
+ * + edge gets a fresh id; edge endpoints rewire to the new ids; the
+ * paste is offset by `(+20, +20)` world units so it doesn't overlay
+ * the original. Wrapped in one undoable batch.
+ *
+ * Returns the new node ids on success, or `null` if the clipboard
+ * didn't contain a canvas-harness payload.
+ *
+ * @example
+ * <button onClick={() => paste(store)}>Paste</button>
+ *
+ * @example
+ * // Programmatic paste from a saved JSON snippet:
+ * paste(store, savedClip, { offset: { x: 0, y: 0 }, select: false })
+ */
+declare const paste: (store: CanvasStore, payload?: SerializedClipboard, opts?: DeserializeOptions) => Promise<(NodeId | EdgeId)[] | null>;
+
+/**
+ * PNG export — see ARCHITECTURE.md §13. Paints the requested set of
+ * nodes + edges into an offscreen canvas at logical coords; returns a
+ * Blob (image/png).
+ */
+type ExportOptions = {
+    /** Bitmap scale multiplier — defaults to 2 for retina-ish output. */
+    scale?: number;
+    /** Padding (logical px) around the bounding rect. Default 16. */
+    padding?: number;
+    /** Skip the background fill. Default false. */
+    transparentBackground?: boolean;
+    /** Background color when not transparent. Default white. */
+    backgroundColor?: string;
+    /** Theme resolver, same one passed to the live renderer. */
+    theme?: ThemeResolver;
+};
+/**
+ * Renders the current selection to a PNG. Returns a `Blob` you can
+ * download, upload, or paste somewhere.
+ *
+ * Bounding rect is computed from the selected nodes; edges between
+ * selected nodes are included, edges crossing the boundary are
+ * dropped.
+ *
+ * @example
+ * // Download the selection as a PNG file.
+ * const blob = await exportSelection(store, { scale: 2 })
+ * const url = URL.createObjectURL(blob)
+ * Object.assign(document.createElement('a'), {
+ *   href: url, download: 'scene.png',
+ * }).click()
+ * URL.revokeObjectURL(url)
+ *
+ * @example
+ * // Transparent PNG for slide-deck overlays.
+ * const blob = await exportSelection(store, { transparentBackground: true })
+ */
+declare const exportSelection: (store: CanvasStore, opts?: ExportOptions) => Promise<Blob>;
+/**
+ * Renders an arbitrary world-space viewport to a PNG. Use to capture
+ * the current screen, a minimap, or a specific region.
+ *
+ * @example
+ * const viewport = worldViewport(staticSurface, store.getCamera())
+ * const blob = await exportViewport(store, viewport)
+ */
+declare const exportViewport: (store: CanvasStore, viewport: {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}, opts?: ExportOptions) => Promise<Blob>;
+
+/**
+ * SVG export — see ARCHITECTURE.md §13.
+ *
+ * **Scope**: matches PNG export for shape geometry + edge geometry, but
+ * markdown content is emitted as **plain text** (no inline bold /
+ * italic / highlight). SVG `<text>` doesn't support our markdown
+ * dialect without tspan positioning math; deferred to v2. PNG export
+ * preserves all markdown styling via the bitmap pipeline.
+ */
+type SvgExportOptions = {
+    padding?: number;
+    transparentBackground?: boolean;
+    backgroundColor?: string;
+};
+/**
+ * Renders the current selection to an SVG string. Synchronous —
+ * unlike PNG, no canvas roundtrip needed.
+ *
+ * **Caveat:** SVG `<text>` doesn't support our markdown dialect, so
+ * `**bold**` / `==hl==` etc. render as plain text with the syntax
+ * stripped. PNG export preserves all markdown via the bitmap pipeline.
+ *
+ * @example
+ * const svg = exportSelectionSvg(store)
+ * const blob = new Blob([svg], { type: 'image/svg+xml' })
+ */
+declare const exportSelectionSvg: (store: CanvasStore, opts?: SvgExportOptions) => string;
+
+/**
+ * AI scene context — see ARCHITECTURE.md §13.
+ *
+ * Returns a human- or machine-readable snapshot of the scene for use
+ * as a system-prompt payload or AI tool-call argument. **Markdown is
+ * the prose form** (better for LLM comprehension token-per-token);
+ * JSON is the structured form for downstream automation.
+ *
+ * Output keeps it tight: each node + edge becomes one line, with
+ * truncation when the scene is large.
+ */
+type GetContextOptions = {
+    format?: 'markdown' | 'json';
+    /** Restrict to the current selection. Default: include the whole scene. */
+    selectionOnly?: boolean;
+    /** Truncate node list at this count. Default 500. */
+    maxNodes?: number;
+};
+/**
+ * Returns a snapshot of the scene suitable for an LLM system prompt or
+ * a tool-call argument.
+ *
+ * - `format: 'markdown'` (default) — full-text prose summary. Better
+ *   for LLM token economy.
+ * - `format: 'json'` — structured `SceneContextJson` shape; lighter
+ *   than `SerializedScene` (no internal fields).
+ *
+ * @example
+ * // System prompt
+ * const ctx = getContext(store) as string
+ * await anthropic.messages.create({
+ *   system: `Current scene:\n${ctx}`,
+ *   ...
+ * })
+ *
+ * @example
+ * // JSON for downstream automation
+ * const ctx = getContext(store, { format: 'json', selectionOnly: true })
+ */
+declare const getContext: (store: CanvasStore, opts?: GetContextOptions) => string | SceneContextJson;
+type SceneContextJson = {
+    camera: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    nodes: ContextNode[];
+    edges: ContextEdge[];
+    truncated: boolean;
+};
+type ContextNode = {
+    id: string;
+    type: string;
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    angle?: number;
+    content?: string;
+    style?: Record<string, unknown>;
+};
+type ContextEdge = {
+    id: string;
+    source: string | {
+        x: number;
+        y: number;
+    };
+    target: string | {
+        x: number;
+        y: number;
+    };
+    pathStyle?: string;
+};
+
+/**
+ * Op schemas — see ARCHITECTURE.md §13.
+ *
+ * Hand-written JSON-Schema definitions for the `Op` discriminated
+ * union. AI agents use these to validate generated ops before calling
+ * `store.applyOp`; tool-use frameworks (Anthropic, OpenAI, Vertex)
+ * advertise the schemas as callable tool definitions.
+ *
+ * Hand-written (not derived from TS) so the schemas survive when the
+ * runtime shape evolves without an explicit schema update.
+ */
+/**
+ * JSON-Schema definitions for every `Op` variant. Use to validate
+ * agent-generated ops before calling `store.applyOp`, or to feed into
+ * an LLM tool-use loop.
+ *
+ * @example
+ * import Ajv from 'ajv'
+ * const ajv = new Ajv()
+ * const validate = ajv.compile(opSchemas.nodeAdd)
+ * if (validate(generatedOp)) store.applyOp(generatedOp)
+ */
+declare const opSchemas: {
+    readonly nodeAdd: {
+        readonly type: "object";
+        readonly required: readonly ["type", "node"];
+        readonly properties: {
+            readonly type: {
+                readonly const: "node.add";
+            };
+            readonly node: {
+                readonly type: "object";
+                readonly required: readonly ["id", "type", "x", "y", "w", "h", "angle", "z", "groups"];
+                readonly properties: {
+                    readonly id: {
+                        readonly type: "string";
+                        readonly description: "Stable id (typically generated via `store.generateId()`).";
+                    };
+                    readonly type: {
+                        readonly type: "string";
+                        readonly description: "Node type — rect / ellipse / diamond / tag / capsule / thought-cloud / layered-rect / layered-ellipse / layered-diamond / text / a registered custom type.";
+                    };
+                    readonly x: {
+                        readonly type: "number";
+                    };
+                    readonly y: {
+                        readonly type: "number";
+                    };
+                    readonly w: {
+                        readonly type: "number";
+                        readonly minimum: 0;
+                    };
+                    readonly h: {
+                        readonly type: "number";
+                        readonly minimum: 0;
+                    };
+                    readonly angle: {
+                        readonly type: "number";
+                        readonly description: "Rotation in radians (clockwise).";
+                    };
+                    readonly z: {
+                        readonly type: "number";
+                    };
+                    readonly groups: {
+                        readonly type: "array";
+                        readonly items: {
+                            readonly type: "string";
+                        };
+                    };
+                    readonly content: {
+                        readonly type: "string";
+                        readonly description: "Markdown content (for text-bearing shapes).";
+                    };
+                    readonly style: {
+                        readonly type: "object";
+                        readonly description: "Style bag — see ARCHITECTURE.md §3.4 (Style type).";
+                    };
+                    readonly hidden: {
+                        readonly type: "boolean";
+                    };
+                };
+            };
+        };
+    };
+    readonly nodeUpdate: {
+        readonly type: "object";
+        readonly required: readonly ["type", "id", "patch", "prev"];
+        readonly properties: {
+            readonly type: {
+                readonly const: "node.update";
+            };
+            readonly id: {
+                readonly type: "string";
+            };
+            readonly patch: {
+                readonly type: "object";
+            };
+            readonly prev: {
+                readonly type: "object";
+            };
+        };
+    };
+    readonly nodeRemove: {
+        readonly type: "object";
+        readonly required: readonly ["type", "node"];
+        readonly properties: {
+            readonly type: {
+                readonly const: "node.remove";
+            };
+            readonly node: {
+                readonly type: "object";
+                readonly required: readonly ["id", "type", "x", "y", "w", "h", "angle", "z", "groups"];
+                readonly properties: {
+                    readonly id: {
+                        readonly type: "string";
+                        readonly description: "Stable id (typically generated via `store.generateId()`).";
+                    };
+                    readonly type: {
+                        readonly type: "string";
+                        readonly description: "Node type — rect / ellipse / diamond / tag / capsule / thought-cloud / layered-rect / layered-ellipse / layered-diamond / text / a registered custom type.";
+                    };
+                    readonly x: {
+                        readonly type: "number";
+                    };
+                    readonly y: {
+                        readonly type: "number";
+                    };
+                    readonly w: {
+                        readonly type: "number";
+                        readonly minimum: 0;
+                    };
+                    readonly h: {
+                        readonly type: "number";
+                        readonly minimum: 0;
+                    };
+                    readonly angle: {
+                        readonly type: "number";
+                        readonly description: "Rotation in radians (clockwise).";
+                    };
+                    readonly z: {
+                        readonly type: "number";
+                    };
+                    readonly groups: {
+                        readonly type: "array";
+                        readonly items: {
+                            readonly type: "string";
+                        };
+                    };
+                    readonly content: {
+                        readonly type: "string";
+                        readonly description: "Markdown content (for text-bearing shapes).";
+                    };
+                    readonly style: {
+                        readonly type: "object";
+                        readonly description: "Style bag — see ARCHITECTURE.md §3.4 (Style type).";
+                    };
+                    readonly hidden: {
+                        readonly type: "boolean";
+                    };
+                };
+            };
+        };
+    };
+    readonly edgeAdd: {
+        readonly type: "object";
+        readonly required: readonly ["type", "edge"];
+        readonly properties: {
+            readonly type: {
+                readonly const: "edge.add";
+            };
+            readonly edge: {
+                readonly type: "object";
+                readonly required: readonly ["id", "source", "target", "pathStyle", "z", "groups"];
+                readonly properties: {
+                    readonly id: {
+                        readonly type: "string";
+                    };
+                    readonly source: {
+                        readonly oneOf: readonly [{
+                            readonly type: "object";
+                            readonly required: readonly ["nodeId", "localOffset"];
+                            readonly properties: {
+                                readonly nodeId: {
+                                    readonly type: "string";
+                                };
+                                readonly localOffset: {
+                                    readonly type: "object";
+                                    readonly required: readonly ["x", "y"];
+                                    readonly properties: {
+                                        readonly x: {
+                                            readonly type: "number";
+                                        };
+                                        readonly y: {
+                                            readonly type: "number";
+                                        };
+                                    };
+                                };
+                            };
+                        }, {
+                            readonly type: "object";
+                            readonly required: readonly ["worldPoint"];
+                            readonly properties: {
+                                readonly worldPoint: {
+                                    readonly type: "object";
+                                    readonly required: readonly ["x", "y"];
+                                    readonly properties: {
+                                        readonly x: {
+                                            readonly type: "number";
+                                        };
+                                        readonly y: {
+                                            readonly type: "number";
+                                        };
+                                    };
+                                };
+                            };
+                        }];
+                    };
+                    readonly target: {
+                        readonly oneOf: readonly [{
+                            readonly type: "object";
+                            readonly required: readonly ["nodeId", "localOffset"];
+                            readonly properties: {
+                                readonly nodeId: {
+                                    readonly type: "string";
+                                };
+                                readonly localOffset: {
+                                    readonly type: "object";
+                                    readonly required: readonly ["x", "y"];
+                                    readonly properties: {
+                                        readonly x: {
+                                            readonly type: "number";
+                                        };
+                                        readonly y: {
+                                            readonly type: "number";
+                                        };
+                                    };
+                                };
+                            };
+                        }, {
+                            readonly type: "object";
+                            readonly required: readonly ["worldPoint"];
+                            readonly properties: {
+                                readonly worldPoint: {
+                                    readonly type: "object";
+                                    readonly required: readonly ["x", "y"];
+                                    readonly properties: {
+                                        readonly x: {
+                                            readonly type: "number";
+                                        };
+                                        readonly y: {
+                                            readonly type: "number";
+                                        };
+                                    };
+                                };
+                            };
+                        }];
+                    };
+                    readonly pathStyle: {
+                        readonly type: "string";
+                        readonly enum: readonly ["bezier", "straight", "polyline"];
+                    };
+                    readonly z: {
+                        readonly type: "number";
+                    };
+                    readonly groups: {
+                        readonly type: "array";
+                        readonly items: {
+                            readonly type: "string";
+                        };
+                    };
+                    readonly style: {
+                        readonly type: "object";
+                    };
+                    readonly hidden: {
+                        readonly type: "boolean";
+                    };
+                };
+            };
+        };
+    };
+    readonly edgeUpdate: {
+        readonly type: "object";
+        readonly required: readonly ["type", "id", "patch", "prev"];
+        readonly properties: {
+            readonly type: {
+                readonly const: "edge.update";
+            };
+            readonly id: {
+                readonly type: "string";
+            };
+            readonly patch: {
+                readonly type: "object";
+            };
+            readonly prev: {
+                readonly type: "object";
+            };
+        };
+    };
+    readonly edgeRemove: {
+        readonly type: "object";
+        readonly required: readonly ["type", "edge"];
+        readonly properties: {
+            readonly type: {
+                readonly const: "edge.remove";
+            };
+            readonly edge: {
+                readonly type: "object";
+                readonly required: readonly ["id", "source", "target", "pathStyle", "z", "groups"];
+                readonly properties: {
+                    readonly id: {
+                        readonly type: "string";
+                    };
+                    readonly source: {
+                        readonly oneOf: readonly [{
+                            readonly type: "object";
+                            readonly required: readonly ["nodeId", "localOffset"];
+                            readonly properties: {
+                                readonly nodeId: {
+                                    readonly type: "string";
+                                };
+                                readonly localOffset: {
+                                    readonly type: "object";
+                                    readonly required: readonly ["x", "y"];
+                                    readonly properties: {
+                                        readonly x: {
+                                            readonly type: "number";
+                                        };
+                                        readonly y: {
+                                            readonly type: "number";
+                                        };
+                                    };
+                                };
+                            };
+                        }, {
+                            readonly type: "object";
+                            readonly required: readonly ["worldPoint"];
+                            readonly properties: {
+                                readonly worldPoint: {
+                                    readonly type: "object";
+                                    readonly required: readonly ["x", "y"];
+                                    readonly properties: {
+                                        readonly x: {
+                                            readonly type: "number";
+                                        };
+                                        readonly y: {
+                                            readonly type: "number";
+                                        };
+                                    };
+                                };
+                            };
+                        }];
+                    };
+                    readonly target: {
+                        readonly oneOf: readonly [{
+                            readonly type: "object";
+                            readonly required: readonly ["nodeId", "localOffset"];
+                            readonly properties: {
+                                readonly nodeId: {
+                                    readonly type: "string";
+                                };
+                                readonly localOffset: {
+                                    readonly type: "object";
+                                    readonly required: readonly ["x", "y"];
+                                    readonly properties: {
+                                        readonly x: {
+                                            readonly type: "number";
+                                        };
+                                        readonly y: {
+                                            readonly type: "number";
+                                        };
+                                    };
+                                };
+                            };
+                        }, {
+                            readonly type: "object";
+                            readonly required: readonly ["worldPoint"];
+                            readonly properties: {
+                                readonly worldPoint: {
+                                    readonly type: "object";
+                                    readonly required: readonly ["x", "y"];
+                                    readonly properties: {
+                                        readonly x: {
+                                            readonly type: "number";
+                                        };
+                                        readonly y: {
+                                            readonly type: "number";
+                                        };
+                                    };
+                                };
+                            };
+                        }];
+                    };
+                    readonly pathStyle: {
+                        readonly type: "string";
+                        readonly enum: readonly ["bezier", "straight", "polyline"];
+                    };
+                    readonly z: {
+                        readonly type: "number";
+                    };
+                    readonly groups: {
+                        readonly type: "array";
+                        readonly items: {
+                            readonly type: "string";
+                        };
+                    };
+                    readonly style: {
+                        readonly type: "object";
+                    };
+                    readonly hidden: {
+                        readonly type: "boolean";
+                    };
+                };
+            };
+        };
+    };
+    readonly groupUpsert: {
+        readonly type: "object";
+        readonly required: readonly ["type", "group"];
+        readonly properties: {
+            readonly type: {
+                readonly const: "group.upsert";
+            };
+            readonly group: {
+                readonly type: "object";
+                readonly required: readonly ["id", "memberIds"];
+                readonly properties: {
+                    readonly id: {
+                        readonly type: "string";
+                    };
+                    readonly memberIds: {
+                        readonly type: "array";
+                        readonly items: {
+                            readonly type: "string";
+                        };
+                    };
+                    readonly name: {
+                        readonly type: "string";
+                    };
+                };
+            };
+            readonly prev: {
+                readonly type: "object";
+                readonly required: readonly ["id", "memberIds"];
+                readonly properties: {
+                    readonly id: {
+                        readonly type: "string";
+                    };
+                    readonly memberIds: {
+                        readonly type: "array";
+                        readonly items: {
+                            readonly type: "string";
+                        };
+                    };
+                    readonly name: {
+                        readonly type: "string";
+                    };
+                };
+            };
+        };
+    };
+    readonly groupRemove: {
+        readonly type: "object";
+        readonly required: readonly ["type", "group"];
+        readonly properties: {
+            readonly type: {
+                readonly const: "group.remove";
+            };
+            readonly group: {
+                readonly type: "object";
+                readonly required: readonly ["id", "memberIds"];
+                readonly properties: {
+                    readonly id: {
+                        readonly type: "string";
+                    };
+                    readonly memberIds: {
+                        readonly type: "array";
+                        readonly items: {
+                            readonly type: "string";
+                        };
+                    };
+                    readonly name: {
+                        readonly type: "string";
+                    };
+                };
+            };
+        };
+    };
+};
+/**
+ * Tool definition in the Anthropic Messages API shape.
+ */
+type AnthropicToolDef = {
+    name: string;
+    description: string;
+    input_schema: object;
+};
+/**
+ * Returns op schemas wrapped as Anthropic Messages-API tool
+ * definitions. Drop into the `tools` field of a `messages.create`
+ * request to let an agent mutate the canvas directly.
+ *
+ * @example
+ * const response = await anthropic.messages.create({
+ *   model: 'claude-opus-4-7',
+ *   tools: opSchemasAsAnthropicTools(),
+ *   messages: [{ role: 'user', content: 'Add a red sticky note' }],
+ * })
+ * for (const block of response.content) {
+ *   if (block.type === 'tool_use' && block.name.startsWith('canvas_')) {
+ *     const op = toOp(block.name, block.input)
+ *     store.applyOp(op)
+ *   }
+ * }
+ */
+declare const opSchemasAsAnthropicTools: () => AnthropicToolDef[];
+
+/**
+ * Extension system — see ARCHITECTURE.md §13.9.
+ *
+ * The escape hatch for features the core won't ship: snap-to-grid,
+ * alignment guides, minimap, autosave, AI plugins. Extensions get a
+ * store handle + event subscription helper; they can mutate the store
+ * (via the regular API), subscribe to events, and clean up on uninstall.
+ *
+ * Bare-bones by design — anything more (paint hooks, custom handles,
+ * shortcut registration) is a v2 concern. Authors who need those today
+ * can compose them inside `onInstall` against the store directly.
+ */
+type ExtensionApi = {
+    /** The store the extension is attached to. */
+    store: CanvasStore;
+    /**
+     * Subscribe to a store event with automatic cleanup on uninstall —
+     * authors don't have to thread their own teardown.
+     */
+    on<E extends StoreEventName>(event: E, cb: StoreEventHandler<E>): Unsubscribe;
+};
+type Extension = {
+    /** Unique name; one extension per name per store. */
+    name: string;
+    /**
+     * 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`).
+     */
+    onInstall(api: ExtensionApi): undefined | (() => void);
+};
+/**
+ * Defines an extension. Pure identity — exists for symmetry with
+ * `defineNode` and to make call sites read nicely.
+ *
+ * @example
+ * export const snapToGrid = defineExtension({
+ *   name: 'snap-to-grid',
+ *   onInstall: api => {
+ *     api.on('interaction', state => {
+ *       if (state.mode !== 'dragging') return
+ *       const snapped = {
+ *         x: Math.round(state.dragDelta.x / 20) * 20,
+ *         y: Math.round(state.dragDelta.y / 20) * 20,
+ *       }
+ *       api.store.setInteractionState({ dragDelta: snapped })
+ *     })
+ *   },
+ * })
+ */
+declare const defineExtension: (ext: Extension) => Extension;
+/**
+ * Installs an extension against a store. Returns an `uninstall()`
+ * function. Re-installing the same name replaces the previous
+ * instance.
+ *
+ * @example
+ * useEffect(() => {
+ *   if (snapEnabled) return installExtension(store, snapToGrid)
+ * }, [store, snapEnabled])
+ */
+declare const installExtension: (store: CanvasStore, ext: Extension) => Unsubscribe;
+/** Test / debug aid: list installed extension names for a store. */
+declare const installedExtensions: (store: CanvasStore) => string[];
+
+/**
+ * @canvas-harness/core
+ *
+ * Framework-agnostic core for the canvas-harness library.
+ * See ARCHITECTURE.md and IMPLEMENTATION.md at the repo root.
+ *
+ * Phase 1 ships: types, ids, camera, spatial index, store skeleton, codec.
+ */
+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 };