@grafloria/element 0.3.18 → 0.3.20

package/src/libs/renderer/src/ext/public-api.js

@@ -0,0 +1,201 @@
+"use strict";
+/**
+ * ============================================================================
+ * Card 4 — the public reactive state API + imperative instance handle
+ * ============================================================================
+ *
+ * SCOPE, STATED PLAINLY. This card is a DOCUMENTED SURFACE, not a new engine.
+ * Waves 3/4 already shipped the machinery:
+ *
+ *   ViewportController    clientToWorld / worldToClient / zoomAtPoint /
+ *                         fitToBounds / onChange          (framework-free camera)
+ *   InteractionController the interaction brain
+ *   createDiagram()       the headless instance + its event bus
+ *
+ * What was missing was a NAMED, stable, semver'd surface over them. A host had to
+ * know that "screen → flow" is spelled `viewport.clientToWorld(x, y, rect)` and
+ * had to fetch the rect itself; that there is no `zoomTo`; that to observe the
+ * nodes you subscribe to a string-keyed event and re-read the model yourself; and
+ * that `getIntersectingNodes` — table stakes for a marquee or a drop target —
+ * simply did not exist anywhere.
+ *
+ * `createDiagramApi(instance)` is that surface. Everything here delegates; the
+ * only genuinely NEW logic is `getIntersectingNodes` (rect/rect overlap) and the
+ * selector-subscription plumbing.
+ *
+ * ---------------------------------------------------------------------------
+ * Reactivity WITHOUT a framework
+ * ---------------------------------------------------------------------------
+ * `subscribe(selector, listener)` is a pull-on-push store: on any relevant
+ * change we re-run the selector and notify ONLY if its value actually changed
+ * (`Object.is` on the projected value, with a shallow array compare — the
+ * selectors here all project arrays). That is what lets a React `useSyncExternal
+ * Store`, a Vue `ref`, or a Svelte store bind to it without re-rendering on every
+ * mousemove.
+ *
+ * Every subscribe() returns an unsubscribe, and `dispose()` drops the lot.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createDiagramApi = createDiagramApi;
+const tslib_1 = require("tslib");
+const disposable_1 = require("./disposable");
+/** World rect of a node, honouring group nesting. */
+function nodeRect(node) {
+    const p = typeof node.getWorldPosition === 'function' ? node.getWorldPosition() : node.position;
+    return { x: p.x, y: p.y, width: node.size.width, height: node.size.height };
+}
+const overlaps = (a, b) => a.x < b.x + b.width && a.x + a.width > b.x && a.y < b.y + b.height && a.y + a.height > b.y;
+const contains = (outer, inner) => inner.x >= outer.x &&
+    inner.y >= outer.y &&
+    inner.x + inner.width <= outer.x + outer.width &&
+    inner.y + inner.height <= outer.y + outer.height;
+/** Shallow equality — enough for the array projections these selectors produce. */
+function sameValue(a, b) {
+    if (Object.is(a, b))
+        return true;
+    if (Array.isArray(a) && Array.isArray(b)) {
+        if (a.length !== b.length)
+            return false;
+        for (let i = 0; i < a.length; i++)
+            if (!Object.is(a[i], b[i]))
+                return false;
+        return true;
+    }
+    return false;
+}
+function createDiagramApi(instance) {
+    const store = new disposable_1.DisposableStore();
+    const model = () => instance.getModel();
+    const engine = () => instance.getEngine();
+    const rect = () => instance.container.getBoundingClientRect();
+    const getNodes = () => model().getNodes();
+    const getEdges = () => model().getLinks();
+    const getSelectedNodes = () => model().getSelectedNodes();
+    const getSelectedEdges = () => model().getLinks().filter((l) => l.state === 'selected');
+    const getSnapshot = () => ({
+        nodes: getNodes(),
+        edges: getEdges(),
+        selectedNodes: getSelectedNodes(),
+        selectedEdges: getSelectedEdges(),
+        viewport: instance.viewport.getViewport(),
+        zoom: instance.viewport.getZoom(),
+    });
+    // -- the subscription hub ---------------------------------------------------
+    // ONE set of upstream listeners feeds every selector, so N subscribers cost one
+    // model subscription, not N.
+    const subscribers = new Set();
+    const notify = () => {
+        if (subscribers.size === 0)
+            return;
+        const snapshot = getSnapshot();
+        for (const sub of [...subscribers]) {
+            const next = sub.selector(snapshot);
+            if (sameValue(next, sub.last))
+                continue;
+            sub.last = next;
+            sub.listener(next);
+        }
+    };
+    for (const event of [
+        'nodes:change',
+        'edges:change',
+        'selection:change',
+        'viewport:change',
+    ]) {
+        store.add(instance.on(event, notify));
+    }
+    return {
+        getNodes,
+        getEdges,
+        getSelectedNodes,
+        getSelectedEdges,
+        getViewport: () => instance.viewport.getViewport(),
+        getZoom: () => instance.viewport.getZoom(),
+        getSnapshot,
+        subscribe(selector, listener) {
+            const sub = {
+                selector: selector,
+                listener: listener,
+                last: selector(getSnapshot()),
+            };
+            subscribers.add(sub);
+            return store.add(() => subscribers.delete(sub));
+        },
+        fitView: (padding) => instance.fitView(padding),
+        zoomTo(zoom) {
+            // About the viewport CENTRE — zooming about the world origin would fling
+            // the content off-screen whenever the camera is not at (0,0).
+            const before = instance.viewport.getViewport();
+            const cx = before.x + before.width / 2;
+            const cy = before.y + before.height / 2;
+            instance.viewport.setZoom(zoom);
+            const after = instance.viewport.getViewport();
+            instance.viewport.setViewport({
+                x: cx - after.width / 2,
+                y: cy - after.height / 2,
+                width: after.width,
+                height: after.height,
+            });
+            instance.render();
+        },
+        zoomIn(step = 1.2) {
+            this.zoomTo(instance.viewport.getZoom() * step);
+        },
+        zoomOut(step = 1.2) {
+            this.zoomTo(instance.viewport.getZoom() / step);
+        },
+        centerOn(point) {
+            const v = instance.viewport.getViewport();
+            instance.viewport.setViewport({
+                x: point.x - v.width / 2,
+                y: point.y - v.height / 2,
+                width: v.width,
+                height: v.height,
+            });
+            instance.render();
+        },
+        // The rect is fetched HERE. Making the caller pass it (as
+        // `ViewportController.clientToWorld` does) is the single most common way to
+        // get this wrong, because a stale rect silently offsets every conversion.
+        screenToFlow: (point) => instance.viewport.clientToWorld(point.x, point.y, rect()),
+        flowToScreen: (point) => instance.viewport.worldToClient(point.x, point.y, rect()),
+        getIntersectingNodes(target, options = {}) {
+            const { fully = false, visibleOnly = true } = options;
+            return getNodes().filter((node) => {
+                var _a;
+                if (visibleOnly && ((_a = node.state) === null || _a === void 0 ? void 0 : _a.visible) === false)
+                    return false;
+                const r = nodeRect(node);
+                return fully ? contains(target, r) : overlaps(target, r);
+            });
+        },
+        getNodeAt: (point) => { var _a; return (_a = model().getNodeAtPosition(point.x, point.y)) !== null && _a !== void 0 ? _a : null; },
+        // The engine's command stack is `engine.commandManager` (there is no
+        // `executeCommand` on DiagramEngine), and undo/redo are ASYNC. We surface
+        // them as promises rather than pretending they are synchronous — a caller
+        // that awaits gets a correct "the model has settled" signal.
+        execute(command) {
+            return tslib_1.__awaiter(this, void 0, void 0, function* () {
+                yield engine().commandManager.execute(command);
+                instance.render();
+            });
+        },
+        undo() {
+            return tslib_1.__awaiter(this, void 0, void 0, function* () {
+                yield engine().undo();
+                instance.render();
+            });
+        },
+        redo() {
+            return tslib_1.__awaiter(this, void 0, void 0, function* () {
+                yield engine().redo();
+                instance.render();
+            });
+        },
+        dispose: () => {
+            subscribers.clear();
+            store.dispose();
+        },
+    };
+}
+//# sourceMappingURL=public-api.js.map

package/src/libs/renderer/src/ext/registry-scope.d.ts

@@ -0,0 +1,93 @@
+/**
+ * ============================================================================
+ * The per-diagram REGISTRY PARTITION
+ * ============================================================================
+ *
+ * The renderer's contribution registries — shapes, named styles, link/label
+ * templates, markers, and the link pipeline — were module-scope `Map`s. One
+ * process, one vocabulary. Two diagrams on one page therefore could not disagree
+ * about what `badge` looks like, and worse, unloading one diagram's extension
+ * RESTORED the registry to its pre-registration state and silently stripped the
+ * shape out from under the diagram beside it.
+ *
+ * This module is the partition. It stores nothing about diagrams and knows
+ * nothing about shapes: it is a bag of named tables plus one ambient pointer at
+ * "whose tables are we reading right now".
+ *
+ * ---------------------------------------------------------------------------
+ * WHY AMBIENT (dynamic) SCOPE RATHER THAN A THREADED PARAMETER
+ * ---------------------------------------------------------------------------
+ * The obvious fix — pass the scope down to every read — does not survive contact
+ * with the read sites. Two of them are nowhere near an instance:
+ *
+ *   port-layout.ts  `shapeStrategy(input, args)` — the DEFAULT port layout, run
+ *                   per port per frame, three call frames below the last place
+ *                   instance identity existed (`SVGRenderer` → getPortPosition-
+ *                   ForShape → runPortLayout → shapeStrategy). It takes geometry
+ *                   and nothing else.
+ *   style-cascade.ts `resolveNodeStyle(node, theme, options)` — a free function
+ *                   whose only ambient argument is the theme.
+ *
+ * Threading a context through those means changing three layers of free-function
+ * signatures that exist precisely because they are pure geometry. Ambient scope
+ * costs one wrapper at the renderer's entry points and reaches all of them.
+ *
+ * THE SAFETY PROPERTY THAT MAKES THIS SOUND. A read that happens outside any
+ * activation falls back to the process-global registry — which is exactly what
+ * it did before this module existed. So the failure mode of a missed wrap point
+ * is "behaves like it always did", never "reads another diagram's table". The
+ * mechanism can only ever add isolation, never subtract correctness.
+ *
+ * IT IS SAFE AGAINST INTERLEAVING because activation spans a SYNCHRONOUS render
+ * pass on a single-threaded runtime, and it restores the previous scope in a
+ * `finally`. Nothing else can run in the middle of a frame. Deliberately, no
+ * WRITE path is ambient: an extension may register from a click handler or after
+ * an `await`, long outside any activation, so writes bind their scope EXPLICITLY
+ * at capability-construction time (see `diagram-registry.ts`).
+ */
+/** Table names. Constants rather than string literals so a typo cannot silently
+ * create a second, empty table that reads as "nothing registered". */
+export declare const SHAPES = "shapes";
+export declare const STYLES = "styles";
+export declare const LINK_TEMPLATES = "linkTemplates";
+export declare const LABEL_TEMPLATES = "labelTemplates";
+export declare const MARKERS = "markers";
+export declare const ANCHORS = "anchors";
+export declare const CONNECTION_POINTS = "connectionPoints";
+export declare const CONNECTORS = "connectors";
+/**
+ * One diagram's private overlay over the process-global registries.
+ *
+ * An entry here SHADOWS the global one of the same name for reads taken inside
+ * this scope; a name absent here falls through. That layering is what lets a
+ * diagram override a built-in (or an app-wide `registerShape()` at import time)
+ * for itself alone, without mutating what anybody else sees.
+ */
+export declare class RegistryScope {
+    private readonly tables;
+    /** The named table, created on demand. Use for WRITES. */
+    table<V>(name: string): Map<string, V>;
+    /** The named table if it exists, WITHOUT creating it. Use for READS. */
+    peek<V>(name: string): Map<string, V> | undefined;
+    /** True when this diagram has contributed nothing — i.e. it is pure fall-through. */
+    isEmpty(): boolean;
+    /** Drop every contribution (instance teardown). */
+    clear(): void;
+}
+/** The active scope, or null. Hosts should not need this; the registries do. */
+export declare function activeRegistryScope(): RegistryScope | null;
+/**
+ * The active scope's table for `name`, or undefined when there is no scope or it
+ * has no such table. THE READ HELPER every registry uses — deliberately one
+ * function so all of them shadow identically.
+ */
+export declare function scopedTable<V>(name: string): Map<string, V> | undefined;
+/**
+ * Run `fn` with `scope` active, restoring whatever was active before.
+ *
+ * An EMPTY scope is treated as no scope at all. That is not merely an
+ * optimisation: it keeps the hot read path for a diagram that contributed
+ * nothing — which is every existing embedder and all 104 demos — at exactly its
+ * previous cost, one null check with no Map lookup behind it.
+ */
+export declare function runInRegistryScope<T>(scope: RegistryScope | null | undefined, fn: () => T): T;

package/src/libs/renderer/src/ext/registry-scope.js

@@ -0,0 +1,142 @@
+"use strict";
+/**
+ * ============================================================================
+ * The per-diagram REGISTRY PARTITION
+ * ============================================================================
+ *
+ * The renderer's contribution registries — shapes, named styles, link/label
+ * templates, markers, and the link pipeline — were module-scope `Map`s. One
+ * process, one vocabulary. Two diagrams on one page therefore could not disagree
+ * about what `badge` looks like, and worse, unloading one diagram's extension
+ * RESTORED the registry to its pre-registration state and silently stripped the
+ * shape out from under the diagram beside it.
+ *
+ * This module is the partition. It stores nothing about diagrams and knows
+ * nothing about shapes: it is a bag of named tables plus one ambient pointer at
+ * "whose tables are we reading right now".
+ *
+ * ---------------------------------------------------------------------------
+ * WHY AMBIENT (dynamic) SCOPE RATHER THAN A THREADED PARAMETER
+ * ---------------------------------------------------------------------------
+ * The obvious fix — pass the scope down to every read — does not survive contact
+ * with the read sites. Two of them are nowhere near an instance:
+ *
+ *   port-layout.ts  `shapeStrategy(input, args)` — the DEFAULT port layout, run
+ *                   per port per frame, three call frames below the last place
+ *                   instance identity existed (`SVGRenderer` → getPortPosition-
+ *                   ForShape → runPortLayout → shapeStrategy). It takes geometry
+ *                   and nothing else.
+ *   style-cascade.ts `resolveNodeStyle(node, theme, options)` — a free function
+ *                   whose only ambient argument is the theme.
+ *
+ * Threading a context through those means changing three layers of free-function
+ * signatures that exist precisely because they are pure geometry. Ambient scope
+ * costs one wrapper at the renderer's entry points and reaches all of them.
+ *
+ * THE SAFETY PROPERTY THAT MAKES THIS SOUND. A read that happens outside any
+ * activation falls back to the process-global registry — which is exactly what
+ * it did before this module existed. So the failure mode of a missed wrap point
+ * is "behaves like it always did", never "reads another diagram's table". The
+ * mechanism can only ever add isolation, never subtract correctness.
+ *
+ * IT IS SAFE AGAINST INTERLEAVING because activation spans a SYNCHRONOUS render
+ * pass on a single-threaded runtime, and it restores the previous scope in a
+ * `finally`. Nothing else can run in the middle of a frame. Deliberately, no
+ * WRITE path is ambient: an extension may register from a click handler or after
+ * an `await`, long outside any activation, so writes bind their scope EXPLICITLY
+ * at capability-construction time (see `diagram-registry.ts`).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RegistryScope = exports.CONNECTORS = exports.CONNECTION_POINTS = exports.ANCHORS = exports.MARKERS = exports.LABEL_TEMPLATES = exports.LINK_TEMPLATES = exports.STYLES = exports.SHAPES = void 0;
+exports.activeRegistryScope = activeRegistryScope;
+exports.scopedTable = scopedTable;
+exports.runInRegistryScope = runInRegistryScope;
+/** Table names. Constants rather than string literals so a typo cannot silently
+ * create a second, empty table that reads as "nothing registered". */
+exports.SHAPES = 'shapes';
+exports.STYLES = 'styles';
+exports.LINK_TEMPLATES = 'linkTemplates';
+exports.LABEL_TEMPLATES = 'labelTemplates';
+exports.MARKERS = 'markers';
+exports.ANCHORS = 'anchors';
+exports.CONNECTION_POINTS = 'connectionPoints';
+exports.CONNECTORS = 'connectors';
+/**
+ * One diagram's private overlay over the process-global registries.
+ *
+ * An entry here SHADOWS the global one of the same name for reads taken inside
+ * this scope; a name absent here falls through. That layering is what lets a
+ * diagram override a built-in (or an app-wide `registerShape()` at import time)
+ * for itself alone, without mutating what anybody else sees.
+ */
+class RegistryScope {
+    constructor() {
+        this.tables = new Map();
+    }
+    /** The named table, created on demand. Use for WRITES. */
+    table(name) {
+        let table = this.tables.get(name);
+        if (!table) {
+            table = new Map();
+            this.tables.set(name, table);
+        }
+        return table;
+    }
+    /** The named table if it exists, WITHOUT creating it. Use for READS. */
+    peek(name) {
+        return this.tables.get(name);
+    }
+    /** True when this diagram has contributed nothing — i.e. it is pure fall-through. */
+    isEmpty() {
+        for (const table of this.tables.values()) {
+            if (table.size > 0)
+                return false;
+        }
+        return true;
+    }
+    /** Drop every contribution (instance teardown). */
+    clear() {
+        this.tables.clear();
+    }
+}
+exports.RegistryScope = RegistryScope;
+/**
+ * The scope reads resolve against right now. `null` means "the process-global
+ * registries", which is both the default and the pre-existing behaviour.
+ */
+let active = null;
+/** The active scope, or null. Hosts should not need this; the registries do. */
+function activeRegistryScope() {
+    return active;
+}
+/**
+ * The active scope's table for `name`, or undefined when there is no scope or it
+ * has no such table. THE READ HELPER every registry uses — deliberately one
+ * function so all of them shadow identically.
+ */
+function scopedTable(name) {
+    return active === null ? undefined : active.peek(name);
+}
+/**
+ * Run `fn` with `scope` active, restoring whatever was active before.
+ *
+ * An EMPTY scope is treated as no scope at all. That is not merely an
+ * optimisation: it keeps the hot read path for a diagram that contributed
+ * nothing — which is every existing embedder and all 104 demos — at exactly its
+ * previous cost, one null check with no Map lookup behind it.
+ */
+function runInRegistryScope(scope, fn) {
+    const next = scope && !scope.isEmpty() ? scope : null;
+    // Re-entrancy (export → render) is common and must not pay for a try/finally.
+    if (next === active)
+        return fn();
+    const previous = active;
+    active = next;
+    try {
+        return fn();
+    }
+    finally {
+        active = previous;
+    }
+}
+//# sourceMappingURL=registry-scope.js.map

package/src/libs/renderer/src/ext/tools.d.ts

@@ -0,0 +1,164 @@
+/**
+ * ============================================================================
+ * Card 5 — overridable interaction tools + connection validation
+ * ============================================================================
+ *
+ * SCOPE, STATED PLAINLY. Wave 2 shipped a `ToolManager` that already arbitrates
+ * gestures (one active tool per gesture, movement threshold, DELIBERATE gating)
+ * — but it lives in `libs/renderer-angular`, and the framework-free
+ * `DomEventBinder` in `libs/renderer` REIMPLEMENTS the same two rules rather
+ * than sharing it. The brief said "make those pluggable, don't rewrite them",
+ * and rewriting either one is out of scope for this wave.
+ *
+ * So this ships the REGISTRY and the VALIDATION hook — the two things that were
+ * genuinely absent — and the binder consults them:
+ *
+ *   1. A TOOL REGISTRY. The five gesture tools stop being privileged code paths
+ *      and become named registrations that a host can REPLACE. A registered tool
+ *      gets first refusal on a gesture (`hitTest` → `onPointerDown`); if no tool
+ *      claims it, the built-in ladder runs exactly as before. This is additive:
+ *      with no tools registered, behaviour is byte-identical.
+ *
+ *   2. `isValidConnection`. The engine could only veto a connection through
+ *      hardcoded rules (port type + `maxConnections` on `PortModel.canConnectTo`);
+ *      a HOST had no way to inject "an Order may not connect to an Invoice".
+ *      Validators registered here are consulted wherever the renderer offers a
+ *      connection — and ALL must pass.
+ *
+ * NOTE ON OWNERSHIP: `wave6/ports` owns port internals and the engine's
+ * connection-validation internals. This registry therefore lives in the
+ * RENDERER's extension layer and is consumed at the renderer's own seams; it
+ * does NOT reach into `PortModel.canConnectTo` or `ConnectionStateManager`.
+ * If that sibling promotes a validation hook in the engine, this becomes a thin
+ * forwarder to it.
+ */
+import type { LinkModel, NodeModel, PortModel } from '@grafloria/engine';
+import type { Disposer } from './disposable';
+/** Everything a validator needs to judge a proposed connection. */
+export interface ConnectionCandidate {
+    sourceNode: NodeModel;
+    sourcePort: PortModel | null;
+    targetNode: NodeModel;
+    targetPort: PortModel | null;
+    /** Present when RECONNECTING an existing link rather than drawing a new one. */
+    link?: LinkModel;
+}
+/** Return false (or a reason string) to veto. */
+export type ConnectionValidator = (candidate: ConnectionCandidate) => boolean | string;
+/**
+ * Register a connection validator. ALL registered validators must pass for a
+ * connection to be offered — veto power, not voting power, because a rule that
+ * can be outvoted is not a rule.
+ */
+export declare function registerConnectionValidator(validator: ConnectionValidator): Disposer;
+export interface ConnectionValidity {
+    valid: boolean;
+    /** The first veto's reason, when it gave one. */
+    reason?: string;
+}
+/**
+ * Evaluate every registered validator. This is the public `isValidConnection`
+ * hook. With no validators registered it is `{ valid: true }` — i.e. free.
+ */
+export declare function isValidConnection(candidate: ConnectionCandidate): ConnectionValidity;
+/** How many validators are live (tests assert this returns to 0 after dispose). */
+export declare function connectionValidatorCount(): number;
+export declare function clearConnectionValidators(): void;
+/** The built-in gesture tools, by name. A registration may REPLACE any of them. */
+export type BuiltinToolId = 'select' | 'node-drag' | 'link-draw' | 'marquee' | 'pan';
+export type ToolId = BuiltinToolId | (string & {});
+export interface ToolModifiers {
+    shift: boolean;
+    ctrl: boolean;
+    alt: boolean;
+    meta: boolean;
+}
+/** A pointer gesture event, in both coordinate spaces. */
+export interface ToolPointerEvent {
+    type: 'down' | 'move' | 'up' | 'cancel';
+    /** World-space (camera applied). */
+    world: {
+        x: number;
+        y: number;
+    };
+    /** Element-local CSS px — the drag threshold is measured here. */
+    screen: {
+        x: number;
+        y: number;
+    };
+    modifiers: ToolModifiers;
+    /** The original DOM event, when there was one. */
+    source?: PointerEvent | MouseEvent;
+}
+/** What the gesture landed on, resolved once on pointerdown. */
+export interface ToolHitContext {
+    node?: NodeModel;
+    link?: LinkModel;
+    port?: PortModel;
+    /** True when the pointer went down on empty canvas. */
+    empty: boolean;
+    /** Was the hit node already selected BEFORE this gesture? (DELIBERATE mode). */
+    nodeWasSelected?: boolean;
+}
+/**
+ * A canvas tool. `hitTest` is the claim: return true on pointerdown and this
+ * tool OWNS the whole gesture (move/up/cancel) — no other tool, and none of the
+ * built-in ladder, will see it.
+ */
+export interface CanvasTool {
+    readonly id: ToolId;
+    /**
+     * Higher wins when several tools claim the same gesture. Built-in-replacing
+     * tools should use a priority > 0; the built-in ladder is effectively 0.
+     *
+     * See the ARBITRATION CONTRACT on {@link registerTool} — in particular: a
+     * missing priority defaults to 1, and a TIE resolves by registration order,
+     * which no tool should rely on.
+     */
+    readonly priority?: number;
+    /** Claim this gesture? */
+    hitTest(event: ToolPointerEvent, hit: ToolHitContext): boolean;
+    onPointerDown?(event: ToolPointerEvent, hit: ToolHitContext): void;
+    onPointerMove?(event: ToolPointerEvent, hit: ToolHitContext): void;
+    onPointerUp?(event: ToolPointerEvent, hit: ToolHitContext): void;
+    onCancel?(): void;
+    /** Called when the tool is unregistered while active. */
+    dispose?(): void;
+}
+/**
+ * Register (or replace) a canvas tool. Returns a disposer that RESTORES the
+ * previous tool of the same id — so overriding `'node-drag'` and then unloading
+ * the extension gives the original back rather than leaving a hole.
+ *
+ * ## The arbitration contract (wave14, defect 2)
+ *
+ * On every pointerdown, {@link resolveTool} asks EVERY registered tool
+ * `hitTest(event, hit)` and the gesture goes to the claiming tool with the
+ * HIGHEST `priority` (default 1; the built-in ladder is effectively 0). Ties
+ * resolve by registration order — first registered wins — and that is a
+ * fallback, NOT a contract: tools composed from different waves and extensions
+ * register in an order nobody designed. A tool that can ever be active at the
+ * same time as another MUST state an explicit priority.
+ *
+ * Choosing one: a POINT-SPECIFIC claim (hitTest inspects the point — "is there
+ * ink under the pointer?") should outrank a POINT-AGNOSTIC mode claim (hitTest
+ * is just "am I active?"), because the specific tool only fires where it means
+ * to and would otherwise be starved by the broad one everywhere it matters.
+ * The whiteboard tools are the worked example: draw/rectangle/eraser sit at
+ * `WHITEBOARD_MODE_TOOL_PRIORITY` (1), the ink-hit-only StrokeEditTool at
+ * `WHITEBOARD_INK_TOOL_PRIORITY` (2) — see whiteboard-tools.ts.
+ */
+export declare function registerTool(tool: CanvasTool): Disposer;
+export declare function getTool(id: string): CanvasTool | undefined;
+export declare function hasTool(id: string): boolean;
+export declare function listTools(): string[];
+export declare function clearTools(): void;
+/**
+ * The tool (if any) that claims this gesture, highest priority first (ties:
+ * first registered — see the arbitration contract on {@link registerTool}).
+ *
+ * The DomEventBinder calls this FIRST on pointerdown. `undefined` means "no
+ * registered tool wants it" — and then the built-in ladder runs untouched, which
+ * is why adding this seam changed no existing behaviour.
+ */
+export declare function resolveTool(event: ToolPointerEvent, hit: ToolHitContext): CanvasTool | undefined;