@invana/graph 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,4872 @@
+import { SourceEmitter, CanvasEventBus, ConnectorLabelPlacement, ConnectorLabelStyle, InsetAnchor, ShapeFill, ShapeLabelPlacement, ShapeLabelStyle, WorldLayer, WorldLayerHit, PrimitivesRenderer, LayerOptions, CanvasContext, ScreenLayer, ScreenLayerHit, EventEmitter, Behaviour, BehaviourOptions, ElementSizeLODBehaviour, ElementSizeLODBehaviourOptions, NumberOrGetter } from '@invana/canvas';
+import { RingConnectorDecorationStyle, GlowConnectorDecorationStyle, MarchingAntsConnectorDecorationStyle, RippleConnectorDecorationStyle, FlyMarkerConnectorDecorationStyle, FlowParticlesConnectorDecorationStyle, RevealConnectorDecorationStyle, Point, RingDecorationStyle, GlowDecorationStyle, PulseRingDecorationStyle, MarchingAntsDecorationStyle, LiquidFillDecorationStyle, ToggleDecorationStyle, ResizeHandleDecorationStyle, SelectionFrameDecorationStyle, TogglePlacement, Rect } from '@invana/canvas/primitives';
+
+/**
+ * `@invana/graph` — `GraphStore` type definitions.
+ *
+ * See `apps/docs/graph/data-model.md` for the user-facing description and
+ * `apps/docs/graph/store-plan.md` for the implementation rationale.
+ *
+ * **v3 G6-aligned shape**: per-instance descriptor is flat with
+ * `{ id, type, data, style, state, states, combo, children, ... }`.
+ * `state` (singular) is the per-instance overlay catalogue;
+ * `states` (plural) is the active-state list.
+ */
+/** A node in the graph. `id` is unique within a `GraphStore`. */
+interface GraphNode<D = unknown> {
+    /** Stable identity. Must be unique within the store. */
+    id: string;
+    /** Type tag — matches a `NodeOption.type` template if any. Free-form. */
+    type?: string;
+    /** Arbitrary user payload — opaque to the store. */
+    data?: D;
+    /** Logical parent. Cycles are rejected at write time. */
+    parentId?: string;
+    /** Canonical position. Owned by the store; mutated by layouts and drags. */
+    position?: {
+        x: number;
+        y: number;
+    };
+    /** True iff layouts must not move this node. */
+    pinned?: boolean;
+    /**
+     * Currently-active state names (plural). Each name should match a key in
+     * `style.state` (per-instance overlay catalogue) or in
+     * `GraphLayerOptions.node.state` (layer-level catalogue).
+     *
+     * The store treats this field as opaque metadata. The layer reads it on
+     * insert and update to toggle visual states via `setNodeState`. On
+     * update with `states` present in the patch the layer REPLACES the
+     * visible state set with the new array — runtime states applied via
+     * `setNodeState` (e.g. hover) are wiped. Pass an empty array (or
+     * `null`) to clear.
+     */
+    states?: readonly string[] | null;
+    /**
+     * Visual + structural style for this node. Typed via
+     * `import('../layer/types').NodeStyle` in consumer code; left as `unknown`
+     * here to avoid a store → layer dependency cycle.
+     */
+    style?: unknown;
+    /**
+     * Per-instance overlay catalogue keyed by state name (singular `state`).
+     * Each value is a `NodeStyle` patch applied when that name appears in
+     * {@link states}. Typed by the consumer as
+     * `Readonly<Record<string, NodeStyle>>`.
+     */
+    state?: unknown;
+}
+/** A directed edge. Multi-edges between the same pair are allowed. */
+interface GraphEdge<D = unknown> {
+    /** Stable identity. Must be unique within the store. */
+    id: string;
+    /** Source node id. */
+    source: string;
+    /** Target node id. */
+    target: string;
+    /** Predicate / FK label / "calls" / "depends-on" — free-form. */
+    type?: string;
+    /** Arbitrary user payload — opaque to the store. */
+    data?: D;
+    /** Sibling of {@link GraphNode.states} — currently-active state names. */
+    states?: readonly string[] | null;
+    /** Per-instance style. Typed by consumer as `EdgeStyle`. */
+    style?: unknown;
+    /** Per-instance overlay catalogue. Typed by consumer as `Record<string, EdgeStyle>`. */
+    state?: unknown;
+}
+/**
+ * Constructor options for `GraphStore`.
+ *
+ * Defaults are tuned for sync, single-process, batch-driven use. Streaming
+ * feeds should set `flushMode: 'frame'` and `unknownEndpoint: 'buffer'`.
+ */
+interface GraphStoreOptions {
+    /**
+     * `'sync'` — events fire synchronously at each mutation / on `batch` exit.
+     * `'frame'` — events coalesce into a single flush per animation frame.
+     * Default `'sync'`.
+     */
+    flushMode?: 'sync' | 'frame';
+    /**
+     * What to do when `addEdge` is called with an unknown source or target id.
+     * - `'throw'` (default) — reject and throw.
+     * - `'buffer'` — park in the pending-edge buffer; admit when the endpoint arrives.
+     * - `'drop'` — silently discard.
+     */
+    unknownEndpoint?: 'throw' | 'buffer' | 'drop';
+    /**
+     * Drop a buffered edge (and emit `edge:orphaned`) if it has been pending
+     * for more than this many frames. Default `Infinity` (never expire).
+     * Only meaningful with `unknownEndpoint: 'buffer'`.
+     */
+    pendingEdgeTTL?: number;
+    /**
+     * Initial slot capacity for the underlying `ColumnStore`s. Larger up-front
+     * capacity avoids early geometric growth on bulk inserts. Default 256.
+     */
+    initialCapacity?: number;
+    /**
+     * Identity for the store's event-source envelopes on the canvas tap channel
+     * (telemetry). Becomes `source.id` on every `{ kind: 'store' }` event the bus
+     * publishes. Default `'graph-store'`; pass the owning layer's id to
+     * disambiguate multiple graphs. See `store-owns-state-plan.md` § 6.
+     */
+    id?: string;
+}
+/**
+ * Event-map shape for `GraphStore.events` (used by `EventEmitter<E>`).
+ *
+ * Subscribe to fine-grained `node:*` / `edge:*` events for per-entity updates,
+ * or to `flush` for aggregated per-batch counts.
+ */
+type GraphStoreEventMap = {
+    'node:add': {
+        nodeId: string;
+    };
+    'node:update': {
+        nodeId: string;
+        patch: Partial<GraphNode>;
+    };
+    'node:remove': {
+        nodeId: string;
+    };
+    'edge:add': {
+        edgeId: string;
+    };
+    'edge:update': {
+        edgeId: string;
+        patch: Partial<GraphEdge>;
+    };
+    'edge:remove': {
+        edgeId: string;
+    };
+    /** Emitted when a buffered edge is dropped after exceeding `pendingEdgeTTL`. */
+    'edge:orphaned': {
+        edgeId: string;
+    };
+    /**
+     * A runtime (presence) state was toggled on a node — `on` reflects the
+     * post-change membership of the runtime set. Fired per-toggle on flush,
+     * deduped per `(id, name)` within the flush window. `actor` is reserved for
+     * collaboration (the originating user); `undefined` in single-user mode.
+     * Document `states[]` changes ride `node:update`, not this event.
+     */
+    'node:state': {
+        nodeId: string;
+        name: string;
+        on: boolean;
+        actor?: string;
+    };
+    /** Edge sibling of `node:state`. */
+    'edge:state': {
+        edgeId: string;
+        name: string;
+        on: boolean;
+        actor?: string;
+    };
+    /** Aggregate counts per flush. Fires once per batch / RAF flush. */
+    flush: {
+        addedNodes: number;
+        updatedNodes: number;
+        removedNodes: number;
+        addedEdges: number;
+        updatedEdges: number;
+        removedEdges: number;
+    };
+};
+/** Direction of an adjacency / neighbor query. */
+type EdgeDirection = 'in' | 'out' | 'both';
+/** Position record (used by `getPosition` / `setPosition`). */
+interface Vec2 {
+    x: number;
+    y: number;
+}
+
+/**
+ * `GraphStore` — the domain primitive for `@invana/graph`.
+ *
+ * Composes two `ColumnStore`s (from `@invana/canvas`) for hot fields plus
+ * `Map<id, payload>` for cold fields. Adjacency uses per-slot `Int32Array`
+ * indices via {@link AdjacencyIndex}. Streaming feeds get RAF-coalesced
+ * flushing via {@link FrameFlushScheduler} and out-of-order edge handling
+ * via {@link PendingEdges}.
+ *
+ * See `apps/docs/graph/data-model.md` for the user-facing description and
+ * `apps/docs/graph/store-plan.md` for the implementation rationale.
+ */
+
+declare class GraphStore {
+    private readonly flushMode;
+    private readonly unknownEndpoint;
+    private readonly pendingEdgeTTL;
+    private readonly nodeCols;
+    private readonly edgeCols;
+    private readonly nodeMap;
+    private readonly edgeMap;
+    private readonly childrenIndex;
+    private readonly nodeRuntimeStates;
+    private readonly edgeRuntimeStates;
+    private readonly outAdj;
+    private readonly inAdj;
+    private readonly pending;
+    /**
+     * Public event bus. Subscribe via `store.events.on('node:add', ...)`.
+     *
+     * A `SourceEmitter` (`{ kind: 'store' }`): once the owning layer calls
+     * {@link bindBus} on mount, every emit also publishes a `CanvasEvent` envelope
+     * to the canvas tap channel, so telemetry sees all store mutations
+     * (`store-owns-state-plan.md` § 6).
+     */
+    readonly events: SourceEmitter<GraphStoreEventMap>;
+    /** Per-flush counters. Reset on `flush()`. */
+    private counters;
+    /** Pending dedup-ed event payloads to fire on the next flush. */
+    private pendingNodeAdds;
+    private pendingNodeUpdates;
+    private pendingNodeRemoves;
+    private pendingEdgeAdds;
+    private pendingEdgeUpdates;
+    private pendingEdgeRemoves;
+    private pendingEdgeOrphans;
+    /**
+     * Pending runtime-state toggles, keyed by `"<id>\u0000<name>"` so repeated
+     * toggles of the same (id, name) within a flush window collapse to one event.
+     * The emitted `on` is read from live set membership at flush time, so an
+     * add+remove in the same frame nets out correctly.
+     */
+    private pendingNodeStates;
+    private pendingEdgeStates;
+    /** Depth of nested `batch()` calls. Flushes only on outermost exit. */
+    private batchDepth;
+    private flushScheduler;
+    /** Monotonic version counter. Bumps on every mutation including silent. */
+    private _version;
+    /**
+     * Monotonic flush counter. Bumps on every `doFlush` regardless of which
+     * code path triggered the flush. Used by `PendingEdges` TTL accounting.
+     */
+    private _frame;
+    constructor(opts?: GraphStoreOptions);
+    /**
+     * Attach (or detach with `undefined`) the canvas event bus this store's
+     * events forward to. Called by the owning `GraphLayer` on mount/unmount so
+     * store mutations reach the telemetry tap channel (§ 6). Local
+     * `store.events.on(...)` subscribers work with or without a bus.
+     */
+    bindBus(bus: CanvasEventBus | undefined): void;
+    /** Monotonic counter. Bumps on every mutation including silent position writes. */
+    get version(): number;
+    /** Number of live (non-tombstoned) nodes. */
+    nodeCount(): number;
+    /** Number of live (non-tombstoned) edges. */
+    edgeCount(): number;
+    hasNode(id: string): boolean;
+    hasEdge(id: string): boolean;
+    getNode<D = unknown>(id: string): GraphNode<D> | undefined;
+    getEdge<D = unknown>(id: string): GraphEdge<D> | undefined;
+    nodes(): IterableIterator<GraphNode>;
+    edges(): IterableIterator<GraphEdge>;
+    outDegree(nodeId: string): number;
+    inDegree(nodeId: string): number;
+    /**
+     * Yield edges incident to `nodeId` in the requested direction.
+     * `'out'` — edges where `nodeId` is the source.
+     * `'in'`  — edges where `nodeId` is the target.
+     * `'both'` — out then in.
+     */
+    edgesOf(nodeId: string, dir?: EdgeDirection): IterableIterator<GraphEdge>;
+    /** Yield neighbor node ids in the requested direction. */
+    neighborsOf(nodeId: string, dir?: EdgeDirection): IterableIterator<string>;
+    parentOf(id: string): string | undefined;
+    childrenOf(parentId: string): IterableIterator<string>;
+    descendantsOf(id: string): IterableIterator<string>;
+    ancestorsOf(id: string): IterableIterator<string>;
+    getPosition(id: string): Vec2 | undefined;
+    /**
+     * Set a single node's position.
+     *
+     * Default fires `node:update`. `opts.silent: true` skips the event and just
+     * bumps `version` — use for layout sim ticks at 60fps.
+     */
+    setPosition(id: string, pos: Vec2, opts?: {
+        silent?: boolean;
+    }): void;
+    /**
+     * Set many positions in a single tight loop.
+     *
+     * `xy` is packed `[x0, y0, x1, y1, ...]` (length must equal `ids.length * 2`).
+     * `opts.silent: true` skips events — sim-tick fastpath. Otherwise emits one
+     * deduped `node:update` per id.
+     */
+    setPositionsBulk(ids: readonly string[], xy: Float32Array, opts?: {
+        silent?: boolean;
+    }): void;
+    setPinned(id: string, pinned: boolean): void;
+    isPinned(id: string): boolean;
+    pinnedIds(): IterableIterator<string>;
+    /** Strict add — throws on duplicate. */
+    addNode<D>(node: GraphNode<D>): void;
+    /** Add-or-merge. Streaming-friendly path. */
+    upsertNode<D>(node: GraphNode<D>): void;
+    updateNode<D>(id: string, patch: Partial<GraphNode<D>>): void;
+    /**
+     * Remove a node. Cascades by default — removes all incident edges first.
+     * `cascade: false` throws if any incident edges still exist.
+     */
+    removeNode(id: string, opts?: {
+        cascade?: boolean;
+    }): void;
+    addEdge<D>(edge: GraphEdge<D>): void;
+    upsertEdge<D>(edge: GraphEdge<D>): void;
+    updateEdge<D>(id: string, patch: Partial<GraphEdge<D>>): void;
+    /**
+     * Reverse an edge's direction — swap its `source` and `target`. No-op if the
+     * edge doesn't exist. Routes through {@link updateEdge}, so adjacency indexes
+     * are rewired and an `edge:update` is enqueued like any other re-pointing.
+     */
+    reverseEdge(id: string): void;
+    removeEdge(id: string): void;
+    /**
+     * Add a runtime (presence) state to a node. Idempotent — re-adding an already
+     * active state is a no-op (no event). No-op if the node id is unknown.
+     *
+     * @param id    Node id.
+     * @param name  State name (e.g. `'selected'`, `'highlighted'`, `'lineage'`).
+     * @param _opts Reserved for collaboration — `actor` will tag the change with
+     *   its originating user once presence replication lands (§ 5). Unused today.
+     */
+    addNodeState(id: string, name: string, _opts?: {
+        actor?: string;
+    }): void;
+    /**
+     * Remove a runtime (presence) state from a node. No-op if the state isn't
+     * currently active (no event) or the node is unknown.
+     */
+    removeNodeState(id: string, name: string, _opts?: {
+        actor?: string;
+    }): void;
+    /**
+     * Toggle a runtime (presence) state on a node — `on ? addNodeState :
+     * removeNodeState`. Convenience for callers (e.g. hover) that compute the
+     * desired membership as a boolean. Default `on = true`.
+     */
+    setNodeState(id: string, name: string, on?: boolean, opts?: {
+        actor?: string;
+    }): void;
+    /** Toggle a runtime (presence) state on an edge. See {@link setNodeState}. */
+    setEdgeState(id: string, name: string, on?: boolean, opts?: {
+        actor?: string;
+    }): void;
+    /**
+     * Strip a runtime (presence) state from every node that carries it, in one
+     * pass — e.g. clearing a transient `'selected'` / `'lineage'` set. Touches the
+     * presence compartment only; a document state of the same name in `states[]`
+     * is unaffected (change those via {@link updateNode}).
+     */
+    clearNodeState(name: string): void;
+    /** Add a runtime (presence) state to an edge. See {@link addNodeState}. */
+    addEdgeState(id: string, name: string, _opts?: {
+        actor?: string;
+    }): void;
+    /** Remove a runtime (presence) state from an edge. See {@link removeNodeState}. */
+    removeEdgeState(id: string, name: string, _opts?: {
+        actor?: string;
+    }): void;
+    /** Strip a runtime (presence) state from every edge. See {@link clearNodeState}. */
+    clearEdgeState(name: string): void;
+    /**
+     * Effective active states of a node — the **union** of its document `states[]`
+     * (feed-owned) and its runtime presence set. This is what the renderer iterates
+     * to apply state overlays. Returns a fresh array; empty if the node is unknown
+     * or carries no states.
+     */
+    nodeStatesOf(id: string): readonly string[];
+    /** Effective active states of an edge — union of document + presence. */
+    edgeStatesOf(id: string): readonly string[];
+    /** True iff `name` is in a node's effective (document ∪ presence) state set. */
+    hasNodeState(id: string, name: string): boolean;
+    /** True iff `name` is in an edge's effective (document ∪ presence) state set. */
+    hasEdgeState(id: string, name: string): boolean;
+    /**
+     * Ids of every node whose effective (document ∪ presence) state set contains
+     * `name`. Scans live nodes; useful for snapshots / iteration.
+     */
+    nodesWithState(name: string): IterableIterator<string>;
+    /** Edge sibling of {@link nodesWithState}. */
+    edgesWithState(name: string): IterableIterator<string>;
+    addNodesBulk(nodes: readonly GraphNode[]): void;
+    addEdgesBulk(edges: readonly GraphEdge[]): void;
+    /**
+     * Append nodes + edges in one batch — non-destructive (does NOT clear).
+     * Convenience for streaming feeds that push a fresh chunk of items as
+     * they arrive. Subscribers see a single `flush`.
+     *
+     * Differs from `GraphLayer.setData`, which clears the store first.
+     */
+    addData(data: {
+        nodes?: readonly GraphNode[];
+        edges?: readonly GraphEdge[];
+    }): void;
+    /**
+     * Apply a streaming delta in a single batch. Order within the batch:
+     * 1. `removed.edgeIds`  — removed first so node removals can't cascade
+     *    them again (no-op double removal is harmless, but explicit is cleaner).
+     * 2. `removed.nodeIds`  — cascade-removes incident edges per `removeNode`'s
+     *    default `cascade: true`.
+     * 3. `added.nodes`      — `upsertNode` (idempotent; safe to re-send).
+     * 4. `added.edges`      — `upsertEdge`.
+     * 5. `updated.nodes`    — partial patches via `updateNode`.
+     * 6. `updated.edges`    — partial patches via `updateEdge`.
+     *
+     * Use `upsertNode` / `upsertEdge` for the `added` lists so a feed that
+     * re-sends an existing id (common in pub-sub) merges rather than throwing.
+     * If you have hard-add semantics, use `addData` instead.
+     *
+     * Subscribers see one `flush` regardless of how many items were touched.
+     */
+    applyDelta(delta: {
+        added?: {
+            nodes?: readonly GraphNode[];
+            edges?: readonly GraphEdge[];
+        };
+        updated?: {
+            nodes?: ReadonlyArray<{
+                id: string;
+                patch: Partial<GraphNode>;
+            }>;
+            edges?: ReadonlyArray<{
+                id: string;
+                patch: Partial<GraphEdge>;
+            }>;
+        };
+        removed?: {
+            nodeIds?: readonly string[];
+            edgeIds?: readonly string[];
+        };
+    }): void;
+    /**
+     * Coalesce all mutations inside `fn` into a single flush. Nested `batch`
+     * calls flush only on the outermost exit.
+     */
+    batch<T>(fn: () => T): T;
+    /**
+     * Drain any pending events. Cancels the RAF-scheduled flush (frame mode).
+     * In sync mode this still works — handy for forcing the TTL eviction sweep
+     * even if no mutation has happened since the last flush.
+     */
+    flush(): void;
+    /** Wipe all data. Cancels any pending flush. */
+    clear(): void;
+    /**
+     * Reclaim tombstoned slots. Invalidates any external code that cached
+     * slot indices. Renderer batch buffers etc. must invalidate first.
+     */
+    compact(): void;
+    private installNode;
+    private installEdge;
+    private handleUnknownEndpoint;
+    private tryAdmitPending;
+    /** True iff `candidateAncestor` is already a descendant of `id`. */
+    private wouldCreateCycle;
+    private readPosition;
+    private enqueueNodeAdd;
+    private enqueueNodeUpdate;
+    private enqueueNodeRemove;
+    private enqueueEdgeAdd;
+    private enqueueEdgeUpdate;
+    private enqueueEdgeRemove;
+    private enqueueEdgeOrphan;
+    /** Queue a node runtime-state change, deduped per `(id, name)` per flush. */
+    private enqueueNodeState;
+    /** Queue an edge runtime-state change, deduped per `(id, name)` per flush. */
+    private enqueueEdgeState;
+    private scheduleFlushIfNeeded;
+    private doFlush;
+}
+
+/**
+ * A field value that's either a static value or a function that derives the
+ * value from the host item (node / edge / raw data).
+ *
+ * Used on every field of `NodeStyle` / `EdgeStyle` (via `ResolvableNodeStyle`
+ * / `ResolvableEdgeStyle`) so callers can supply per-item-derived styling
+ * on the layer template (`options.node.style`) or per-instance input
+ * (`NodeInput.style`) without spreading hints into every node's `data`.
+ *
+ * Resolved per render (layer-level) or once at insert (per-input). Keep
+ * resolvers cheap and pure — they may run per frame. Recursive returns
+ * (a function returning another function) are not unwrapped — return the
+ * final value.
+ *
+ * @example
+ * ```ts
+ * node: {
+ *   style: {
+ *     bgFill:    (n) => groupColors[(n.data as Group).group % groupColors.length],
+ *     shape:     (n) => ({ kind: 'circle', radius: 12 + Math.sqrt((n.data as N).degree ?? 1) * 4 }),
+ *     labelText: (n) => (n.data as N).name,
+ *   },
+ * }
+ * ```
+ */
+type Resolvable<T, I> = T | ((input: I) => T);
+/** Convenience alias for id-resolvers; `D` is the raw data type on input. */
+type ResolvableId<D> = string | ((data: D) => string);
+/**
+ * Unwrap a {@link Resolvable} field for `input`. Static values pass through
+ * untouched; function values are invoked once with `input` and their return
+ * is used. Functions returning further functions are NOT unwrapped — return
+ * the final value.
+ */
+declare function resolveField<T, I>(v: Resolvable<T, I> | undefined, input: I): T | undefined;
+/** Path-style shortcut for an edge. Maps to the canvas router + pathStyle pair. */
+type EdgePathType = 'straight' | 'bezier' | 'quadratic' | 'bump-radial' | 'bump-horizontal' | 'step-radial' | 'orth' | 'manhattan' | 'rounded' | 'smooth' | 'bundle' | 'loop-curve' | 'loop-polyline';
+/**
+ * Endpoint anchor.
+ *
+ * - `'boundary'` (default) — trim the endpoint at the node's outline along
+ *   the line from the other endpoint. Visually the edge stops at the node
+ *   boundary; works with arrows and connector decorations cleanly.
+ * - `'center'` — leave the endpoint at the node's centre. The edge passes
+ *   through the node visually; rely on z-order (nodes drawn on top) to make
+ *   it look like the edge terminates at the boundary. Pick this for radial
+ *   layouts so polar pathStyles (e.g. `bump-radial`) compute their tangent
+ *   from the true node-centre angle rather than the trimmed cut point.
+ * - `'perpendicular'` — exit / enter perpendicular to the host edge of a
+ *   rect-like node. Reserved for box-shaped nodes.
+ * - `'edge-port'` — attach to a specific point on one face of the node's
+ *   bounding box, picked by `{ side, offset }` on the per-endpoint
+ *   `sourceAnchorOpts` / `targetAnchorOpts`. Used by the Sankey layout to
+ *   stack ribbons along the right face of source and left face of target.
+ *
+ * Widened to `string` so anchors registered at runtime (e.g. domain-specific
+ * port anchors) can be referenced by name.
+ */
+type EdgeAnchor = 'boundary' | 'center' | 'perpendicular' | 'edge-port' | (string & {});
+/** Initial-load shape passed to `graphLayer.setData(data)`. */
+interface GraphData {
+    nodes: GraphNode[];
+    edges: GraphEdge[];
+}
+/**
+/**
+ * Canonical interaction-state names with sensible defaults baked into the
+ * GraphLayer's resolver. State styling lives on the layer-level
+ * {@link NodeOption.state} / per-node {@link NodeData.state} catalogue —
+ * `default` is intentionally absent (it's the absence of any active state,
+ * not a state itself).
+ *
+ * The state-config map is open-keyed: consumers can declare additional
+ * named states (e.g. `'pinned'`, `'flagged'`, `'error'`, `'focused'`)
+ * directly on `options.node.state` / `node.state` with the same shape —
+ * they compose via the same merge rules. The canonical set below is
+ * deliberately small; reach for it only when the named driver applies.
+ *
+ * ### Driver → state map
+ *
+ * Each canonical state has a distinct *driver* (what causes the state to
+ * be written) and *lifetime* (when it clears). The visual treatments
+ * overlap (most are stroke rings of various colours), but the semantics
+ * do not — a single node can carry several states simultaneously (e.g.
+ * `selected + hover`) and a behaviour should only write the states it
+ * owns.
+ *
+ * | State         | Driver                                    | Lifetime                          | Cardinality       |
+ * | ------------- | ----------------------------------------- | --------------------------------- | ----------------- |
+ * | `hovered`     | Mouse / touch pointer-over                | Transient — clears on pointer-out | ≤ 1 per layer     |
+ * | `selected`    | Click / lasso / brush — user's chosen set | Sticky until explicitly cleared   | 0–N per layer     |
+ * | `highlighted` | 1-hop neighbours of the hovered / selected | Transient — clears with the driver | 0–N per layer    |
+ * | `dimmed`      | Complement of the focal-emphasis set      | Transient — clears with the driver | 0–N per layer    |
+ * | `disabled`    | Data flag — "not interactive"             | Sticky — owned by the data feed   | 0–N per layer     |
+ *
+ * ### Sticky chosen set — `selected`
+ *
+ * `selected` is the click / lasso / brush state — what the user *chose*.
+ * Persists until explicitly deselected. **Multi-select doesn't need its
+ * own state**: it's just the same `selected` state applied to every
+ * member of `selectedIds: Set<string>`. One node selected → one ring;
+ * ten nodes selected → ten rings.
+ *
+ * `selected` can co-exist with `hovered` — clicking a node doesn't stop
+ * it from being hovered.
+ *
+ * ### Focal-emphasis flow — `highlighted` + `dimmed`
+ *
+ * Written together by a focal-emphasis behaviour (typically driven by
+ * hover or selection). When the user hovers / selects a node:
+ * - its 1-hop neighbours go `highlighted` — *supporting cast*,
+ * - everyone else goes `dimmed` — *pushed back so the focal set pops*.
+ *
+ * Both clear together when emphasis ends. Drop the pair if the product
+ * never needs the "fade everyone except the focal subgraph" interaction.
+ *
+ * ### Data-driven — `disabled`
+ *
+ * Sticky and owned by the data feed (not by an interaction behaviour).
+ * `disabled` is "this node isn't interactive — don't let the user pick
+ * it". Visually overlaps `dimmed` but they're semantically distinct:
+ * - `dimmed` says *"you're focusing elsewhere"* (transient, behaviour).
+ * - `disabled` says *"you can't interact with me"* (sticky, data).
+ * Conflating them would couple interaction code to data code — keep them
+ * separate even if the visual treatment is similar.
+ */
+type CanonicalStateName = 
+/** Mouse / touch pointer is over the node. Transient; one node at a time. */
+'hovered'
+/** User's chosen set (click / lasso / brush). Sticky; many at a time. Multi-select is just this state applied to each member of the selection. */
+ | 'selected'
+/** 1-hop neighbour of the hovered / selected focal — "supporting cast". Transient; cleared with the focal. */
+ | 'highlighted'
+/** Complement of the focal-emphasis set — pushed back so `selected` + `highlighted` pop. Transient. NOT `disabled` — that's a data flag. */
+ | 'dimmed'
+/** Data flag: "not interactive". Sticky; owned by the data feed. Visually similar to `dimmed` but semantically distinct (data, not interaction). */
+ | 'disabled';
+/** Rect-shape option. `cornerRadius` is optional; everything else required. */
+interface RectShapeOption {
+    readonly kind: 'rect';
+    readonly width: number;
+    readonly height: number;
+    readonly cornerRadius?: number;
+}
+/** Circle-shape option. */
+interface CircleShapeOption {
+    readonly kind: 'circle';
+    readonly radius: number;
+}
+/** Arc (annular sector) shape option. All four geometry params required. */
+interface ArcShapeOption {
+    readonly kind: 'arc';
+    readonly innerR: number;
+    readonly outerR: number;
+    readonly startAngle: number;
+    readonly endAngle: number;
+}
+/**
+ * Regular n-gon. With `rotation = 0` the first vertex points straight up, so
+ * a triangle / pentagon / hexagon points up by default. Pass
+ * `rotation: Math.PI / sides` for flat-top.
+ */
+interface RegularPolygonShapeOption {
+    readonly kind: 'regular-polygon';
+    readonly sides: number;
+    readonly radius: number;
+    readonly rotation?: number;
+}
+/**
+ * N-pointed star. Classic 5-point star uses
+ * `{ points: 5, outerRadius: r, innerRadius: r * 0.4 }`.
+ */
+interface StarShapeOption {
+    readonly kind: 'star';
+    readonly points: number;
+    readonly innerRadius: number;
+    readonly outerRadius: number;
+    readonly rotation?: number;
+}
+/**
+ * Free-form polygon. `vertices` are centre-relative — closed implicitly
+ * (last vertex connects to first).
+ */
+interface PolygonShapeOption {
+    readonly kind: 'polygon';
+    readonly vertices: ReadonlyArray<Point>;
+}
+/**
+ * Escape-hatch variant for shape kinds registered at runtime via
+ * `canvas.primitives.registerShape(name, ctor)`. The widened `kind` accepts
+ * any string the type-checker can't match against a built-in variant;
+ * additional spec params are erased at the type level but pass through to
+ * the renderer untouched at runtime (the adapter spreads the whole shape
+ * record into the spec).
+ *
+ * Authors of custom shapes typically declare a local interface
+ * (`interface ChevronShapeOption { kind: 'chevron'; size: number }`) and
+ * cast at the boundary (`style: { shape: chevron as NodeShapeOptions }`).
+ * The index signature was deliberately omitted here so that discriminant
+ * narrowing on the typed built-in variants (`shape.kind === 'rect'` →
+ * `RectShapeOption`) keeps working everywhere else in the codebase.
+ *
+ * Built-in kinds (`'rect'`, `'circle'`, `'arc'`, `'regular-polygon'`,
+ * `'star'`, `'polygon'`) are matched by the typed variants above before
+ * this fallback applies.
+ */
+interface CustomShapeOption {
+    readonly kind: string & {};
+}
+/**
+ * Closed union of the six shape kinds that `@invana/canvas` registers out
+ * of the box. Exported so internal switch-narrowing sites can target it
+ * directly via the {@link isBuiltInNodeShape} type guard.
+ */
+type BuiltInNodeShapeOptions = RectShapeOption | CircleShapeOption | ArcShapeOption | RegularPolygonShapeOption | StarShapeOption | PolygonShapeOption;
+/**
+ * Discriminated union of node shape options. The `kind` field enforces
+ * per-variant required fields at compile time for the six built-in kinds
+ * registered by `@invana/canvas`. {@link CustomShapeOption} provides an
+ * open-keyed fallback for shapes registered at runtime by the consumer.
+ *
+ * Internal call sites that need to read variant-specific fields should
+ * narrow via the {@link isBuiltInNodeShape} type guard first — the
+ * open-keyed `CustomShapeOption.kind` prevents `switch (shape.kind)` over
+ * literals from excluding the custom variant on its own.
+ */
+type NodeShapeOptions = BuiltInNodeShapeOptions | CustomShapeOption;
+/**
+ * Type guard separating the typed built-in variants from
+ * {@link CustomShapeOption}. Use this before reading variant-specific
+ * fields so TypeScript narrows cleanly inside each `case`.
+ */
+declare function isBuiltInNodeShape(shape: NodeShapeOptions): shape is BuiltInNodeShapeOptions;
+/**
+ * Vector inset rendered inside a node's body — glyph (font codepoint), SVG
+ * path, or SVG by URL. Kept structured (discriminated union) because each
+ * kind carries different required params.
+ */
+type NodeIcon = {
+    readonly kind: 'glyph';
+    readonly char: string;
+    readonly fontFamily?: string;
+    readonly fontWeight?: number | string;
+    readonly fontStyle?: 'normal' | 'italic';
+    readonly color?: number;
+    readonly alpha?: number;
+    readonly sizeRatio?: number;
+    readonly anchor?: InsetAnchor;
+} | {
+    readonly kind: 'svg';
+    readonly pathD: string;
+    readonly viewBox?: {
+        readonly width: number;
+        readonly height: number;
+    };
+    readonly strokeWidth?: number;
+    readonly color?: number;
+    readonly alpha?: number;
+    readonly sizeRatio?: number;
+    readonly anchor?: InsetAnchor;
+} | {
+    readonly kind: 'svg-url';
+    readonly url: string;
+    readonly viewBox?: {
+        readonly width: number;
+        readonly height: number;
+    };
+    readonly strokeWidth?: number;
+    readonly color?: number;
+    readonly alpha?: number;
+    readonly sizeRatio?: number;
+    readonly anchor?: InsetAnchor;
+};
+/**
+ * Raster image attached to a node. Mirrors the canvas-level `kind: 'image'`
+ * `ShapeFillLayer` field-for-field. Two orthogonal sizing knobs:
+ *
+ * - `fit` (default `'cover'`) — `'cover'` scales by `max(...)` and fully
+ *   covers the silhouette's AABB (may crop on the cross-axis);
+ *   `'contain'` scales by `min(...)` and fully fits, leaving the
+ *   cross-axis margin transparent (the underlying `bgFill` reads
+ *   through; the texture sampler is pinned to `clamp-to-edge` so the
+ *   margin doesn't tile).
+ * - `padding` (default `0`) — pixel inset on the silhouette before fit
+ *   math runs. The silhouette is re-traced at that inset for the image
+ *   layer only, so the gap between full and inset silhouette paints
+ *   from layers underneath (typically a `solid` `bgFill`). Useful when
+ *   the host silhouette is more restrictive than its AABB (circle,
+ *   polygon, star, arc) and texture corners would otherwise clip
+ *   against the curve.
+ */
+interface NodeImage {
+    readonly url: string;
+    readonly alpha?: number;
+    readonly fit?: 'cover' | 'contain';
+    readonly padding?: number;
+}
+/**
+ * Anchor point on the host node where a badge attaches. The eight cardinal
+ * names address the midpoints / corners of the host's axis-aligned bounding
+ * box; the `{ x, y }` variant pins to an explicit world point and is rarely
+ * needed (use {@link NodeBadge.offsetX} / `offsetY` to nudge an enum anchor
+ * before reaching for raw coordinates).
+ */
+type BadgePlacement = 'top-right' | 'top-left' | 'bottom-right' | 'bottom-left' | 'top' | 'bottom' | 'left' | 'right' | {
+    readonly x: number;
+    readonly y: number;
+};
+/**
+ * Point on the badge's own AABB that lands at the host anchor.
+ *
+ * - The eight cardinal names mirror {@link BadgePlacement} (without the
+ *   custom `{x, y}` variant — origin is always a named point on the badge).
+ * - `'center'` centres the badge on the host anchor — yields the classic
+ *   "half-overhanging" notification-bubble look.
+ *
+ * When omitted, the projection defaults to the **mirror** of `placement`
+ * (e.g. `placement: 'top-right'` → origin `'bottom-left'`) so the badge
+ * sits fully outside the host edge.
+ */
+type BadgeOrigin = 'top-right' | 'top-left' | 'bottom-right' | 'bottom-left' | 'top' | 'bottom' | 'left' | 'right' | 'center';
+/**
+ * Host-modulation effects on a badge. Re-exports the {@link NodeEffects}
+ * surface because a badge is rendered as a shape under the hood — the same
+ * `shake` / `breathing` / future shape-effect kinds apply field-for-field.
+ */
+type BadgeEffects = NodeEffects;
+/**
+ * Small overlay attached to a node — e.g. notification dot, count chip,
+ * status indicator. A badge is rendered as a real shape, so it inherits the
+ * full shape surface: any registered {@link NodeShapeOptions} kind as the
+ * plate, optional {@link NodeIcon} as content, optional label text, plus
+ * nested {@link decorations} / {@link effects} that compose exactly the way
+ * they do on a node body.
+ *
+ * Position resolves from the host's AABB + the `placement` anchor + an
+ * `origin` (which point of the badge sits at the anchor — defaults to the
+ * mirror of `placement` so the badge nests fully outside the host edge).
+ * Use `'center'` for the half-overhanging notification-bubble look.
+ */
+interface NodeBadge {
+    /**
+     * Stable id within the node, for keyed updates / state-overlay diffing.
+     * When omitted, identity falls back to the badge's position in the
+     * containing `badges[]` array.
+     */
+    readonly id?: string;
+    /** Anchor point on the host node's AABB, or an explicit world point. */
+    readonly placement: BadgePlacement;
+    /**
+     * Which point of the badge's own AABB lands at the host anchor.
+     * Default: mirror of `placement` (badge sits fully outside the host edge).
+     * Use `'center'` for the half-overhanging look.
+     */
+    readonly origin?: BadgeOrigin;
+    /**
+     * Pure geometry — any registered {@link NodeShapeOptions} kind. Fill /
+     * stroke / alpha come from the flat sugar fields below, mirroring the
+     * `NodeStyle.shape` + `bgFill` split used for node bodies.
+     */
+    readonly shape: NodeShapeOptions;
+    /** Solid plate colour — projects to the badge shape's first fill layer. */
+    readonly fill?: number;
+    readonly alpha?: number;
+    readonly strokeColor?: number;
+    readonly strokeWidth?: number;
+    /**
+     * Vector inset rendered inside the badge plate (glyph / svg / svg-url).
+     * Projects to an extra fill layer stacked on top of the solid plate.
+     */
+    readonly icon?: NodeIcon;
+    /**
+     * Optional short text rendered centred on the badge (count "3", "!").
+     * Projects to a `'label'` decoration on the badge.
+     */
+    readonly labelText?: string;
+    readonly labelColor?: number;
+    readonly labelFontSize?: number;
+    /** Pixel offset applied after placement resolution. */
+    readonly offsetX?: number;
+    readonly offsetY?: number;
+    readonly zIndex?: number;
+    /**
+     * Decorations attached to the badge plate. Each entry is a regular
+     * {@link NodeDecorationSpec} — glow, ring, marching-ants, pulse-ring, etc.
+     * Identity / merge rules match {@link NodeStyle.decorations} (id-keyed,
+     * `remove: true` drops earlier same-id entries from base under a state
+     * overlay).
+     */
+    readonly decorations?: readonly NodeDecorationSpec[];
+    /**
+     * Effects modulating the badge plate's transform / style each frame
+     * (`shake`, `breathing`, …). Same surface as {@link NodeStyle.effects}.
+     */
+    readonly effects?: BadgeEffects;
+}
+/**
+ * Anchor point along an edge's routed path.
+ *
+ * - `'start'` / `'end'` — anchored *near* the source / target endpoint with
+ *   automatic clearance: the badge is shifted tangentially by its own
+ *   half-extent so it kisses the endpoint node's silhouette from outside
+ *   rather than half-overlapping it. The natural choice for endpoint
+ *   chips, status icons, etc.
+ * - `'middle'` — exact arc-length midpoint (`t = 0.5`).
+ * - A `number` in `[0, 1]` — raw arc-length `t`, no clearance applied.
+ *   Use `placement: 1` when you explicitly want a badge centred on the
+ *   silhouette point. Values outside `[0, 1]` are clamped.
+ *
+ * `'middle'` (not `'center'`) avoids term-clashing with `BadgeOrigin`
+ * where `'center'` means "centre the badge on its own AABB".
+ */
+type EdgeBadgePlacement = 'start' | 'middle' | 'end' | number;
+/**
+ * Small overlay attached to an edge — e.g. flow-rate chip on the midpoint,
+ * count badge at the source endpoint, arrow-tag at the target. A badge is
+ * rendered as a real shape (any registered {@link NodeShapeOptions} kind);
+ * placement is parametric along the routed path.
+ *
+ * Position resolves via `samplePathAt(path, t)` so the badge re-anchors
+ * automatically when the path changes (source / target shape moves, anchor
+ * / router / waypoints change). For loop edges, `'middle'` naturally lands
+ * on the loop apex because the path passes through it at `t ≈ 0.5`.
+ *
+ * Decorations and effects compose exactly the way they do on
+ * {@link NodeBadge}; the badge being shape-rendered means shape decorations
+ * (`glow`, `ring`, `marching-ants`, `pulse-ring`, …) apply uniformly.
+ */
+interface EdgeBadge {
+    /**
+     * Stable id within the edge, for keyed updates / state-overlay diffing.
+     * When omitted, identity falls back to the badge's position in the
+     * containing `badges[]` array.
+     */
+    readonly id?: string;
+    /** Where along the routed path the badge attaches. */
+    readonly placement: EdgeBadgePlacement;
+    /**
+     * Which point of the badge's own AABB lands at the path anchor.
+     * Default for edge badges is `'center'` — the badge centres on the path
+     * point. Use other origins to lift the badge off the line (e.g.
+     * `origin: 'bottom'` puts the badge above the line with its bottom edge
+     * touching the path).
+     */
+    readonly origin?: BadgeOrigin;
+    /**
+     * Pure geometry — any registered {@link NodeShapeOptions} kind. Fill /
+     * stroke / alpha come from the flat sugar fields below, mirroring the
+     * `NodeStyle.shape` + `bgFill` split used for node bodies.
+     */
+    readonly shape: NodeShapeOptions;
+    /** Solid plate colour — projects to the badge shape's first fill layer. */
+    readonly fill?: number;
+    readonly alpha?: number;
+    readonly strokeColor?: number;
+    readonly strokeWidth?: number;
+    /**
+     * Vector inset rendered inside the badge plate (glyph / svg / svg-url).
+     * Projects to an extra fill layer stacked on top of the solid plate.
+     */
+    readonly icon?: NodeIcon;
+    /**
+     * Optional short text rendered centred on the badge (count "3", "!").
+     * Projects to a `'label'` decoration on the badge.
+     */
+    readonly labelText?: string;
+    readonly labelColor?: number;
+    readonly labelFontSize?: number;
+    /**
+     * Shift the path-anchor along the local tangent (positive = forward
+     * toward `'end'`, negative = backward toward `'start'`). Useful for
+     * nudging a `'middle'`-anchored badge sideways without changing `t`.
+     */
+    readonly pathOffset?: number;
+    /** Pixel offset applied after placement resolution. */
+    readonly offsetX?: number;
+    readonly offsetY?: number;
+    /**
+     * When `true`, the badge rotates to follow the path tangent at the
+     * anchor point. Default `false` (badges stay axis-aligned). Useful for
+     * arrow-shaped or directional badges on curved edges.
+     */
+    readonly autoRotate?: boolean;
+    /**
+     * When {@link autoRotate} is `true`, flip the badge by 180° on the
+     * "downward" half of the path so text decorations stay readable on
+     * every edge orientation. Default `true`. Ignored when `autoRotate` is
+     * `false`.
+     */
+    readonly keepUpright?: boolean;
+    readonly zIndex?: number;
+    /**
+     * Decorations attached to the badge plate. Same surface as
+     * {@link NodeBadge.decorations} — shape decorations (`glow`, `ring`,
+     * `marching-ants`, `pulse-ring`) apply because the badge is itself a
+     * shape, regardless of being hosted on a connector.
+     */
+    readonly decorations?: readonly NodeDecorationSpec[];
+    /**
+     * Effects modulating the badge plate's transform / style each frame
+     * (`shake`, `breathing`, …). Same surface as
+     * {@link NodeBadge.effects}.
+     */
+    readonly effects?: BadgeEffects;
+}
+/**
+ * Common fields on every entry in a `decorations[]` array. The `id` gives
+ * stable diff identity (state overlays can re-declare the same id to
+ * override, or set `remove: true` to drop a base-level decoration while a
+ * state is active). When `id` is absent, identity falls back to `kind + array index`.
+ */
+interface DecorationSpecCommon {
+    /** Stable id for diffing. Optional — falls back to `kind#<index>` when absent. */
+    readonly id?: string;
+    /**
+     * When `true`, this entry instructs the resolver to drop any earlier-
+     * precedence decoration with the same `id`. Use it in a state overlay to
+     * temporarily remove a base-level decoration while the state is active.
+     */
+    readonly remove?: boolean;
+}
+/**
+ * Discriminated union of decoration specs attachable to a node via
+ * {@link NodeStyle.decorations}. Each variant pairs `kind` (the registered
+ * canvas decoration name) with the matching style payload from
+ * `@invana/canvas/primitives`.
+ *
+ * Multiples are allowed — the same kind can appear several times (e.g. an
+ * inner + outer ring on a single node), as long as their `id`s differ.
+ * `label` is intentionally absent — labels are managed by the flat
+ * `labelText` / `label*` fields on `NodeStyle`, not by the decorations
+ * array.
+ */
+type NodeDecorationSpec = (DecorationSpecCommon & {
+    readonly kind: 'ring';
+} & RingDecorationStyle) | (DecorationSpecCommon & {
+    readonly kind: 'glow';
+} & GlowDecorationStyle) | (DecorationSpecCommon & {
+    readonly kind: 'pulse-ring';
+} & PulseRingDecorationStyle) | (DecorationSpecCommon & {
+    readonly kind: 'marching-ants';
+} & MarchingAntsDecorationStyle) | (DecorationSpecCommon & {
+    readonly kind: 'liquid-fill';
+} & LiquidFillDecorationStyle) | (DecorationSpecCommon & {
+    readonly kind: 'toggle';
+} & ToggleDecorationStyle) | (DecorationSpecCommon & {
+    readonly kind: 'resize-handle';
+} & ResizeHandleDecorationStyle) | (DecorationSpecCommon & {
+    readonly kind: 'selection-frame';
+} & SelectionFrameDecorationStyle);
+/**
+ * Discriminated union of decoration specs attachable to an edge via
+ * {@link EdgeStyle.decorations}. Mirrors {@link NodeDecorationSpec} for
+ * the connector-target decoration registry. `label-connector` is excluded
+ * for the same reason `label` is — labels live on the flat label fields.
+ */
+type EdgeDecorationSpec = (DecorationSpecCommon & {
+    readonly kind: 'ring-connector';
+} & RingConnectorDecorationStyle) | (DecorationSpecCommon & {
+    readonly kind: 'glow-connector';
+} & GlowConnectorDecorationStyle) | (DecorationSpecCommon & {
+    readonly kind: 'marching-ants-connector';
+} & MarchingAntsConnectorDecorationStyle) | (DecorationSpecCommon & {
+    readonly kind: 'ripple-connector';
+} & RippleConnectorDecorationStyle) | (DecorationSpecCommon & {
+    readonly kind: 'fly-marker-connector';
+} & FlyMarkerConnectorDecorationStyle) | (DecorationSpecCommon & {
+    readonly kind: 'flow-particles-connector';
+} & FlowParticlesConnectorDecorationStyle) | (DecorationSpecCommon & {
+    readonly kind: 'reveal-connector';
+} & RevealConnectorDecorationStyle);
+/**
+ * Host-modulation effects (sibling of decorations). Effects don't add
+ * geometry — they modulate the host's transform (`shake`, `breathing`) or
+ * style channels (tint/alpha). One spec per kind.
+ */
+interface NodeEffects {
+    readonly shake?: unknown | null;
+    readonly breathing?: unknown | null;
+    readonly [kind: string]: unknown | null | undefined;
+}
+/**
+ * Marks a node as a **compound group** — a visual frame drawn behind its
+ * descendants (children point to it via `parentId`). The presence of this
+ * field on a node's resolved {@link NodeStyle} is the only signal the layer
+ * uses to decide whether to apply group semantics; the structural shape
+ * (`style.shape`) stays a regular `rect` / `circle` / etc.
+ *
+ * Group semantics, in summary:
+ *
+ * - **Expanded state** (`collapsed !== true`):
+ *   - The node renders behind its children (z-index pushed underneath when
+ *     `behindChildren !== false`) and is **non-hittable** — pointer events
+ *     pass through the frame to the canvas background. The frame is a pure
+ *     drawing, not an interactive node.
+ *   - With `autoFit: true`, the layer recomputes `width` / `height` (rect)
+ *     or `radius` (circle) every flush from the children's bounding box,
+ *     plus `padding` and optional `headerHeight`. The declared `width` /
+ *     `height` / `radius` fields act as a **lower bound** in this mode.
+ *   - With `autoFit: false`, the layer uses the declared `width` / `height`
+ *     / `radius` literally; children may visually leak outside.
+ *
+ * - **Collapsed state** (`collapsed === true`):
+ *   - The node renders as a normal interactive node (`hittable: true`,
+ *     default z-order). All descendants are hidden from the renderer; edges
+ *     pointing at a hidden descendant are re-routed to the nearest visible
+ *     collapsed-group ancestor at render time (no mutation to the edge data).
+ *   - The layer synthesises a count badge showing the number of hidden
+ *     descendants. The `+`/`−` toggle is rendered via the
+ *     {@link ToggleDecorationStyle} decoration on the group — wire up
+ *     `CollapseExpandBehaviour` to make the toggle clickable.
+ *
+ * Nested groups fall out of the `parentId` chain for free: a group node
+ * whose own `parentId` points at another group becomes a sub-group; the
+ * recompute walks deepest-first.
+ *
+ * Membership uses the existing `GraphNode.parentId` (single hierarchy field
+ * shared with tree structures) — no separate group-membership concept.
+ */
+interface GroupOptions {
+    /**
+     * When `true`, the frame's size tracks the bounding box of its direct
+     * children (computed every flush). When `false`, the declared `width` /
+     * `height` / `radius` are used verbatim. Default `false`.
+     */
+    readonly autoFit?: boolean;
+    /**
+     * When `true`, `GroupResizeBehaviour` mounts corner / radial handle
+     * decorations on this group and lets the user drag to resize. Composes
+     * with `autoFit` per the floor rule on `width` / `height` / `radius`.
+     * Default `false`.
+     */
+    readonly userResizable?: boolean;
+    /** Inset around the children bbox before the frame outline. Default `16`. */
+    readonly padding?: number;
+    /**
+     * True = render the group as a collapsed super-node (children hidden,
+     * +/- toggle shows `+`, count badge shows the hidden descendant count).
+     * Toggle through `CollapseExpandBehaviour` or by updating this field
+     * directly via `store.updateNode`. Default `false`.
+     */
+    readonly collapsed?: boolean;
+    /**
+     * Frame renders at `style.zIndex − 1` so descendants paint on top. Set to
+     * `false` to keep the frame at its declared z-index (and let descendants
+     * paint underneath when their z-index is lower). Default `true`.
+     */
+    readonly behindChildren?: boolean;
+    /**
+     * Optional header band height (px) added above the children bbox. The
+     * frame still draws as a single rect / circle — `headerHeight` only
+     * shifts the auto-fit recompute so the label area at the top stays clear
+     * of children. Default `0`.
+     */
+    readonly headerHeight?: number;
+    /**
+     * Floor (with `autoFit`) or fixed (without) width. Rect frames only.
+     * Ignored for circle frames.
+     */
+    readonly width?: number;
+    /** Sibling of {@link width} for `kind: 'rect'`. */
+    readonly height?: number;
+    /**
+     * Floor (with `autoFit`) or fixed (without) radius. Circle frames only.
+     * Ignored for rect frames.
+     */
+    readonly radius?: number;
+    /**
+     * Where the auto-attached `+` / `−` toggle sits relative to the group's
+     * frame. Two forms:
+     *
+     * - **Keyword** — one of the {@link TogglePlacement} aliases
+     *   (`'bottom'`, `'inside-bottom'`, `'top-right'`, `'bottom-left'`, …).
+     *   Resolved against the host's AABB by the toggle decoration.
+     * - **Shape-local coords** — `{ x, y }`, an absolute point inside the
+     *   host shape's local frame (centre-relative for `circle`, top-left-
+     *   relative for `rect`). Use this when none of the keywords place the
+     *   toggle where you want it (diagonal offsets, mock-specific spots).
+     *
+     * Default `'bottom'` — centred just below the silhouette, matching the
+     * "small bubble attached to the rim" pattern in the reference UI.
+     * Clicks are dispatched at the canvas level by `CollapseExpandBehaviour`,
+     * so the toggle remains clickable regardless of whether the resolved
+     * position falls inside or outside the host's hit area.
+     */
+    readonly togglePlacement?: TogglePlacement | {
+        readonly x: number;
+        readonly y: number;
+    };
+}
+/**
+ * Visual + structural style for a node. Flat-prefixed scalars for orthogonal
+ * properties (`bgFill`, `bgStrokeWidth`, `labelColor`); polymorphic values
+ * kept structured (`shape`, `icon`, `image`, `decorations`, `effects`,
+ * `badges`).
+ *
+ * Per-instance state overlays for a node live at {@link NodeData.state}
+ * (a sibling of `style`), NOT inside `NodeStyle`.
+ */
+interface NodeStyle {
+    readonly shape?: NodeShapeOptions;
+    /**
+     * Unified normalized size. When set, overrides the resolved `shape`'s
+     * intrinsic size fields at style-resolution time (before the spec reaches
+     * the renderer, `boundsOfNode`, or any layout's bounds query). Per-kind
+     * mapping:
+     *
+     * - `circle` / `regular-polygon` — `shape.radius = size`
+     * - `rect` — `shape.width = shape.height = 2 * size`
+     * - `arc` — `shape.outerR = size` (and `shape.innerR` scaled so its ratio
+     *   to `outerR` is preserved)
+     * - `star` — `shape.outerRadius = size` (and `shape.innerRadius` scaled to
+     *   preserve its ratio)
+     * - `polygon` / custom — no canonical size axis; `size` is ignored
+     *
+     * Honoured uniformly by `boundsOfNode`, `D3ForceLayout` (collide.radius
+     * receives the `GraphNode` and reads the normalized `shape.radius` via
+     * `resolveNodeStyle`), and `ElkLayout` (reads bounds via `boundsOfNode`).
+     * Use this when a single number should drive a node's footprint regardless
+     * of which shape kind it renders as — e.g. degree-based sizing,
+     * data-driven scaling.
+     */
+    readonly size?: number;
+    /**
+     * Marks this node as a compound group (visual frame drawn behind its
+     * descendants). See {@link GroupOptions} for the full contract — autoFit
+     * vs userResizable, expanded vs collapsed semantics, header band, edge
+     * re-routing.
+     *
+     * Presence of this field is the only discriminator. The structural shape
+     * (`shape: { kind: 'rect' | 'circle' }`) is unchanged; groups reuse the
+     * same primitives as regular nodes.
+     */
+    readonly group?: GroupOptions;
+    /**
+     * When `true`, `NodeResizeBehaviour` mounts corner-handle decorations on
+     * this node (rect / circle only) and lets the user drag to resize. The
+     * drag writes back to `style.shape.width` / `height` / `radius` directly
+     * (and `position` for non-corner-anchored rect drags). Independent from
+     * `style.group?.userResizable`, which targets group frames specifically
+     * — but both are honoured by the same behaviour, so a single registered
+     * `NodeResizeBehaviour` handles every resizable node in the layer.
+     */
+    readonly resizable?: boolean;
+    /**
+     * Accepts every `ShapeFillLayer` kind — `solid` / `image` / `glyph` /
+     * `svg` / `svg-url` — and arrays for stacked layers. The `image` kind
+     * doubles as silhouette filler and inset content via its `fit` field
+     * (`'inset'` vs the silhouette modes).
+     */
+    readonly bgFill?: ShapeFill;
+    readonly bgAlpha?: number;
+    readonly bgStrokeColor?: number;
+    readonly bgStrokeAlpha?: number;
+    readonly bgStrokeWidth?: number;
+    readonly bgStrokeAlignment?: 'inside' | 'center' | 'outside';
+    readonly bgStrokeDashArray?: readonly [number, number];
+    readonly bgStrokeDashOffset?: number;
+    readonly bgStrokeCap?: 'butt' | 'round' | 'square';
+    readonly bgStrokeJoin?: 'miter' | 'round' | 'bevel';
+    readonly icon?: NodeIcon;
+    readonly image?: NodeImage;
+    readonly labelText?: string;
+    readonly labelColor?: number;
+    readonly labelFontSize?: number;
+    readonly labelFontFamily?: string;
+    readonly labelFontWeight?: number | string;
+    readonly labelFontStyle?: 'normal' | 'italic';
+    readonly labelAlign?: 'left' | 'center' | 'right';
+    readonly labelLineHeight?: number;
+    readonly labelLetterSpacing?: number;
+    readonly labelPlacement?: ShapeLabelPlacement;
+    readonly labelOffsetX?: number;
+    readonly labelOffsetY?: number;
+    readonly labelAlpha?: number;
+    readonly labelMinFontSize?: number;
+    /** Radians. */
+    readonly labelRotation?: number;
+    /** Hide the label below this camera zoom level. */
+    readonly labelMinZoom?: number;
+    /** Hide the label above this camera zoom level. */
+    readonly labelMaxZoom?: number;
+    /** Collision priority — higher wins when two labels overlap. */
+    readonly labelPriority?: number;
+    /** Collision partition — labels in different groups never compete. */
+    readonly labelCollisionGroup?: string;
+    /** Bypass collision entirely — label always renders. */
+    readonly labelForceShow?: boolean;
+    readonly labelBackgroundFill?: number;
+    readonly labelBackgroundAlpha?: number;
+    readonly labelBackgroundStrokeColor?: number;
+    readonly labelBackgroundStrokeWidth?: number;
+    readonly labelBackgroundPadding?: number;
+    readonly labelBackgroundCornerRadius?: number;
+    /**
+     * Escape hatch — full `ShapeLabelStyle` payload from `@invana/canvas`.
+     * Use this when the flat `label*` fields don't cover the case (wrap,
+     * html-text content, custom collision settings, etc.). When set, the
+     * adapter uses this payload verbatim instead of building one from the
+     * flat fields. Flat label fields are ignored on the same node.
+     */
+    readonly labelStyle?: ShapeLabelStyle;
+    readonly badges?: readonly NodeBadge[];
+    /**
+     * Ordered list of decorations attached to the node. Each entry's `kind`
+     * names a registered canvas decoration; the rest of the entry is that
+     * decoration's style payload. See {@link NodeDecorationSpec}.
+     *
+     * The resolver concatenates this array across base style + every active
+     * state's overlay, then dedupes by `id` (later precedence wins). Use
+     * `remove: true` in a higher-precedence overlay to drop an earlier entry
+     * with the same id while a state is active.
+     */
+    readonly decorations?: readonly NodeDecorationSpec[];
+    readonly effects?: NodeEffects;
+}
+/**
+ * Resolver-aware mirror of {@link NodeStyle}. Each field is either a static
+ * value or `(D) => T`. Two scopes use this generic at different `D`:
+ *
+ *   - `NodeInput<D>.style` — resolvers fire at insert (`D` = raw node data).
+ *   - `NodeOption.style` — resolvers fire at render (`D` = stored `GraphNode`).
+ */
+type ResolvableNodeStyle<D = unknown> = {
+    readonly [K in keyof NodeStyle]?: Resolvable<NonNullable<NodeStyle[K]>, D>;
+};
+/**
+ * Per-instance node descriptor as stored by `GraphStore`. All values
+ * concrete (no functions). Flat field layout matching G6's `NodeData`
+ * convention.
+ *
+ * - `state` (singular) = per-instance overlay catalogue.
+ * - `states` (plural) = currently-active state names.
+ */
+interface NodeData<D = unknown> {
+    readonly id: string;
+    /** Type tag (free-form). Matches a `NodeOption` template if any. */
+    readonly type?: string;
+    readonly data?: D;
+    readonly style?: NodeStyle;
+    /** Per-instance overlay catalogue (singular `state`). */
+    readonly state?: Readonly<Record<string, NodeStyle>>;
+    /** Currently-active state names (plural `states`). */
+    readonly states?: readonly string[] | null;
+    readonly position?: {
+        readonly x: number;
+        readonly y: number;
+    };
+    readonly pinned?: boolean;
+    /**
+     * Logical parent id — the only hierarchy field. Use this for both tree
+     * structures AND group/combo membership (the parent is just a regular
+     * node that visually represents the group). The store auto-maintains an
+     * inverse index, queryable via `store.childrenOf(id)` /
+     * `store.descendantsOf(id)`.
+     */
+    readonly parentId?: string;
+}
+/**
+ * What the consumer passes to `GraphLayer.setData`. Same shape as
+ * {@link NodeData} but with Resolvable fields — `id` and per-field styles
+ * may be functions over `data`. Resolvers fire once at insert; the store
+ * holds `NodeData`.
+ */
+interface NodeInput<D = unknown> {
+    readonly id?: ResolvableId<D>;
+    readonly type?: string;
+    readonly data?: D;
+    readonly style?: ResolvableNodeStyle<D>;
+    readonly state?: Readonly<Record<string, ResolvableNodeStyle<D>>>;
+    readonly states?: readonly string[];
+    readonly position?: {
+        readonly x: number;
+        readonly y: number;
+    };
+    readonly pinned?: boolean;
+    readonly parentId?: string;
+}
+/**
+ * Layer-level node template — G6's `node` field on GraphOptions. Resolvers
+ * fire every frame against the stored `GraphNode`.
+ *
+ * No `animation` field — per [[feedback_decoration_vs_animation]], animation
+ * is the per-frame engine, not a node-level config. Decoration / effect
+ * attachments live on `NodeStyle.decorations` / `NodeStyle.effects`.
+ */
+interface NodeOption {
+    /** Type tag this template defines (e.g. 'person', 'doc'). Optional. */
+    readonly type?: string;
+    readonly style?: ResolvableNodeStyle<GraphNode>;
+    readonly state?: Readonly<Record<string, ResolvableNodeStyle<GraphNode>>>;
+    /** Reserved for palette-driven theming. Deferred wiring. */
+    readonly palette?: unknown;
+}
+/** Arrowhead shape catalogue. */
+type ArrowShape = 'triangle' | 'diamond' | 'circle' | 'none';
+/**
+ * Structural variant of an edge — the three-stage connector pipeline
+ * (anchor → router → pathStyle). Variant-specific params live inside
+ * `pathStyleOpts`, so this stays non-discriminated.
+ */
+interface EdgeShapeOptions {
+    readonly pathType?: EdgePathType;
+    readonly sourceAnchor?: EdgeAnchor;
+    readonly targetAnchor?: EdgeAnchor;
+    readonly sourceAnchorOpts?: Readonly<Record<string, unknown>>;
+    readonly targetAnchorOpts?: Readonly<Record<string, unknown>>;
+    readonly pathStyleOpts?: Readonly<Record<string, unknown>>;
+    readonly waypoints?: ReadonlyArray<{
+        readonly x: number;
+        readonly y: number;
+    }>;
+}
+/**
+ * Flat-prefixed style bag for an edge. Edges have one stroke (the path), so
+ * stroke fields are unprefixed. Arrow ends and label keep their distinct
+ * prefixes.
+ */
+interface EdgeStyle {
+    readonly shape?: EdgeShapeOptions;
+    readonly strokeColor?: number;
+    readonly strokeAlpha?: number;
+    readonly strokeWidth?: number;
+    readonly strokeAlignment?: 'inside' | 'center' | 'outside';
+    readonly strokeDashArray?: readonly [number, number];
+    readonly strokeDashOffset?: number;
+    readonly strokeCap?: 'butt' | 'round' | 'square';
+    readonly strokeJoin?: 'miter' | 'round' | 'bevel';
+    readonly arrowSourceShape?: ArrowShape;
+    readonly arrowSourceSize?: number;
+    readonly arrowSourceColor?: number;
+    readonly arrowSourceAlpha?: number;
+    readonly arrowTargetShape?: ArrowShape;
+    readonly arrowTargetSize?: number;
+    readonly arrowTargetColor?: number;
+    readonly arrowTargetAlpha?: number;
+    readonly labelText?: string;
+    readonly labelColor?: number;
+    readonly labelFontSize?: number;
+    readonly labelFontFamily?: string;
+    readonly labelFontWeight?: number | string;
+    readonly labelFontStyle?: 'normal' | 'italic';
+    readonly labelAlign?: 'left' | 'center' | 'right';
+    readonly labelLineHeight?: number;
+    readonly labelLetterSpacing?: number;
+    readonly labelPlacement?: ConnectorLabelPlacement;
+    readonly labelPathOffset?: number;
+    readonly labelAutoRotate?: boolean;
+    readonly labelKeepUpright?: boolean;
+    readonly labelOffsetX?: number;
+    readonly labelOffsetY?: number;
+    readonly labelAlpha?: number;
+    readonly labelMinFontSize?: number;
+    /** Hide the label below this camera zoom level. */
+    readonly labelMinZoom?: number;
+    /** Hide the label above this camera zoom level. */
+    readonly labelMaxZoom?: number;
+    /** Collision priority — higher wins when two labels overlap. */
+    readonly labelPriority?: number;
+    /** Collision partition — labels in different groups never compete. */
+    readonly labelCollisionGroup?: string;
+    /** Bypass collision entirely — label always renders. */
+    readonly labelForceShow?: boolean;
+    readonly labelBackgroundFill?: number;
+    readonly labelBackgroundAlpha?: number;
+    readonly labelBackgroundStrokeColor?: number;
+    readonly labelBackgroundStrokeWidth?: number;
+    readonly labelBackgroundPadding?: number;
+    readonly labelBackgroundCornerRadius?: number;
+    /**
+     * Escape hatch — full `ConnectorLabelStyle` payload from `@invana/canvas`.
+     * Use this when the flat `label*` fields don't cover the case (wrap,
+     * html-text content, etc.). When set, the adapter uses this payload
+     * verbatim instead of building one from the flat fields.
+     */
+    readonly labelStyle?: ConnectorLabelStyle;
+    /**
+     * Ordered list of decorations attached to the edge. Each entry's `kind`
+     * names a registered canvas connector-decoration; the rest is that
+     * decoration's style payload. See {@link EdgeDecorationSpec}.
+     *
+     * Resolver semantics match {@link NodeStyle.decorations}: concatenate
+     * across base + active state overlays, dedupe by `id`, later precedence
+     * wins.
+     */
+    readonly decorations?: readonly EdgeDecorationSpec[];
+    /**
+     * Ordered list of badges attached to the edge. Each entry is a real
+     * {@link EdgeBadge} — any registered shape kind as the plate, optional
+     * icon / labelText sugar, optional nested decorations and effects.
+     * Placement is parametric along the routed path (`'start' | 'middle' |
+     * 'end' | number`) and re-anchors automatically when the path changes
+     * (source / target shape moves, anchor / router / waypoints change).
+     *
+     * Resolver semantics match {@link decorations}: concatenate across base
+     * + active state overlays, dedupe by `id`, later precedence wins.
+     */
+    readonly badges?: readonly EdgeBadge[];
+}
+/** Resolver-aware mirror of {@link EdgeStyle}; generic over the resolver argument. */
+type ResolvableEdgeStyle<D = unknown> = {
+    readonly [K in keyof EdgeStyle]?: Resolvable<NonNullable<EdgeStyle[K]>, D>;
+};
+/** Per-instance edge descriptor — stored by GraphStore, concrete values. */
+interface EdgeData<D = unknown> {
+    readonly id: string;
+    readonly source: string;
+    readonly target: string;
+    /** Predicate / FK label. Free-form. G6 calls this `type`. */
+    readonly type?: string;
+    readonly data?: D;
+    readonly style?: EdgeStyle;
+    readonly state?: Readonly<Record<string, EdgeStyle>>;
+    readonly states?: readonly string[] | null;
+}
+/** Resolver-aware input shape for an edge. */
+interface EdgeInput<D = unknown> {
+    readonly id?: ResolvableId<D>;
+    readonly source: string;
+    readonly target: string;
+    readonly type?: string;
+    readonly data?: D;
+    readonly style?: ResolvableEdgeStyle<D>;
+    readonly state?: Readonly<Record<string, ResolvableEdgeStyle<D>>>;
+    readonly states?: readonly string[];
+}
+/** Layer-level edge template — G6's `edge` field. */
+interface EdgeOption {
+    readonly type?: string;
+    readonly style?: ResolvableEdgeStyle<GraphEdge>;
+    readonly state?: Readonly<Record<string, ResolvableEdgeStyle<GraphEdge>>>;
+    readonly palette?: unknown;
+}
+/**
+ * Canonical node-state overlays auto-merged into every `GraphLayer`'s
+ * `options.node.state` catalogue on construction (unless
+ * `GraphLayerOptions.useDefaultStates: false`). Consumer-supplied
+ * `options.node.state[name]` entries override individual fields per the
+ * normal merge precedence; this map provides the resting visual identity
+ * of each canonical state so a layer that touches no state code still
+ * gets a sensible hover / select / error ring out of the box.
+ *
+ * All values are flat NodeStyle fields — extending or overriding is the
+ * same shape as any other layer-template state overlay. Decorations are
+ * intentionally not declared here so consumers compose them additively
+ * (e.g. a ring decoration on hover) without colliding with the canonical
+ * stroke treatment below.
+ */
+declare const DEFAULT_NODE_STATES: Readonly<Record<CanonicalStateName, NodeStyle>>;
+/**
+ * Canonical edge-state overlays — sibling of {@link DEFAULT_NODE_STATES}.
+ * Auto-merged into every `GraphLayer`'s `options.edge.state` catalogue
+ * unless `GraphLayerOptions.useDefaultStates: false`.
+ */
+declare const DEFAULT_EDGE_STATES: Readonly<Record<CanonicalStateName, EdgeStyle>>;
+/**
+ * Top-level data input shape for `GraphLayer.setData(opts)`. Carries node /
+ * edge inputs plus optional layer-wide id resolvers.
+ */
+interface GraphDataOptions<DN = unknown, DE = unknown> {
+    readonly nodes: readonly NodeInput<DN>[];
+    readonly edges: readonly EdgeInput<DE>[];
+    /** Optional layer-wide id resolver applied to nodes that lack an explicit `id`. */
+    readonly nodeIdResolver?: (data: DN) => string;
+    readonly edgeIdResolver?: (data: DE) => string;
+}
+/** Constructor options for `GraphLayer`. */
+interface GraphLayerOptions {
+    /**
+     * Optional pre-built store. If omitted, the layer creates its own with
+     * default options (`flushMode: 'sync'`, `unknownEndpoint: 'throw'`). Pass
+     * a store you own to share data with other layers / sync code.
+     */
+    store?: GraphStore;
+    /**
+     * Layer-level node template (G6's `node` field). Carries `style` (base
+     * appearance) and `state` (catalogue of named overlays applied while a
+     * state in `node.states[]` is active). Resolver-aware: every field on
+     * `style` / each `state[name]` may be a static value or a function
+     * `(node: GraphNode) => value` that fires every render.
+     */
+    node?: NodeOption;
+    /** Sibling of {@link node} for edges. */
+    edge?: EdgeOption;
+    /**
+     * Auto-merge {@link DEFAULT_NODE_STATES} / {@link DEFAULT_EDGE_STATES}
+     * into `options.node.state` / `options.edge.state` on construction so
+     * every canonical state has a sensible default appearance even when the
+     * consumer supplied no state overlays. Consumer entries win on a
+     * per-name basis (no per-field deep merge here — declare a full
+     * `NodeStyle` if you want to replace a default entry). Default `true`.
+     */
+    useDefaultStates?: boolean;
+    /**
+     * Minimum hover/click target in screen pixels, forwarded to the
+     * internal `PrimitivesRenderer`. Default `6`.
+     *
+     * Behaves as a *fallback*: exact geometric hits always win; only
+     * when no shape contains the cursor does the dispatcher pick the
+     * closest candidate within `hitFloorPx` screen pixels. See
+     * `PrimitivesRendererOptions.hitFloorPx` for details.
+     */
+    hitFloorPx?: number;
+}
+/**
+ * Layer-level event payloads (separate from store events). Pointer/drag/etc.
+ * arrive in later phases; today this is just the aggregated lifecycle.
+ */
+interface GraphLayerEvents {
+    'data:changed': {
+        addedNodes: number;
+        removedNodes: number;
+        updatedNodes: number;
+        addedEdges: number;
+        removedEdges: number;
+        updatedEdges: number;
+    };
+    'positions:updated': {
+        count: number;
+    };
+    /**
+     * A user-driven node drag began. Behaviours emitting this signal the
+     * intent to hold a node's position against any physics / layout that
+     * would otherwise move it. Layouts (e.g. `D3ForceLayout`) subscribe and
+     * apply a *transient* lock — they MUST NOT mutate the store's
+     * `GraphNode.pinned` flag in response, since that is reserved for
+     * user-data semantics (permanent pin). The matching `node:drag-end`
+     * releases the transient lock.
+     *
+     * `nodeId` is the *grabbed* node (the gesture's primary). `nodeIds` is the
+     * full set of primary nodes being dragged together — `[nodeId]` for a plain
+     * single-node drag, or every selected node for a multi-selection drag. Group
+     * descendants are NOT listed here; consumers that care about them expand via
+     * `store.descendantsOf(id)`.
+     */
+    'node:drag-start': {
+        nodeId: string;
+        nodeIds: readonly string[];
+    };
+    'node:drag-end': {
+        nodeId: string;
+        nodeIds: readonly string[];
+    };
+    [event: string]: unknown;
+}
+
+/**
+ * `GraphLayer` — `WorldLayer` subclass that renders a `GraphStore` via a
+ * `PrimitivesRenderer`. Subscribes to store events and projects them into
+ * `addShape` / `addConnector` / `updateShape` / `updateConnector` /
+ * `removeShape` / `removeConnector` calls.
+ *
+ * The store is the source of truth. The layer is a thin projection — no
+ * domain data lives here. Re-emits aggregated `data:changed` and
+ * `positions:updated` events at the layer level for application code that
+ * only cares about visible-graph changes.
+ *
+ * See `apps/docs/graph/data-model.md` for the data model and
+ * `apps/docs/graph/events.md` for the event model.
+ */
+
+interface GraphLayerState {
+    /** Reserved for hover / selection / decoration state in later phases. */
+    readonly _placeholder?: never;
+}
+declare class GraphLayer extends WorldLayer<GraphLayerOptions, GraphLayerState, GraphLayerEvents, never, WorldLayerHit> {
+    /**
+     * Pixi-backed primitives renderer; created in `onMount`.
+     *
+     * Public so behaviours can subscribe to `shape:*` / `connector:*` pointer
+     * events on `graph.getRenderer().events`. Returns `undefined` before mount.
+     */
+    private _renderer?;
+    /** Renderer accessor for behaviours. Undefined before `onMount`. */
+    getRenderer(): PrimitivesRenderer | undefined;
+    /**
+     * Per-frame tick — delegated to `PrimitivesRenderer.tickAnimations` so
+     * animated decorations (`pulse-ring`, `marching-ants`, …) and the
+     * viewport-clipped label-resolution sweep advance every frame.
+     *
+     * `Canvas.tickOnce` duck-types this hook on each layer; without it the
+     * renderer would never tick for graph layers because the field that
+     * holds it (`_renderer`) is private and the alternative fallback path
+     * looks for a public `renderer` property.
+     */
+    tickAnimations(deltaMs: number): void;
+    /** Data source. Either supplied by the caller or self-created. */
+    readonly store: GraphStore;
+    /** Subscription disposers, called in `onUnmount`. */
+    private subs;
+    /**
+     * Edge ids whose endpoint moved since last flush. The connector path is
+     * pinned to shape positions via the `boundary` anchor, but PixiJS doesn't
+     * auto-reroute connectors when an anchored shape moves — we drain this set
+     * on each store flush and call `updateConnector(eid, {})` to force re-route.
+     */
+    private dirtyConnectors;
+    /**
+     * Last-projected collapsed flag per group node id. Read by the
+     * `node:update` handler so it can detect a collapse → expand (or
+     * expand → collapse) flip — the patch itself doesn't carry the
+     * previous style, and the store has already overwritten it by the
+     * time the event fires. Updated by {@link syncGroupSyntheticDecorations}
+     * on every group render.
+     */
+    private readonly lastCollapsedByGroup;
+    /**
+     * Group node ids whose visible frame may need re-projection (auto-fit
+     * recompute, descendant visibility change, collapse / expand toggle).
+     * Drained per flush in deepest-first order — see {@link drainDirtyGroups}.
+     *
+     * Populated by store subscriptions when:
+     * - a group's own spec changes (add / update with `style.group` patch),
+     * - a child's position changes and its parent is a group with `autoFit`,
+     * - a child is added / removed from a group.
+     *
+     * Holding ids (not full snapshots) keeps the bucket idempotent — multiple
+     * mutations within a single batch coalesce to one rerender per group.
+     */
+    private dirtyGroups;
+    /**
+     * Nodes / edges whose active-state set changed since the last flush — drained
+     * once per flush into `rerenderNode` / `rerenderEdge`. Populated from the
+     * store's `node:state` / `edge:state` events; the dedup + once-per-flush drain
+     * keeps an N-item highlight to ≤1 rebuild per item (mirrors
+     * {@link dirtyConnectors}). State itself is owned by the `GraphStore` (presence
+     * compartment) — the layer holds none, just reads `store.nodeStatesOf` at
+     * render. See `store-owns-state-plan.md` § 0 / § 2.5.
+     */
+    private readonly dirtyStateNodes;
+    private readonly dirtyStateEdges;
+    /**
+     * Currently-mounted decoration slot ids per node / edge, so the resolver
+     * can diff (mount new / dispose removed / replace changed) against the
+     * previous render's set. Slot ids are synthesized from `spec.id` or
+     * `${kind}#<index>`. The `'label'` slot is managed separately by
+     * `syncNodeLabel` / `syncEdgeLabel` and never appears in these maps.
+     */
+    private readonly nodeDecorationSlots;
+    private readonly edgeDecorationSlots;
+    /**
+     * Currently-mounted badge slot ids per node, mirroring
+     * {@link nodeDecorationSlots} for badge diffing. Slot id falls back to
+     * `${badge.placement-name}#<index>` when `NodeBadge.id` is absent so
+     * id-less badges stack rather than collapse.
+     */
+    private readonly nodeBadgeSlots;
+    /** Edge-side counterpart of {@link nodeBadgeSlots}. */
+    private readonly edgeBadgeSlots;
+    private nodeOption;
+    private edgeOption;
+    constructor(opts: LayerOptions<GraphLayerOptions>);
+    protected createState(): GraphLayerState;
+    protected onMount(ctx: CanvasContext): void;
+    protected onUnmount(): void;
+    /**
+     * Bulk-load nodes + edges, **replacing** any prior data. Wraps the
+     * underlying store inserts in a single `batch()` so subscribers see one
+     * flush.
+     *
+     * For streaming consumers (constantly arriving data), use the store
+     * directly: `graph.store.addData({ nodes, edges })` appends without
+     * clearing, and `graph.store.applyDelta({ added, updated, removed })`
+     * applies an incremental change in one batch. All other per-id CRUD
+     * (`upsertNode`, `updateNode`, `removeNode`, edge equivalents, `batch`,
+     * `flush`, `clear`) lives on `graph.store` — the store is the single
+     * source of truth and the layer just orchestrates store → renderer.
+     */
+    setData(data: GraphData): void;
+    /**
+     * Remove every node and edge — tearing down their rendered shapes /
+     * connectors and notifying full-repaint consumers (e.g. `MiniMapLayer`). The
+     * canonical way to empty the graph; prefer it over
+     * `setData({ nodes: [], edges: [] })`.
+     *
+     * Note the difference from the low-level `graph.store.clear()`: that is a
+     * silent fast-wipe (no events, drops the pending queues), so on its own it
+     * would leave the canvas painted and dependent layers stale. This method
+     * keeps the renderer and store in sync and fires a single `data:changed`
+     * (which `store.clear()` alone never produces, since `doFlush` skips an empty
+     * flush) so consumers update immediately rather than on some later event.
+     */
+    clear(): void;
+    /**
+     * Force a full re-render of every node and edge from current store state +
+     * active states. Does **not** mutate data and is **not** undoable — it is a
+     * pure render pass. Use it after an external style/theme change that bypassed
+     * the store (e.g. swapping the renderer's palette) or to recover from a
+     * suspected render desync. For data edits prefer the store mutators, which
+     * re-render the affected items automatically.
+     */
+    redraw(): void;
+    /**
+     * Drop every shape / connector this layer has mounted on the renderer and
+     * reset transient routing state. Shared by `clear` / `setData`: `store.clear()`
+     * is silent, so it never drives the renderer's event-based removal path —
+     * the layer must detach explicitly.
+     */
+    private detachAllFromRenderer;
+    /**
+     * Patch the layer-level node template (`options.node.style`) and re-render
+     * every node so the change takes effect immediately. Use this for global
+     * "apply to all nodes" changes (e.g. a toolbar default-fill picker) instead
+     * of looping `store.updateNode` per node.
+     *
+     * Merge is shallow (top-level): structured fields (`shape`, `decorations`,
+     * `badges`, `effects`) are replaced wholesale — spread the prior value if you
+     * mean to patch a single sub-field. Per-node `style`, active states, and
+     * resolver functions still win over the template at resolve time (see
+     * {@link resolveNodeStyle}). No-op visually if the layer isn't mounted yet,
+     * but the template is still updated so later mounts pick it up.
+     */
+    setNodeDefaults(patch: Partial<NodeStyle>): void;
+    /**
+     * Sibling of {@link setNodeDefaults} for the edge template
+     * (`options.edge.style`). Patches the shared edge styling and re-renders
+     * every edge. Same shallow-merge contract — e.g. changing edge "type" means
+     * `setEdgeDefaults({ shape: { ...prevShape, pathType: 'bezier' } })`.
+     */
+    setEdgeDefaults(patch: Partial<EdgeStyle>): void;
+    /** Read-only snapshot of the current node template style (resolved per node at render). */
+    get nodeDefaults(): ResolvableNodeStyle<GraphNode> | undefined;
+    /** Read-only snapshot of the current edge template style. */
+    get edgeDefaults(): ResolvableEdgeStyle<GraphEdge> | undefined;
+    /**
+     * Highlight a node together with its neighbours (in `dir`) and incident edges
+     * — adds the runtime state `state` to all of them in a single
+     * {@link GraphStore.batch}, so the whole neighbourhood repaints in one flush.
+     * No-op if the seed id is unknown. Clear with `store.clearNodeState(state)` +
+     * `store.clearEdgeState(state)`.
+     *
+     * @param id    Seed node id.
+     * @param dir   Adjacency direction for neighbours + incident edges. Default `'both'`.
+     * @param state Runtime state name to apply. Default `'highlighted'`.
+     */
+    highlightNeighbourhood(id: string, dir?: EdgeDirection, state?: string): void;
+    /**
+     * Placeholder hit test — returns `null` until proper hit testing wires up
+     * in a later phase (likely via the canvas hit-test pipeline reading the
+     * renderer's shape registry).
+     */
+    hitTest(_worldX: number, _worldY: number): WorldLayerHit | null;
+    /**
+     * Resolve the active node hints — merges base `node.data` hints (legacy)
+     * and v3 `node.style` with each active state's overlay (legacy + v3),
+     * resolving layer-side resolver functions against the current node.
+     *
+     * Precedence (lowest → highest):
+     * 1. layer `node.style` (resolved against GraphNode, adapted)
+     * 2. `node.data` (legacy hints)
+     * 3. per-node `node.style` (concrete NodeStyle, adapted)
+     * 4. For each active state name in `node.states[]`:
+     *    a. layer legacy `nodeStateConfigs[name]` (resolved)
+     *    b. layer v3 `node.state[name]` (resolved against GraphNode, adapted)
+     *    c. per-node `node.state[name]` (concrete NodeStyle, adapted)
+     */
+    /**
+     * Resolve the final flat NodeStyle for a node by merging contributions from
+     * the layer-level template (`options.node.style`), the per-node `style`,
+     * and every active state's layer + per-node overlay. Object.assign order
+     * encodes precedence (later wins).
+     *
+     * Exposed publicly so behaviours (NodeSizeLODBehaviour, label collision,
+     * minimap, etc.) can read the same effective style the renderer sees,
+     * without duplicating the merge logic.
+     */
+    resolveNodeStyle(node: GraphNode): Partial<NodeStyle>;
+    /** Sibling of {@link resolveNodeStyle} for edges. Public for the same reason. */
+    resolveEdgeStyle(edge: GraphEdge): Partial<EdgeStyle>;
+    /**
+     * Build the renderer-facing shape spec from the resolved {@link NodeStyle}.
+     * Geometry is driven by the discriminated `style.shape` union; paint comes
+     * from the flat `bg*` fields.
+     *
+     * The `kind` discriminator and any spec params on `style.shape` pass
+     * straight through to the renderer, so any shape registered via
+     * `canvas.primitives.registerShape(name, ctor)` is usable by name — built-
+     * ins (`rect` / `circle` / `arc` / `regular-polygon` / `star` / `polygon`)
+     * and custom shapes alike. An unknown `kind` errors loudly in the
+     * renderer's `addShape` rather than silently falling back to a circle.
+     */
+    /**
+     * Local AABB for `node`'s resolved shape. Delegates to the registered
+     * shape's `static boundsOf` via `PrimitivesRenderer.boundsOfSpec`, so
+     * built-in and custom shape kinds flow through the same hook.
+     *
+     * Returns `undefined` when:
+     * - the renderer isn't mounted yet,
+     * - the resolved `style.shape.kind` isn't registered, or
+     * - the registered ctor doesn't implement `boundsOf`.
+     *
+     * The returned rect is in the shape's local (centre-relative) frame —
+     * `node.position` is *not* baked in. Consumers that only need a size
+     * read `width` / `height`; consumers that need world-space corners
+     * offset by `node.position` themselves.
+     *
+     * Used by `MiniMapLayer` to estimate node footprint before the source
+     * renderer mounts and by `ElkLayout` (and other layouts) to read node
+     * sizes for layout-time placement — both without switching over a
+     * closed shape-kind enum.
+     */
+    boundsOfNode(node: GraphNode): Rect | undefined;
+    /**
+     * Frame the camera on a set of nodes — fit the viewport to the world-space
+     * box spanning their positions, plus `padding` screen px. Unknown ids are
+     * skipped; a no-op when none resolve or the layer isn't mounted.
+     *
+     * Graph-domain sugar over the geometry-only {@link Camera.fitContent}: it
+     * resolves ids → positions so callers (e.g. a "zoom to node" context-menu
+     * action) don't have to.
+     *
+     * @param ids     Node ids to frame.
+     * @param padding Screen-pixel padding around the fitted box. Default `160`.
+     */
+    focusNodes(ids: Iterable<string>, padding?: number): void;
+    /**
+     * Frame the camera on a set of edges — fit the viewport to the box spanning
+     * both endpoints of each edge, plus `padding` screen px. Unknown ids (or
+     * edges with an unplaced endpoint) are skipped; a no-op when none resolve or
+     * the layer isn't mounted.
+     *
+     * @param ids     Edge ids to frame.
+     * @param padding Screen-pixel padding around the fitted box. Default `160`.
+     */
+    focusEdges(ids: Iterable<string>, padding?: number): void;
+    /** Fit the camera to the AABB spanning `pts` (+ padding). No-op if empty / unmounted. */
+    private fitPoints;
+    private nodeSpec;
+    /**
+     * Build the renderer-facing connector spec from the resolved
+     * {@link EdgeStyle}. The three-stage pipeline (anchor → router →
+     * pathStyle) is driven by `style.shape.pathType` + the anchor / router
+     * options on the same struct; paint comes from the flat `stroke*` fields.
+     */
+    private edgeSpec;
+    /**
+     * Re-render a single node from its current data + active state stack.
+     *
+     * Prefers `renderer.updateShape` (instance-preserving) over the
+     * `removeShape + addShape` fallback so the renderer's per-instance
+     * state — `gfxScale` (written by `NodeSizeLODBehaviour`), attached
+     * decorations, badges, effects — survives a state toggle. Falls back
+     * to remove+add only when the rebuilt spec has a different `kind`,
+     * which `updateShape` can't safely handle (the `IShape` class is
+     * fixed at construction time).
+     */
+    private rerenderNode;
+    /**
+     * Re-render a single edge from its current data + active state stack.
+     *
+     * Always uses `renderer.updateConnector` so `inst.strokeWidthScale`
+     * (written by `EdgeSizeLODBehaviour` as `1/cameraScale`) survives the
+     * state-driven full-spec replacement. The fresh spec carries the new
+     * "base" stroke width; the multiplier applies on top at draw time.
+     */
+    private rerenderEdge;
+    private drainDirtyConnectors;
+    private installNodeShape;
+    private installEdgeConnector;
+    /**
+     * Project the resolved `label` hint onto the canvas `'label'` decoration
+     * slot for the given node. A `null` / `undefined` hint clears the slot.
+     * Called after every `addShape` and every `rerenderNode` since decorations
+     * are dropped when the shape is destroyed.
+     */
+    private syncNodeLabel;
+    private syncEdgeLabel;
+    /**
+     * Resolve the final list of decorations for a node by concatenating every
+     * contributing layer (layer template + per-node base + each active state
+     * overlay) and deduping by `id`. Later precedence wins; `remove: true`
+     * drops an earlier same-id entry. Entries without an explicit `id` fall
+     * back to `${kind}#<combined-index>` — unique per source position, so
+     * id-less decorations stack rather than collapsing.
+     *
+     * Returns a `Map<slotId, NodeDecorationSpec>` keyed by the resolved
+     * identity. Caller emits one `setDecoration` call per slot to the
+     * renderer; the slot id is reused on subsequent renders to enable diffing.
+     */
+    private resolveNodeDecorations;
+    /** Sibling of {@link resolveNodeDecorations} for edges. */
+    private resolveEdgeDecorations;
+    /**
+     * Project the resolved decoration array onto the canvas renderer for the
+     * given node. Diffs against the previous render's slot set tracked in
+     * {@link nodeDecorationSlots}: mounts new ids, removes vanished ones,
+     * replaces specs whose slot id appears in both.
+     */
+    private syncNodeDecorations;
+    /** Sibling of {@link syncNodeDecorations} for edges. */
+    private syncEdgeDecorations;
+    /**
+     * Resolve the final list of badges for a node by concatenating every
+     * contributing layer (layer template + per-node base + each active state
+     * overlay) and deduping by `id`. Later precedence wins. Entries without an
+     * explicit `id` fall back to `badge#<combined-index>` so id-less badges
+     * stack rather than collapsing.
+     */
+    private resolveNodeBadges;
+    /**
+     * Project the resolved badge map onto the canvas renderer for the given
+     * node. Diffs against the previous render's slot set tracked in
+     * {@link nodeBadgeSlots}: mounts new ids, removes vanished ones, replaces
+     * specs whose slot id appears in both.
+     */
+    private syncNodeBadges;
+    /** Sibling of {@link resolveNodeBadges} for edges. */
+    private resolveEdgeBadges;
+    /** Sibling of {@link syncNodeBadges} for edges. */
+    private syncEdgeBadges;
+    private updateNodeShape;
+    private queueIncidentConnectors;
+    /**
+     * True iff `node`'s resolved style carries a `group` field — the only
+     * signal that promotes the node from a regular renderable into a
+     * compound-group frame.
+     *
+     * Cheap to call: reads {@link resolveNodeStyle} which is already
+     * memoised per render cycle through `Object.assign` of the merged
+     * contributions.
+     */
+    isGroupNode(node: GraphNode): boolean;
+    /** True when this group node's resolved style carries `group.collapsed === true`. */
+    isCollapsedGroup(node: GraphNode): boolean;
+    /**
+     * Public predicate behaviours can use to filter group nodes out of their
+     * own hit pipeline. Hover / select / drag should typically skip groups
+     * when the group is *expanded* (the frame is interaction-less) but treat
+     * a collapsed group as a regular node. Returns one of:
+     *
+     * - `'none'`  — the id is not a group (treat as a regular node).
+     * - `'expanded'` — group, currently expanded. Behaviours wanting to honour
+     *   the "interaction-less frame" intent should early-return.
+     * - `'collapsed'` — group, currently collapsed. Behaviours that act on
+     *   regular nodes should treat this as a normal target.
+     * - `undefined` — no such node.
+     *
+     * The string form is preferred over a boolean pair so a future
+     * `'collapsed-locked'` (or similar) can be added without breaking callers.
+     */
+    getGroupRole(nodeId: string): 'none' | 'expanded' | 'collapsed' | undefined;
+    /**
+     * Climb the `parentId` chain from `nodeId` (exclusive) and return the
+     * first ancestor whose resolved style has `group.collapsed === true`, or
+     * `undefined` if no such ancestor exists. Used to decide whether a node
+     * is currently hidden (any collapsed ancestor → hidden) and where to
+     * re-route an incident edge (to that collapsed ancestor).
+     */
+    collapsedAncestor(nodeId: string): string | undefined;
+    /**
+     * Resolve which renderer-side shape id an edge endpoint should attach to
+     * for `nodeId`. Returns the nearest collapsed-group ancestor when the
+     * node is hidden, or `nodeId` unchanged when the node is visible. Pure
+     * read — the store's `edge.source` / `edge.target` are never mutated.
+     */
+    effectiveEndpoint(nodeId: string): string;
+    /**
+     * Walk the `parentId` chain from `nodeId` and `add` every group ancestor
+     * to {@link dirtyGroups}. Called whenever a descendant moves, is added,
+     * or otherwise triggers an auto-fit recompute.
+     */
+    private markGroupAncestorsDirty;
+    /**
+     * After a group flips `collapsed`, every descendant changes visibility
+     * and every incident edge of every descendant needs re-routing (the
+     * endpoint now resolves to either the original node or to the collapsed
+     * group ancestor). Walk the subtree once, re-render each descendant
+     * (which re-projects `visible`), and queue incident edges for re-route.
+     */
+    private refreshDescendantsAndIncidentEdges;
+    /**
+     * Compute the world-space AABB of the direct (one-level) children of
+     * `groupId`. Returns `undefined` when the group has no children — the
+     * caller falls back to whatever floor size the group's declared
+     * width/height/radius provides.
+     *
+     * Recurses into child groups via {@link boundsOfNode} so a child whose
+     * own frame has already been auto-fit contributes its current size, not
+     * its stored declared size.
+     */
+    private directChildrenWorldBounds;
+    /**
+     * Project an expanded group's spec — apply auto-fit (when enabled),
+     * compose the children-derived width/height/radius with the group's
+     * declared floor, and shift `pos` so the frame wraps the bbox correctly.
+     *
+     * For `kind: 'rect'`: `pos` becomes top-left of the framed area; size is
+     * `max(declared, childrenAABB) + 2 · padding (+ headerHeight on y)`.
+     *
+     * For `kind: 'circle'`: `pos` becomes the AABB centroid; `radius` is
+     * `max(declared, AABB half-diagonal) + padding`. The half-diagonal is
+     * the smallest enclosing-circle approximation that's still cheap
+     * (`Math.hypot` over AABB half-extents); true minimum-enclosing-circle
+     * (Welzl) is out of scope.
+     *
+     * Non-rect / non-circle group shapes pass through untouched — autoFit is
+     * a no-op outside those two kinds. Domain shapes that want their own
+     * fit math can extend the layer's projection later.
+     */
+    private projectGroupShape;
+    /**
+     * Force a group's frame to re-project right now (outside the normal
+     * flush cycle). Public escape hatch for feeds that remove children
+     * individually without triggering a position change on a sibling — the
+     * `node:remove` event doesn't carry the parentId, so the layer can't
+     * mark the parent dirty on its own. Domain code can call this after
+     * `store.removeNode` to make the auto-fit frame catch up.
+     */
+    recomputeGroup(groupId: string): void;
+    /**
+     * Drain {@link dirtyGroups} in deepest-first order. Each pop re-renders
+     * the group (re-running `nodeSpec` with the latest auto-fit math) and
+     * marks the group's own parent chain dirty so a multi-level nested
+     * group cascade settles in one flush.
+     *
+     * Bounded by `MAX_PASSES` to defend against a pathological cycle (which
+     * the cycle-rejecting store should already prevent on insert, but the
+     * extra guard is cheap).
+     */
+    private drainDirtyGroups;
+    /**
+     * Count of ancestors between `nodeId` and the root (`parentId === undefined`).
+     * Used by {@link drainDirtyGroups} to order deepest first so a child
+     * group recomputes before any group that depends on its bounds.
+     */
+    private depthOf;
+    /**
+     * Project the synthetic group-only decorations onto the renderer:
+     * - the `+` / `−` toggle button at the group's bottom anchor; and
+     * - a centred count badge (label decoration) when the group is
+     *   collapsed, showing the number of hidden descendants.
+     *
+     * Called on every node lifecycle event for group nodes. Cleared
+     * automatically when `style.group` goes away (the slots get `null` so
+     * any previous mount disposes).
+     */
+    private syncGroupSyntheticDecorations;
+    private updateEdgeConnector;
+}
+
+/**
+ * `MiniMapLayer` — bird's-eye overview of a `GraphLayer` with a draggable
+ * viewport indicator.
+ *
+ * Implemented as a `ScreenLayer` rather than a self-hosted pixi `Application`
+ * — much cheaper, no extra GPU surface, and pans/zooms/visibility integrate
+ * with the main canvas naturally. The minimap occupies a fixed
+ * `width × height` rectangle anchored to a corner of the viewport.
+ *
+ * Cross-layer dependency declared via `graphLayerId` per the canvas
+ * architecture rule: no inference of "the only graph layer". You must point
+ * the minimap at a specific id.
+ *
+ * @example
+ * ```ts
+ * const graph = new GraphLayer({ id: 'graph', options: {} });
+ * canvas.layers.add(graph);
+ *
+ * const minimap = new MiniMapLayer({
+ *   id: 'minimap',
+ *   options: { graphLayerId: 'graph', position: 'bottom-right' },
+ * });
+ * canvas.layers.add(minimap);
+ * ```
+ */
+
+/** Anchor corner inside the canvas viewport. */
+type MiniMapPosition = 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+/** Constructor options for `MiniMapLayer`. */
+interface MiniMapLayerOptions {
+    /** Required — the `GraphLayer` id this minimap mirrors. */
+    graphLayerId: string;
+    /** Minimap width in screen pixels. Default `200`. */
+    width?: number;
+    /** Minimap height in screen pixels. Default `150`. */
+    height?: number;
+    /** Background fill `0xRRGGBB`. Default `0x1a1a2e`. */
+    backgroundColor?: number;
+    /** Border colour `0xRRGGBB`. Default `0x444444`. */
+    borderColor?: number;
+    /** Border stroke width. Default `1`. */
+    borderWidth?: number;
+    /** Viewport indicator fill. Default `0x4a90d9`. */
+    viewportFill?: number;
+    /** Viewport indicator stroke. Default `0x2a70b9`. */
+    viewportStroke?: number;
+    /** Viewport indicator fill alpha 0–1. Default `0.3`. */
+    viewportFillAlpha?: number;
+    /** Viewport indicator stroke width. Default `2`. */
+    viewportStrokeWidth?: number;
+    /** World-space padding around node bounds. Default `20`. */
+    padding?: number;
+    /** Whether dragging the minimap pans the main camera. Default `true`. */
+    enableDrag?: boolean;
+    /** Anchor corner. Default `'bottom-right'`. */
+    position?: MiniMapPosition;
+    /**
+     * Inset from the chosen corner, in screen pixels. Pass a single number for a
+     * symmetric inset, or `{ x, y }` for independent horizontal / vertical insets
+     * (e.g. to bottom-align the minimap with a control rail while clearing its
+     * width). A missing axis on the object form falls back to `10`. Default `10`.
+     */
+    margin?: number | {
+        x?: number;
+        y?: number;
+    };
+}
+interface MiniMapState {
+    readonly _placeholder?: never;
+}
+declare class MiniMapLayer extends ScreenLayer<MiniMapLayerOptions, MiniMapState, Record<string, never>, never, ScreenLayerHit> {
+    private opts;
+    private readonly graphLayerId;
+    private graph;
+    private ctxRef;
+    /** Inner content container (the minimap's drawable area). */
+    private inner;
+    private bgGfx;
+    private worldGfx;
+    private viewportGfx;
+    /** Per-frame projection scale + offset (world → minimap-local). */
+    private scale;
+    private offsetX;
+    private offsetY;
+    /** Drag state. */
+    private isDragging;
+    private dragOffsetX;
+    private dragOffsetY;
+    /** ResizeObserver disposer. */
+    private offResize;
+    private offCameraPan;
+    private offCameraZoom;
+    constructor(opts: LayerOptions<MiniMapLayerOptions>);
+    protected createState(): MiniMapState;
+    protected onMount(ctx: CanvasContext): void;
+    protected onUnmount(): void;
+    hitTest(): ScreenLayerHit | null;
+    /** Force a re-paint. Cheap — call after mutating colours / sizes externally. */
+    refresh(): void;
+    setOptions(patch: Partial<Omit<MiniMapLayerOptions, 'graphLayerId'>>): void;
+    private viewportSize;
+    private layoutPosition;
+    private repaint;
+    private paintBackground;
+    private paintWorld;
+    /**
+     * Pre-mount / pre-install fallback for shape bounds. Used when the renderer
+     * hasn't yet built an instance for a node (very brief window — the layer's
+     * `data:changed` event repaints the minimap as soon as the renderer catches
+     * up).
+     *
+     * Delegates to {@link GraphLayer.boundsOfNode}, which routes through the
+     * shape registry's `static boundsOf` hook — built-in and custom shape
+     * kinds flow through the same code path. Falls back to a 32px square
+     * AABB centred on the node's stored position when the resolved shape
+     * isn't registered or its ctor doesn't expose `boundsOf`.
+     */
+    private fallbackNodeBounds;
+    private paintViewportIndicator;
+    /** Union node bounds with the current camera-visible bounds. */
+    private effectiveBounds;
+    /**
+     * AABB of all drawn node *footprints* + padding, queried directly from the
+     * renderer's per-instance world bounds — so arcs / polygons / stars /
+     * custom shapes contribute their true extent, not a hardcoded size-derived
+     * estimate. Pre-mount nodes fall through to a position+default-size box.
+     * Returns a 1000×1000 placeholder when the layer has no nodes yet.
+     */
+    private nodeBounds;
+    private projectBounds;
+    private worldToMinimap;
+    private minimapToWorld;
+    private wireInteractions;
+    private onMiniPointerDown;
+    private onMiniPointerMove;
+    private onMiniPointerUp;
+    /** Position the main camera so the world point `(wx, wy)` lands at screen centre. */
+    private panMainCameraTo;
+}
+
+/**
+ * `@invana/graph` — undo/redo history types.
+ *
+ * History is a **command/transaction journal**: each undoable change is one
+ * {@link HistoryEntry} holding the ordered {@link HistoryOp}s applied to the
+ * {@link GraphStore}, each carrying enough state to be inverted. Inverses are
+ * captured *before* the mutation runs (read-before-write), which is the only way
+ * to reconstruct a deleted node/edge — the store's `node:remove` / `edge:remove`
+ * events fire *after* the data is already gone.
+ *
+ * Only mutations routed through {@link GraphHistory.transaction} (or pushed via
+ * {@link GraphHistory.push}) are recorded. Silent layout-sim position writes and
+ * streaming feed deltas bypass the journal by design, so they never flood the
+ * undo stack.
+ */
+
+/**
+ * A single invertible store mutation. `removeNode` carries the cascade-removed
+ * incident `edges` so undo can restore them alongside the node. `update*` ops
+ * carry both `before` (for undo) and `after` (for redo) partial states.
+ */
+type HistoryOp = {
+    kind: 'addNode';
+    node: GraphNode;
+} | {
+    kind: 'removeNode';
+    node: GraphNode;
+    edges: GraphEdge[];
+} | {
+    kind: 'updateNode';
+    id: string;
+    before: Partial<GraphNode>;
+    after: Partial<GraphNode>;
+} | {
+    kind: 'moveNode';
+    id: string;
+    before: Vec2;
+    after: Vec2;
+} | {
+    kind: 'addEdge';
+    edge: GraphEdge;
+} | {
+    kind: 'removeEdge';
+    edge: GraphEdge;
+} | {
+    kind: 'updateEdge';
+    id: string;
+    before: Partial<GraphEdge>;
+    after: Partial<GraphEdge>;
+};
+/** One undoable unit of work — a labelled, ordered list of {@link HistoryOp}s. */
+interface HistoryEntry {
+    /** Ops in application order. Undo replays inverses in reverse; redo replays forward. */
+    ops: HistoryOp[];
+    /** Human label for the change (e.g. `'delete selection'`, `'paste'`). */
+    label?: string;
+}
+/**
+ * The mutation surface handed to {@link GraphHistory.transaction}'s callback.
+ * Each method applies the change to the store **and** journals its inverse.
+ * Use these instead of calling `store.*` directly so the change is undoable.
+ */
+interface HistoryRecorder {
+    /** Add a node (inverse: remove it). */
+    addNode(node: GraphNode): void;
+    /** Remove a node + its incident edges, cascading (inverse: re-add node + edges). */
+    removeNode(id: string): void;
+    /** Patch a node (inverse: restore the patched fields' prior values). */
+    updateNode(id: string, patch: Partial<GraphNode>): void;
+    /** Move a node (inverse: restore the prior position). */
+    moveNode(id: string, position: Vec2): void;
+    /** Add an edge (inverse: remove it). */
+    addEdge(edge: GraphEdge): void;
+    /** Remove an edge (inverse: re-add it). */
+    removeEdge(id: string): void;
+    /** Patch an edge (inverse: restore the patched fields' prior values). */
+    updateEdge(id: string, patch: Partial<GraphEdge>): void;
+}
+/** Event-map for {@link GraphHistory.events}. */
+type GraphHistoryEventMap = {
+    /** Fired after every undo / redo / record / clear so observers can re-read state. */
+    change: {
+        canUndo: boolean;
+        canRedo: boolean;
+        undoDepth: number;
+        redoDepth: number;
+    };
+};
+/** Constructor options for {@link GraphHistory}. */
+interface GraphHistoryOptions {
+    /** Maximum undo depth; oldest entries are dropped past this. Default `100`. */
+    limit?: number;
+}
+
+/**
+ * `GraphHistory` — undo/redo for a {@link GraphStore}.
+ *
+ * A **command/transaction journal**, not a snapshot store and not a passive
+ * event listener. Mutations are recorded only when routed through
+ * {@link GraphHistory.transaction} (or {@link GraphHistory.push}); everything
+ * else — streaming feed deltas, silent layout-sim position writes — bypasses the
+ * journal, so the undo stack stays meaningful and small.
+ *
+ * @example
+ * ```ts
+ * const history = new GraphHistory(layer.store);
+ * history.transaction('delete selection', (rec) => {
+ *   for (const id of selectedIds) rec.removeNode(id);
+ * });
+ * history.undo(); // restores the nodes + their incident edges
+ * ```
+ */
+
+declare class GraphHistory {
+    /** Fires `change` after every mutation so observers can re-read undo/redo state. */
+    readonly events: EventEmitter<GraphHistoryEventMap>;
+    private readonly store;
+    private readonly limit;
+    private readonly undoStack;
+    private readonly redoStack;
+    /** Ops buffer for the in-flight transaction. Non-null only while recording. */
+    private recording;
+    /** Nesting depth — only the outermost `transaction` commits an entry. */
+    private depth;
+    constructor(store: GraphStore, opts?: GraphHistoryOptions);
+    /** True iff there is at least one entry that can be undone. */
+    get canUndo(): boolean;
+    /** True iff there is at least one undone entry that can be redone. */
+    get canRedo(): boolean;
+    /**
+     * Run `fn`'s mutations as one undoable entry. Mutations MUST go through the
+     * {@link HistoryRecorder} passed to `fn` to be journaled. The whole body runs
+     * inside {@link GraphStore.batch}, so the canvas sees a single flush. Nested
+     * `transaction` calls merge into the outermost entry. Returns `fn`'s result.
+     */
+    transaction<T>(label: string, fn: (rec: HistoryRecorder) => T): T;
+    /**
+     * Record an already-applied entry. Escape hatch for mutations that happen
+     * outside {@link transaction} — e.g. a drag behaviour that writes positions
+     * during the gesture and, on release, pushes a single `moveNode` op with the
+     * captured start/end positions. The ops are assumed to be applied already;
+     * this only journals them.
+     */
+    push(entry: HistoryEntry): void;
+    /** Revert the most recent entry and move it onto the redo stack. No-op if empty. */
+    undo(): void;
+    /** Re-apply the most recently undone entry and move it back onto the undo stack. */
+    redo(): void;
+    /** Wipe both stacks. Use when loading a fresh dataset. */
+    clear(): void;
+    private commit;
+    private emitChange;
+    /**
+     * The recorder handed to `transaction` callbacks. Each method applies the
+     * change to the store and appends its op (carrying the pre-mutation state) to
+     * the in-flight ops buffer.
+     */
+    private readonly recorder;
+    private record;
+    /** Snapshot the patched fields' prior values for a node. `null` if unknown id. */
+    private captureNodeBefore;
+    private captureEdgeBefore;
+    /** Cloned incident edges (both directions), deduped — self-loops appear once. */
+    private incidentEdges;
+    private applyForward;
+    private applyInverse;
+    /** Re-add edges whose both endpoints exist; skip duplicates and danglers. */
+    private readdEdges;
+}
+
+/**
+ * `GraphClipboard` — copy / cut / paste / delete for a {@link GraphStore}.
+ *
+ * Holds an in-memory buffer of cloned node/edge specs. It does **not** read the
+ * current selection itself — the caller passes the ids in (the canvas-react
+ * `useClipboard` hook reads them off a `ClickSelectBehaviour`). This keeps the
+ * clipboard decoupled from the selection mechanism and trivially testable.
+ *
+ * cut / paste / delete each run as a single undoable {@link GraphHistory}
+ * transaction when a history instance is supplied; otherwise they fall back to a
+ * plain {@link GraphStore.batch} (one flush, not undoable).
+ *
+ * @example
+ * ```ts
+ * const clipboard = new GraphClipboard(layer.store);
+ * clipboard.copy(selectedNodeIds, selectedEdgeIds);
+ * const { nodeIds } = clipboard.paste(history); // offset + re-id'd
+ * clickSelect.selectMultiple(nodeIds.map((id) => ({ id })));
+ * ```
+ */
+
+/** Event-map for {@link GraphClipboard.events}. */
+type GraphClipboardEventMap = {
+    /** Fired whenever the buffer's contents change (copy / clear). Drives "can paste". */
+    change: {
+        hasContent: boolean;
+    };
+};
+/** Constructor options for {@link GraphClipboard}. */
+interface GraphClipboardOptions {
+    /** Offset applied to pasted node positions to avoid exact overlap. Default `{x:24,y:24}`. */
+    pasteOffset?: Vec2;
+    /**
+     * Candidate id generator for pasted nodes/edges. Called with increasing
+     * `attempt` until the returned id is free. Default `${oldId}-copy[-N]`.
+     */
+    remapId?: (oldId: string, attempt: number) => string;
+}
+/** Ids produced by a {@link GraphClipboard.paste}. */
+interface PasteResult {
+    nodeIds: string[];
+    edgeIds: string[];
+}
+declare class GraphClipboard {
+    /** Fires `change` whenever the buffer's contents change (copy / clear). */
+    readonly events: EventEmitter<GraphClipboardEventMap>;
+    private readonly store;
+    private readonly pasteOffset;
+    private readonly remapId;
+    private bufferedNodes;
+    private bufferedEdges;
+    constructor(store: GraphStore, opts?: GraphClipboardOptions);
+    /** True iff the buffer holds at least one node or edge (drives "can paste"). */
+    get hasContent(): boolean;
+    /** Empty the buffer. */
+    clearBuffer(): void;
+    /**
+     * Snapshot the given ids into the buffer (clones, so later store mutations
+     * don't mutate the buffer). Unknown ids are skipped. Replaces prior contents.
+     */
+    copy(nodeIds: readonly string[], edgeIds?: readonly string[]): void;
+    /** Copy the ids into the buffer, then delete them as one undoable transaction. */
+    cut(nodeIds: readonly string[], edgeIds: readonly string[], history?: GraphHistory): void;
+    /** Delete the given ids as one undoable transaction. Buffer is left untouched. */
+    delete(nodeIds: readonly string[], edgeIds: readonly string[], history?: GraphHistory): void;
+    /**
+     * Insert the buffer with fresh ids (collision-free) and a position offset, as
+     * one undoable transaction. Only buffered edges whose **both** endpoints were
+     * also buffered are pasted, with endpoints remapped to the new node ids.
+     * `parentId` is remapped when the parent was pasted too, else dropped.
+     *
+     * Returns the new ids so the caller can re-select the pasted items.
+     */
+    paste(history?: GraphHistory): PasteResult;
+    /** Remove explicit edges first, then nodes (cascade), mirroring `applyDelta`. */
+    private removeAsTransaction;
+    /** Pick the first remapped id that is neither already in the store nor reserved. */
+    private freshId;
+    /**
+     * A recorder that mutates the store directly without journaling — used when no
+     * {@link GraphHistory} is supplied so paste/cut/delete still run as one batch.
+     */
+    private plainRecorder;
+}
+
+/**
+ * `HoverActivateBehaviour` — toggles a named visual state on hovered nodes /
+ * edges (and optionally their N-hop neighbours), with optional dimming of
+ * everything else.
+ *
+ * Layer-scoped: constructed with a target `layerId` referencing a
+ * {@link GraphLayer}. Subscribes to that layer's renderer pointer events
+ * (`shape:pointerover` / `connector:pointerover`) and drives layer state via
+ * `layer.store.setNodeState` / `layer.store.setEdgeState`.
+ *
+ * Default `enabled: false` — register, then explicitly enable. Matches the
+ * project rule that no behaviour auto-activates.
+ *
+ * Defaults align with the canonical state catalogue auto-merged into
+ * every `GraphLayer`: `state: 'hovered'` for the focal (and N-hop
+ * neighbours when `degree > 0`), and optional `inactiveState: 'dimmed'`
+ * for everything else. Override these when the project's state
+ * vocabulary diverges.
+ *
+ * @example
+ * ```ts
+ * // Layer defaults already include `hovered`, `highlighted`, `dimmed` —
+ * // no setup needed beyond registering the behaviour.
+ *
+ * canvas.behaviours.register(
+ *   new HoverActivateBehaviour({
+ *     id: 'hover',
+ *     layerId: 'graph',
+ *     enabled: true,
+ *     // state defaults to 'hovered'
+ *     inactiveState: 'dimmed',
+ *     degree: 1,
+ *   }),
+ * );
+ * ```
+ */
+
+/** Element kind for hover targets. */
+type HoverableElementType = 'shape' | 'connector';
+/** Edge-traversal direction filter for neighbour expansion. */
+type HoverDirection = 'in' | 'out' | 'both';
+/** Element handed to hover callbacks. */
+interface HoverableElement {
+    readonly id: string;
+    readonly type: HoverableElementType;
+    /** Arbitrary user payload from `node.data` or `edge.data`. */
+    readonly data: unknown;
+}
+/** Constructor options for `HoverActivateBehaviour`. */
+interface HoverActivateBehaviourOptions extends BehaviourOptions {
+    /** Required — the `GraphLayer` id this behaviour drives. */
+    layerId: string;
+    /**
+     * Per-target enable predicate. `boolean` is a global on/off; a function
+     * runs per pointer-over and may veto activation. Default `true`.
+     */
+    enable?: boolean | ((element: HoverableElement) => boolean);
+    /**
+     * State name applied to the hovered focal element (and its N-hop
+     * neighbours when `degree > 0`). Default `'hovered'` — matches the
+     * canonical state catalogue auto-merged into every `GraphLayer`. Pass
+     * a custom name when the behaviour should write a project-specific
+     * state instead (e.g. `'focal'`).
+     */
+    state?: string;
+    /**
+     * State name applied to every element *not* in the active set. Leave
+     * `undefined` to skip inactive dimming. Default `undefined`.
+     */
+    inactiveState?: string;
+    /**
+     * Lift the active set (the hovered focal element + its N-hop neighbours)
+     * above the rest within its render layer for the duration of the hover, so
+     * unrelated nodes / edges don't paint over the highlighted data. Edges raise
+     * above other edges (still below all nodes); neighbour nodes raise above
+     * other nodes. Reset when the hover clears. Visual-only — restacking doesn't
+     * affect hit-testing. Default `true`.
+     */
+    raiseActive?: boolean;
+    /**
+     * N-hop neighbour radius. `0` = hovered element only; `1` = direct
+     * neighbours + connecting edges; `N` = N-hop. Default `0`.
+     */
+    degree?: number;
+    /** Direction for neighbour traversal. Default `'both'`. */
+    direction?: HoverDirection;
+    /**
+     * Camera scale at or below which the behaviour swaps `state` for
+     * `zoomedOutState` (and `zoomedOutEdgeState` for edges). The hovered set
+     * gets re-painted through the swapped state names whenever the camera
+     * crosses this threshold mid-hover. Omit (or leave both zoomed-out names
+     * undefined) and the behaviour is identical to today.
+     *
+     * Typical use: at world-level zoom every node collapses to ~1 anti-aliased
+     * pixel, so the normal `active` state is invisible against background
+     * dots. A bigger `active-far` config (size + strokeWidth bumped) makes
+     * the hovered node pop.
+     */
+    zoomThreshold?: number;
+    /**
+     * State name applied to the hovered node + N-hop neighbour nodes when
+     * `camera.scale <= zoomThreshold`. Falls back to `state` when undefined
+     * (no node-side zoom swap, but edges may still swap via
+     * `zoomedOutEdgeState`).
+     */
+    zoomedOutState?: string;
+    /**
+     * State name applied to connecting edges when
+     * `camera.scale <= zoomThreshold` AND `degree > 0`. Falls back to `state`
+     * when undefined.
+     */
+    zoomedOutEdgeState?: string;
+    /**
+     * Gfx-transform scale multiplier applied to each hovered node (and the
+     * N-hop neighbour nodes) when `camera.scale <= zoomThreshold`. Pure
+     * transform write via {@link PrimitivesRenderer.scaleShape} — no geometry
+     * rebuild, no styling change. Use this when you want the hovered node to
+     * just *grow visually* at low zoom (so it stands out against ~1 px
+     * background dots) while keeping its original colour, stroke, and label.
+     *
+     * Multiplies the existing `gfx.scale`, so if `NodeSizeLODBehaviour` is
+     * also active it will overwrite the multiplier on the next zoom frame —
+     * prefer `zoomedOutState` with a bigger `size` in that case. For stories
+     * without an LOD behaviour, this is the cleanest "scale on hover" knob.
+     *
+     * Only nodes are scaled — connectors don't compose cleanly with
+     * `gfx.scale` (the polyline would shift, not just thicken). The hovered
+     * node's outgoing edges still anchor to its geometric position, which
+     * sits inside the now-bigger silhouette — visually acceptable.
+     *
+     * `undefined` (default) and `1` both disable the multiplier.
+     */
+    zoomedOutScale?: number;
+    /** Fired when an element first becomes hovered. */
+    onHover?: (element: HoverableElement) => void;
+    /** Fired when hover ends on a previously hovered element. */
+    onHoverEnd?: (element: HoverableElement) => void;
+}
+interface ResolvedOptions$6 {
+    enable: boolean | ((element: HoverableElement) => boolean);
+    state: string;
+    inactiveState: string | undefined;
+    raiseActive: boolean;
+    degree: number;
+    direction: HoverDirection;
+    zoomThreshold: number | undefined;
+    zoomedOutState: string | undefined;
+    zoomedOutEdgeState: string | undefined;
+    zoomedOutScale: number | undefined;
+    onHover: ((element: HoverableElement) => void) | undefined;
+    onHoverEnd: ((element: HoverableElement) => void) | undefined;
+}
+declare class HoverActivateBehaviour extends Behaviour {
+    /** Bound target layer — resolved in `onRegister`. */
+    private layer;
+    private opts;
+    /** Subscription disposers, called in `onDestroy`. */
+    private subs;
+    /** Currently hovered element, or `null`. */
+    private current;
+    /** Neighbour ids that received the active state (excluding `current`). */
+    private activeIds;
+    /** Element ids that received the inactive state. */
+    private inactiveIds;
+    /**
+     * State name actually applied to nodes for the current hover — equals
+     * `opts.state` normally, `opts.zoomedOutState` when the camera was below
+     * `opts.zoomThreshold` at activation (or after a mid-hover swap). Tracked
+     * so `clearHover` / `swapStates` remove whatever was actually applied,
+     * not just whatever the current `opts.state` is now.
+     */
+    private appliedNodeState;
+    /** Sibling of {@link appliedNodeState} for edges. */
+    private appliedEdgeState;
+    /**
+     * Gfx-transform multiplier currently applied to the hovered node set.
+     * `1` (or `null`) means no multiplier is active. Tracked so a threshold
+     * cross or clear can reset only the ids we actually scaled.
+     */
+    private appliedScale;
+    /** Node ids currently scaled via `renderer.scaleShape` — reset on clear. */
+    private readonly scaledNodeIds;
+    /**
+     * `gfx.zIndex` written to the active set when `raiseActive` is on. Any value
+     * above the default `0` lifts the element over its untouched peers; `1` is
+     * enough and keeps hover- and selection-raises on the same tier.
+     */
+    private static readonly RAISED_Z_INDEX;
+    /** Ids currently raised via `renderer.raiseShape` / `raiseConnector`. */
+    private readonly raisedIds;
+    constructor(opts: HoverActivateBehaviourOptions);
+    protected onRegister(ctx: CanvasContext): void;
+    protected onDestroy(): void;
+    protected onDisable(): void;
+    /** The element currently driving the hover effect, or `null`. */
+    get hoveredElement(): HoverableElement | null;
+    /** Read-only snapshot of resolved options. */
+    get options(): Readonly<ResolvedOptions$6>;
+    /**
+     * Runtime option update. State-affecting changes clear any in-flight hover
+     * so the next hover applies the new visuals cleanly.
+     */
+    setOptions(patch: Partial<HoverActivateBehaviourOptions>): void;
+    /** Clear all states applied by the current hover. */
+    clearHover(): void;
+    private handlePointerOver;
+    private handlePointerOut;
+    private activate;
+    /**
+     * Choose which node + edge state names AND gfx scale to apply right now,
+     * based on `camera.scale` vs. `opts.zoomThreshold`.
+     *
+     * - `node` / `edge`: `opts.state` (or `opts.zoomedOutState` /
+     *   `opts.zoomedOutEdgeState` at far zoom). Each role falls back to
+     *   `opts.state` independently.
+     * - `scale`: `1` (or `opts.zoomedOutScale` at far zoom). The scale
+     *   multiplier is independent of the state-name swap — a story can
+     *   configure either, both, or neither.
+     */
+    private pickTier;
+    /**
+     * Handle a `camera:zoom` event while a hover is active. Two independent
+     * dimensions may change as the camera crosses the threshold:
+     *
+     * - State names — swap via {@link swapStates} (state-config-driven
+     *   restyle, composes with `NodeSizeLODBehaviour`).
+     * - Scale multiplier — re-apply via {@link applyScale} (`gfx.scale`
+     *   write, does NOT compose with LOD).
+     *
+     * Idempotent: a zoom that doesn't cross the threshold leaves both
+     * dimensions unchanged and exits cheaply.
+     */
+    private handleCameraZoom;
+    /**
+     * Set / reset `gfx.scale` on the hovered node set. Pure transform write
+     * via {@link PrimitivesRenderer.scaleShape} — no geometry rebuild,
+     * preserves the node's spec-driven colour, stroke, label, etc.
+     *
+     * Resets any previously-scaled ids first so `applyScale(1)` is a clean
+     * teardown. Only ids that resolve to shapes (not connectors) are
+     * touched — `activeIds` is a flat set of mixed kinds; `renderer.hasShape`
+     * filters out edge ids cheaply.
+     */
+    private applyScale;
+    /**
+     * Raise the current hovered set (`current` + `activeIds`) above their peers
+     * via `renderer.raiseShape` / `raiseConnector`. `activeIds` is a flat set of
+     * mixed kinds, so each id is dispatched by `hasShape` / `hasConnector`.
+     * Tracked in {@link raisedIds} so {@link resetRaise} restores exactly the
+     * ids we touched.
+     */
+    private applyRaise;
+    /** Reset every id raised by {@link applyRaise} back to the default z (0). */
+    private resetRaise;
+    /**
+     * Walk the current hovered set (`current` + `activeIds`) and replace the
+     * previously-applied state names with `picked.node` / `picked.edge`.
+     * Skips work per-role when the state name didn't change for that role
+     * (e.g. only the edge state swapped while the node state stayed put).
+     *
+     * `activeIds` is a flat set containing both node and edge ids — we don't
+     * track type per id, so we call `setNodeState` / `setEdgeState` for both;
+     * mismatched calls (an id that doesn't exist in that store) no-op
+     * gracefully. Matches the existing pattern in {@link clearHover}.
+     */
+    private swapStates;
+    /** BFS neighbourhood expansion using the store's adjacency index. */
+    private collectNeighbours;
+    private applyInactive;
+    private resolveElement;
+}
+
+/**
+ * `ModifierTracker` — global helper that tracks which keyboard modifier keys
+ * are currently held. Several behaviours (Click/Brush/Lasso) need to know
+ * the modifier state at the moment of a pointer event, but the renderer's
+ * shape/connector pointer events don't carry that info — they're synthesised
+ * from PixiJS events. Tracking modifiers via window-level key events is the
+ * pragmatic substitute.
+ *
+ * Reference-counted: the first behaviour to call `attach()` installs the
+ * window listeners; subsequent `attach()` calls just bump the counter.
+ * `detach()` removes the listeners when the count returns to zero.
+ *
+ * @internal — not exported from `@invana/graph`. Used by behaviours.
+ */
+type ModifierKey = 'shift' | 'control' | 'alt' | 'meta';
+
+/**
+ * `ClickSelectBehaviour` — toggles a named visual state on clicked nodes /
+ * edges with optional N-degree neighbour expansion, modifier-driven
+ * multi-select, and optional dimming of unselected elements.
+ *
+ * Layer-scoped: constructed with a target `layerId`. Subscribes to that
+ * layer's renderer click events and to the canvas-level `background:click`
+ * for clear-on-background behaviour.
+ *
+ * Default `enabled: false` — register, then explicitly enable.
+ *
+ * The canonical `selected` state is auto-merged into every
+ * `GraphLayer`'s state catalogue — no setup needed. Override the layer's
+ * `options.node.state.selected` to customise the visual.
+ *
+ * @example
+ * ```ts
+ * canvas.behaviours.register(
+ *   new ClickSelectBehaviour({
+ *     id: 'select',
+ *     layerId: 'graph',
+ *     enabled: true,
+ *     multiple: true,
+ *     degree: 1,
+ *   }),
+ * );
+ * ```
+ */
+
+/** Element kind for selection targets. */
+type SelectableElementType = HoverableElementType;
+/** Edge-traversal direction filter. */
+type SelectDirection = HoverDirection;
+/** Modifier-key names accepted by `trigger`. */
+type SelectModifierKey = ModifierKey;
+/** Element handed to selection callbacks. */
+interface SelectableElement {
+    readonly id: string;
+    readonly type: SelectableElementType;
+    /** Arbitrary user payload from `node.data` or `edge.data`. */
+    readonly data: unknown;
+}
+/** Per-flush snapshot fired to `onSelectionChange`. */
+interface SelectionSnapshot {
+    shapeIds: string[];
+    connectorIds: string[];
+}
+/** Event-map for {@link ClickSelectBehaviour.events}. */
+type ClickSelectEventMap = {
+    /**
+     * Fired once whenever the selection set is replaced (click, `select*`,
+     * `clearSelection`, or brush/lasso delegation). The non-clobbering complement
+     * to the `onSelectionChange` callback — observers (e.g. the canvas-react
+     * `useSelection` hook) subscribe here instead of hijacking the callback.
+     */
+    'selection:change': SelectionSnapshot;
+};
+/** Constructor options for `ClickSelectBehaviour`. */
+interface ClickSelectBehaviourOptions extends BehaviourOptions {
+    /** Required — the `GraphLayer` id this behaviour drives. */
+    layerId: string;
+    /**
+     * Per-target enable predicate. `boolean` is a global on/off; a function
+     * runs per click and may veto. Default `true`.
+     */
+    enable?: boolean | ((element: SelectableElement) => boolean);
+    /**
+     * Allow more than one element selected at a time. When `true`, a qualifying
+     * click (see `trigger`) toggles the element in/out of the selection; when
+     * `false` it replaces the selection with the clicked element. Default `false`.
+     */
+    multiple?: boolean;
+    /**
+     * Modifier key(s) required for a click to affect the selection **at all**.
+     * When non-empty, a click that holds none of these is ignored — a plain
+     * (unmodified) click selects nothing, and a plain left-drag stays a pure
+     * pan. With a modifier held, the click selects (replacing the selection, or
+     * toggling membership when `multiple` is `true`). Empty array = every click
+     * selects, no modifier needed. Default `[]` (plain click selects). Pass
+     * `['shift']` to gate selection behind the Shift key.
+     */
+    trigger?: SelectModifierKey[];
+    /**
+     * N-hop neighbour radius around each seed. `0` = clicked element only.
+     * Default `0`.
+     */
+    degree?: number;
+    /** Direction for neighbour traversal. Default `'both'`. */
+    direction?: SelectDirection;
+    /** Active-state name. Default `'selected'`. */
+    state?: string;
+    /**
+     * State applied to every element that is *not* selected. `undefined`
+     * disables dimming. Default `undefined`.
+     */
+    unselectedState?: string;
+    /**
+     * Lift the selected set (seeds + degree-expanded neighbours) above the rest
+     * within its render layer, so unrelated nodes / edges don't paint over the
+     * selection. Edges raise above other edges (still below all nodes); nodes
+     * raise above other nodes. Reset when the selection clears. Visual-only —
+     * restacking doesn't affect hit-testing. Default `true`.
+     */
+    raiseActive?: boolean;
+    /** Clear selection when clicking the empty canvas background. Default `true`. */
+    clearOnBackground?: boolean;
+    /** Fired when an element becomes selected. */
+    onSelect?: (element: SelectableElement) => void;
+    /** Fired when an element becomes deselected. */
+    onDeselect?: (element: SelectableElement) => void;
+    /** Fired once per click with the post-settle selection snapshot. */
+    onSelectionChange?: (snapshot: SelectionSnapshot) => void;
+}
+interface ResolvedOptions$5 {
+    enable: boolean | ((element: SelectableElement) => boolean);
+    multiple: boolean;
+    trigger: SelectModifierKey[];
+    degree: number;
+    direction: SelectDirection;
+    state: string;
+    unselectedState: string | undefined;
+    raiseActive: boolean;
+    clearOnBackground: boolean;
+    onSelect: ((element: SelectableElement) => void) | undefined;
+    onDeselect: ((element: SelectableElement) => void) | undefined;
+    onSelectionChange: ((snapshot: SelectionSnapshot) => void) | undefined;
+}
+declare class ClickSelectBehaviour extends Behaviour {
+    /**
+     * Selection event bus. Subscribe to `'selection:change'` for a reactive
+     * snapshot every time the selection set is replaced. Independent of (and
+     * additive to) the `onSelectionChange` option.
+     */
+    readonly events: EventEmitter<ClickSelectEventMap>;
+    private layer;
+    private opts;
+    /** Subscription disposers. */
+    private subs;
+    /** Seed set — ids the user *directly* clicked / passed to `select*`. */
+    private seeds;
+    /** Expanded set — seeds + degree-expanded neighbours. */
+    private selected;
+    /** Ids currently rendered with the `unselectedState`. */
+    private unselectedIds;
+    /**
+     * `gfx.zIndex` written to the selected set when `raiseActive` is on. Any
+     * value above the default `0` lifts the element over its untouched peers;
+     * `1` matches `HoverActivateBehaviour`'s raise tier.
+     */
+    private static readonly RAISED_Z_INDEX;
+    /** Ids currently raised via `renderer.raiseShape` / `raiseConnector`. */
+    private readonly raisedIds;
+    /** True when the most recent click already consumed an element. */
+    private clickConsumedByElement;
+    /** Pointerdown screen-position — used to distinguish a click from a drag. */
+    private pointerDownScreen;
+    /**
+     * Set once the pointer travels past the click/drag threshold while a button
+     * is held. Used to suppress the synthetic element `click` that fires at the
+     * end of a node drag — without it, dragging a selected node would collapse
+     * the whole selection down to that one node on release.
+     */
+    private pressMoved;
+    constructor(opts: ClickSelectBehaviourOptions);
+    protected onRegister(ctx: CanvasContext): void;
+    protected onDestroy(): void;
+    protected onDisable(): void;
+    /** Resolved current options (read-only snapshot). */
+    get options(): Readonly<ResolvedOptions$5>;
+    /**
+     * Runtime option update. State-affecting changes clear the current
+     * visual selection and re-apply with the new options.
+     */
+    setOptions(patch: Partial<ClickSelectBehaviourOptions>): void;
+    /** Replace the selection with a single element. */
+    select(id: string, type?: SelectableElementType): void;
+    /** Replace the selection with the given (id, type) pairs. */
+    selectMultiple(elements: Array<{
+        id: string;
+        type?: SelectableElementType;
+    }>): void;
+    /** Add a single element to the current selection. */
+    addToSelection(id: string, type?: SelectableElementType): void;
+    /** Remove a single element from the current selection. */
+    deselect(id: string): void;
+    /** Toggle the membership of `id` in the selection. */
+    toggle(id: string, type?: SelectableElementType): void;
+    /** True iff `id` is part of the rendered selection (seed or expanded). */
+    isSelected(id: string): boolean;
+    /** All currently selected ids (seeds + expanded). */
+    getSelectedIds(): string[];
+    /** Currently selected shape (node) ids. */
+    getSelectedShapeIds(): string[];
+    /** Currently selected connector (edge) ids. */
+    getSelectedConnectorIds(): string[];
+    /** Clear the entire selection and any dimming. */
+    clearSelection(): void;
+    /**
+     * Select every node and edge on the target layer. Replaces the current
+     * selection. No-op if the layer isn't mounted.
+     */
+    selectAll(): void;
+    /**
+     * Select a node together with its neighbours (in the given direction) and the
+     * edges incident to it. Replaces the current selection. No-op if the layer
+     * isn't mounted.
+     *
+     * @param id  Seed node id.
+     * @param dir Adjacency direction for neighbours + incident edges. Default `'both'`.
+     */
+    selectNeighbourhood(id: string, dir?: 'in' | 'out' | 'both'): void;
+    private handleElementClick;
+    /**
+     * Core selection engine: replace seeds, recompute expansion, swap visuals,
+     * diff-emit callbacks.
+     */
+    private applySelection;
+    /** Expand seeds by `degree` hops (BFS) — same shape as HoverActivate. */
+    private expandSeeds;
+    private clearVisualsOnly;
+    /**
+     * Raise the selected set above its peers via `renderer.raiseShape` /
+     * `raiseConnector`. `selected` carries the element type per id, so each is
+     * dispatched directly. Tracked in {@link raisedIds} so {@link resetRaise}
+     * restores exactly the ids we touched.
+     */
+    private applyRaise;
+    /** Reset every id raised by {@link applyRaise} back to the default z (0). */
+    private resetRaise;
+    private applyUnselected;
+    private resolveElement;
+    private buildSnapshot;
+}
+
+/**
+ * `ClickInspectBehaviour` — tracks the **single** node / edge a user clicked for
+ * *inspection / editing*, independent of {@link ClickSelectBehaviour}.
+ *
+ * Selection and inspection are different concerns: selection drives highlighting
+ * and multi-element drag (and may hold many elements at once); inspection feeds a
+ * property editor (`InspectorPanel`), which only ever edits **one** element. This
+ * behaviour is the authority for the latter — it remembers the last element
+ * clicked and clears on a background click — so the editor never has to reach
+ * into the selection set (where a multi-select would leave it with nothing single
+ * to show).
+ *
+ * Layer-scoped: constructed with a target `layerId`. Subscribes to that layer's
+ * renderer click events; uses a native DOM `click` listener for the
+ * clear-on-background path (the engine doesn't emit `background:click` today),
+ * mirroring `ClickSelectBehaviour`.
+ *
+ * Default `enabled: false` — register, then explicitly enable.
+ *
+ * @example
+ * ```ts
+ * canvas.behaviours.register(
+ *   new ClickInspectBehaviour({ id: 'click-inspect', layerId: 'graph', enabled: true }),
+ * );
+ * canvas.behaviours.get<ClickInspectBehaviour>('click-inspect')
+ *   ?.events.on('inspect:change', (t) => console.log(t)); // { kind, id } | null
+ * ```
+ */
+
+/** The single element currently targeted for inspection / editing. */
+interface InspectTarget {
+    kind: 'node' | 'edge';
+    id: string;
+}
+/** Event-map for {@link ClickInspectBehaviour.events}. */
+type ClickInspectEventMap = {
+    /**
+     * Fired whenever the inspected element changes — a node / edge click sets it,
+     * a background click (or `clear`) sets it to `null`.
+     */
+    'inspect:change': InspectTarget | null;
+};
+/** Constructor options for `ClickInspectBehaviour`. */
+interface ClickInspectBehaviourOptions extends BehaviourOptions {
+    /** Required — the `GraphLayer` id this behaviour reads clicks from. */
+    layerId: string;
+    /** Clear the inspected element when clicking the empty canvas. Default `true`. */
+    clearOnBackground?: boolean;
+}
+declare class ClickInspectBehaviour extends Behaviour {
+    /**
+     * Inspection event bus. Subscribe to `'inspect:change'` for the current
+     * single target (or `null`) every time it changes.
+     */
+    readonly events: EventEmitter<ClickInspectEventMap>;
+    private layer;
+    private readonly clearOnBackground;
+    /** Subscription disposers. */
+    private subs;
+    /** Current inspected element, or `null`. */
+    private target;
+    /** True when the most recent click already consumed an element. */
+    private clickConsumedByElement;
+    /** Pointerdown screen-position — used to distinguish a click from a drag. */
+    private pointerDownScreen;
+    /**
+     * Set once the pointer travels past the click/drag threshold while a button
+     * is held — suppresses the synthetic element `click` fired at the end of a
+     * node drag so a drag doesn't open the inspector.
+     */
+    private pressMoved;
+    constructor(opts: ClickInspectBehaviourOptions);
+    protected onRegister(ctx: CanvasContext): void;
+    protected onDestroy(): void;
+    protected onDisable(): void;
+    /** The element currently targeted for inspection, or `null`. */
+    getTarget(): InspectTarget | null;
+    /** Set the inspected element explicitly (e.g. from a context menu). */
+    setTarget(target: InspectTarget | null): void;
+    /** Clear the inspected element. */
+    clear(): void;
+    private handleElementClick;
+}
+
+/**
+ * `BrushSelectBehaviour` — click-and-drag rectangular selection in screen
+ * space. Every shape (and optionally connector) enclosed by the rectangle is
+ * unioned with the existing selection.
+ *
+ * When a {@link ClickSelectBehaviour} is registered on the canvas (default
+ * id `'click-select'`), the brush delegates selection mutations through it
+ * so both behaviours stay in sync. Without a click-select target, the brush
+ * falls back to driving `GraphLayer` state directly.
+ *
+ * Default `enabled: false` — register, then explicitly enable.
+ *
+ * Note: this behaviour creates a `Graphics` overlay attached to `ctx.stage`
+ * for the rubber-band rectangle. That's one of two narrow carve-outs where
+ * `@invana/graph` reaches into pixi directly — the alternative would be to
+ * mount a private `ScreenLayer` per behaviour, which leaks an unnamed layer
+ * id into the public registry.
+ *
+ * @example
+ * ```ts
+ * canvas.behaviours.register(
+ *   new BrushSelectBehaviour({
+ *     id: 'brush',
+ *     layerId: 'graph',
+ *     enabled: true,
+ *     trigger: ['shift'],
+ *     enableElements: ['shape', 'connector'],
+ *   }),
+ * );
+ * ```
+ */
+
+/** Element kinds the brush will pick up. */
+type BrushSelectElementType = SelectableElementType;
+/** Modifier-key names accepted by `trigger`. */
+type BrushModifierKey = ModifierKey;
+/** Visual style for the rubber-band rectangle. */
+interface BrushSelectStyle {
+    /** Fill color `0xRRGGBB`. Default `0x1677ff`. */
+    fill?: number;
+    /** Fill opacity 0–1. Default `0.1`. */
+    fillAlpha?: number;
+    /** Stroke color `0xRRGGBB`. Default `0x1677ff`. */
+    stroke?: number;
+    /** Stroke opacity 0–1. Default `0.8`. */
+    strokeAlpha?: number;
+    /** Stroke width in pixels. Default `1`. */
+    strokeWidth?: number;
+    /** Dash pattern `[dashLen, gapLen]`. `[]` for solid. Default `[4, 4]`. */
+    strokeDash?: number[];
+}
+/** Constructor options for `BrushSelectBehaviour`. */
+interface BrushSelectBehaviourOptions extends BehaviourOptions {
+    /** Required — the `GraphLayer` id this behaviour brushes over. */
+    layerId: string;
+    /**
+     * Optional `ClickSelectBehaviour` id to delegate to. Default `'click-select'`.
+     * If found, the brush hands the merged selection to the click-select layer
+     * so both stay in sync. Otherwise the brush mutates `GraphLayer` state
+     * directly.
+     */
+    clickSelectId?: string;
+    /**
+     * Per-drag enable predicate. `boolean` global on/off; or a function
+     * called with the pointerdown native event. Default `true`.
+     */
+    enable?: boolean | ((event: PointerEvent) => boolean);
+    /**
+     * Element types eligible for brush selection. Default `['shape', 'connector']`.
+     */
+    enableElements?: BrushSelectElementType[];
+    /**
+     * Modifier key(s) that must be held during pointerdown to activate the
+     * brush. Empty array = any left-drag activates. Default `['shift']`.
+     */
+    trigger?: BrushModifierKey[];
+    /**
+     * Live-update the selection as the rect grows. `false` = apply only on
+     * release. Default `false`.
+     */
+    immediately?: boolean;
+    /**
+     * Visual state name applied to brushed elements when no `ClickSelectBehaviour`
+     * is targeted. Ignored on the delegate path. Default `'selected'`.
+     */
+    state?: string;
+    /** Rectangle style. */
+    style?: BrushSelectStyle;
+    /**
+     * Clear selection when the user clicks on the empty background (no drag).
+     * Default `true`.
+     */
+    clearOnBackground?: boolean;
+    /** Fired once on release if the brush produced a selection change. */
+    onSelect?: (snapshot: SelectionSnapshot) => void;
+}
+interface ResolvedOptions$4 {
+    enable: boolean | ((event: PointerEvent) => boolean);
+    enableElements: BrushSelectElementType[];
+    trigger: BrushModifierKey[];
+    immediately: boolean;
+    state: string;
+    style: BrushSelectStyle;
+    clearOnBackground: boolean;
+    onSelect: ((snapshot: SelectionSnapshot) => void) | undefined;
+}
+declare class BrushSelectBehaviour extends Behaviour {
+    private readonly clickSelectId;
+    private opts;
+    private layer;
+    private ctxRef;
+    private overlay;
+    private gfx;
+    private dragActive;
+    private dragStart;
+    private dragCurrent;
+    private listenerDisposers;
+    constructor(opts: BrushSelectBehaviourOptions);
+    protected onRegister(ctx: CanvasContext): void;
+    protected onDestroy(): void;
+    protected onDisable(): void;
+    get options(): Readonly<ResolvedOptions$4>;
+    setOptions(patch: Partial<BrushSelectBehaviourOptions>): void;
+    private screenFromEvent;
+    private handlePointerDown;
+    private handlePointerMove;
+    private handlePointerUp;
+    private cancelDrag;
+    private drawRect;
+    private drawDashedRect;
+    private clearRect;
+    private rectHasArea;
+    private triggerActive;
+    private applySelection;
+    private clearSelection;
+}
+
+/**
+ * `LassoSelectBehaviour` — click-and-drag freeform polygon selection in
+ * **world** space (the polygon stays anchored to the graph during pan/zoom).
+ *
+ * Mirrors {@link BrushSelectBehaviour} but operates with point-in-polygon
+ * containment instead of an AABB rect. Delegates to a
+ * {@link ClickSelectBehaviour} when one is registered.
+ *
+ * Default `enabled: false` — register, then explicitly enable.
+ *
+ * Same pixi-overlay carve-out as `BrushSelectBehaviour` — the world-space
+ * polygon is rendered into a `Graphics` attached to `ctx.world` (which
+ * pans/zooms with the camera).
+ */
+
+/** Element kinds the lasso will pick up. */
+type LassoSelectElementType = SelectableElementType;
+/** Modifier-key names accepted by `trigger`. */
+type LassoModifierKey = ModifierKey;
+/** Visual style for the polygon overlay. Same shape as the brush style. */
+interface LassoSelectStyle {
+    fill?: number;
+    fillAlpha?: number;
+    stroke?: number;
+    strokeAlpha?: number;
+    /** Stroke width in *screen* pixels (auto-divided by zoom). Default `1`. */
+    strokeWidth?: number;
+    /** Dash pattern in screen pixels `[dashLen, gapLen]`. Default `[4, 4]`. */
+    strokeDash?: number[];
+}
+/** Constructor options for `LassoSelectBehaviour`. */
+interface LassoSelectBehaviourOptions extends BehaviourOptions {
+    layerId: string;
+    clickSelectId?: string;
+    enable?: boolean | ((event: PointerEvent) => boolean);
+    enableElements?: LassoSelectElementType[];
+    trigger?: LassoModifierKey[];
+    immediately?: boolean;
+    state?: string;
+    style?: LassoSelectStyle;
+    clearOnBackground?: boolean;
+    onSelect?: (snapshot: SelectionSnapshot) => void;
+}
+interface ResolvedOptions$3 {
+    enable: boolean | ((event: PointerEvent) => boolean);
+    enableElements: LassoSelectElementType[];
+    trigger: LassoModifierKey[];
+    immediately: boolean;
+    state: string;
+    style: LassoSelectStyle;
+    clearOnBackground: boolean;
+    onSelect: ((snapshot: SelectionSnapshot) => void) | undefined;
+}
+declare class LassoSelectBehaviour extends Behaviour {
+    private readonly clickSelectId;
+    private opts;
+    private layer;
+    private ctxRef;
+    private overlay;
+    private gfx;
+    private dragActive;
+    /** Polygon points in WORLD space. */
+    private worldPoints;
+    private lastScreen;
+    private startScreen;
+    private listenerDisposers;
+    constructor(opts: LassoSelectBehaviourOptions);
+    protected onRegister(ctx: CanvasContext): void;
+    protected onDestroy(): void;
+    protected onDisable(): void;
+    get options(): Readonly<ResolvedOptions$3>;
+    setOptions(patch: Partial<LassoSelectBehaviourOptions>): void;
+    private screenFromEvent;
+    private handlePointerDown;
+    private handlePointerMove;
+    private handlePointerUp;
+    private cancelDrag;
+    private gestureHasArea;
+    private drawPolygon;
+    private drawDashedClosed;
+    private clearPolygon;
+    private triggerActive;
+    private applySelection;
+    private clearSelection;
+}
+
+/**
+ * `DragNodeBehaviour` — pointer-drag a `GraphLayer` node by writing the new
+ * position to its `GraphStore` (not directly to the renderer).
+ *
+ * Differs from `@invana/canvas` `DragShapeBehaviour` in one important way:
+ * the position update flows through the store, so:
+ *   - `node:update` events fire — anyone listening (server replication,
+ *     analytics, animations) sees the move.
+ *   - The layer's connector-reroute pass runs naturally on the store flush.
+ *
+ * **Doesn't pin during the drag.** The transient hold against an active
+ * physics layout is done via the layer's `node:drag-start` / `node:drag-end`
+ * events — layouts (e.g. `D3ForceLayout` clamping `fx/fy`) subscribe and
+ * manage the lock internally. The store's `GraphNode.pinned` flag is *not*
+ * touched mid-gesture, since that flag is user-data semantics (permanent
+ * pin) and a drag shouldn't silently mutate it.
+ *
+ * **Pin on release is opt-in.** Set `pinOnRelease: true` to call
+ * `store.setPinned(id, true)` on drag-end — useful when you want the user's
+ * placement to survive future layout passes. Off by default; when off, a
+ * released node is free again and the next layout tick may move it.
+ *
+ * **Selection-aware.** With `dragSelection` (default on), grabbing a node that
+ * is part of the current selection drags the whole selection together. The
+ * selection is read from the layer's `selectionState` visual state, so it works
+ * with any select behaviour (click / lasso / brush) — this behaviour is not
+ * coupled to a specific one.
+ *
+ * Default `enabled: false` — register, then explicitly enable.
+ *
+ * @example
+ * ```ts
+ * canvas.behaviours.register(
+ *   new DragNodeBehaviour({ id: 'drag', layerId: 'graph', enabled: true }),
+ * );
+ * ```
+ */
+
+/** Constructor options for `DragNodeBehaviour`. */
+interface DragNodeBehaviourOptions extends BehaviourOptions {
+    /** Required — the `GraphLayer` id whose nodes this behaviour drags. */
+    layerId: string;
+    /**
+     * Predicate to restrict which node ids are draggable. Returning `false`
+     * ignores the pointerdown. Default = every node is draggable.
+     */
+    filter?: (id: string) => boolean;
+    /** Cursor applied to the canvas while dragging. Default `'grabbing'`. */
+    dragCursor?: string;
+    /**
+     * When `true`, set `GraphNode.pinned = true` on the dragged node when
+     * the gesture ends (real drag only — a click that didn't move is a
+     * no-op). The store's pinned flag is read by layouts (e.g.
+     * `D3ForceLayout` writes pinned nodes to d3-force's `fx/fy`) so the
+     * node stays where the user dropped it across future layout passes.
+     * Default `false`. To un-pin a pinned node, call
+     * `graph.store.setPinned(id, false)` explicitly.
+     */
+    pinOnRelease?: boolean;
+    /**
+     * When `true` (the default), dragging a node that is itself a compound
+     * group (resolved `style.group` set) translates every descendant by the
+     * same delta in one `setPositionsBulk` call so the whole subtree moves
+     * together. Set to `false` to drag the group frame on its own — useful
+     * only when descendants are layout-driven and should stay put.
+     *
+     * For auto-fit groups the frame's position is layer-derived from the
+     * children bbox; moving descendants moves the frame naturally on the
+     * next flush. For non-auto-fit groups, the group's stored `position`
+     * is also updated so the declared frame follows the cursor.
+     */
+    groupAware?: boolean;
+    /**
+     * When `true` (the default), grabbing a node that is part of the current
+     * selection drags the **whole selection** together — every selected node
+     * moves by the same delta. Grabbing an unselected node (or a selection of
+     * one) falls back to a plain single-node drag. Set `false` to always drag
+     * just the grabbed node regardless of selection.
+     *
+     * Selection is read from the layer's visual state (see `selectionState`),
+     * so this works uniformly whatever set it — click, lasso, or brush — with
+     * no coupling to a specific select behaviour.
+     */
+    dragSelection?: boolean;
+    /**
+     * Name of the layer visual-state that marks a node as selected. Default
+     * `'selected'`, matching `ClickSelectBehaviour`'s default `state`. Only
+     * consulted when `dragSelection` is on. Override if your select behaviour
+     * writes a different state name.
+     */
+    selectionState?: string;
+    /**
+     * When `true` (the default), a plain (no-modifier) press anywhere inside the
+     * current selection's union bounding box — *including the empty world space
+     * between the selected nodes* — grabs the whole selection and drags it, the
+     * way Figma / PowerPoint let you drag a multi-selection by its body rather
+     * than by a specific item.
+     *
+     * Without this, a selection is only draggable by pressing squarely on one of
+     * the selected nodes; pressing in the gaps does nothing (no shape is hit, so
+     * no drag starts). Off the back of a brush/lasso selection that almost always
+     * reads as "the selection won't move" — hence default on.
+     *
+     * Only meaningful when `dragSelection` is also on. The press must carry no
+     * modifier key (so it never collides with brush / lasso / shift-to-add) and
+     * must not land on a node (those go through the normal per-node path). This
+     * does mean panning the camera by dragging from *inside* the selection box is
+     * no longer possible — drag from outside the box, or set this `false`.
+     */
+    selectionBodyDrag?: boolean;
+    /**
+     * Extra world-space padding added around the selection's union bounding box
+     * when testing a press for {@link selectionBodyDrag}. Widens the grab target
+     * so presses just outside the tightest box still catch. Default `0`.
+     */
+    selectionBodyPadding?: number;
+}
+declare class DragNodeBehaviour extends Behaviour {
+    private layer;
+    private ctxRef;
+    private readonly filter?;
+    private readonly dragCursor;
+    private readonly groupAware;
+    private readonly pinOnRelease;
+    private readonly dragSelection;
+    private readonly selectionState;
+    private readonly selectionBodyDrag;
+    private readonly selectionBodyPadding;
+    private state;
+    private offShapeDown;
+    private offCanvasDown;
+    private canvasEl;
+    private prevCursor;
+    /**
+     * Pointer id captured on `pointerdown` so we can hold the capture on the
+     * canvas element for the duration of the drag — otherwise the cursor
+     * crossing the canvas bounds (e.g. over a lil-gui panel) fires
+     * `pointercancel` on the document and the drag ends prematurely.
+     */
+    private capturedPointerId;
+    constructor(opts: DragNodeBehaviourOptions);
+    protected onRegister(ctx: CanvasContext): void;
+    protected onDestroy(): void;
+    protected onDisable(): void;
+    /**
+     * Resolve the set of *primary* nodes a gesture on `grabbedId` should drag.
+     * With `dragSelection` on, a grab on a selected node drags every selected
+     * node (filtered by `filter`); otherwise — or for a selection of one — just
+     * the grabbed node. Group descendants are added later, in the first move.
+     */
+    private resolveDragSet;
+    /** Current selection (nodes carrying `selectionState`), filtered by `filter`. */
+    private selectedNodeIds;
+    /**
+     * World-space union AABB of the given nodes, or `null` if none resolve. Each
+     * node contributes its `boundsOfNode` rect (centre-relative, so offset by the
+     * node's stored position); a node whose shape kind reports no bounds collapses
+     * to a zero-size point at its centre.
+     */
+    private selectionBounds;
+    /**
+     * Selection-body drag entry point (see `selectionBodyDrag`). A plain press on
+     * empty world space that falls inside the selection's union bounds grabs the
+     * whole selection. Presses on a node, with a modifier held, or outside the
+     * bounds are left alone so the per-node / brush / lasso / pan paths win.
+     */
+    private onCanvasPointerDown;
+    private startDrag;
+    /**
+     * Low-level drag start shared by the per-node path ({@link startDrag}) and the
+     * selection-body path ({@link onCanvasPointerDown}). `primaryId` is the gesture's
+     * emitted primary; `ids` is the full primary set to translate together.
+     */
+    private beginDrag;
+    private endDrag;
+    private readonly onWindowPointerMove;
+    private readonly onWindowPointerUp;
+    private clientToScreen;
+}
+
+/**
+ * `ContextMenuBehaviour` — surfaces right-click (context-menu) gestures on
+ * nodes, edges, and the empty canvas as a single `onContextMenu` callback.
+ *
+ * Layer-scoped: constructed with a target `layerId`. Subscribes to that
+ * layer's renderer `shape:contextmenu` / `connector:contextmenu` events and to
+ * the engine-level `background:contextmenu` (empty-canvas right-click).
+ *
+ * **Headless.** The behaviour does not render any menu UI — it resolves the
+ * target (node id + `data`, edge id + `data`, or canvas) and hands the caller
+ * everything needed to position and populate their own menu. The browser's
+ * native menu is suppressed by `Canvas` (`suppressBrowserContextMenu`, default
+ * `true`), so no `preventDefault` is needed here.
+ *
+ * Default `enabled: false` — register, then explicitly enable.
+ *
+ * @example
+ * ```ts
+ * canvas.behaviours.register(
+ *   new ContextMenuBehaviour({
+ *     id: 'context-menu',
+ *     layerId: 'graph',
+ *     enabled: true,
+ *     onContextMenu: ({ targetType, id, screen }) => {
+ *       showMenu(targetType, id, screen.x, screen.y);
+ *     },
+ *   }),
+ * );
+ * ```
+ */
+
+/** Which kind of target a context-menu gesture landed on. */
+type ContextMenuTargetType = 'node' | 'edge' | 'canvas';
+/** Payload handed to {@link ContextMenuBehaviourOptions.onContextMenu}. */
+interface ContextMenuEvent {
+    /** What was right-clicked. */
+    readonly targetType: ContextMenuTargetType;
+    /** Node/edge id, or `null` for an empty-canvas right-click. */
+    readonly id: string | null;
+    /**
+     * Arbitrary user payload from `node.data` / `edge.data`. `undefined` for a
+     * canvas right-click or when the resolved item carries no `data`.
+     */
+    readonly data: unknown;
+    /** Pointer position in world (scene) coordinates. */
+    readonly world: {
+        readonly x: number;
+        readonly y: number;
+    };
+    /**
+     * Pointer position in screen (canvas-relative) coordinates, via
+     * `camera.toScreen`. Add the canvas element's bounding-rect offset to place
+     * a `position: fixed` menu, or use directly inside a `position: relative`
+     * canvas container.
+     */
+    readonly screen: {
+        readonly x: number;
+        readonly y: number;
+    };
+}
+/** Constructor options for `ContextMenuBehaviour`. */
+interface ContextMenuBehaviourOptions extends BehaviourOptions {
+    /** Required — the `GraphLayer` id this behaviour drives. */
+    layerId: string;
+    /**
+     * Which targets fire `onContextMenu`. A right-click on a target not in this
+     * list is ignored. Default `['node', 'edge', 'canvas']`.
+     */
+    targets?: readonly ContextMenuTargetType[];
+    /**
+     * Optional transient state name applied to the right-clicked node/edge (e.g.
+     * `'context-open'`). The previously marked target is cleared first, so at
+     * most one element carries it at a time. Cleared on disable/destroy.
+     * `null`/`undefined` disables this. Default `null`.
+     */
+    state?: string | null;
+    /** Fired on a qualifying right-click. */
+    onContextMenu?: (event: ContextMenuEvent) => void;
+}
+interface ResolvedOptions$2 {
+    targets: readonly ContextMenuTargetType[];
+    state: string | null;
+    onContextMenu: ((event: ContextMenuEvent) => void) | undefined;
+}
+declare class ContextMenuBehaviour extends Behaviour {
+    private layer;
+    private opts;
+    /** Subscription disposers. */
+    private subs;
+    /** Element currently carrying `opts.state`, so we can clear it on the next open. */
+    private statedTarget;
+    constructor(opts: ContextMenuBehaviourOptions);
+    protected onRegister(ctx: CanvasContext): void;
+    protected onDestroy(): void;
+    protected onDisable(): void;
+    /** Resolved current options (read-only snapshot). */
+    get options(): Readonly<ResolvedOptions$2>;
+    /** Merge new options. Unspecified fields keep their current value. */
+    setOptions(patch: Partial<ContextMenuBehaviourOptions>): void;
+    private handle;
+    /** Move the transient `opts.state` marker onto the freshly clicked target. */
+    private applyStatedTarget;
+    private clearStatedTarget;
+}
+
+/**
+ * `CreateNodeBehaviour` — click empty canvas to add a node to a `GraphLayer`.
+ *
+ * Layer-scoped; mutates the store directly (like `DragNodeBehaviour`) and also
+ * fires an `onNodeCreate` callback. A `createNode` factory lets the consumer
+ * shape the node (id, style, data) or veto by returning `null`.
+ *
+ * Background-click detection mirrors `ClickSelectBehaviour`: the renderer fires
+ * `shape:click` / `connector:click` synchronously during the native DOM click,
+ * so a flag set there tells us the click landed on an element (don't create).
+ * A pointer-move threshold between `pointerdown` and `click` distinguishes a
+ * click from a camera pan.
+ *
+ * Default `enabled: false` — register, then explicitly enable (e.g. an "Add"
+ * tool mode toggles it on).
+ */
+
+/** Constructor options for `CreateNodeBehaviour`. */
+interface CreateNodeBehaviourOptions extends BehaviourOptions {
+    /** Required — the `GraphLayer` id this behaviour adds nodes to. */
+    layerId: string;
+    /**
+     * Build the node to insert from the click's world position. Return `null`
+     * to veto creation. Default: `{ id: <generated>, position }`.
+     */
+    createNode?: (world: {
+        x: number;
+        y: number;
+    }) => GraphNode | null;
+    /** Fired after a node is added to the store. */
+    onNodeCreate?: (node: GraphNode) => void;
+}
+declare class CreateNodeBehaviour extends Behaviour {
+    private layer;
+    private ctxRef;
+    private canvasEl;
+    private readonly makeNode;
+    private readonly onNodeCreate?;
+    /** Subscription disposers. */
+    private subs;
+    /** True when the in-flight click already landed on a node/edge. */
+    private clickConsumedByElement;
+    /** Pointerdown screen-position — used to distinguish a click from a drag/pan. */
+    private pointerDownScreen;
+    constructor(opts: CreateNodeBehaviourOptions);
+    protected onRegister(ctx: CanvasContext): void;
+    protected onDestroy(): void;
+    private clientToScreen;
+}
+
+/**
+ * `DrawEdgeBehaviour` — drag from a source node to a target node to create an
+ * edge, with a dashed rubber-band preview that follows the cursor.
+ *
+ * Layer-scoped; mutates the store directly (like `DragNodeBehaviour`) and fires
+ * an `onEdgeCreate` callback. A `createEdge` factory shapes the edge (id, style,
+ * data) or vetoes by returning `null` (e.g. to reject duplicates).
+ *
+ * The preview is a **transient renderer connector** routed from the source
+ * shape to a free `{ kind: 'point' }` endpoint updated on every pointermove —
+ * no "cursor node", so hit-testing for the drop target is unaffected. The
+ * target node under the cursor is found with `renderer.hitTest(...)`.
+ *
+ * Pointer-capture + `clientToScreen` lifecycle mirrors `DragNodeBehaviour`.
+ *
+ * Default `enabled: false`. Don't run this and `DragNodeBehaviour` enabled at
+ * the same time — both start on `shape:pointerdown` (a tool mode toggle should
+ * pick one).
+ */
+
+/** Constructor options for `DrawEdgeBehaviour`. */
+interface DrawEdgeBehaviourOptions extends BehaviourOptions {
+    /** Required — the `GraphLayer` id this behaviour draws edges in. */
+    layerId: string;
+    /**
+     * Allow releasing on the *source* node to create a self-loop. Default
+     * `false` (releasing on the source cancels). When `true`, the default
+     * `createEdge` factory styles a self-loop as `pathType: 'loop-curve'` with
+     * `sourceAnchor`/`targetAnchor` set to `'center'` (a loop needs center
+     * anchors — `'boundary'` collapses it onto a single silhouette point).
+     */
+    allowSelfLoop?: boolean;
+    /**
+     * Build the edge to insert from the endpoints. Return `null` to veto (e.g.
+     * a duplicate or disallowed pair). Default: `{ id: <generated>, source, target }`,
+     * or a loop-styled edge when `source === target` (see {@link allowSelfLoop}).
+     */
+    createEdge?: (source: string, target: string) => GraphEdge | null;
+    /** Fired after an edge is added to the store. */
+    onEdgeCreate?: (edge: GraphEdge) => void;
+    /** Rubber-band preview stroke. Defaults to a dashed light-blue line. */
+    draftStyle?: Partial<{
+        color: number;
+        width: number;
+        alpha: number;
+        dash: [number, number];
+    }>;
+}
+declare class DrawEdgeBehaviour extends Behaviour {
+    private layer;
+    private ctxRef;
+    private canvasEl;
+    private readonly makeEdge;
+    private readonly onEdgeCreate?;
+    private readonly allowSelfLoop;
+    private readonly draft;
+    private offShapeDown;
+    private sourceId;
+    private candidateTarget;
+    private capturedPointerId;
+    constructor(opts: DrawEdgeBehaviourOptions);
+    protected onRegister(ctx: CanvasContext): void;
+    protected onDestroy(): void;
+    protected onDisable(): void;
+    private startDraw;
+    private endDraw;
+    private readonly onWindowPointerMove;
+    private readonly onWindowPointerUp;
+    private clientToScreen;
+}
+
+/**
+ * `EraseBehaviour` — click a node or edge to delete it from a `GraphLayer`.
+ *
+ * The "eraser" tool of a drawing toolbar: clicking a node removes it **and**
+ * cascades its incident edges; clicking an edge removes just that edge. Like
+ * {@link CreateNodeBehaviour} / `DrawEdgeBehaviour` it mutates the store
+ * directly and fires a callback — but `onErase` reports the *removed* element
+ * with enough captured state (the node + its incident edges, or the edge) to
+ * reconstruct it, so a consumer can journal an undoable delete.
+ *
+ * Hit detection rides the renderer's synchronous `shape:click` /
+ * `connector:click` channels — the same ones `ClickSelectBehaviour` uses — so
+ * the clicked element's id arrives directly; no world-space hit-testing needed.
+ *
+ * Default `enabled: false` — register, then explicitly enable (e.g. a "Delete"
+ * tool mode toggles it on). Don't run it enabled alongside `ClickSelect` /
+ * `DragNode` on the same layer: all three react to a node press, so a tool-mode
+ * switch should leave exactly one on.
+ */
+
+/** Which element kinds the eraser removes. */
+type EraseTargetKind = 'node' | 'edge' | 'both';
+/**
+ * Payload describing what {@link EraseBehaviour} just removed. Carries the full
+ * pre-removal element(s) so a consumer can rebuild them (undo). A removed node
+ * carries its cascade-removed incident `edges`.
+ */
+type ErasedElement = {
+    kind: 'node';
+    node: GraphNode;
+    edges: GraphEdge[];
+} | {
+    kind: 'edge';
+    edge: GraphEdge;
+};
+/** Constructor options for `EraseBehaviour`. */
+interface EraseBehaviourOptions extends BehaviourOptions {
+    /** Required — the `GraphLayer` id this behaviour erases from. */
+    layerId: string;
+    /** Which element kinds a click removes. Default `'both'`. */
+    target?: EraseTargetKind;
+    /** Fired after an element is removed, with the captured pre-removal state. */
+    onErase?: (removed: ErasedElement) => void;
+}
+declare class EraseBehaviour extends Behaviour {
+    private layer;
+    private readonly target;
+    private readonly onErase?;
+    /** Subscription disposers. */
+    private subs;
+    constructor(opts: EraseBehaviourOptions);
+    protected onRegister(ctx: CanvasContext): void;
+    protected onDestroy(): void;
+    /** Capture node + incident edges, cascade-remove, then report. */
+    private eraseNode;
+    /** Capture the edge, remove it, then report. */
+    private eraseEdge;
+    /** Cloned incident edges (both directions), deduped — self-loops appear once. */
+    private incidentEdges;
+}
+
+/**
+ * `CollapseExpandBehaviour` — clicks on a group node's `+` / `−` toggle
+ * decoration flip the group between expanded and collapsed states.
+ *
+ * Listens for native DOM `pointerdown` on the canvas element rather than
+ * the renderer's `shape:pointerdown` channel. The reason: the toggle
+ * decoration is typically anchored to (or *outside*) the host's
+ * silhouette — outside-`'bottom'` for collapsed circles in the reference
+ * UI — and PixiJS's hit-test rejects clicks outside the silhouette so a
+ * shape-level subscription would never fire for those placements. A
+ * canvas-wide listener tests the click against the toggle's cached hit
+ * geometry regardless of where it sits.
+ *
+ * Layer-scoped. Default `enabled: false` per the no-auto-registration rule.
+ *
+ * @example
+ * ```ts
+ * canvas.behaviours.register(
+ *   new CollapseExpandBehaviour({
+ *     id: 'collapse-expand',
+ *     layerId: 'graph',
+ *     enabled: true,
+ *   }),
+ * );
+ * ```
+ */
+
+/**
+ * Slot id the `GraphLayer` mounts the group's `+` / `−` toggle decoration on.
+ * Re-exported for advanced consumers that want to read or override the
+ * decoration; most callers shouldn't need it.
+ */
+declare const GROUP_TOGGLE_SLOT = "group-toggle";
+interface CollapseExpandBehaviourOptions extends BehaviourOptions {
+    /** Required — the `GraphLayer` id this behaviour drives. */
+    layerId: string;
+}
+declare class CollapseExpandBehaviour extends Behaviour {
+    private layer;
+    private ctxRef;
+    private canvasEl;
+    constructor(opts: CollapseExpandBehaviourOptions);
+    protected onRegister(ctx: CanvasContext): void;
+    protected onDestroy(): void;
+    private readonly onPointerDown;
+    /**
+     * Convert a `PointerEvent` into world coordinates and walk every group
+     * node in the layer. Return the first group whose mounted toggle
+     * decoration's hit area contains the click, or `null` if none match.
+     */
+    private findToggleHit;
+    /**
+     * Flip `style.group.collapsed` via `store.updateNode`, preserving the
+     * rest of the prior style. Per `feedback_updatenode_replaces_style` the
+     * store replaces `style` wholesale on update — the spread keeps every
+     * other field intact.
+     */
+    private toggleCollapsed;
+}
+
+/**
+ * `NodeResizeBehaviour` — drag-resize any node (group or regular) whose
+ * resolved style opts into resizing.
+ *
+ * The behaviour:
+ * 1. mounts a single `SelectionFrameDecoration` on every eligible node.
+ *    The decoration paints a dashed AABB outline plus round handles at
+ *    the corners (and edge midpoints for rect hosts). For circle hosts
+ *    only the radial `'right'` handle is exposed so the user always
+ *    grows / shrinks the radius isotropically. Eligibility =
+ *    `style.resizable === true` (regular nodes) OR
+ *    `style.group?.userResizable === true` (compound groups);
+ * 2. listens at the **canvas DOM level** for `pointerdown`. The handles
+ *    sit at AABB corners, which fall outside the silhouette for circles
+ *    and on the edge for rects — PixiJS's shape hit-test rejects those
+ *    clicks. Canvas-level listening sidesteps the issue: every click is
+ *    tested against the decoration's cached per-handle hit geometry;
+ * 3. on drag (window-level `pointermove`), writes the new size back via
+ *    `store.updateNode`. The target field depends on the eligibility
+ *    flag: groups go to `style.group.width / height / radius`, regular
+ *    nodes go to `style.shape.width / height / radius`. Position is also
+ *    rewritten so the opposite anchor stays fixed on rect drags (except
+ *    for auto-fit groups, where the layer derives the frame's position
+ *    from the children bbox).
+ *
+ * Layer-scoped. Default `enabled: false`.
+ *
+ * @example
+ * ```ts
+ * canvas.behaviours.register(
+ *   new NodeResizeBehaviour({ id: 'resize', layerId: 'graph', enabled: true }),
+ * );
+ * ```
+ */
+
+interface NodeResizeBehaviourOptions extends BehaviourOptions {
+    /** Required — the `GraphLayer` id this behaviour drives. */
+    layerId: string;
+    /** Handle outer radius in px. Default `5`. */
+    handleRadius?: number;
+    /** Handle fill colour. Default `0xffffff`. */
+    handleFill?: number;
+    /** Frame border + handle outline colour. Default `0x6b7fff`. */
+    frameColor?: number;
+    /** Dash pattern `[dashLength, gapLength]` in px. Default `[5, 4]`. */
+    dashArray?: readonly [number, number];
+    /** Gap between host silhouette and the dashed frame. Default `4`. */
+    framePadding?: number;
+    /** Minimum width / height / radius the behaviour allows during drag. Default `20`. */
+    minSize?: number;
+}
+declare class NodeResizeBehaviour extends Behaviour {
+    private layer;
+    private ctxRef;
+    private canvasEl;
+    private prevCursor;
+    private state;
+    private subs;
+    private readonly opts;
+    /** Node ids that currently have a selection-frame decoration mounted. */
+    private readonly mountedNodes;
+    constructor(opts: NodeResizeBehaviourOptions);
+    protected onRegister(ctx: CanvasContext): void;
+    protected onDestroy(): void;
+    protected onEnable(): void;
+    protected onDisable(): void;
+    /**
+     * Returns the write-target a drag on this node would use, or `null` when
+     * the node isn't resizable. A group with `userResizable: true` always
+     * writes to `style.group.*`; a non-group with `style.resizable: true`
+     * writes to `style.shape.*`.
+     */
+    private resizeTarget;
+    private refreshAllFrames;
+    private mountFrameFor;
+    private clearFrameFor;
+    private clearAllFrames;
+    private readonly onCanvasPointerDown;
+    private findHandleHit;
+    private startDrag;
+    private endDrag;
+    private readonly onWindowPointerMove;
+    private readonly onWindowPointerUp;
+    /**
+     * Apply the new geometry to the store. Branch on `target`:
+     *
+     * - `target === 'group'` — write to `style.group.width / height / radius`.
+     *   Position is updated for rect drags only when `autoFit !== true` (the
+     *   layer derives the position from the children bbox when auto-fit is on,
+     *   so writing it would either be redundant or fight the recompute).
+     * - `target === 'shape'` — write to `style.shape.width / height / radius`.
+     *   Position is updated for rect drags so the opposite anchor stays put.
+     *
+     * Either way the store replaces `style` wholesale on update (see
+     * `feedback_updatenode_replaces_style`), so the spread preserves every
+     * other field.
+     */
+    private commit;
+}
+
+/**
+ * `LabelCollisionBehaviour` — hides overlapping node / edge labels via a
+ * greedy priority-sorted sweep so dense graphs stay legible.
+ *
+ * Strategy: each pass collects every label's world-space AABB, sorts the
+ * label set by `priority` (configurable resolver — `priority` field on the
+ * style, node-degree, or a custom callback), and walks high-to-low. A label
+ * is **shown** if its AABB doesn't overlap any label already shown in the
+ * same `collisionGroup`; otherwise it's hidden for this frame. Labels with
+ * `forceShow: true` skip the check entirely (use for hovered / selected
+ * elements).
+ *
+ * Default groups partition node labels and edge labels — a node label never
+ * loses to an edge label of higher priority.
+ *
+ * The behaviour reruns on every store flush (data churn) and on every
+ * `camera:zoom` / `camera:pan` event (viewport churn). A small hysteresis
+ * timer keeps just-flipped labels from immediately flipping back when zoom
+ * leaves them right on the overlap boundary.
+ *
+ * Default `enabled: false` — register, then explicitly enable. Matches the
+ * project rule that no behaviour auto-activates.
+ *
+ * @example
+ * ```ts
+ * canvas.behaviours.register(
+ *   new LabelCollisionBehaviour({
+ *     id: 'label-collision',
+ *     layerId: 'graph',
+ *     enabled: true,
+ *     prioritise: 'node-degree',
+ *   }),
+ * );
+ * ```
+ */
+
+/** What the behaviour does with an overlap. `'hide'` is the only strategy in v0. */
+type LabelCollisionStrategy = 'hide';
+/** How label priority is resolved when sorting. */
+type LabelPriorityResolver = 'priority-field' | 'node-degree' | ((kind: 'node' | 'edge', id: string) => number);
+interface LabelCollisionBehaviourOptions extends BehaviourOptions {
+    /** Required — the `GraphLayer` id this behaviour drives. */
+    layerId: string;
+    /** Default `'hide'`. */
+    strategy?: LabelCollisionStrategy;
+    /** Default `'priority-field'`. Falls back to node-degree when undefined. */
+    prioritise?: LabelPriorityResolver;
+    /**
+     * Hysteresis: a just-hidden label stays hidden for at least this many ms
+     * before it can re-appear, and vice versa. Stops flicker when zoom is
+     * right at an overlap boundary. Default `100`.
+     */
+    flickerGuardMs?: number;
+    /**
+     * Default `'nodes'` for node labels, `'edges'` for edge labels. Set to a
+     * custom mapping if you want different partitioning (e.g. all in one
+     * group so edges can win priority against nodes).
+     */
+    groups?: {
+        nodes?: string;
+        edges?: string;
+    };
+}
+declare class LabelCollisionBehaviour extends Behaviour {
+    private layer;
+    private opts;
+    /** Last-flip timestamp per label id (perf.now()). */
+    private readonly lastFlip;
+    /** Last visibility decision per label id. */
+    private readonly lastVisible;
+    /** Subscription disposers, called in onDestroy. */
+    private subs;
+    /** Coalesce repeated triggers within a single frame. */
+    private scheduled;
+    constructor(opts: LabelCollisionBehaviourOptions);
+    protected onRegister(ctx: CanvasContext): void;
+    protected onDestroy(): void;
+    protected onEnable(): void;
+    protected onDisable(): void;
+    /** Coalesce repeated triggers within a microtask. Cheap; runs at most once per frame. */
+    private schedule;
+    /**
+     * Walk every label, sort by priority, greedy-hide overlaps within the
+     * same `collisionGroup`. Mutates label `gfx.visible`; doesn't touch
+     * decoration state otherwise.
+     */
+    private runPass;
+    private priorityFor;
+    private degreeOf;
+}
+
+/**
+ * `LabelResolutionLODBehaviour` — re-rasterise label glyphs at higher
+ * resolution as the camera zooms in, so text stays crisp instead of
+ * sampling-blurry when the user inspects nodes up close.
+ *
+ * **Why this is tier-based, not step-based.** Pixi rasterises each `Text`
+ * to a glyph texture exactly once (default resolution = renderer DPR).
+ * When the world is scaled 5×, that texture is upsampled 5× — fuzzy.
+ * Re-rasterising fixes the fuzziness but regenerates every label's
+ * texture on the GPU, which is the expensive part. With a few thousand
+ * labels (e.g. the H-1B pack story) a re-raster is a multi-hundred-ms
+ * frame pause — perceptible as a stutter mid-zoom.
+ *
+ * An earlier design snapped the zoom to a step (e.g. `step: 0.5`) and
+ * re-rastered at every snap boundary — so a continuous zoom from 1× to
+ * 6× crossed ~10 boundaries and dropped frames at each one. This design
+ * uses **discrete tiers**: a few widely-spaced minZoom thresholds, with
+ * a multiplier per tier. In a typical zoom-in-and-stay session the user
+ * crosses one boundary, pays one re-raster, and the rest is GPU-cheap.
+ *
+ * **Hysteresis** keeps boundary scrolls (1.49 → 1.51 → 1.49) from
+ * flickering between tiers. After crossing UP into tier N, the behaviour
+ * only reverts to tier N-1 when zoom drops below
+ * `levels[N].minZoom - hysteresis`.
+ *
+ * Default `enabled: false` — register, then explicitly enable. Matches
+ * the project rule that no behaviour auto-activates.
+ *
+ * @example
+ * ```ts
+ * canvas.behaviours.register(
+ *   new LabelResolutionLODBehaviour({
+ *     id: 'label-resolution',
+ *     layerId: 'graph',
+ *     enabled: true,
+ *     // Defaults: 1× DPR by default, jump to 4× DPR once zoom > 1.5.
+ *     // Override for more or fewer tiers.
+ *     levels: [
+ *       { minZoom: 0,   multiplier: 1 },
+ *       { minZoom: 1.5, multiplier: 4 },
+ *       { minZoom: 5,   multiplier: 8 },
+ *     ],
+ *   }),
+ * );
+ * ```
+ */
+
+/** One discrete LOD tier. Highest `minZoom` ≤ current zoom wins. */
+interface LabelResolutionLODTier {
+    /** Camera zoom (`canvas.camera.scale`) at which this tier becomes active. */
+    minZoom: number;
+    /** Multiplier applied to `baseResolution` while this tier is active. */
+    multiplier: number;
+}
+interface LabelResolutionLODBehaviourOptions extends BehaviourOptions {
+    /** Required — the `GraphLayer` id this behaviour drives. */
+    layerId: string;
+    /**
+     * Base resolution to multiply by the active tier's multiplier. Default
+     * `window.devicePixelRatio` (≈ 1 on standard displays, 2 on retina). Set
+     * this if your Canvas was initialised with a custom `resolution` option.
+     */
+    baseResolution?: number;
+    /**
+     * Discrete zoom tiers, evaluated as a step function. Each tier names a
+     * `minZoom` at which it activates and a `multiplier` applied to
+     * `baseResolution` while it's active. Order doesn't matter — the
+     * behaviour sorts by `minZoom` internally.
+     *
+     * Pick *few, widely-spaced* tiers: every additional tier means another
+     * GPU re-raster of every label during a typical zoom-in pass. Default:
+     * `[{ minZoom: 0, multiplier: 1 }, { minZoom: 1.5, multiplier: 4 }]` —
+     * one threshold, one re-raster.
+     */
+    levels?: LabelResolutionLODTier[];
+    /**
+     * Hysteresis applied to *downward* tier changes. After crossing UP into
+     * tier N at `levels[N].minZoom`, the behaviour only reverts to tier N-1
+     * once zoom drops below `levels[N].minZoom - hysteresis`. Prevents
+     * flicker when the user dithers on a threshold. Default `0.1`.
+     */
+    hysteresis?: number;
+}
+declare class LabelResolutionLODBehaviour extends Behaviour {
+    private layer;
+    private readonly opts;
+    private subs;
+    /**
+     * Index into `opts.levels` of the currently active tier. Re-evaluated
+     * on every camera-zoom event; the renderer is only nudged when this
+     * index actually changes, so a continuous zoom inside one tier costs
+     * nothing past the cheap comparison below.
+     */
+    private currentTierIdx;
+    /** Last resolution actually pushed to the renderer. */
+    private lastPushed;
+    constructor(opts: LabelResolutionLODBehaviourOptions);
+    protected onRegister(ctx: CanvasContext): void;
+    protected onDestroy(): void;
+    protected onEnable(): void;
+    protected onDisable(): void;
+    /**
+     * Re-evaluate the active tier under the current camera zoom and push the
+     * tier's resolution to the renderer only when the tier index changes.
+     * Continuous zoom inside one tier is a constant-time no-op past the
+     * `idx === currentTierIdx` check below.
+     */
+    private apply;
+}
+
+/**
+ * `NodeSizeLODBehaviour` — keep `GraphLayer` node bodies (and their
+ * outline strokes) at a fixed screen-pixel size across camera zoom.
+ *
+ * Concrete subclass of `ElementSizeLODBehaviour` — that base owns the
+ * RAF coalescing, `camera:zoom` subscription, and enable/disable
+ * lifecycle. This class only knows how to rescale graph nodes.
+ *
+ * ## How it works (transform-scale fast path)
+ *
+ * On enable (and on `reflow()` after a GUI knob moves), the behaviour
+ * does **one** expensive O(N) pass: it rewrites every node's spec so
+ * the geometric values (`radius`, `width`, `height`, `stroke.width`)
+ * carry the target-pixel sizes as if they were world units. Then per
+ * `camera:zoom` it does the cheap pass: a single
+ * `renderer.scaleShape(id, 1 / cameraScale)` per node, which just writes
+ * the gfx transform — no `Graphics.clear()`, no path retrace, no spec
+ * mutation. That collapses thousands of geometry rebuilds per zoom
+ * frame into thousands of transform writes (~50× cheaper).
+ *
+ * Stroke width travels along the transform (Pixi strokes are in local
+ * units), so the stroke is pixel-constant by construction. There is no
+ * way to opt the stroke out of the transform while keeping the body in
+ * — the two are coupled by the single scale factor.
+ *
+ * Pair with {@link EdgeSizeLODBehaviour} when you also want pixel-constant
+ * edge strokes. They're independent behaviours; their RAF callbacks
+ * batch into the same animation frame, so registering both has the same
+ * per-frame cost as one monolith doing both passes.
+ *
+ * Supports `circle` and `rect` node shapes. `arc`-shape nodes are
+ * skipped — their geometry is in `innerR` / `outerR` / sweep angles and
+ * doesn't map cleanly to a single screen-px input.
+ *
+ * Hosts with `setDecoration` decorations or attached badges are also
+ * supported, but those auxiliary visuals are **not** re-anchored on
+ * each zoom — the underlying `scaleShape` fast path skips the
+ * decoration / badge refresh that `updateShape` performs. Acceptable
+ * for halos/glows (still centred on the host); inappropriate for
+ * placement-sensitive badges. Use `updateShape` directly in that case.
+ *
+ * @example
+ * ```ts
+ * import { NodeSizeLODBehaviour } from '@invana/graph';
+ *
+ * canvas.behaviours.register(
+ *   new NodeSizeLODBehaviour({
+ *     id: 'node-size-lod',
+ *     enabled: true,
+ *     layers: [
+ *       {
+ *         layerId: 'graph',
+ *         sizePx: 6,          // node diameter in screen px
+ *         strokeWidthPx: 1,   // outline width in screen px (omit to leave in world units)
+ *       },
+ *     ],
+ *   }),
+ * );
+ * ```
+ */
+
+/** Per-`GraphLayer` config — one entry per layer this behaviour rescales. */
+interface NodeSizeLODConfig {
+    /** Required — the `GraphLayer` whose nodes are rescaled. */
+    layerId: string;
+    /**
+     * Target body size in screen px for nodes that don't carry a per-node
+     * `data.size` override. Falls back to the layer's `nodeDefaults.size`
+     * when omitted. Accepts a static number or a getter — getters re-read
+     * on every reflow so GUI sliders update live.
+     */
+    sizePx?: NumberOrGetter;
+    /**
+     * Target outline width in screen px. When omitted, the layer's
+     * `nodeDefaults.strokeWidth` (or each node's `data.strokeWidth`) is
+     * reinterpreted as the implicit pixel target — the transform-scale
+     * fast path always pins both body and stroke together, so the stroke
+     * is pixel-constant even without an explicit value here. Setting an
+     * explicit value just changes what that pixel target is.
+     */
+    strokeWidthPx?: NumberOrGetter;
+}
+interface NodeSizeLODBehaviourOptions extends ElementSizeLODBehaviourOptions {
+    /** One config per `GraphLayer` to drive. */
+    layers: NodeSizeLODConfig[];
+}
+declare class NodeSizeLODBehaviour extends ElementSizeLODBehaviour {
+    private readonly configs;
+    private resolved;
+    /**
+     * Pending reanchor timer. The per-frame `scaleShape` fast path is cheap
+     * (transform writes only), but `reanchorAllConnectors` rebuilds every
+     * connector's Pixi geometry — at thousands of edges that drops fps to
+     * the floor under a continuous zoom gesture. Coalesce to a single
+     * trailing-edge call.
+     */
+    private reanchorTimer;
+    constructor(opts: NodeSizeLODBehaviourOptions);
+    protected onResolveTargets(ctx: CanvasContext): void;
+    protected onReleaseTargets(): void;
+    /**
+     * Per-frame fast path. Sets `gfx.scale = 1 / cameraScale` on every node
+     * via the renderer's transform fast path — no geometry rebuild. The
+     * spec was pre-set to "target-px values treated as world units" by
+     * {@link writeBaseline} at enable / reflow time, so:
+     *
+     *     on-screen = nativeWorldSize × cameraScale × gfxScale
+     *               = (sizePx / 1)    × cameraScale × (1 / cameraScale)
+     *               = sizePx ✓
+     *
+     * Stroke width scales with the body (Pixi's stroke is in local units)
+     * — which is precisely the pixel-constant intent.
+     */
+    protected apply(rawScale: number): void;
+    private scheduleReanchor;
+    private flushReanchor;
+    protected onEnable(): void;
+    protected onDisable(): void;
+    reflow(): void;
+    /**
+     * One-shot O(N) pass that rewrites every node's spec via
+     * `renderer.updateShape`. Two flavours:
+     *
+     * - `'target'` — write the LOD-on baseline: `radius = sizePx / 2`,
+     *   `stroke.width = strokeWidthPx`. The per-frame `gfx.scale = 1 / cs`
+     *   then collapses the world-unit values back to pixel-constant.
+     * - `'worldUnit'` — restore the LOD-off baseline: `radius = (data.size
+     *   ?? defaults.size) / 2`, `stroke.width = data.strokeWidth ??
+     *   defaults.strokeWidth`. Matches what `GraphLayer.nodeSpec` would
+     *   write for a fresh `addShape`.
+     *
+     * Expensive (each `updateShape` rebuilds the underlying Pixi geometry)
+     * — only call on transitions (enable / disable / slider change), not
+     * per frame.
+     */
+    private writeBaseline;
+    private writeLayerBaseline;
+}
+
+/**
+ * `EdgeSizeLODBehaviour` — keep `GraphLayer` connector stroke widths at
+ * a fixed screen-pixel width across camera zoom.
+ *
+ * Concrete subclass of `ElementSizeLODBehaviour`. Pair with
+ * {@link NodeSizeLODBehaviour} when you also want pixel-constant nodes
+ * (typical for map-overlay use cases — at city zoom a `strokeWidth: 0.6`
+ * becomes a 150-px slab without this behaviour).
+ *
+ * Uses `PrimitivesRenderer.setConnectorStroke` (not `updateConnector`)
+ * to patch the stroke spec and redraw on the cached path. Crucially,
+ * this skips `recomputeConnectorPath`, which would iterate every shape
+ * in the renderer to build an obstacle list — `O(edges × shapes)` per
+ * reflow and lethal during continuous zoom. The path doesn't depend on
+ * camera scale, so re-routing on a stroke-only change is wasted work.
+ *
+ * @example
+ * ```ts
+ * import { EdgeSizeLODBehaviour } from '@invana/graph';
+ *
+ * canvas.behaviours.register(
+ *   new EdgeSizeLODBehaviour({
+ *     id: 'edge-size-lod',
+ *     enabled: true,
+ *     layers: [{ layerId: 'graph', strokeWidthPx: 0.6 }],
+ *   }),
+ * );
+ * ```
+ */
+
+/** Per-`GraphLayer` config — one entry per layer this behaviour rescales. */
+interface EdgeSizeLODConfig {
+    /** Required — the `GraphLayer` whose edges are rescaled. */
+    layerId: string;
+    /**
+     * Target stroke width in screen px for edges that don't carry a
+     * per-edge `data.strokeWidth` override. Falls back to the layer's
+     * `edgeDefaults.strokeWidth`. Accepts a static number or a getter
+     * (`() => settings.targetEdgePx`).
+     */
+    strokeWidthPx?: NumberOrGetter;
+}
+interface EdgeSizeLODBehaviourOptions extends ElementSizeLODBehaviourOptions {
+    /** One config per `GraphLayer` to drive. */
+    layers: EdgeSizeLODConfig[];
+}
+declare class EdgeSizeLODBehaviour extends ElementSizeLODBehaviour {
+    private readonly configs;
+    private resolved;
+    constructor(opts: EdgeSizeLODBehaviourOptions);
+    protected onResolveTargets(ctx: CanvasContext): void;
+    protected onReleaseTargets(): void;
+    /**
+     * Per-zoom-frame apply: write the screen-px / world-px ratio to every
+     * managed edge as a render-time stroke multiplier. The renderer's draw
+     * pipeline reads `inst.strokeWidthScale` and multiplies it into the
+     * spec's `stroke.width` at draw time, so state-config strokes (e.g.
+     * `active: { strokeWidth: 1.5 }`) are interpreted in the same screen-px
+     * unit the layer's "live" strokes are interpreted in — no LOD-loss
+     * across a `GraphLayer.rerenderEdge` rebuild, and no inversion of the
+     * caller's intent.
+     *
+     * The strokeWidthPx config field is unused under this model — every
+     * spec width is treated as the target screen-px. Kept on the type for
+     * back-compat; a future revision may remove it.
+     */
+    protected apply(rawScale: number): void;
+}
+
+/**
+ * `ParallelEdgeBehaviour` — fans edges that share the same `(source, target)`
+ * pair so they don't overlap. Cross-edge coordination that belongs above the
+ * per-edge connector pipeline (anchor → router → pathStyle), since each
+ * pipeline stage sees only one edge in isolation.
+ *
+ * Layer-scoped: constructed with a target `layerId` referencing a
+ * {@link GraphLayer}. Watches the store for edge add/remove and node
+ * position changes, groups edges by `groupBy(edge)` (default
+ * `${source}::${target}`), and rewrites each group's `style.shape` so its
+ * members fan out symmetrically. Two dimensions are written, depending on
+ * which anchor each edge uses:
+ *
+ *  1. **`sourceAnchorOpts.offset` / `targetAnchorOpts.offset`** — for edges
+ *     using `'edge-port'` or `'silhouette-port'` anchors, the endpoints are
+ *     pushed along the host's face by `rank × spacing`. Combined with the
+ *     port anchor's `side: 'auto'` mode, this fans the endpoints across the
+ *     shape silhouette without the caller having to derive sides manually.
+ *  2. **A single midpoint `waypoint`** — bows the path's middle by
+ *     `rank × spacing`. The bow axis is chosen per edge from its
+ *     `pathType`: axis-aligned routers (`manhattan` / `orth` / `rounded`)
+ *     get an axis-aligned offset along the non-dominant axis;
+ *     curve-through-control-point styles (`straight` / `smooth` / `bundle`)
+ *     get a perpendicular offset. Override via `basis`.
+ *
+ * Default `enabled: false` — register, then explicitly enable. Matches the
+ * project rule that no behaviour auto-activates.
+ *
+ * `onDisable` does **not** undo prior patches — edges keep whatever waypoint
+ * / anchor opts they had at the moment of disable. Re-enabling resumes
+ * patching on the next store mutation. Callers that need a clean slate must
+ * clear edge styles themselves.
+ *
+ * @example
+ * ```ts
+ * canvas.behaviours.register(
+ *   new ParallelEdgeBehaviour({
+ *     id: 'parallel-edges',
+ *     layerId: 'graph',
+ *     enabled: true,
+ *     spacing: 12,
+ *   }),
+ * );
+ * ```
+ */
+
+/**
+ * Axis along which a group of parallel edges spreads.
+ *
+ * - `'auto'` — derive from each edge's `pathType`. Axis-aligned routers
+ *   (`manhattan`, `orth`, `rounded`) use `'axis-aligned'`; all others use
+ *   `'perpendicular'`.
+ * - `'perpendicular'` — offset along the unit vector perpendicular to
+ *   `target - source`. Suitable for curve-through-midpoint styles
+ *   (`straight`, `smooth`, `bundle`).
+ * - `'axis-aligned'` — offset along the non-dominant axis between source and
+ *   target. Suitable for axis-aligned routers (`manhattan`, `orth`,
+ *   `rounded`) where the bow control point should sit on a horizontal or
+ *   vertical mid-corridor.
+ */
+type ParallelEdgeBasis = 'auto' | 'perpendicular' | 'axis-aligned';
+/** A bucket of edges that share endpoints and should be fanned together. */
+interface ParallelEdgeGroup {
+    /** Source node id shared by every edge in this group. */
+    readonly sourceId: string;
+    /** Target node id shared by every edge in this group. */
+    readonly targetId: string;
+    /** Geometric centre of the source node (renderer ref or store position). */
+    readonly sourceCenter: Vec2;
+    /** Geometric centre of the target node. */
+    readonly targetCenter: Vec2;
+    /**
+     * Edges in this group, in store iteration order. Distribution policies
+     * decide which edge gets which rank — the default centres the group so
+     * `edges[i]` receives rank `k = i - (N-1)/2`.
+     */
+    readonly edges: ReadonlyArray<GraphEdge>;
+}
+/** Patch a distribution policy emits for one edge in the group. */
+interface ParallelEdgePatch {
+    /** Edge id this patch applies to. */
+    readonly edgeId: string;
+    /** New `sourceAnchorOpts`. Merged onto the edge's existing shape. */
+    readonly sourceAnchorOpts?: Readonly<Record<string, unknown>>;
+    /** New `targetAnchorOpts`. */
+    readonly targetAnchorOpts?: Readonly<Record<string, unknown>>;
+    /** New `waypoints`. Pass an empty array to clear. */
+    readonly waypoints?: ReadonlyArray<{
+        readonly x: number;
+        readonly y: number;
+    }>;
+}
+/** Settings the behaviour passes through to a distribution policy. */
+interface ParallelEdgeDistributeContext {
+    readonly spacing: number;
+    readonly basis: ParallelEdgeBasis;
+    readonly anchorOffset: boolean;
+}
+/**
+ * Pluggable distribution policy. Receives a group of co-located edges plus
+ * the behaviour's settings and returns one patch per edge it wants to update.
+ *
+ * The default policy {@link centeredRanksPolicy} fans edges symmetrically
+ * around rank zero — pass a custom function to implement one-sided fanout,
+ * data-driven offsets, weighted spacing, etc.
+ */
+type ParallelEdgeDistribute = (group: ParallelEdgeGroup, ctx: ParallelEdgeDistributeContext) => ReadonlyArray<ParallelEdgePatch>;
+/** Constructor options for {@link ParallelEdgeBehaviour}. */
+interface ParallelEdgeBehaviourOptions extends BehaviourOptions {
+    /** Required — the `GraphLayer` id this behaviour drives. */
+    layerId: string;
+    /** Spacing between adjacent ranks in world units. Default `12`. */
+    spacing?: number;
+    /**
+     * Basis the default distribution policy uses to translate a rank into a
+     * waypoint / anchor-offset direction. Default `'auto'`.
+     */
+    basis?: ParallelEdgeBasis;
+    /**
+     * When `true` and an edge uses a port anchor (`'edge-port'` or
+     * `'silhouette-port'`), the default policy writes
+     * `sourceAnchorOpts: { side: 'auto', offset }` and the matching target
+     * opts so endpoints fan along the host face. When `false`, the policy
+     * only writes waypoints. Default `true`.
+     */
+    anchorOffset?: boolean;
+    /**
+     * Group key for an edge. Edges that produce the same key are bundled and
+     * distributed together. Return `null` to exclude an edge. Default groups
+     * by directed pair `${source}::${target}`.
+     */
+    groupBy?: (edge: GraphEdge) => string | null;
+    /**
+     * Distribution policy. Default {@link centeredRanksPolicy}.
+     */
+    distribute?: ParallelEdgeDistribute;
+}
+interface ResolvedOptions$1 {
+    spacing: number;
+    basis: ParallelEdgeBasis;
+    anchorOffset: boolean;
+    groupBy: (edge: GraphEdge) => string | null;
+    distribute: ParallelEdgeDistribute;
+}
+/**
+ * Default distribution policy — centres `N` ranks around zero, then for each
+ * edge writes one midpoint waypoint plus (optionally) port-anchor offsets.
+ *
+ * Exported so callers can compose it (e.g. wrap with a filter) or call
+ * directly when implementing a custom variant that wants to reuse the
+ * default geometry for some edges.
+ */
+declare const centeredRanksPolicy: ParallelEdgeDistribute;
+declare class ParallelEdgeBehaviour extends Behaviour {
+    /** Bound target layer — resolved in `onRegister`. */
+    private layer;
+    private opts;
+    /** Subscription disposers, called in `onDestroy`. */
+    private subs;
+    /** Re-entrancy guard: `true` while writing patches to the store. */
+    private patching;
+    constructor(opts: ParallelEdgeBehaviourOptions);
+    protected onRegister(ctx: CanvasContext): void;
+    protected onDestroy(): void;
+    protected onEnable(): void;
+    /** Read-only snapshot of resolved options. */
+    get options(): Readonly<ResolvedOptions$1>;
+    /** Runtime option update. Re-runs the distribution immediately if enabled. */
+    setOptions(patch: Partial<ParallelEdgeBehaviourOptions>): void;
+    /**
+     * Force a recompute pass. Useful after bulk mutations performed inside a
+     * `store.batch()` that callers want to flush through the behaviour
+     * immediately.
+     */
+    recompute(): void;
+}
+
+/**
+ * `DegreeSizeBehaviour` — sizes nodes by their connection count.
+ *
+ * For each node, counts incident edges in the configured `direction`
+ * (`'in'` / `'out'` / `'both'`), normalizes against the max observed degree,
+ * and writes a `style.size` value scaled between `minSize` and `maxSize`.
+ *
+ * Because `style.size` flows through `GraphLayer.resolveNodeStyle` (which
+ * rewrites the node's `shape` geometry before any consumer reads it), the
+ * sizes are picked up uniformly by:
+ *   - the renderer (visual radius / width grows),
+ *   - `boundsOfNode` (ELK and other layouts that query bounds),
+ *   - D3ForceLayout's collide.radius callback (reads `style.shape.radius`
+ *     off the resolved style).
+ *
+ * The behaviour does NOT auto-rerun any layout — write sizes first, then
+ * call `layout.apply(graph)` yourself. This matches the rest of the
+ * behaviour catalogue: no behaviour runs layouts implicitly.
+ *
+ * Lifecycle:
+ *   - `onEnable()`        — snapshot prior per-node `style.size`, compute,
+ *                           apply.
+ *   - on store changes    — recompute and reapply (microtask-debounced).
+ *   - `onDisable()`       — restore the snapshotted prior `style.size`
+ *                           values, clear snapshot.
+ *
+ * Defaults are `direction: 'both'`, `minSize: 8`, `maxSize: 32`,
+ * `scale: 'sqrt'` — the sqrt curve dampens the long-tail effect typical of
+ * real graphs (a few super-hubs would otherwise blow past the slider) while
+ * still giving visually distinct sizing.
+ *
+ * @example
+ * ```ts
+ * canvas.behaviours.register(
+ *   new DegreeSizeBehaviour({
+ *     id: 'degree-size',
+ *     layerId: 'graph',
+ *     enabled: true,
+ *     direction: 'both',
+ *     minSize: 6,
+ *     maxSize: 40,
+ *     scale: 'sqrt',
+ *   }),
+ * );
+ * // ...after registering, run the layout:
+ * void layout.apply(graph);
+ * ```
+ */
+
+/** Scaling curve used to map raw degree → output size. */
+type DegreeSizeScale = 'linear' | 'sqrt' | 'log';
+/** Constructor options for `DegreeSizeBehaviour`. */
+interface DegreeSizeBehaviourOptions extends BehaviourOptions {
+    /** Required — the `GraphLayer` id this behaviour drives. */
+    layerId: string;
+    /**
+     * Edges to count when computing each node's degree.
+     *
+     * - `'in'`   — only edges where the node is the target.
+     * - `'out'`  — only edges where the node is the source.
+     * - `'both'` — sum of in + out. Default.
+     */
+    direction?: EdgeDirection;
+    /** Output `style.size` for a node with degree === 0. Default `8`. */
+    minSize?: number;
+    /**
+     * Output `style.size` for the node with the maximum observed degree.
+     * Default `32`. Anything smaller than `minSize` is allowed but pointless.
+     */
+    maxSize?: number;
+    /**
+     * Curve mapping normalized degree (0..1) to a size between `minSize` and
+     * `maxSize`. Default `'sqrt'`.
+     *
+     * - `'linear'` — size = min + (max - min) * (degree / maxDegree)
+     * - `'sqrt'`   — size = min + (max - min) * sqrt(degree / maxDegree)
+     *                dampens the long tail typical of real graphs
+     * - `'log'`    — size = min + (max - min) * log1p(degree) / log1p(maxDegree)
+     *                aggressive dampening; better for power-law graphs
+     */
+    scale?: DegreeSizeScale;
+    /**
+     * Optional override. When provided, supersedes `minSize` / `maxSize` /
+     * `scale` and is called per-node with that node's degree plus the max
+     * degree across the layer. Returns the literal `style.size` to write.
+     */
+    sizeFn?: (degree: number, maxDegree: number) => number;
+}
+interface ResolvedOptions {
+    direction: EdgeDirection;
+    minSize: number;
+    maxSize: number;
+    scale: DegreeSizeScale;
+    sizeFn: ((degree: number, maxDegree: number) => number) | undefined;
+}
+declare class DegreeSizeBehaviour extends Behaviour {
+    /** Bound target layer — resolved in `onRegister`. */
+    private layer;
+    private opts;
+    /** Subscription disposers, called in `onDestroy`. */
+    private readonly subs;
+    /**
+     * Snapshot of each touched node's prior `style.size`, captured on the
+     * first write to that node. `undefined` means the node had no `size`
+     * field before — restore by writing `undefined`. Cleared on `disable` /
+     * `destroy`.
+     */
+    private readonly prior;
+    /** Microtask debounce flag — coalesces bursts of store events. */
+    private recomputeScheduled;
+    /** Re-entrancy guard — set while writing patches so our own emits no-op. */
+    private patching;
+    constructor(opts: DegreeSizeBehaviourOptions);
+    protected onRegister(ctx: CanvasContext): void;
+    protected onEnable(): void;
+    protected onDisable(): void;
+    protected onDestroy(): void;
+    /** Read-only snapshot of resolved options. */
+    get options(): Readonly<ResolvedOptions>;
+    /**
+     * Runtime option update. Re-runs `applyAll()` immediately if enabled so
+     * GUI slider changes are visible without an extra call.
+     */
+    setOptions(patch: Partial<DegreeSizeBehaviourOptions>): void;
+    /**
+     * Force a recompute + write pass. Useful after a bulk `store.batch()`
+     * the caller wants reflected immediately (the microtask-debounced
+     * subscription would otherwise fire on the next tick).
+     */
+    recompute(): void;
+    private scheduleRecompute;
+    /**
+     * Compute degree for every node, map to size, and write back via
+     * `store.updateNode` (merged with the prior `style` per the
+     * `updateNode replaces style wholesale` contract).
+     *
+     * Nodes touched here have their original `style.size` captured into
+     * `this.prior` on first write so `revertAll()` can restore them.
+     */
+    private applyAll;
+    /** Restore each touched node's prior `style.size` and clear the snapshot. */
+    private revertAll;
+}
+
+/**
+ * `ResponsiveThemeBehaviour` — keeps a `GraphLayer`'s theme-dependent styling in
+ * sync with the host's colour scheme.
+ *
+ * It owns the *entire* theme-driven look of graph content via three `light` /
+ * `dark` variant pairs:
+ *   - `node` — applied to every node through `setNodeDefaults` (shallow-merge into
+ *     the shared template, re-rendering every node).
+ *   - `edge` — applied to every edge through `setEdgeDefaults`.
+ *   - `group` — applied *only* to group nodes (those carrying `style.group`),
+ *     layered on top of `node`. Since the engine has no group template /
+ *     `setGroupDefaults`, group variants are written per-group-node via
+ *     `store.updateNode` and re-applied as groups are added.
+ *
+ * Background theming is deliberately *not* this behaviour's job — that stays with
+ * `BackgroundLayer` (`{ light, dark }` colour props) / `ThemedBackgroundLayer`.
+ *
+ * Why a behaviour and not React state: the declarative `<GraphLayer>` wrapper
+ * applies its `node`/`edge` style props only at mount, so React-state colour
+ * changes wouldn't reach existing — or freshly-drawn — items. Patching the layer
+ * template imperatively does, and new nodes inherit the patched template.
+ *
+ * `mode`:
+ *   - `'auto'` (default) — follows the host's `prefers-color-scheme`, flipping
+ *     live when the OS appearance changes.
+ *   - `'light'` / `'dark'` — pin a variant explicitly.
+ *
+ * Lifecycle:
+ *   - `onEnable()`  — arm the media query (when `auto`) and apply the resolved
+ *                     variant immediately.
+ *   - `onDisable()` — detach the media query. The layer keeps the last applied
+ *                     defaults (no revert — there is no "un-themed" baseline to
+ *                     restore to).
+ *
+ * @example
+ * ```ts
+ * canvas.behaviours.register(
+ *   new ResponsiveThemeBehaviour({
+ *     id: 'theme',
+ *     layerId: 'graph',
+ *     enabled: true,
+ *     node: {
+ *       light: { bgStrokeColor: 0xffffff },
+ *       dark:  { bgStrokeColor: 0x0f172a },
+ *     },
+ *     edge: {
+ *       light: { strokeColor: 0xcbd5e1 },
+ *       dark:  { strokeColor: 0x475569 },
+ *     },
+ *     group: {
+ *       light: { bgFill: 0xeef2ff, bgStrokeColor: 0x6b7fff },
+ *       dark:  { bgFill: 0x1e293b, bgStrokeColor: 0x475569 },
+ *     },
+ *   }),
+ * );
+ * ```
+ *
+ * @remarks
+ * The `group` pass tracks `node:add` / `flush`, so groups present at `setData`
+ * and groups added afterwards are themed. A node that *becomes* a group later via
+ * `node:update` is not re-themed (we don't watch `node:update`, to avoid a write
+ * loop with our own `updateNode` calls).
+ */
+
+/** The concrete variant currently being applied after mode resolution. */
+type ThemeKind = 'light' | 'dark';
+/** Mode selector. `'auto'` follows `prefers-color-scheme`; the rest pin. */
+type ThemeMode = 'auto' | 'light' | 'dark';
+/** A light / dark pair of style patches; each side is optional. */
+interface ThemeVariants<S> {
+    /** Patch applied when the resolved kind is `'light'`. */
+    light?: Partial<S>;
+    /** Patch applied when the resolved kind is `'dark'`. */
+    dark?: Partial<S>;
+}
+/** Constructor options for `ResponsiveThemeBehaviour`. */
+interface ResponsiveThemeBehaviourOptions extends BehaviourOptions {
+    /** Required — the `GraphLayer` id this behaviour themes. */
+    layerId: string;
+    /**
+     * How light vs dark is decided. `'auto'` (default) follows the host's
+     * `prefers-color-scheme`; `'light'` / `'dark'` pin a variant.
+     */
+    mode?: ThemeMode;
+    /**
+     * Node style applied per resolved kind via `setNodeDefaults` (shallow-merge
+     * into the layer's node template). Omit a side to leave it unthemed.
+     */
+    node?: ThemeVariants<NodeStyle>;
+    /**
+     * Edge style applied per resolved kind via `setEdgeDefaults` (shallow-merge
+     * into the layer's edge template). Omit a side to leave it unthemed.
+     */
+    edge?: ThemeVariants<EdgeStyle>;
+    /**
+     * Style applied to group nodes only (those with `style.group`), layered on top
+     * of `node`. Full `NodeStyle` per resolved kind. Because the engine has no
+     * group template, this is written per-group-node via `store.updateNode` and
+     * re-applied as groups are added. Omit a side to leave it unthemed.
+     */
+    group?: ThemeVariants<NodeStyle>;
+}
+declare class ResponsiveThemeBehaviour extends Behaviour {
+    /** Bound target layer — resolved in `onRegister`. */
+    private layer;
+    private mode;
+    private node?;
+    private edge?;
+    private group?;
+    private mediaQuery;
+    private mediaListener;
+    /** Store-event disposers for the group re-theme subscription. */
+    private readonly subs;
+    /** Microtask debounce flag — coalesces bursts of `node:add` / `flush`. */
+    private groupApplyScheduled;
+    /** Re-entrancy guard — set while our own `updateNode` writes are in flight. */
+    private patching;
+    constructor(opts: ResponsiveThemeBehaviourOptions);
+    protected onRegister(ctx: CanvasContext): void;
+    protected onEnable(): void;
+    protected onDisable(): void;
+    protected onDestroy(): void;
+    /** Current mode setting. */
+    getMode(): ThemeMode;
+    /** Concrete kind currently resolved from the mode. */
+    getResolvedKind(): ThemeKind;
+    /**
+     * Switch mode. `'auto'` re-arms the system listener; `'light'` / `'dark'`
+     * detach it and pin. Re-applies immediately when enabled.
+     */
+    setMode(mode: ThemeMode): void;
+    /**
+     * Replace the light/dark style variants. Re-applies immediately when enabled
+     * so live tweaking (e.g. from a GUI) is visible without an extra call.
+     */
+    setVariants(variants: {
+        node?: ThemeVariants<NodeStyle>;
+        edge?: ThemeVariants<EdgeStyle>;
+        group?: ThemeVariants<NodeStyle>;
+    }): void;
+    /** Resolve the active kind and push its variants onto the layer. */
+    private applyTheme;
+    /**
+     * Write the group variant onto every group node, layered over its current
+     * style. There is no group template, so this targets instances directly; the
+     * per-instance style wins over the node template, giving groups
+     * `node[kind]` (base) + `group[kind]` (override).
+     */
+    private applyGroupTheme;
+    /**
+     * Microtask-debounced re-apply of the group pass when new group nodes appear.
+     * Node/edge variants need no rescheduling — they live on the template, so new
+     * nodes inherit them automatically.
+     */
+    private scheduleGroupApply;
+    /**
+     * Arm the `prefers-color-scheme` listener when in `'auto'` mode; detach it
+     * otherwise. A system flip re-applies the resolved variant.
+     */
+    private wireMediaQuery;
+    private detachMediaQuery;
+}
+
+export { type ArcShapeOption, type ArrowShape, type BadgeEffects, type BadgeOrigin, type BadgePlacement, type BrushModifierKey, BrushSelectBehaviour, type BrushSelectBehaviourOptions, type BrushSelectElementType, type BrushSelectStyle, type BuiltInNodeShapeOptions, type CanonicalStateName, type CircleShapeOption, ClickInspectBehaviour, type ClickInspectBehaviourOptions, type ClickInspectEventMap, ClickSelectBehaviour, type ClickSelectBehaviourOptions, type ClickSelectEventMap, CollapseExpandBehaviour, type CollapseExpandBehaviourOptions, ContextMenuBehaviour, type ContextMenuBehaviourOptions, type ContextMenuEvent, type ContextMenuTargetType, CreateNodeBehaviour, type CreateNodeBehaviourOptions, type CustomShapeOption, DEFAULT_EDGE_STATES, DEFAULT_NODE_STATES, type DecorationSpecCommon, DegreeSizeBehaviour, type DegreeSizeBehaviourOptions, type DegreeSizeScale, DragNodeBehaviour, type DragNodeBehaviourOptions, DrawEdgeBehaviour, type DrawEdgeBehaviourOptions, type EdgeAnchor, type EdgeBadge, type EdgeBadgePlacement, type EdgeData, type EdgeDecorationSpec, type EdgeDirection, type EdgeInput, type EdgeOption, type EdgePathType, type EdgeShapeOptions, EdgeSizeLODBehaviour, type EdgeSizeLODBehaviourOptions, type EdgeSizeLODConfig, type EdgeStyle, EraseBehaviour, type EraseBehaviourOptions, type EraseTargetKind, type ErasedElement, GROUP_TOGGLE_SLOT, GraphClipboard, type GraphClipboardEventMap, type GraphClipboardOptions, type GraphData, type GraphDataOptions, type GraphEdge, GraphHistory, type GraphHistoryEventMap, type GraphHistoryOptions, GraphLayer, type GraphLayerEvents, type GraphLayerOptions, type GraphNode, GraphStore, type GraphStoreEventMap, type GraphStoreOptions, type GroupOptions, type HistoryEntry, type HistoryOp, type HistoryRecorder, HoverActivateBehaviour, type HoverActivateBehaviourOptions, type HoverDirection, type HoverableElement, type HoverableElementType, type InspectTarget, LabelCollisionBehaviour, type LabelCollisionBehaviourOptions, type LabelCollisionStrategy, type LabelPriorityResolver, LabelResolutionLODBehaviour, type LabelResolutionLODBehaviourOptions, type LassoModifierKey, LassoSelectBehaviour, type LassoSelectBehaviourOptions, type LassoSelectElementType, type LassoSelectStyle, MiniMapLayer, type MiniMapLayerOptions, type MiniMapPosition, type NodeBadge, type NodeData, type NodeDecorationSpec, type NodeEffects, type NodeIcon, type NodeImage, type NodeInput, type NodeOption, NodeResizeBehaviour, type NodeResizeBehaviourOptions, type NodeShapeOptions, NodeSizeLODBehaviour, type NodeSizeLODBehaviourOptions, type NodeSizeLODConfig, type NodeStyle, type ParallelEdgeBasis, ParallelEdgeBehaviour, type ParallelEdgeBehaviourOptions, type ParallelEdgeDistribute, type ParallelEdgeDistributeContext, type ParallelEdgeGroup, type ParallelEdgePatch, type PasteResult, type PolygonShapeOption, type RectShapeOption, type RegularPolygonShapeOption, type Resolvable, type ResolvableEdgeStyle, type ResolvableId, type ResolvableNodeStyle, ResponsiveThemeBehaviour, type ResponsiveThemeBehaviourOptions, type SelectDirection, type SelectModifierKey, type SelectableElement, type SelectableElementType, type SelectionSnapshot, type StarShapeOption, type ThemeKind, type ThemeMode, type ThemeVariants, type Vec2, centeredRanksPolicy, isBuiltInNodeShape, resolveField };