@invana/canvas 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,2034 @@
+import { E as EventMap, a as EventEmitter, b as EventSource, C as CanvasEventBus, c as Camera, P as PrimitivesRenderer } from './index-D0Z3YfJv.js';
+export { br as AnchorCtx, bs as AnchorShapeRef, bq as AnchorSpec, L as ArcShape, bF as ArcSpec, U as ArrowMarker, W as ArrowMarkerSpec, b2 as BadgeOptions, b3 as BadgePlacement, bH as BaseConnectorSpec, bz as BaseShapeSpec, aZ as BreathingConnectorEffect, a_ as BreathingConnectorEffectStyle, aX as BreathingEffect, aY as BreathingEffectStyle, l as CameraOptions, f as CanvasEvent, k as CanvasEventBusOptions, h as CanvasGlobalEvents, G as CircleShape, bA as CircleSpec, O as CompositePart, M as CompositeShape, N as CompositeSpec, Q as Connector, b4 as ConnectorBadgePlacement, r as ConnectorBase, t as ConnectorDecorationBase, bU as ConnectorDecorationCtor, bM as ConnectorDecorationHostInfo, v as ConnectorEffectBase, bI as ConnectorEndpointSpec, bK as ConnectorHostInfo, cg as ConnectorLabelPlacement, ch as ConnectorLabelStyle, by as ConnectorPaintStyle, D as DEFAULT_TAP_EXCLUDE, bX as DecorationSpec, bV as DecorationTarget, F as Easing, u as EffectBase, c5 as EffectSpec, bY as EffectTarget, bZ as EffectTargetKind, bg as Endpoint, d as EventHandler, g as EventSourceKind, a$ as FadeInConnectorEffect, b0 as FadeInConnectorEffectStyle, b1 as FadeInEasingName, at as FlowParticlesConnectorDecoration, au as FlowParticlesConnectorDecorationStyle, ar as FlyMarkerConnectorDecoration, as as FlyMarkerConnectorDecorationStyle, av as GlowConnectorDecoration, aw as GlowConnectorDecorationStyle, ad as GlowDecoration, ae as GlowDecorationStyle, c6 as HitResult, ci as HtmlTagStyle, bn as IAnchor, bO as IConnector, bR as IConnectorDecoration, bP as IDecorationBase, c1 as IEffectBase, bl as IPathStyle, bk as IRouter, bN as IShape, bQ as IShapeDecoration, c2 as IShapeEffect, bv as InsetAnchor, a8 as LOOP_CURVE_PRESETS, ca as LabelBackground, aG as LabelConnectorDecoration, c9 as LabelContent, aF as LabelDecoration, cd as LabelStyleCommon, cc as LabelVisibility, cb as LabelWrap, ah as LiquidFillDecoration, ai as LiquidFillDecorationStyle, a9 as LoopCurvePresetName, an as MarchingAntsConnectorDecoration, ao as MarchingAntsConnectorDecorationStyle, aj as MarchingAntsDecoration, ak as MarchingAntsDecorationStyle, bG as MarkerShapeSpec, b5 as NamedBadgePlacement, bo as Obstacle, bh as Path, bi as PathCommand, bm as PathStyleEndpoints, n as Point, I as PolygonShape, bC as PolygonSpec, bj as Polyline, q as PrimitiveBase, c7 as PrimitivesRendererEventMap, p as PrimitivesRendererOptions, af as PulseRingDecoration, ag as PulseRingDecorationStyle, R as Rect, H as RectShape, bB as RectSpec, bW as RegisterDecorationOptions, c4 as RegisterEffectOptions, J as RegularPolygonShape, bD as RegularPolygonSpec, c8 as RenderStats, aL as ResizeHandleDecoration, aM as ResizeHandleDecorationStyle, aO as ResizeHandleHitGeometry, aN as ResizeHandlePlacement, az as RevealConnectorDecoration, aA as RevealConnectorDecorationStyle, aB as RevealDirection, aC as RevealEasingName, aD as RevealHostStroke, aE as RevealRepeat, ap as RingConnectorDecoration, aq as RingConnectorDecorationStyle, al as RingDecoration, am as RingDecorationStyle, ax as RippleConnectorDecoration, ay as RippleConnectorDecorationStyle, bp as RouterCtx, aT as SelectionFrameBorderStyle, aP as SelectionFrameDecoration, aQ as SelectionFrameDecorationStyle, aS as SelectionFrameHandleHit, aU as SelectionFrameHandleShape, aR as SelectionFramePlacement, aV as ShakeEffect, aW as ShakeEffectStyle, S as ShapeBase, bS as ShapeCtor, s as ShapeDecorationBase, bT as ShapeDecorationCtor, bL as ShapeDecorationHostInfo, c3 as ShapeEffectCtor, c0 as ShapeEffectHostInfo, bt as ShapeFill, bu as ShapeFillLayer, bJ as ShapeHostInfo, ce as ShapeLabelPlacement, cf as ShapeLabelStyle, bx as ShapePaintStyle, bw as ShapeStroke, K as StarShape, bE as StarSpec, b$ as StyleOverride, T as TapHandler, j as TapOptions, o as TextureRegistry, aH as ToggleDecoration, aI as ToggleDecorationStyle, aK as ToggleHitGeometry, aJ as TogglePlacement, b_ as TransformDelta, w as Tween, x as TweenOptions, bf as Vec2, V as arrowMarkerSpec, a3 as bezierPathStyle, ab as boundaryAnchor, a5 as bumpRadialPathStyle, aa as centerAnchor, be as distanceToPolylineSq, B as easeInOutCubic, z as easeInOutSine, A as easeOutCubic, $ as erRouter, i as isExcludedFromTap, y as linear, a7 as loopCurvePathStyle, m as makeCanvasEvent, e as makeEventType, Z as manhattanRouter, _ as metroRouter, b8 as mirrorPlacement, a1 as normalPathStyle, a0 as oneSideRouter, b7 as originToBadgeLocal, Y as orthRouter, bd as pathBounds, ac as perpendicularAnchor, b6 as placementToHostAnchor, a4 as quadraticPathStyle, b9 as resolveBadgePosition, a2 as roundedPathStyle, ba as samplePath, bb as samplePathAt, a6 as smoothPathStyle, X as straightRouter, bc as tangentAt } from './index-D0Z3YfJv.js';
+import { StoreApi } from 'zustand/vanilla';
+export { StoreApi } from 'zustand/vanilla';
+import { Container, Graphics, Application } from 'pixi.js';
+export { Graphics } from 'pixi.js';
+import 'pixi-viewport';
+
+/**
+ * `SourceEmitter` — typed event emitter that auto-forwards every emit to a
+ * `CanvasEventBus.tap()` channel as a structured envelope.
+ *
+ * Architecture: see `architecture-proposal.md` §2.5.
+ *
+ * Each source (a `Layer`, a `Behaviour`, a `Layout`, the `Canvas` itself)
+ * holds one of these. Local subscribers see the plain payload (`on(name, fn)`);
+ * the bus's tap subscribers see the envelope (`{ type, timestamp, source, payload }`).
+ *
+ * The forward path is a single method call (`bus.publish(envelope)`). Tap
+ * filtering (exclude / sampleRate) lives in the bus, not here, so the emit
+ * cost stays constant whether 0 or 100 taps are subscribed.
+ *
+ * In dev, payloads are run through `assertSerialisableInDev` so violations
+ * surface immediately with the offending path.
+ *
+ * @example
+ * class GraphLayer {
+ *   readonly events: SourceEmitter<{ 'node:click': { id: string } }>;
+ *
+ *   constructor(id: string, ctx: CanvasContext) {
+ *     this.events = new SourceEmitter({ kind: 'layer', id }, ctx.events);
+ *   }
+ *
+ *   onShapeClick(id: string) {
+ *     // local handlers + bus tap, both fired:
+ *     this.events.emit('node:click', { id });
+ *   }
+ * }
+ */
+
+declare class SourceEmitter<E extends EventMap = EventMap> extends EventEmitter<E> {
+    private readonly source;
+    /**
+     * @param source — `{ kind: 'layer' | 'behaviour' | 'layout' | 'canvas' | 'store', id }`.
+     *   Identity of this emitter; used as the `source` field of each envelope.
+     * @param bus — Optional. When present, every `emit()` also publishes a
+     *   `CanvasEvent` envelope to this bus's tap channel. Pass `undefined`
+     *   for emitters that should be local-only (rare; mostly tests).
+     */
+    private bus?;
+    constructor(source: EventSource, bus?: CanvasEventBus);
+    /**
+     * Attach (or detach) the bus this emitter forwards to.
+     *
+     * Use case: a `Layer` is constructed before it knows which `Canvas` it'll be
+     * mounted on. The Layer creates its `SourceEmitter` upfront with no bus,
+     * then `mount(ctx)` calls `events.setBus(ctx.events)` to start forwarding.
+     * Pass `undefined` to detach (e.g. on unmount).
+     */
+    setBus(bus: CanvasEventBus | undefined): void;
+    /**
+     * Emit to local subscribers AND publish to the bus's tap channel.
+     * Order: local handlers run first (synchronous, in registration order),
+     * then the envelope is published. A throwing local handler is caught
+     * (logged via `console.error` per `EventEmitter`) and does not block the
+     * tap publish.
+     */
+    emit<K extends keyof E>(event: K, payload: E[K]): void;
+    /** Convenience: source identity (read-only). */
+    get sourceInfo(): EventSource;
+}
+
+/**
+ * Dev-mode walker that asserts an event payload is serialisable.
+ *
+ * Architecture: see `architecture-proposal.md` §2.5 (Serialisability discipline).
+ *
+ * Once the canvas advertises `tap()` as telemetry-ready, payloads must be
+ * serialisable: only ids, numbers, strings, plain objects, arrays, and
+ * `Map`/`Set` containing the same. PixiJS objects, DOM nodes, function refs,
+ * and class instances must NOT appear in payloads — they break:
+ *
+ *   - JSON-based telemetry sinks (Datadog, log shippers)
+ *   - structured-clone-based sinks (BroadcastChannel, postMessage to workers)
+ *   - devtools time-travel
+ *   - test snapshots
+ *
+ * The walker is **dev-only**. The exported `assertSerialisable` is
+ * unconditionally callable, but `assertSerialisableInDev` is the public
+ * entry point that the bus uses — it inlines a build-time NODE_ENV check
+ * so production bundlers tree-shake the entire walker out.
+ *
+ * @example violation log
+ *   [canvas] payload at 'node.shape' is not serialisable: BaseShape (class instance)
+ */
+/**
+ * Walk `value`, returning a list of human-readable violation messages.
+ * Empty array means "fully serialisable".
+ *
+ * The walker is iterative-ish: it uses recursion but with explicit cycle
+ * detection so a self-referencing payload doesn't blow the stack.
+ */
+declare function findSerialisationViolations(value: unknown, rootPath?: string): string[];
+/**
+ * Convenience: assert a payload is serialisable. In dev, logs warnings via
+ * `console.warn` for each violation (with offending path). In production,
+ * compiles to a no-op via `process.env.NODE_ENV` substitution.
+ *
+ * Pass a `context` string so the warning includes which event triggered it,
+ * e.g. `assertSerialisableInDev(payload, "emit('node:click')")`.
+ */
+declare function assertSerialisableInDev(value: unknown, context: string): void;
+
+/**
+ * `Store<T>` — typed alias of `zustand/vanilla` `StoreApi<T>` plus a thin
+ * factory that pre-composes the middleware stack we use everywhere.
+ *
+ * Architecture: see `architecture-proposal.md` §2.1 (state vs. data — bifurcated).
+ *
+ * **Use this only for small, observable interaction state** — hover, selection,
+ * drag intent, decoration overrides, view modes. The cardinality should stay
+ * comfortably below a few thousand items per slice; typical state size is
+ * tens of fields, not megabytes.
+ *
+ * For bulk hot data (positions, attributes for tens of thousands or millions
+ * of items), use `ColumnStore` instead. Immer + Map at 500k entries clones the
+ * whole Map on every mutation (5–50 ms each); typed-array columns are 10 ns.
+ *
+ * Middleware stack (outer → inner):
+ *
+ *   devtools  →  subscribeWithSelector  →  immer  →  state creator
+ *
+ *   - **immer** lets recipes mutate a draft; the produced state is structurally
+ *     shared with the previous state (untouched branches kept by reference).
+ *   - **subscribeWithSelector** adds the `subscribe(selector, listener, opts?)`
+ *     overload so consumers can subscribe to a slice instead of the whole state.
+ *   - **devtools** is enabled only in non-production builds (Redux DevTools
+ *     extension). Tree-shaken / no-op in production.
+ *
+ * @example
+ * type GraphLayerState = {
+ *   hoveredId: string | null;
+ *   selectedIds: ReadonlySet<string>;
+ *   haloIds: ReadonlySet<string>;
+ * };
+ *
+ * const store = createLayerStore<GraphLayerState>(
+ *   { hoveredId: null, selectedIds: new Set(), haloIds: new Set() },
+ *   { name: 'GraphLayer:graph-1' }
+ * );
+ *
+ * // immer-style mutation
+ * store.setState((draft) => { draft.hoveredId = 'n-42'; });
+ *
+ * // selector subscription — fires only when haloIds changes
+ * const off = store.subscribe(
+ *   (s) => s.haloIds,
+ *   (curr, prev) => { ... },
+ *   { equalityFn: Object.is }
+ * );
+ */
+
+/**
+ * The store API surface exposed to consumers.
+ *
+ * After middleware composition, the runtime store has:
+ *   - `setState(recipe)` — immer recipe that mutates a draft (immer middleware).
+ *   - `setState(partial)` and `setState(updater)` — vanilla forms (still work).
+ *   - `subscribe(listener)` — vanilla zustand API.
+ *   - `subscribe(selector, listener, opts?)` — added by `subscribeWithSelector`.
+ *
+ * The `setState` overload union mirrors what the immer middleware produces at
+ * runtime; `Store<T>` is what `createLayerStore<T>()` returns.
+ */
+type Store<T> = Omit<StoreApi<T>, 'setState' | 'subscribe'> & {
+    setState: {
+        /** Immer recipe form — mutate the draft, return nothing. Preferred. */
+        (recipe: (draft: T) => void): void;
+        /** Direct partial / replacement / updater forms — also accepted. */
+        (partial: T | Partial<T> | ((state: T) => T | Partial<T> | void), replace?: false): void;
+        /** Replace-state form (second arg = true). */
+        (state: T, replace: true): void;
+    };
+    subscribe: StoreApi<T>['subscribe'] & {
+        <U>(selector: (state: T) => U, listener: (selectedState: U, previousSelectedState: U) => void, options?: {
+            equalityFn?: (a: U, b: U) => boolean;
+            fireImmediately?: boolean;
+        }): () => void;
+    };
+};
+interface CreateLayerStoreOptions {
+    /**
+     * Devtools display name. Used as the "store" name in Redux DevTools.
+     * Convention: `<ClassName>:<id>` (e.g. `'GraphLayer:graph-1'`).
+     */
+    name?: string;
+    /**
+     * Force devtools on/off. Default: enabled when `process.env.NODE_ENV !== 'production'`.
+     * High-frequency mutation sites can pass `enableDevtools: false` per-store
+     * to avoid devtools serialisation cost in dev too.
+     */
+    enableDevtools?: boolean;
+}
+/**
+ * Create a `Store<T>` with our standard middleware stack.
+ *
+ * Pass either an initial state object, or a creator function that takes the
+ * zustand `set` / `get` (already wrapped with immer) and returns initial state.
+ * The creator form is useful when initial state needs to reference itself or
+ * close over imperative setup; the object form is the common case.
+ */
+declare function createLayerStore<T extends object>(initial: T, opts?: CreateLayerStoreOptions): Store<T>;
+declare function createLayerStore<T extends object>(creator: (set: (recipe: (draft: T) => void) => void, get: () => T) => T, opts?: CreateLayerStoreOptions): Store<T>;
+
+/**
+ * `ColumnStore<TSchema>` — typed-array column store for **bulk hot data**.
+ *
+ * Architecture: see `architecture-proposal.md` §2.1.
+ *
+ * Designed to scale to millions of items at machine-rate mutation (1000s/sec
+ * from external feeds). Where `Store<T>` (zustand+immer) makes per-mutation
+ * structural-sharing trade-offs that cap out around 5–10k for hot data,
+ * `ColumnStore` mutates typed-array slots in place at ~10 ns per write.
+ *
+ * **Mental model**
+ *
+ * One id-keyed object would be:   `{ id: 'n-42', x: 100, y: 50, color: 0x... }`
+ * In a ColumnStore that's:        slot 17 across N parallel typed-array columns.
+ *
+ * Lookup goes id → slot (`Map<string, number>`), then any number of columns
+ * are read/written by indexing slot. Slots are recycled when items are removed,
+ * so the column buffers stay compact under churn.
+ *
+ * **Performance characteristics at 500k items**
+ *
+ * | Op | Cost |
+ * |---|---|
+ * | `add(id, row)` | ~100 ns (Map.set + N TypedArray writes) |
+ * | `set(id, col, value)` | ~50 ns (Map.get + TypedArray write) |
+ * | `column(name)[slot] = value` (fast-path) | ~10 ns (single TypedArray write) |
+ * | `addBulk(rows)` for 500k | ~5–20 ms |
+ * | Memory for 500k × 5 columns × 4 bytes | ~10 MB |
+ *
+ * Compare immer + Map<string, object> at 500k: ~5–50 ms per single-field
+ * mutation (clones the entire 500k Map every time), ~150–250 MB memory.
+ *
+ * @example
+ * type NodeSchema = { x: 'f32'; y: 'f32'; color: 'u32'; size: 'f32' };
+ *
+ * class GraphNodeStore extends ColumnStore<NodeSchema> {
+ *   constructor() {
+ *     super({ x: 'f32', y: 'f32', color: 'u32', size: 'f32' }, { initialCapacity: 1024 });
+ *   }
+ * }
+ *
+ * const nodes = new GraphNodeStore();
+ * nodes.add('n-1', { x: 10, y: 20, color: 0x3b82f6, size: 8 });
+ * nodes.set('n-1', 'x', 30);                  // typesafe per-field setter
+ *
+ * // Renderer fast path — hold refs once, write directly:
+ * const xCol = nodes.column('x');
+ * const slot = nodes.slot('n-1')!;
+ * xCol[slot] = 40;                            // ~10 ns per write
+ * nodes.touch();                              // bump version after fast-path writes
+ */
+/**
+ * Numeric type tags for typed-array columns. Each maps to a JS TypedArray ctor.
+ *
+ * - `i8 / u8` — small integers (1 byte). Use for booleans, bitfields, packed enums.
+ * - `i16 / u16` — medium integers (2 bytes). Use for short integer ids, type-tags.
+ * - `i32 / u32` — large integers (4 bytes). Use for slot refs, packed colors, hashes.
+ * - `f32` — single-precision floats (4 bytes). Default for coordinates, weights.
+ * - `f64` — double-precision floats (8 bytes). Use only when precision matters.
+ */
+type ColumnType = 'i8' | 'u8' | 'i16' | 'u16' | 'i32' | 'u32' | 'f32' | 'f64';
+type ColumnSchema = Record<string, ColumnType>;
+type ColumnValue<T extends ColumnType> = T extends 'f32' | 'f64' ? number : number;
+type ColumnArray<T extends ColumnType> = T extends 'i8' ? Int8Array : T extends 'u8' ? Uint8Array : T extends 'i16' ? Int16Array : T extends 'u16' ? Uint16Array : T extends 'i32' ? Int32Array : T extends 'u32' ? Uint32Array : T extends 'f32' ? Float32Array : T extends 'f64' ? Float64Array : never;
+type RowOf<TSchema extends ColumnSchema> = {
+    [K in keyof TSchema]: ColumnValue<TSchema[K]>;
+};
+interface ColumnStoreOptions {
+    /** Initial slot capacity. Doubles on overflow. Default 256. */
+    initialCapacity?: number;
+    /** Max capacity. Throws on overflow. Default 16_777_216 (~16M). */
+    maxCapacity?: number;
+}
+declare class ColumnStore<TSchema extends ColumnSchema = ColumnSchema> {
+    private readonly schema;
+    private readonly columnNames;
+    private readonly maxCapacity;
+    /** id → slot. The only object-keyed lookup on the hot path. */
+    private readonly idIndex;
+    /** slot → id. Filled slots have a string; recycled holes have `undefined`. */
+    private readonly idReverse;
+    /** Stack of recycled slots. `add()` pops from here before extending. */
+    private readonly freeSlots;
+    /** TypedArray per column. Replaced on grow (new buffer with copied data). */
+    private columns;
+    /** Current capacity (length of each TypedArray). */
+    private _capacity;
+    /** High-water mark — largest slot index ever assigned + 1. Not necessarily filled. */
+    private _highWater;
+    /** Mutation version. Increments on any add/remove/set or `touch()`. */
+    private _version;
+    constructor(schema: TSchema, opts?: ColumnStoreOptions);
+    /** Number of items currently stored. */
+    get size(): number;
+    /** Current allocated capacity. Grows automatically when filled. */
+    get capacity(): number;
+    /** Mutation counter — bumps on any change. Subscribers diff this. */
+    get version(): number;
+    /** True iff `id` has been added. */
+    has(id: string): boolean;
+    /** Returns the slot for `id`, or `undefined`. Useful for the renderer fast path. */
+    slot(id: string): number | undefined;
+    /** Returns the id at `slot`, or `undefined` if the slot is free. */
+    idAt(slot: number): string | undefined;
+    /**
+     * Direct access to a column's TypedArray. **Holds a stable reference until
+     * the column is grown** (then the underlying buffer is replaced).
+     *
+     * Use the version field to detect grow events:
+     *   const v = store.version; const col = store.column('x');
+     *   // if (store.version !== v) the col reference may be stale
+     *
+     * Renderer fast path: cache `column(name)` and `slot(id)` once per frame
+     * and write directly. Bump `touch()` after batched fast-path writes so
+     * subscribers know.
+     */
+    column<K extends keyof TSchema>(name: K): ColumnArray<TSchema[K]>;
+    /** Read a single value. ~50 ns: Map.get + TypedArray read. */
+    get<K extends keyof TSchema>(id: string, name: K): ColumnValue<TSchema[K]> | undefined;
+    /** Materialise a full row by id. Allocates an object — avoid in hot loops. */
+    row(id: string): RowOf<TSchema> | undefined;
+    /**
+     * Add a new item. Throws if `id` already exists.
+     * Reuses a recycled slot when available; otherwise extends (and grows).
+     */
+    add(id: string, row: RowOf<TSchema>): number;
+    /**
+     * Bulk add. Grows once if needed (cheaper than N individual grows).
+     * Throws if any id already exists.
+     */
+    addBulk(items: ReadonlyArray<{
+        id: string;
+        row: RowOf<TSchema>;
+    }>): void;
+    /**
+     * Set a single field. ~50 ns: Map.get + TypedArray write.
+     * No-op if id doesn't exist.
+     */
+    set<K extends keyof TSchema>(id: string, name: K, value: ColumnValue<TSchema[K]>): void;
+    /**
+     * Update multiple fields of one item in one call. Avoids N version bumps.
+     */
+    update(id: string, partial: Partial<RowOf<TSchema>>): void;
+    /**
+     * Remove an item. Recycles the slot. No-op if id doesn't exist.
+     */
+    remove(id: string): void;
+    /** Bulk remove. */
+    removeBulk(ids: readonly string[]): void;
+    /**
+     * Mark the store as mutated without actually changing anything via the API.
+     * Use this after batches of fast-path writes via `column(...)[slot] = ...`
+     * so version-bump-driven subscribers know to re-read.
+     */
+    touch(): void;
+    /**
+     * Drop all items and recycled slots. Keeps the current capacity (no shrink).
+     * Cheap reset for repopulating from a feed.
+     */
+    clear(): void;
+    /**
+     * Iterate over (id, slot) pairs in insertion order of currently-live ids.
+     * O(idIndex.size) — does NOT walk holes.
+     */
+    forEach(cb: (id: string, slot: number) => void): void;
+    /** Iterator over live ids only. */
+    ids(): IterableIterator<string>;
+    private allocSlot;
+    /**
+     * Grow each column's TypedArray to at least `target` capacity.
+     * Doubles past target until met (so we don't grow once per add in a tight loop).
+     */
+    private grow;
+}
+
+/**
+ * `DirtyBatcher<TBucket>` — accumulates "this id changed" signals between
+ * frames, deduplicates them, and hands a per-frame snapshot to a flush callback.
+ *
+ * Architecture: see `architecture-proposal.md` §2.1 (Render projection).
+ *
+ * **Single responsibility:** absorb high-frequency dirty signals; nothing else.
+ * No rendering, no PixiJS knowledge, no `requestAnimationFrame` of its own.
+ * Canvas owns the single RAF (proposal §2.1) and calls `flush()` once per tick.
+ *
+ * **Performance properties (the contract that makes the architecture work)**
+ *
+ * - `mark(bucket, id)`: O(1) — Map.get + Set.add. No allocation in steady state.
+ * - `markAll(bucket)`: O(1) — sets a flag.
+ * - `flush()`: O(1) — Map swap, no copy.
+ * - Per-frame work for the consumer is proportional to `changed` ids,
+ *   never total scene size.
+ * - Sets are reused across frames (cleared after swap-out, not reallocated).
+ *   Zero GC pressure in steady state.
+ *
+ * **Double buffering & mid-flush mutations**
+ *
+ * `flush()` returns a snapshot whose Sets are the previous frame's accumulated
+ * marks. The "active" Sets are swapped to the empty buffer, so any `mark()`
+ * call made *during* the consumer's flush handler lands in the next frame's
+ * bucket — never corrupts the iteration in flight, never loops.
+ *
+ * @example
+ * type GraphDirty = 'shape' | 'halo' | 'edge';
+ * const dirty = new DirtyBatcher<GraphDirty>();
+ *
+ * // anywhere — mutation site
+ * dirty.mark('shape', 'n-42');
+ *
+ * // canvas tick
+ * if (dirty.hasPending()) {
+ *   const snap = dirty.flush();
+ *   for (const id of snap.buckets.shape) renderer.updateShape(id, ...);
+ *   for (const id of snap.buckets.halo)  renderer.setDecoration(id, 'halo', ...);
+ * }
+ */
+/**
+ * The frozen snapshot handed to the flush handler.
+ *
+ * `buckets` is a ReadonlyMap keyed by bucket name; each value is the Set of
+ * dirty ids for that bucket this frame. Buckets that have never been touched
+ * are absent (use `snap.buckets.get(bucket) ?? EMPTY_SET` to handle missing).
+ *
+ * `rebuildAll` is the Set of buckets the consumer marked with `markAll()`.
+ * For those buckets, the consumer should iterate the underlying data
+ * (not the per-id Set) — usually meaning "rebuild everything in this category."
+ */
+interface DirtySnapshot<TBucket extends string = string> {
+    readonly buckets: ReadonlyMap<TBucket, ReadonlySet<string>>;
+    readonly rebuildAll: ReadonlySet<TBucket>;
+}
+declare class DirtyBatcher<TBucket extends string = string> {
+    private active;
+    private buffer;
+    /** True iff at least one mark has landed since the last flush. */
+    private _dirty;
+    /**
+     * Mark a single id as dirty in a bucket. O(1), no allocation in steady state.
+     *
+     * Bucket Sets are created lazily on first mark and reused thereafter.
+     * If the bucket is currently flagged `markAll`, this call is redundant
+     * (consumer will iterate all data anyway) but cheap and harmless.
+     */
+    mark(bucket: TBucket, id: string): void;
+    /**
+     * Flag a whole bucket as needing rebuild. The consumer's flush handler
+     * should iterate its full data set for this bucket, ignoring the per-id Set.
+     *
+     * Use for bulk events: theme change, LOD swap, "everything moved",
+     * data feed wholesale replace.
+     */
+    markAll(bucket: TBucket): void;
+    /** Cheap check the canvas tick uses to decide whether to call `flush()`. */
+    hasPending(): boolean;
+    /**
+     * Swap buffers and return the previous frame's snapshot. After this call:
+     *   - The returned snapshot is stable for the duration of the consumer's
+     *     handler (any new marks land in the freshly-cleared other buffer).
+     *   - `hasPending()` returns false until the next mark.
+     *
+     * The handed-out Sets are still owned by the batcher — the consumer must
+     * **not retain references past the flush call**. The next `flush()` will
+     * reuse and clear them.
+     */
+    flush(): DirtySnapshot<TBucket>;
+    /**
+     * Drop both buffers. Call on layer unmount. After reset(), the batcher is
+     * usable again from a clean state.
+     */
+    reset(): void;
+    /** Number of dirty ids in a bucket. Returns 0 if bucket has never been touched. */
+    bucketSize(bucket: TBucket): number;
+    /** True iff the bucket has been flagged for rebuild this frame. */
+    isRebuildAll(bucket: TBucket): boolean;
+}
+
+/**
+ * `Layer` — base class for everything composable onto `canvas.layers`.
+ *
+ * Architecture: see `architecture-proposal.md` §2.1.
+ *
+ * **What every Layer owns:**
+ *   - `id` — stable identifier; used by registries, events, telemetry envelopes.
+ *   - `options` — construction-time, mostly-immutable config.
+ *   - `state` — UI / interaction state (`Store<T>` zustand+immer; small, observable).
+ *   - `events` — typed `SourceEmitter` that auto-forwards to the canvas tap.
+ *   - `dirty` — `DirtyBatcher` for per-frame batched flush.
+ *   - `visible` / `hittable` / `zIndex` / `cullable` — composition flags.
+ *
+ * **Lifecycle:** `mount(ctx)` → … → `unmount()`. `Canvas` calls these via the
+ * `LayerRegistry`. `flush()` is called once per Canvas tick when
+ * `dirty.hasPending()` is true.
+ *
+ * **Bulk hot data (`data`)** is NOT on the base class — it lives on subclasses
+ * that need it (e.g. `GraphLayer` ships `GraphNodeStore`). See
+ * `architecture-proposal.md` §2.1 for the bifurcated state/data model.
+ *
+ * **What subclasses provide:**
+ *   - `createState()` — initial UI state.
+ *   - `applyDirty(snap)` — translate dirty buckets → renderer commands.
+ *   - `onMount()` / `onUnmount()` — domain-specific setup/teardown
+ *     (subscribe to feeds, register decorations, etc.).
+ *   - `WorldLayer` / `ScreenLayer` add `hitTest(coord, coord)`.
+ */
+
+/**
+ * The subset of `Layer` the `LayerRegistry` and `Canvas.tick` interact with.
+ * Lets the registry stay decoupled from the abstract class implementation.
+ */
+interface ILayer {
+    readonly id: string;
+    visible: boolean;
+    hittable: boolean;
+    zIndex: number;
+    cullable: boolean;
+    mount(ctx: CanvasContext): void;
+    unmount(): void;
+    flush(): void;
+    hasPending(): boolean;
+}
+interface LayerOptions<TOptions = unknown> {
+    id: string;
+    options: TOptions;
+    visible?: boolean;
+    hittable?: boolean;
+    zIndex?: number;
+    /**
+     * Off-screen culling participation. Default `true`. Set `false` for
+     * full-canvas effect layers (background gradient, overlay) that should
+     * always render regardless of camera visibility.
+     */
+    cullable?: boolean;
+    /** Optional: name shown in devtools. Default `'<ClassName>:<id>'`. */
+    devtoolsName?: string;
+}
+declare abstract class Layer<TOptions = unknown, TState extends object = object, TEvents extends EventMap = EventMap, TDirtyBucket extends string = string> implements ILayer {
+    readonly id: string;
+    readonly options: TOptions;
+    readonly state: Store<TState>;
+    readonly events: SourceEmitter<TEvents>;
+    readonly dirty: DirtyBatcher<TDirtyBucket>;
+    /** Backing field for the `visible` accessor. */
+    private _visible;
+    hittable: boolean;
+    zIndex: number;
+    cullable: boolean;
+    /**
+     * Whether this layer renders. Setting `false` hides the layer's pixi
+     * container (via `onVisibleChange`, overridden by `WorldLayer` /
+     * `ScreenLayer`) and the Canvas tick skips its flush.
+     */
+    get visible(): boolean;
+    set visible(value: boolean);
+    /** Set by `mount(ctx)`; cleared by `unmount()`. */
+    protected ctx?: CanvasContext;
+    /** True between `mount` and `unmount`. */
+    get mounted(): boolean;
+    constructor(opts: LayerOptions<TOptions>);
+    mount(ctx: CanvasContext): void;
+    unmount(): void;
+    /** Convenience accessor; throws when called pre-mount. */
+    protected get context(): CanvasContext;
+    /** Whether `flush()` has work to do this frame. */
+    hasPending(): boolean;
+    /**
+     * Called by Canvas tick when `hasPending()` is true. Swaps the dirty
+     * snapshot, hands it to `applyDirty`. Subclasses normally don't override.
+     */
+    flush(): void;
+    /** Build the initial UI / interaction state. Called once in the constructor. */
+    protected abstract createState(): TState;
+    /**
+     * Translate a dirty snapshot into renderer / pixi commands.
+     * Default: no-op. Override when the layer batches work via `dirty.mark(...)`.
+     */
+    protected applyDirty(_snap: DirtySnapshot<TDirtyBucket>): void;
+    /** Domain-specific mount setup (subscribe to peers, attach renderer, etc.). */
+    protected onMount(_ctx: CanvasContext): void;
+    /** Domain-specific unmount teardown. */
+    protected onUnmount(_ctx: CanvasContext): void;
+    /**
+     * Called whenever `visible` changes (setter only — not on initial
+     * construction). Subclasses override to keep their pixi container's
+     * `.visible` in sync. Default: no-op.
+     */
+    protected onVisibleChange(_value: boolean): void;
+}
+
+/**
+ * `LayerRegistry` — stores the Layers added to a Canvas.
+ *
+ * Architecture: see `architecture-proposal.md` §2.4 (CanvasContext.layers).
+ *
+ * **Responsibilities**
+ *   - Add / remove (with mount / unmount lifecycle).
+ *   - Typed `get<T>(id)`.
+ *   - `byZOrder()` iteration — used by the Canvas tick.
+ *   - Fires `'layer:added'` / `'layer:removed'` on the bus.
+ *
+ * **Lifecycle wiring**
+ *
+ * The registry doesn't itself construct the `CanvasContext` — it would be
+ * circular (the registry is a field of the context). Instead the Canvas
+ * passes a `getContext()` thunk; `add(layer)` resolves it at the moment of
+ * mount. This keeps the registry decoupled from the context's full shape.
+ */
+
+interface LayerRegistryOptions {
+    /**
+     * Resolves the `CanvasContext` at the moment of mount. The Canvas creates
+     * its registries before the context object exists, so this thunk lets the
+     * registry defer the context lookup.
+     */
+    getContext: () => CanvasContext;
+    /** Bus for `layer:added` / `layer:removed` events. */
+    bus: CanvasEventBus;
+}
+declare class LayerRegistry {
+    private readonly layers;
+    private readonly getContext;
+    private readonly bus;
+    /** Cached z-sorted view; invalidated on add/remove/setZIndex. */
+    private zOrderCache;
+    constructor(opts: LayerRegistryOptions);
+    /** Number of registered layers. */
+    get size(): number;
+    /**
+     * Add a Layer to the canvas. Calls `layer.mount(ctx)` and fires `layer:added`.
+     * Throws if `id` is already registered.
+     */
+    add(layer: ILayer): void;
+    /**
+     * Remove a Layer. Calls `layer.unmount()` and fires `layer:removed`.
+     * No-op if `id` isn't registered.
+     */
+    remove(id: string): void;
+    /** Typed get by id. Returns `undefined` if not found. */
+    get<T extends ILayer = ILayer>(id: string): T | undefined;
+    has(id: string): boolean;
+    /** Snapshot of all layers in insertion order. */
+    list(): readonly ILayer[];
+    /**
+     * Iterate layers in z-order (low → high). The Canvas tick walks layers in
+     * z-order to flush dirty work; rendering order is then determined by
+     * pixi's child order (handled by `SurfaceManager.setWorldLayerZ`).
+     *
+     * The result is cached and reused until `add` / `remove` / `setZIndex` invalidates.
+     */
+    byZOrder(): readonly ILayer[];
+    /**
+     * Update a layer's `zIndex` and propagate to surfaces. Invalidates the
+     * z-order cache. No-op if the layer isn't registered.
+     */
+    setZIndex(id: string, zIndex: number): void;
+    /**
+     * Tear down every registered layer. Called on Canvas destroy.
+     * Iteration is over a snapshot so unmount-triggered side effects don't
+     * corrupt the loop.
+     */
+    clear(): void;
+}
+
+/**
+ * `Behaviour` — input subscriber that translates user input into state mutations.
+ *
+ * Architecture: see `architecture-proposal.md` §2.2.
+ *
+ * Behaviours own neither rendering output nor source-of-truth data. They
+ * subscribe to layer events (`'node:hover'`, `'shape:click'`) or canvas events
+ * (`'pointerdown'`) and mutate the appropriate `state` slice.
+ *
+ * **Default `enabled: false`.** Registration wires the behaviour up; the
+ * developer explicitly enables it. Matches the rule that no input behaviour
+ * is auto-active (`architecture-proposal.md` §2.2 + repo CLAUDE.md rule 7).
+ *
+ * **`shortcuts`** is advisory metadata — used by `BehaviourRegistry` to log
+ * conflict warnings when two enabled behaviours claim the same gesture
+ * (e.g. lasso vs. pan both wanting `'shift+drag'`). The framework warns;
+ * it does not enforce — that's the developer's job.
+ */
+
+/** What `BehaviourRegistry` sees. */
+interface IBehaviour {
+    readonly id: string;
+    readonly enabled: boolean;
+    readonly scope: 'layer' | 'canvas';
+    readonly layerId?: string;
+    readonly shortcuts?: readonly string[];
+    register(ctx: CanvasContext): void;
+    destroy(): void;
+    enable(): void;
+    disable(): void;
+}
+interface BehaviourOptions {
+    id: string;
+    /**
+     * Layer-scoped behaviours target a specific Layer by id. Canvas-scoped
+     * behaviours have no `layerId` and `scope: 'canvas'`.
+     */
+    layerId?: string;
+    /** Default `false` — the developer explicitly enables. */
+    enabled?: boolean;
+    /**
+     * Gesture identifiers this behaviour claims. Used by `BehaviourRegistry`
+     * for conflict warnings. Format is convention-free (`'shift+drag'`,
+     * `'wheel+ctrl'`, `'rclick'`); registries match strings as-is.
+     */
+    shortcuts?: readonly string[];
+}
+declare abstract class Behaviour implements IBehaviour {
+    readonly id: string;
+    readonly layerId?: string;
+    readonly shortcuts?: readonly string[];
+    /**
+     * `'layer'` if `layerId` is set, otherwise `'canvas'`. Set automatically
+     * from the constructor — subclasses don't need to re-declare.
+     */
+    readonly scope: 'layer' | 'canvas';
+    protected _enabled: boolean;
+    protected ctx?: CanvasContext;
+    constructor(opts: BehaviourOptions);
+    get enabled(): boolean;
+    /** Called by `BehaviourRegistry.register(behaviour)`. Subscribes to inputs. */
+    register(ctx: CanvasContext): void;
+    /** Called by `BehaviourRegistry.unregister(id)`. Drops subscriptions. */
+    destroy(): void;
+    enable(): void;
+    disable(): void;
+    /** Subscribe to events / setup any handler resources. */
+    protected abstract onRegister(ctx: CanvasContext): void;
+    /** Cleanup on destroy. Default no-op. */
+    protected onDestroy(_ctx: CanvasContext): void;
+    /** Hook fired when the developer enables the behaviour. */
+    protected onEnable(): void;
+    /** Hook fired on disable. */
+    protected onDisable(): void;
+    /**
+     * Convenience `if (!enabled) return;` for use inside event handlers
+     * (without rebinding `this` cost).
+     */
+    protected get isEnabled(): boolean;
+}
+
+/**
+ * `BehaviourRegistry` — stores Behaviours and toggles their enabled state.
+ *
+ * Architecture: see `architecture-proposal.md` §2.2.
+ *
+ * **Responsibilities**
+ *   - `register` / `unregister` (with register / destroy lifecycle).
+ *   - `setEnabled(id, enabled)` — toggles + fires `'behaviour:enabled'` /
+ *     `'behaviour:disabled'`.
+ *   - Typed `get<T>(id)`.
+ *   - **Gesture-conflict warning**: when two enabled behaviours claim the same
+ *     `shortcut`, log a `console.warn`. Doesn't enforce — the developer
+ *     decides whether two behaviours can coexist on the same gesture.
+ */
+
+interface BehaviourRegistryOptions {
+    getContext: () => CanvasContext;
+    bus: CanvasEventBus;
+}
+declare class BehaviourRegistry {
+    private readonly behaviours;
+    private readonly getContext;
+    private readonly bus;
+    constructor(opts: BehaviourRegistryOptions);
+    get size(): number;
+    /**
+     * Register a Behaviour. Calls `behaviour.register(ctx)` + fires
+     * `'behaviour:registered'`. If `behaviour.enabled` is `true` at construction
+     * time (the developer opted in via `enabled: true` option), also fires
+     * `'behaviour:enabled'` and runs the conflict-warning check.
+     *
+     * Throws on duplicate id.
+     */
+    register(behaviour: IBehaviour): void;
+    /** Remove a behaviour. Calls `destroy()`. No-op if not registered. */
+    unregister(id: string): void;
+    /** Enable / disable a behaviour. Fires the corresponding bus event. */
+    setEnabled(id: string, enabled: boolean): void;
+    get<T extends IBehaviour = IBehaviour>(id: string): T | undefined;
+    has(id: string): boolean;
+    list(): readonly IBehaviour[];
+    /** Tear down all behaviours. Called on Canvas destroy. */
+    clear(): void;
+    private warnOnShortcutConflict;
+}
+
+/**
+ * `CanvasContext` — the shared service surface every Layer / Behaviour /
+ * Layout receives at mount/register time.
+ *
+ * Architecture: see `architecture-proposal.md` §2.4.
+ *
+ * **One context, three audiences.** Per the proposal, there is no separate
+ * `LayerContext` / `BehaviourContext` / `LayoutContext` — the same shape is
+ * handed to every participant so cross-cutting access (read peer layers,
+ * fire camera moves, tap telemetry) doesn't need three parallel context types.
+ *
+ * The `Canvas` builds a concrete object that satisfies this interface and
+ * passes it down. Tests can construct a stub by satisfying these fields.
+ */
+
+interface CanvasContext {
+    /** Layer registry — `add / remove / get<T>(id) / list / byZOrder`. */
+    readonly layers: LayerRegistry;
+    /**
+     * Behaviour registry — `register / setEnabled / get<T>(id) / list`.
+     * Behaviours never auto-enable; the developer registers + enables explicitly
+     * (`architecture-proposal.md` §2.2).
+     */
+    readonly behaviours: BehaviourRegistry;
+    /** Camera — pan/zoom/projection. Wraps a `pixi-viewport` `Viewport`. */
+    readonly camera: Camera;
+    /** Canvas-wide event bus + telemetry tap channel. */
+    readonly events: CanvasEventBus;
+    /**
+     * The world container — a `pixi-viewport` `Viewport` instance. Camera-
+     * transformed; `WorldLayer.mount` attaches its root sub-layer container
+     * here. Typed as `Container` so domain code doesn't depend on
+     * `pixi-viewport`; reach for the `Viewport`-specific API via
+     * `camera.viewport`.
+     */
+    readonly world: Container;
+    /**
+     * The pixi `app.stage` (or test stage) — the renderer root. `ScreenLayer.mount`
+     * attaches its root container here, as a sibling of `world`. Pixi's child
+     * order = draw order: `world` is added first (bottom), each `ScreenLayer`'s
+     * root is added after (above). No screen-wrapper container exists.
+     */
+    readonly stage: Container;
+    /**
+     * The underlying HTMLCanvasElement when running in DOM mode (`Canvas.init`).
+     * Undefined for `Canvas.initWithStage` (headless / test path). Layers that
+     * overlay DOM content above the canvas — `DevInfoLayer`, tooltips, popovers —
+     * read this to find a parent element and to attach native DOM listeners.
+     */
+    readonly canvasElement?: HTMLCanvasElement;
+}
+
+/**
+ * `WorldLayer` — abstract base for layers that live in **world coordinate space**.
+ *
+ * Architecture: see `architecture-proposal.md` §2.1.
+ *
+ * - Camera-affected: pans / zooms with the camera.
+ * - Owns a root pixi `Container` (RenderGroup) attached to `surfaces.world`.
+ * - `hitTest(worldX, worldY)` — input is in world coordinates.
+ *
+ * Subclasses call `this.createGraphics(label?)` or `this.createContainer(label?)`
+ * to add pixi display objects, and override `onMount(ctx)` to wire up renderers.
+ * For stacked draw-order (e.g. edges below nodes), use separate Layer instances.
+ *
+ * The type-distinct `hitTest` signature (vs. `ScreenLayer`'s) is what stops
+ * consumers passing screen coords to a world layer or vice versa.
+ */
+
+interface WorldLayerHit {
+    /** Whatever the subclass chooses to return — a node id, a sub-region, etc. */
+    readonly id: string;
+    readonly subId?: string;
+    readonly kind?: string;
+}
+declare abstract class WorldLayer<TOptions = unknown, TState extends object = object, TEvents extends EventMap = EventMap, TDirtyBucket extends string = string, THit extends WorldLayerHit = WorldLayerHit> extends Layer<TOptions, TState, TEvents, TDirtyBucket> {
+    /** Backing field — assigned in `mount`, cleared in `unmount`. */
+    protected _container?: Container;
+    /**
+     * Root pixi `Container` (RenderGroup) for this layer. Available from
+     * `onMount(ctx)` for the layer's lifetime. Throws before mount / after unmount.
+     *
+     * Pass to `ShapesRenderer` as the `container` option when wiring up a renderer
+     * inside `onMount`. Subclass-only — not part of the external layer API.
+     */
+    protected get container(): Container;
+    constructor(opts: LayerOptions<TOptions>);
+    mount(ctx: CanvasContext): void;
+    /** Keep the pixi container in sync when `layer.visible` is toggled. */
+    protected onVisibleChange(value: boolean): void;
+    unmount(): void;
+    /**
+     * Create a pixi `Graphics` attached to this layer's root container. The
+     * sanctioned way for layer authors to obtain a `Graphics` for direct
+     * painting via `@invana/canvas/draw` primitives — keeps pixi internal
+     * (no `new Graphics()` in user code).
+     */
+    createGraphics(label?: string): Graphics;
+    /**
+     * Create a plain pixi `Container` attached to this layer's root container.
+     * Useful as a parent for mounted display objects (e.g. text sprites).
+     */
+    createContainer(label?: string): Container;
+    /**
+     * Update this layer's z-order relative to its peers. Keeps the iteration
+     * field (`this.zIndex`, used by `LayerRegistry.byZOrder()`) and the pixi
+     * container's `zIndex` in sync, and flips `surfaces.world` into sorted mode
+     * so the change renders.
+     */
+    setZIndex(z: number): void;
+    /**
+     * Return the world-space AABB of everything currently rendered on this layer.
+     * Delegates to Pixi's `getLocalBounds()` — a one-shot scene-graph traversal.
+     * Suitable for "fit to content" calls; do not call every frame.
+     */
+    getBounds(): {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    /**
+     * Hit-test in world coordinates. Returns the topmost hit or `null`.
+     * Concrete layers implement this against their own data + spatial index.
+     *
+     * The `Canvas`-level hit-test orchestration (top-down by z-order, stop on
+     * first hit, screen-layers-before-world per proposal Q6) calls this.
+     */
+    abstract hitTest(worldX: number, worldY: number): THit | null;
+}
+
+/**
+ * `ScreenLayer` — abstract base for layers that live in **screen / viewport coordinate space**.
+ *
+ * Architecture: see `architecture-proposal.md` §2.1.
+ *
+ * - Viewport-fixed: NOT camera-affected. Pans / zooms do not transform it.
+ * - Owns a root pixi `Container` attached directly to `ctx.stage`.
+ *   Plain `Container` (not a RenderGroup) — screen-space content is typically
+ *   lightweight HUD-style rendering that doesn't need its own GPU batch boundary.
+ * - `hitTest(screenX, screenY)` — input is in screen pixels.
+ *
+ * Examples: `MiniMapLayer`, `DevInfoLayer`, HUD, tool palettes.
+ *
+ * The type-distinct `hitTest` signature (vs. `WorldLayer`'s) is what stops
+ * consumers passing world coords to a screen layer or vice versa.
+ */
+
+interface ScreenLayerHit {
+    readonly id: string;
+    readonly subId?: string;
+    readonly kind?: string;
+}
+declare abstract class ScreenLayer<TOptions = unknown, TState extends object = object, TEvents extends EventMap = EventMap, TDirtyBucket extends string = string, THit extends ScreenLayerHit = ScreenLayerHit> extends Layer<TOptions, TState, TEvents, TDirtyBucket> {
+    /** Backing field — assigned in `mount`, cleared in `unmount`. */
+    protected _container?: Container;
+    /**
+     * Root pixi `Container` for this screen-space layer. Available from
+     * `onMount(ctx)` for the layer's lifetime. Throws before mount / after unmount.
+     *
+     * Subclass-only — not part of the external layer API.
+     */
+    protected get container(): Container;
+    constructor(opts: LayerOptions<TOptions>);
+    mount(ctx: CanvasContext): void;
+    /** Keep the pixi container in sync when `layer.visible` is toggled. */
+    protected onVisibleChange(value: boolean): void;
+    unmount(): void;
+    /**
+     * Create a pixi `Graphics` attached to this layer's root container. The
+     * sanctioned way for layer authors to obtain a `Graphics` for direct
+     * painting via `@invana/canvas/draw` primitives.
+     */
+    createGraphics(label?: string): Graphics;
+    /**
+     * Create a plain pixi `Container` attached to this layer's root container.
+     * Useful as a parent for mounted display objects.
+     */
+    createContainer(label?: string): Container;
+    /**
+     * Update this layer's z-order relative to its peers. Keeps the iteration
+     * field (`this.zIndex`) and the pixi container's `zIndex` in sync, and
+     * flips `ctx.stage` into sorted mode so the change renders.
+     */
+    setZIndex(z: number): void;
+    /** Hit-test in screen / viewport coordinates. Top-most hit or `null`. */
+    abstract hitTest(screenX: number, screenY: number): THit | null;
+}
+
+/**
+ * `DevInfoLayer` — developer overlay that continuously displays:
+ *   - Canvas display size
+ *   - Camera position (x, y) and zoom scale
+ *   - Visible world bounds
+ *   - Pointer position (screen and world coords)
+ *   - Frame rate (FPS)
+ *
+ * Implemented as a `ScreenLayer` whose visible artifact is a plain
+ * absolutely-positioned HTML `<div>` layered above the canvas (so it never
+ * interferes with pointer events on the scene). The pixi `container` from
+ * `ScreenLayer` is unused — overlay rendering is pure DOM.
+ *
+ * Headless / offscreen mode: when `ctx.canvasElement` is undefined (i.e.
+ * `Canvas.initWithStage`), the layer mounts cleanly but renders nothing.
+ *
+ * @example
+ * ```ts
+ * import { DevInfoLayer } from '@invana/canvas/toolkit';
+ *
+ * const devInfo = new DevInfoLayer({ corner: 'top-right' });
+ * canvas.layers.add(devInfo);
+ *
+ * // Toggle at runtime
+ * devInfo.setEnabled(false);
+ * ```
+ */
+
+type DevInfoCorner = 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+interface DevInfoLayerOptions {
+    /** Which corner to anchor the overlay. Default: 'bottom-left' */
+    corner?: DevInfoCorner;
+    /** Show the overlay. Can be toggled at runtime via setEnabled(). Default: true */
+    enabled?: boolean;
+    /** Font size in px. Default: 11 */
+    fontSize?: number;
+    /** Panel opacity 0–1. Default: 0.92 */
+    opacity?: number;
+    /** Overlay background CSS color. Default: 'rgba(10,10,10,0.82)' */
+    backgroundColor?: string;
+    /** Text color. Default: '#c8d3e0' */
+    textColor?: string;
+    /** Accent / header color. Default: '#4fc3f7' */
+    accentColor?: string;
+}
+interface DevInfoLayerCtorOptions extends DevInfoLayerOptions {
+    /** Layer id. Default: 'dev-info'. */
+    id?: string;
+    /** Pixi z-index inside the screen stage. Default: 9999 (top). */
+    zIndex?: number;
+}
+interface DevInfoState {
+    enabled: boolean;
+}
+declare class DevInfoLayer extends ScreenLayer<DevInfoLayerOptions, DevInfoState> {
+    private _opts;
+    private _overlay;
+    private _pointerScreen;
+    private _pointerWorld;
+    private _onPointerMove;
+    private _unsubs;
+    private _rafId;
+    private _fps;
+    private _frameCount;
+    private _lastFpsTimestamp;
+    constructor(opts?: DevInfoLayerCtorOptions);
+    protected createState(): DevInfoState;
+    /** Overlay is DOM with `pointer-events:none` — never participates in hit-testing. */
+    hitTest(_screenX: number, _screenY: number): ScreenLayerHit | null;
+    protected onMount(): void;
+    protected onUnmount(): void;
+    /** Show or hide the overlay at runtime without removing the layer. */
+    setEnabled(enabled: boolean): void;
+    enable(): void;
+    disable(): void;
+    /** Update display options (corner, colors, font size, …) at runtime. */
+    setOptions(partial: Partial<DevInfoLayerOptions>): void;
+    private _mountOverlay;
+    private _unmountOverlay;
+    private _applyStyles;
+    private _startFpsTicker;
+    private _stopFpsTicker;
+    private _update;
+}
+
+/**
+ * `BackgroundLayer` — solid colour or tiled pattern fill behind the world.
+ *
+ * Architecture: see `architecture-proposal.md` §2.1.
+ *
+ * Implemented as a `ScreenLayer` for two practical reasons:
+ *
+ * 1. The pattern needs to cover the *viewport*, not the world bounds. A
+ *    WorldLayer would require sizing an infinite rectangle.
+ * 2. `TilingSprite` lets us mimic camera-following cheaply by adjusting
+ *    `tileScale` + `tilePosition` on each pan/zoom — no per-frame geometry
+ *    rebuild needed.
+ *
+ * When `followCamera` is `true` (default), the pattern shifts and scales with
+ * the camera so the background feels like part of the world ("graph paper").
+ * When `false`, the pattern is fixed to the screen.
+ *
+ * @example
+ * ```ts
+ * canvas.layers.add(new BackgroundLayer({
+ *   id: 'bg',
+ *   options: { type: 'pattern', patternType: 'dots', backgroundColor: 0x0f172a },
+ * }));
+ * ```
+ */
+
+/** Top-level background style. `'solid'` skips the pattern texture entirely. */
+type BackgroundType = 'solid' | 'pattern';
+/** Pattern texture kind. */
+type BackgroundPatternType = 'dots' | 'grid' | 'lines';
+/**
+ * Mode selector for light/dark colour resolution. `'auto'` follows the host's
+ * `prefers-color-scheme` media query; `'light'` / `'dark'` pin explicitly.
+ */
+type BackgroundMode = 'auto' | 'light' | 'dark';
+/** The concrete kind currently being rendered after mode resolution. */
+type BackgroundKind = 'light' | 'dark';
+/**
+ * A colour input. Pass a `number` / CSS string for a single colour, or a
+ * `{ light, dark }` pair to swap based on the layer's `mode`.
+ */
+type BackgroundColor = number | string | {
+    light: number | string;
+    dark: number | string;
+};
+/** Construction-time options for `BackgroundLayer`. */
+interface BackgroundLayerOptions {
+    /** `'solid'` paints a flat fill; `'pattern'` overlays a tiled texture. Default `'solid'`. */
+    type?: BackgroundType;
+    /** Tile texture kind when `type === 'pattern'`. Default `'dots'`. */
+    patternType?: BackgroundPatternType;
+    /**
+     * Pattern foreground colour (dot / line / grid colour). Accepts `0xRRGGBB`,
+     * a CSS string, or a `{ light, dark }` pair resolved against `mode`.
+     */
+    color?: BackgroundColor;
+    /** Solid-fill colour painted behind the pattern. Same accepted forms as `color`. */
+    backgroundColor?: BackgroundColor;
+    /** Dot radius / line thickness, in *texture pixels*. Default `1`. */
+    size?: number;
+    /** Tile cell spacing, in *texture pixels*. Default `12`. */
+    spacing?: number;
+    /** Pattern alpha 0–1. Default `0.6`. */
+    alpha?: number;
+    /**
+     * `true` (default): pattern shifts + scales with the camera. `false`: pattern
+     * stays fixed to the screen regardless of camera state.
+     */
+    followCamera?: boolean;
+    /**
+     * How `{ light, dark }` colour variants are resolved. `'auto'` (default)
+     * follows `prefers-color-scheme`; `'light'` / `'dark'` pin explicitly. Has
+     * no effect when both colours are plain scalars.
+     */
+    mode?: BackgroundMode;
+}
+interface BackgroundLayerState {
+    readonly _placeholder?: never;
+}
+declare class BackgroundLayer extends ScreenLayer<BackgroundLayerOptions, BackgroundLayerState, Record<string, never>, never, ScreenLayerHit> {
+    private opts;
+    private tiling;
+    private patternTexture;
+    /** DPR baked into the current pattern texture — used to compensate `tileScale`. */
+    private textureDpr;
+    private resizeObserver;
+    private offCameraPan;
+    private offCameraZoom;
+    private modeMediaQuery;
+    private modeMediaListener;
+    private camX;
+    private camY;
+    private camScale;
+    constructor(opts: LayerOptions<BackgroundLayerOptions>);
+    protected createState(): BackgroundLayerState;
+    protected onMount(ctx: CanvasContext): void;
+    protected onUnmount(): void;
+    /**
+     * Hit tests on the background always miss — clicks fall through to the
+     * world layer beneath, which is what users expect for a bg.
+     */
+    hitTest(): ScreenLayerHit | null;
+    /** Merge-update options + re-render. */
+    setOptions(changes: Partial<BackgroundLayerOptions>): void;
+    /** Snapshot of the resolved options. */
+    getOptions(): Required<BackgroundLayerOptions>;
+    /**
+     * Set the colour-resolution mode. `'auto'` re-arms the system listener;
+     * `'light'` / `'dark'` pin explicitly. No-op when mode is unchanged.
+     */
+    setMode(mode: BackgroundMode): void;
+    /** Current mode setting. */
+    getMode(): BackgroundMode;
+    /** Concrete kind currently being rendered after mode resolution. */
+    getResolvedKind(): BackgroundKind;
+    private viewportSize;
+    private render;
+    private syncTileTransform;
+    private createPatternTexture;
+    private resolveColor;
+    private hasVariantColor;
+    private wireModeMediaQuery;
+    private detachModeMediaQuery;
+}
+
+/**
+ * Mode selector. `'auto'` follows `prefers-color-scheme`; `'light'` / `'dark'`
+ * pin explicitly.
+ */
+type ThemedBackgroundMode = 'auto' | 'light' | 'dark';
+/** The concrete variant currently being rendered after mode resolution. */
+type ThemedBackgroundKind = 'light' | 'dark';
+/** A named look bundling both a light and dark variant. */
+interface ThemedBackgroundTheme {
+    /** Stable identifier — referenced by `setTheme(id)` and `defaultTheme`. */
+    id: string;
+    /** Optional human-friendly label for UIs. */
+    label?: string;
+    /** Style applied when the resolved kind is `'light'`. */
+    light: BackgroundLayerOptions;
+    /** Style applied when the resolved kind is `'dark'`. */
+    dark: BackgroundLayerOptions;
+}
+/** Construction-time options for `ThemedBackgroundLayer`. */
+interface ThemedBackgroundLayerOptions {
+    /** Named themes. Must contain at least one entry. */
+    themes: ThemedBackgroundTheme[];
+    /** Id of the theme to start with. Defaults to `themes[0].id`. */
+    defaultTheme?: string;
+    /** Initial mode. Defaults to `'auto'`. */
+    mode?: ThemedBackgroundMode;
+}
+/** Layer-event map fired by `ThemedBackgroundLayer.events`. */
+interface ThemedBackgroundLayerEvents {
+    'theme:switched': {
+        theme: ThemedBackgroundTheme;
+        resolvedKind: ThemedBackgroundKind;
+        source: 'initial' | 'manual';
+    };
+    'mode:updated': {
+        mode: ThemedBackgroundMode;
+        previousMode: ThemedBackgroundMode;
+        resolvedKind: ThemedBackgroundKind;
+        source: 'manual' | 'system';
+    };
+    [event: string]: unknown;
+}
+interface ThemedBackgroundLayerState {
+    readonly _placeholder?: never;
+}
+declare class ThemedBackgroundLayer extends BackgroundLayer {
+    private readonly themes;
+    private activeId;
+    private currentMode;
+    private mediaQuery;
+    private mediaListener;
+    readonly events: EventEmitter<ThemedBackgroundLayerEvents> & BackgroundLayer['events'];
+    constructor(opts: LayerOptions<ThemedBackgroundLayerOptions>);
+    protected createState(): ThemedBackgroundLayerState;
+    protected onMount(ctx: CanvasContext): void;
+    protected onUnmount(): void;
+    /**
+     * Switch to a theme by id. Mode is preserved. Throws on unknown id.
+     * Emits `'theme:switched'`.
+     */
+    setTheme(id: string): void;
+    /**
+     * Set the mode. `'auto'` re-arms the system listener; `'light'` / `'dark'`
+     * pin explicitly. Emits `'mode:updated'` when the mode actually changes.
+     */
+    setMode(mode: ThemedBackgroundMode): void;
+    /** Currently active theme. */
+    getActiveTheme(): ThemedBackgroundTheme;
+    /** Current mode setting. */
+    getMode(): ThemedBackgroundMode;
+    /** Concrete kind currently being rendered. */
+    getResolvedKind(): ThemedBackgroundKind;
+    /** Snapshot of the configured themes. */
+    getThemes(): readonly ThemedBackgroundTheme[];
+    private applyResolved;
+    private emitThemeSwitched;
+    private emitModeUpdated;
+    private wireMediaQuery;
+    private detachMediaQuery;
+}
+
+/**
+ * `LayersPanelLayer` — developer overlay that lists every layer currently
+ * mounted on the canvas and exposes a checkbox per row to toggle that
+ * layer's `visible` flag.
+ *
+ * Implemented as a `ScreenLayer` whose visible artifact is a plain
+ * absolutely-positioned HTML `<div>` layered above the canvas — same pattern
+ * as `DevInfoLayer`. Unlike `DevInfoLayer`, the overlay receives pointer
+ * events (so the checkboxes are clickable); the layer itself still opts out
+ * of engine hit-testing via `hittable: false`.
+ *
+ * The panel re-renders on `'layer:added'` / `'layer:removed'`. The panel's
+ * own row is filtered out so the user can't hide it via itself.
+ *
+ * Headless / offscreen mode: when `ctx.canvasElement` is undefined (i.e.
+ * `Canvas.initWithStage`), the layer mounts cleanly but renders nothing.
+ *
+ * @example
+ * ```ts
+ * import { LayersPanelLayer } from '@invana/canvas';
+ *
+ * const panel = new LayersPanelLayer({ corner: 'top-right' });
+ * canvas.layers.add(panel);
+ *
+ * // Toggle the panel itself at runtime
+ * panel.setEnabled(false);
+ * ```
+ */
+
+type LayersPanelCorner = 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+interface LayersPanelLayerOptions {
+    /** Which corner to anchor the overlay. Default: 'top-right' */
+    corner?: LayersPanelCorner;
+    /** Show the overlay. Toggle at runtime via setEnabled(). Default: true */
+    enabled?: boolean;
+    /** Font size in px. Default: 11 */
+    fontSize?: number;
+    /** Panel opacity 0–1. Default: 0.92 */
+    opacity?: number;
+    /** Overlay background CSS color. Default: 'rgba(10,10,10,0.82)' */
+    backgroundColor?: string;
+    /** Text color. Default: '#c8d3e0' */
+    textColor?: string;
+    /** Accent / header color. Default: '#4fc3f7' */
+    accentColor?: string;
+    /**
+     * Layer ids to hide from the list. The panel's own id is always hidden
+     * regardless of this option.
+     */
+    hideIds?: readonly string[];
+}
+interface LayersPanelLayerCtorOptions extends LayersPanelLayerOptions {
+    /** Layer id. Default: 'layers-panel'. */
+    id?: string;
+    /** Pixi z-index inside the screen stage. Default: 9998 (just below DevInfoLayer). */
+    zIndex?: number;
+}
+interface LayersPanelState {
+    enabled: boolean;
+}
+declare class LayersPanelLayer extends ScreenLayer<LayersPanelLayerOptions, LayersPanelState> {
+    private _opts;
+    private _overlay;
+    private _onChange;
+    private _unsubs;
+    constructor(opts?: LayersPanelLayerCtorOptions);
+    protected createState(): LayersPanelState;
+    /** Overlay is DOM — never participates in the engine's hit-testing. */
+    hitTest(_screenX: number, _screenY: number): ScreenLayerHit | null;
+    protected onMount(): void;
+    protected onUnmount(): void;
+    /** Show or hide the panel at runtime without removing the layer. */
+    setEnabled(enabled: boolean): void;
+    enable(): void;
+    disable(): void;
+    /** Update display options (corner, colors, font size, …) at runtime. */
+    setOptions(partial: Partial<LayersPanelLayerOptions>): void;
+    /**
+     * Force a re-render of the panel. Call this if external code mutates
+     * `layer.visible` on a registered layer and you want the checkboxes to
+     * reflect the new state. (The engine does not emit an event for visibility
+     * mutations.)
+     */
+    refresh(): void;
+    private _mountOverlay;
+    private _unmountOverlay;
+    private _applyStyles;
+    private _render;
+}
+
+/**
+ * `DragPanBehaviour` — pointer-drag panning via the pixi-viewport `drag` plugin.
+ *
+ * An optional `modifier` key restricts the gesture so you can reserve plain
+ * drag for other behaviours (e.g. lasso, rubber-band select):
+ *
+ *   - `'none'`  (default) — any left-button drag pans.
+ *   - `'space'`            — Space + drag (Figma / Sketch style).
+ *   - `'shift'`            — Shift + drag.
+ *   - `'alt'`              — Alt/Option + drag.
+ *
+ * A decelerate plugin is added alongside by default, giving momentum after
+ * the pointer lifts. Disable with `decelerate: false`.
+ *
+ * The canvas cursor swaps to `dragCursor` (`'grabbing'` by default) the moment
+ * a qualifying pointer is pressed — so it reads as "holding the canvas, ready
+ * to drag" before any movement happens — and restores on release. The press is
+ * matched against the configured `mouseButtons` and `modifier`; the `space`
+ * modifier can't be read off a pointer event, so for that mode the swap falls
+ * back to pixi-viewport's `drag-start` (fires once the gesture actually moves).
+ * The idle cursor is left untouched, so this never fights the renderer's hover
+ * cursor.
+ */
+
+type DragModifier = 'none' | 'space' | 'shift' | 'alt';
+interface DragPanBehaviourOptions extends BehaviourOptions {
+    /** Which modifier key must be held during drag. Default `'none'`. */
+    modifier?: DragModifier;
+    /** Allowed mouse buttons. Default `'left'`. Forwarded to pixi-viewport. */
+    mouseButtons?: 'all' | 'left' | 'right' | 'middle';
+    /** Add momentum deceleration after pointer lift. Default `true`. */
+    decelerate?: boolean;
+    /**
+     * Cursor applied to the canvas while the pan pointer is held. Set on
+     * pointer-press (matching `mouseButtons` / `modifier`), restored to the
+     * previous value on release. Default `'grabbing'`.
+     */
+    dragCursor?: string;
+}
+declare class DragPanBehaviour extends Behaviour {
+    private readonly modifier;
+    private readonly mouseButtons;
+    private readonly withDecelerate;
+    private readonly dragCursor;
+    /** Canvas the cursor swap targets; `null` on headless / custom stages. */
+    private canvasEl;
+    /** Cursor saved when the pan pointer is pressed, restored on release. */
+    private prevCursor;
+    constructor(opts: DragPanBehaviourOptions);
+    protected onRegister(ctx: CanvasContext): void;
+    protected onEnable(): void;
+    protected onDisable(): void;
+    private readonly onPointerDown;
+    /** Swap to the drag cursor, saving the prior value. No-op if already armed. */
+    private readonly armCursor;
+    /** Restore the saved cursor and detach the release listeners. */
+    private readonly restoreCursor;
+    /** Does this pointer button match the configured `mouseButtons`? */
+    private buttonAllowed;
+    /**
+     * Is the configured modifier satisfied for this press? `shift` / `alt` read
+     * off the event; `none` is always true; `space` returns `false` here (not
+     * detectable on a pointer event) and is handled by the `drag-start` fallback.
+     */
+    private modifierHeld;
+}
+
+/**
+ * `DragShapeBehaviour` — pointer-drag move for individual shapes managed by
+ * a `PrimitivesRenderer`. Layer-scoped: constructed with a specific renderer
+ * reference; the same canvas can host multiple layers, each with its own
+ * drag behaviour.
+ *
+ * Default `enabled: false` — register, then explicitly enable. Matches the
+ * project rule that no behaviour auto-activates.
+ *
+ * What happens on drag:
+ *   1. `shape:pointerdown` from the renderer → drag start. Records the
+ *      pointer's world position and the shape's current `(spec.x, spec.y)`.
+ *   2. The viewport's pan plugin is paused so the camera doesn't pan while
+ *      you're moving a shape.
+ *   3. Window-level `pointermove` updates the shape via
+ *      `renderer.updateShape(id, { x, y })` so the click point stays under
+ *      the cursor. Window events are used (rather than pixi container events)
+ *      so the drag continues smoothly even when the pointer slides off the
+ *      original shape or off the canvas momentarily.
+ *   4. When `reRouteConnectors` is `true` (default), every connector is
+ *      re-routed after each move — useful when the moved shape is an
+ *      obstacle for an obstacle-aware router. Set `false` if you're moving
+ *      a node whose edges should re-route via a smarter graph-level signal
+ *      (or if you have thousands of edges and the cost matters).
+ *   5. `pointerup` / `pointercancel` → drag end. Viewport pan resumes.
+ *
+ * The behaviour observes the renderer's public surface only: subscribes to
+ * `shape:pointerdown`, calls `getShapePosition` / `updateShape` /
+ * `reRouteAllConnectors`. No private access.
+ */
+
+interface DragShapeBehaviourOptions extends BehaviourOptions {
+    /** The renderer whose shapes this behaviour can drag. */
+    readonly renderer: PrimitivesRenderer;
+    /**
+     * Optional predicate to restrict which shape ids are draggable. Returning
+     * `false` ignores the pointerdown. Default = every shape is draggable.
+     */
+    readonly filter?: (id: string) => boolean;
+    /**
+     * Re-route every connector after each move. Default `true` — needed for
+     * obstacle-aware routers (`manhattan` etc.) so they recompute when
+     * obstacles move. Set `false` to avoid the per-move re-route cost.
+     */
+    readonly reRouteConnectors?: boolean;
+    /**
+     * Optional cursor while dragging. Applied on drag start and cleared on
+     * drag end. Default `'grabbing'`.
+     */
+    readonly dragCursor?: string;
+}
+declare class DragShapeBehaviour extends Behaviour {
+    private readonly renderer;
+    private readonly filter?;
+    private readonly reRouteConnectors;
+    private readonly dragCursor;
+    private state;
+    private offShapeDown?;
+    private viewport?;
+    private canvasEl;
+    private prevCursor;
+    constructor(opts: DragShapeBehaviourOptions);
+    protected onRegister(ctx: CanvasContext): void;
+    protected onDestroy(_ctx: CanvasContext): void;
+    protected onDisable(): void;
+    private startDrag;
+    private endDrag;
+    private readonly onWindowPointerMove;
+    private readonly onWindowPointerUp;
+    /** Convert a window-level `(clientX, clientY)` to canvas-relative screen coords. */
+    private clientToScreen;
+}
+
+/**
+ * `WheelZoomBehaviour` — scroll-wheel zooming via the pixi-viewport `wheel` plugin.
+ *
+ * By default, any scroll wheel event zooms. Set `requireCtrl: true` to
+ * restrict to Ctrl+scroll (frees plain scroll for page scrolling — good
+ * for accessibility contexts where the canvas is inline on a scrollable page).
+ *
+ * `trackpadPinch: true` is enabled so two-finger trackpad pinches zoom
+ * instead of scroll. Pair with `PinchZoomBehaviour` for touch devices.
+ */
+
+interface WheelZoomBehaviourOptions extends BehaviourOptions {
+    /**
+     * If `true`, only Ctrl+scroll triggers zoom; plain scroll falls through
+     * to the browser. Good for inline canvas embeds. Default `false`.
+     */
+    requireCtrl?: boolean;
+    /** Zoom speed per wheel tick, as a fraction. Default `0.1` (10%). */
+    percent?: number;
+    /**
+     * Smooth-scroll frame count. `false` = instant snap. Default `false`.
+     * Set to e.g. `8` for an ease-out feel.
+     */
+    smooth?: false | number;
+}
+declare class WheelZoomBehaviour extends Behaviour {
+    private readonly requireCtrl;
+    private readonly percent;
+    private readonly smooth;
+    constructor(opts: WheelZoomBehaviourOptions);
+    protected onRegister(_ctx: CanvasContext): void;
+    protected onEnable(): void;
+    protected onDisable(): void;
+}
+
+/**
+ * `PinchZoomBehaviour` — two-finger pinch-to-zoom via the pixi-viewport `pinch` plugin.
+ *
+ * Designed for touch screens and trackpads. Works alongside
+ * `WheelZoomBehaviour` (which handles trackpad pinch-as-scroll separately via
+ * its `trackpadPinch` flag); this behaviour handles native touch pinch events.
+ *
+ * Set `noDrag: true` if you want pinch to only zoom, not also pan (useful
+ * when you have a separate `DragPanBehaviour` and don't want conflicts).
+ */
+
+interface PinchZoomBehaviourOptions extends BehaviourOptions {
+    /**
+     * If `true`, suppress the implicit pan that accompanies a pinch gesture.
+     * Default `false` — pinch both zooms and centres the viewport on the
+     * midpoint between the two fingers.
+     */
+    noDrag?: boolean;
+    /** Zoom speed multiplier. Default `0.1`. */
+    percent?: number;
+}
+declare class PinchZoomBehaviour extends Behaviour {
+    private readonly noDrag;
+    private readonly percent;
+    constructor(opts: PinchZoomBehaviourOptions);
+    protected onRegister(_ctx: CanvasContext): void;
+    protected onEnable(): void;
+    protected onDisable(): void;
+}
+
+/**
+ * `KeyboardCameraInputBehaviour` — keyboard pan and zoom for accessibility.
+ *
+ * Default keymap (all configurable via `keymap` option):
+ *
+ *   Pan up/down/left/right  →  Arrow keys
+ *   Zoom in                 →  `+` / `=` / `NumpadAdd`
+ *   Zoom out                →  `-` / `NumpadSubtract`
+ *   Reset zoom to 1:1       →  `0` / `Numpad0`
+ *
+ * Events attach to `document` so the canvas does not need to be
+ * individually focused. Input fields, textareas, and selects are
+ * excluded automatically — keyboard events whose `target` is an editable
+ * element fall through unhandled.
+ *
+ * Arrow key direction follows the "scroll" metaphor: ArrowUp pans the
+ * viewport so you see content *above* the current view.
+ */
+
+interface KeyboardCameraKeymap {
+    panUp: string[];
+    panDown: string[];
+    panLeft: string[];
+    panRight: string[];
+    zoomIn: string[];
+    zoomOut: string[];
+    resetZoom: string[];
+}
+interface KeyboardCameraInputBehaviourOptions extends BehaviourOptions {
+    /** Pan distance per key press in screen pixels. Default `40`. */
+    panStep?: number;
+    /**
+     * Zoom multiplier per key press. `1.1` = 10% in/out per press.
+     * Default `1.1`.
+     */
+    zoomFactor?: number;
+    /** Override individual key groups. Merged with the defaults. */
+    keymap?: Partial<KeyboardCameraKeymap>;
+}
+declare class KeyboardCameraInputBehaviour extends Behaviour {
+    private readonly panStep;
+    private readonly zoomFactor;
+    private readonly keymap;
+    private _handler?;
+    constructor(opts: KeyboardCameraInputBehaviourOptions);
+    protected onRegister(_ctx: CanvasContext): void;
+    protected onEnable(): void;
+    protected onDisable(): void;
+    private _onKeyDown;
+    private _match;
+}
+
+/**
+ * `ElementSizeLODBehaviour` — abstract base for zoom-driven "keep this
+ * element at a fixed screen-pixel size" behaviours.
+ *
+ * Sits in the same family as `LabelResolutionLODBehaviour`: both react
+ * to `camera:zoom`, both adapt how some kind of entity renders as the
+ * camera scale changes. This base owns the shared plumbing — event
+ * subscription, RAF coalescing of bursts, enable/disable lifecycle —
+ * and leaves the *what to rescale* to concrete subclasses.
+ *
+ * ## Why a base + subclass split
+ *
+ * The "screen-constant size" need shows up across domains: graph nodes
+ * and edges today; swimlane lane headers, annotation pins, ER table
+ * decorations tomorrow. Putting the camera-zoom plumbing in canvas (which
+ * already owns the camera and the behaviour base) and the per-element
+ * rescaling in domain packages means:
+ *
+ * - Each domain ships its own subclass next to its data model. No need
+ *   to modify an upstream "knows about everything" class to add a new
+ *   element kind.
+ * - The browser RAF callback batches every behaviour's scheduled
+ *   callback into the same frame, so registering multiple subclasses
+ *   has effectively the same per-frame cost as one monolith doing N
+ *   passes.
+ *
+ * ## Concrete subclass contract
+ *
+ * Override `onResolveTargets(ctx)` once at register to resolve layer
+ * references. Override `apply(scale)` to walk those targets and write
+ * the rescaled geometry through the renderer's fast paths
+ * (`updateShape`, `setConnectorStroke`, etc.).
+ *
+ * `disable()` calls `apply(1)` — your apply function should be
+ * idempotent at scale 1 (which is what "restore to world-unit sizing"
+ * means).
+ *
+ * ## MapLibre note
+ *
+ * `MapLayer` writes the pixi-viewport transform directly to mirror
+ * MapLibre's camera. It re-emits `camera:zoom` on the canvas event bus
+ * after each move so subclasses of this behaviour react under MapLibre
+ * gestures the same as under `WheelZoomBehaviour`. Without that bridge
+ * these behaviours would silently no-op under MapLibre.
+ */
+
+/** A static value or a getter — getters are re-read on every `apply`. */
+type NumberOrGetter = number | (() => number);
+/** Coerce a {@link NumberOrGetter} to its current numeric value, or `undefined`. */
+declare function resolveNumberOrGetter(v: NumberOrGetter | undefined): number | undefined;
+interface ElementSizeLODBehaviourOptions extends BehaviourOptions {
+    /**
+     * Skip `apply` when the relative scale change since the last applied
+     * frame is below this threshold (`|scale - lastScale| / lastScale`).
+     * Set to `0` to disable the skip. Default `0.005` (0.5%) — sub-pixel
+     * stroke / size deltas at typical screen DPIs, which the user can't
+     * perceive but a wheel-zoom gesture fires 60×/sec of.
+     */
+    scaleEpsilon?: number;
+    /**
+     * When `> 0`, switch from per-frame RAF apply to a trailing-edge
+     * debounce: skip work during a continuous gesture and run one final
+     * `apply` after `settleMs` of zoom silence. Useful for expensive
+     * passes (e.g. thousands of connector redraws) where mid-gesture
+     * visual drift is preferable to a frame-rate collapse. Default `0`
+     * (RAF mode).
+     */
+    settleMs?: number;
+}
+declare abstract class ElementSizeLODBehaviour extends Behaviour {
+    private readonly subs;
+    /**
+     * Pending `requestAnimationFrame` handle. Non-null while a reflow is
+     * scheduled but hasn't fired yet — collapses bursts of `camera:zoom`
+     * events (the wheel-zoom gesture fires 100+/sec) into one `apply`
+     * call per animation frame. Critical for keeping fps above 60 during
+     * a continuous zoom over thousands of entities.
+     */
+    private rafHandle;
+    /**
+     * Settle timer (debounce) handle. Used instead of `rafHandle` when
+     * `settleMs > 0`. Re-armed on every `camera:zoom`; firing triggers a
+     * single `apply` at the latest scale.
+     */
+    private settleTimer;
+    /**
+     * Scale at the last `apply` call. Drives the `scaleEpsilon` skip:
+     * the next scheduled apply bails if the current scale is within
+     * epsilon of this value. `null` means "no prior apply, never skip".
+     */
+    private lastAppliedScale;
+    private readonly scaleEpsilon;
+    private readonly settleMs;
+    constructor(opts: ElementSizeLODBehaviourOptions);
+    protected onRegister(ctx: CanvasContext): void;
+    protected onDestroy(): void;
+    protected onEnable(): void;
+    protected onDisable(): void;
+    /**
+     * Force an immediate reflow at the current camera scale. Useful after
+     * tuning a config knob (e.g. moving a GUI slider that a `NumberOrGetter`
+     * reads from) — push the new sizes without waiting for the next zoom.
+     *
+     * Bypasses the epsilon skip and the settle debounce — explicit calls
+     * are always treated as "apply now."
+     */
+    reflow(): void;
+    /**
+     * Called once on register. Resolve layer references from `ctx.layers`
+     * and stash them on `this` for later `apply` calls. Throw a descriptive
+     * error if a required layer isn't present — the canvas guarantees
+     * `ctx.layers` is fully populated before behaviours register.
+     */
+    protected abstract onResolveTargets(ctx: CanvasContext): void;
+    /** Optional teardown hook — drop layer refs / caches. Default no-op. */
+    protected onReleaseTargets(): void;
+    /**
+     * Apply rescaling at the given camera scale. Called by `onEnable`,
+     * each `camera:zoom` (RAF coalesced), and by `onDisable` with
+     * `scale = 1` to restore world-unit sizing.
+     *
+     * Implementations should be idempotent — calling twice with the same
+     * scale is a no-op visually.
+     */
+    protected abstract apply(scale: number): void;
+    /**
+     * Route a `camera:zoom` to either the RAF path (default) or the
+     * trailing-edge debounce path (`settleMs > 0`). Both eventually call
+     * {@link tryApply}, which honours the epsilon skip.
+     */
+    private scheduleReflow;
+    /**
+     * Apply at the current camera scale if (a) still enabled, (b) the
+     * scale has moved by more than `scaleEpsilon` since the last apply.
+     * Updates {@link lastAppliedScale} only on a real apply, so cumulative
+     * sub-epsilon drift is eventually caught.
+     */
+    private tryApply;
+    private applyAndRemember;
+    private cancelScheduledReflow;
+}
+
+/**
+ * `Layout` — function from data to positions.
+ *
+ * Architecture: see `architecture-proposal.md` §2.3.
+ *
+ * Per the proposal:
+ *  - A Layout does NOT register with the canvas.
+ *  - It does NOT render.
+ *  - It does NOT subscribe to input.
+ *  - You instantiate it and call it against a layer.
+ *
+ *      const layout = new D3ForceLayout({ charge: -300 });
+ *      layout.events.on('end', () => canvas.camera.fitContent(...));
+ *      await layout.apply(graphLayer);
+ *
+ * Continuous-running cases (e.g. always-relax force simulation) are handled
+ * by a thin wrapper Behaviour that calls `apply()` on a tick — keeps the
+ * Layout API clean while supporting the rare continuous case.
+ *
+ * Whether two layouts conflict is a domain concern (don't apply two layouts
+ * to the same data) — not enforced here.
+ *
+ * ## Lifecycle events
+ *
+ * Every layout owns a typed `events` emitter and fires three lifecycle
+ * events around `apply()`:
+ *
+ *  - `start` — emitted once, synchronously, after the layout has set up
+ *    its internal state and just before it begins producing positions.
+ *  - `tick` — emitted whenever the layout writes a fresh batch of positions.
+ *    One-shot layouts (e.g. ELK) fire it once. Iterative layouts (force
+ *    sims) fire it on every iteration. High-frequency; subscribe sparingly.
+ *  - `end` — emitted once when the run terminates. `reason` distinguishes
+ *    a natural settle from an external `stop()` call.
+ *
+ * Subscribe to these events to drive camera fits, progress UI, etc. —
+ * instead of listening to per-tick `data:changed` on the layer, which
+ * conflates "structure changed" with "positions updated".
+ */
+
+/**
+ * Why the run ended.
+ *
+ *  - `completed` — the layout settled / finished on its own.
+ *  - `stopped`   — `stop()` (or a second `apply()`) cancelled it.
+ */
+type LayoutEndReason = 'completed' | 'stopped';
+/**
+ * Lifecycle events fired by every `Layout`.
+ *
+ * Subclass-specific telemetry (e.g. d3-force's `alpha`) belongs on a
+ * subclass-specific event map, not here.
+ */
+type LayoutEvents = {
+    start: Record<string, never>;
+    tick: Record<string, never>;
+    end: {
+        reason: LayoutEndReason;
+    };
+};
+declare abstract class Layout<TLayer extends Layer<any, any, any, any> = Layer<any, any, any, any>> {
+    /**
+     * Lifecycle event bus. See class docs for the event vocabulary.
+     * Subclasses with richer telemetry can declare their own typed
+     * emitter on top (`override readonly events = new EventEmitter<MyEvents>()`).
+     */
+    readonly events: EventEmitter<LayoutEvents>;
+    /**
+     * Run the layout against `layer`. Resolves when the run terminates
+     * (either a natural settle or an external `stop()`).
+     *
+     * Calling `apply()` again on the same instance must cancel any in-flight
+     * run first.
+     */
+    abstract apply(layer: TLayer): Promise<void>;
+}
+
+/**
+ * `Canvas` — the engine root.
+ *
+ * Architecture: see `architecture-proposal.md` (whole document) and
+ * `decorations-plan.md` §11.9 (RenderGroups + Ticker integration).
+ *
+ * **What it owns**
+ *   - The pixi `Application` (created by `init`) and its `Ticker`.
+ *   - The `CanvasEventBus` (typed canvas-wide events + tap channel).
+ *   - The `SurfaceManager` (world + screen RenderGroups).
+ *   - The `Camera` (pan/zoom/projection).
+ *   - The `LayerRegistry` and `BehaviourRegistry`.
+ *   - The `CanvasContext` object handed to every Layer / Behaviour.
+ *
+ * **What it does per tick** (single RAF, delegated to pixi `Ticker`):
+ *   1. Walk layers in z-order.
+ *   2. Skip invisible layers.
+ *   3. If a layer has pending dirty work, call `layer.flush()`.
+ *   4. Pixi auto-renders the stage at end of tick.
+ *
+ * Animation runner (Tweens) and per-renderer animation ticks land in later
+ * steps; this Canvas implementation has the hook points but doesn't yet
+ * orchestrate them.
+ *
+ * **Two init paths**
+ *   - `init(opts)` — the production path. Creates a pixi `Application`,
+ *     mounts its canvas into the DOM container, hooks the ticker.
+ *   - `initWithStage(stage, sw, sh)` — the test / headless path. Skips pixi
+ *     `Application` entirely. Caller provides a `Container` (which can be
+ *     a freshly-constructed pixi `Container()`) and viewport dimensions.
+ *     Useful for unit tests that want to exercise the layer pipeline without
+ *     standing up a renderer.
+ */
+
+interface CanvasOptions {
+    /**
+     * Stable identifier for this Canvas instance. Used as the source id on
+     * envelopes published by the bus's own `emit()`. Default: `'canvas'`.
+     * Override when running multiple Canvas instances in one document.
+     */
+    id?: string;
+    /** DOM element pixi mounts its `<canvas>` into. Required by `init()`. */
+    container?: HTMLElement;
+    /** Preferred backend. Default `'webgpu'`. Pixi falls back via its own logic. */
+    preference?: 'webgpu' | 'webgl' | 'canvas';
+    /** Viewport width in CSS pixels. Default = `container.clientWidth`. */
+    width?: number;
+    /** Viewport height in CSS pixels. Default = `container.clientHeight`. */
+    height?: number;
+    /** Device pixel ratio. Default `window.devicePixelRatio`. */
+    resolution?: number;
+    /** GPU MSAA. Default `true`. Auto-disabled on the Canvas backend. */
+    antialias?: boolean;
+    /** `true` → opaque scene, `backgroundAlpha = 1` (skips per-frame blend). */
+    opaque?: boolean;
+    /** Background colour. Default `0` (black, but only visible when `opaque: true`). */
+    backgroundColor?: number;
+    /** GPU power preference. Default `'high-performance'`. */
+    powerPreference?: 'high-performance' | 'low-power';
+    /** Suppress pixi's "PixiJS X.X.X" startup log. Default `true`. */
+    hello?: boolean;
+    /**
+     * Automatically resize the renderer and camera when the container element
+     * changes size. Covers both window resize and programmatic expand/collapse.
+     * Uses `ResizeObserver` internally. Default `false`.
+     */
+    autoResize?: boolean;
+    /**
+     * Suppress the browser's native right-click context menu on the canvas
+     * element. Diagram apps typically want to show their own menu UI via the
+     * `shape:contextmenu` / `connector:contextmenu` events. Default `true`.
+     *
+     * Set to `false` if the app wants the OS context menu (e.g. for
+     * accessibility / dev tooling on right-click).
+     */
+    suppressBrowserContextMenu?: boolean;
+}
+declare class Canvas {
+    readonly id: string;
+    readonly options: CanvasOptions;
+    /**
+     * Public surface — populated by `init()` / `initWithStage()`. Accessing
+     * before init throws (definite-assignment via `!`). Use `isInitialised`
+     * to guard if needed.
+     */
+    readonly events: CanvasEventBus;
+    /**
+     * The world container — a `pixi-viewport` `Viewport` instance attached to
+     * `app.stage`. Camera-transformed; `WorldLayer`s mount their roots here.
+     * Typed as `Container` so consumers don't depend on `pixi-viewport`; reach
+     * for the `Viewport`-specific API via `camera.viewport`.
+     */
+    world: Container;
+    /**
+     * The pixi `Application.stage` (or, for `initWithStage`, the caller-
+     * provided stage). `ScreenLayer`s mount their roots directly here, as
+     * siblings of `world` — `world` is added first (bottom), each ScreenLayer
+     * after (above). No "screen" wrapper container.
+     */
+    stage: Container;
+    camera: Camera;
+    layers: LayerRegistry;
+    behaviours: BehaviourRegistry;
+    context: CanvasContext;
+    private app?;
+    private _isInitialised;
+    private _onRendererResize?;
+    constructor(opts?: CanvasOptions);
+    get isInitialised(): boolean;
+    /** Pixi `Application`, available after `init()` (not `initWithStage`). */
+    get application(): Application | undefined;
+    /**
+     * Production init: create a pixi `Application`, mount its canvas into the
+     * supplied DOM container, wire the ticker, and emit
+     * `'renderer:initialised'` on the bus.
+     *
+     * The selected backend (and capabilities) flows through the bus event so
+     * consumers see which renderer pixi resolved.
+     */
+    init(opts: CanvasOptions): Promise<void>;
+    /**
+     * Headless / test init. Caller provides a pre-built stage `Container`
+     * and viewport dimensions; we skip pixi's `Application` setup entirely.
+     *
+     * Use case: unit tests of the layer / behaviour / dirty / state pipeline
+     * that don't need an actual GPU renderer.
+     */
+    initWithStage(stage: Container, screenWidth: number, screenHeight: number): void;
+    /**
+     * Run one tick manually with a fixed delta. Useful in tests; in production
+     * pixi's ticker calls `tick` automatically.
+     */
+    tickOnce(deltaMs?: number): void;
+    /** Pixi ticker callback. Bound via `add(this.tick, this)`. */
+    private tick;
+    /**
+     * Tear down everything: ticker callback, registries (which unmount their
+     * Layers / destroy their Behaviours and any ScreenLayer roots they own),
+     * the world subtree, bus subscriptions, pixi Application. Idempotent.
+     */
+    destroy(): void;
+    private _wireScene;
+    private _detectBackend;
+    private _capabilities;
+}
+
+/**
+ * `loadIconFont` — inject an icon-font stylesheet at runtime, then await
+ * font readiness so the very first paint rasterises against the real
+ * webfont (not a fallback with the wrong metrics).
+ *
+ * The mechanic:
+ *
+ *   1. Attaching `<link rel="stylesheet" href=…>` kicks off:
+ *      stylesheet download → CSS parse → `@font-face` registration → WOFF
+ *      fetch.
+ *   2. The browser's `FontFaceSet` only knows about the family **after**
+ *      the `@font-face` declaration is parsed — calling
+ *      `document.fonts.load(…)` before that returns an empty result.
+ *   3. So we wait for the link's `load` event first, then ask the
+ *      `FontFaceSet` to actually load the face.
+ *
+ * Vendor-agnostic: takes any stylesheet URL and any font-family name. The
+ * canvas library does not know about Font Awesome / Material Symbols /
+ * Phosphor / Heroicons / etc. — consumers point this at whichever icon
+ * font (or regular webfont) they want.
+ *
+ * @example
+ * ```ts
+ * await loadIconFont(
+ *   'https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.5.0/css/all.min.css',
+ *   'Font Awesome 6 Free',
+ * );
+ * // now safe to render `{ kind: 'glyph', char: '', fontFamily: 'Font Awesome 6 Free', fontWeight: 900 }`.
+ * ```
+ *
+ * Idempotent: subsequent calls with the same `stylesheetUrl` reuse the
+ * existing `<link>` element. Safe to call from N stories that all use the
+ * same icon font.
+ *
+ * SSR-safe: a no-op when `document` is undefined.
+ */
+declare function loadIconFont(stylesheetUrl: string, fontFamilyToProbe?: string, fontWeightToProbe?: number | string, fontStyleToProbe?: 'normal' | 'italic'): Promise<void>;
+
+export { BackgroundLayer, type BackgroundLayerOptions, type BackgroundPatternType, type BackgroundType, Behaviour, type BehaviourOptions, BehaviourRegistry, type BehaviourRegistryOptions, Camera, Canvas, type CanvasContext, CanvasEventBus, type CanvasOptions, type ColumnArray, type ColumnSchema, ColumnStore, type ColumnStoreOptions, type ColumnType, type ColumnValue, type CreateLayerStoreOptions, type DevInfoCorner, DevInfoLayer, type DevInfoLayerCtorOptions, type DevInfoLayerOptions, DirtyBatcher, type DirtySnapshot, type DragModifier, DragPanBehaviour, type DragPanBehaviourOptions, DragShapeBehaviour, type DragShapeBehaviourOptions, ElementSizeLODBehaviour, type ElementSizeLODBehaviourOptions, EventEmitter, EventMap, EventSource, type IBehaviour, type ILayer, KeyboardCameraInputBehaviour, type KeyboardCameraInputBehaviourOptions, type KeyboardCameraKeymap, Layer, type LayerOptions, LayerRegistry, type LayerRegistryOptions, type LayersPanelCorner, LayersPanelLayer, type LayersPanelLayerCtorOptions, type LayersPanelLayerOptions, Layout, type LayoutEndReason, type LayoutEvents, type NumberOrGetter, PinchZoomBehaviour, type PinchZoomBehaviourOptions, PrimitivesRenderer, type RowOf, ScreenLayer, type ScreenLayerHit, SourceEmitter, type Store, type ThemedBackgroundKind, ThemedBackgroundLayer, type ThemedBackgroundLayerEvents, type ThemedBackgroundLayerOptions, type ThemedBackgroundMode, type ThemedBackgroundTheme, WheelZoomBehaviour, type WheelZoomBehaviourOptions, WorldLayer, type WorldLayerHit, assertSerialisableInDev, createLayerStore, findSerialisationViolations, loadIconFont, resolveNumberOrGetter };