synabun 1.3.0 → 2.0.0

package/mcp-server/dist/services/vector-cache.d.ts

@@ -0,0 +1,68 @@
+/**
+ * In-memory vector cache for similarity search.
+ *
+ * Holds all row vectors of one table in a single contiguous Float32Array
+ * matrix (~14MB for 9k memories at 384 dims), so a search is one dot-product
+ * sweep instead of a full-table scan with per-row BLOB decode.
+ *
+ * Coherence model:
+ * - Same-process writes patch the cache incrementally via set()/remove(),
+ *   or call invalidate() for bulk operations.
+ * - Cross-process writes are detected with `PRAGMA data_version`, which
+ *   changes whenever ANOTHER connection commits to the database file.
+ *   On change the cache fully reloads (one scan, amortized across queries).
+ */
+import type { DatabaseSync } from 'node:sqlite';
+interface TopKResult {
+    id: string;
+    score: number;
+}
+export declare class VectorCache {
+    private getDb;
+    private loadSql;
+    private getVectorSql;
+    private entity?;
+    private ids;
+    private rowIndexById;
+    private matrix;
+    private dim;
+    private count;
+    private capacity;
+    private loaded;
+    private lastDataVersion;
+    private lastSequence;
+    private refreshing;
+    reloadCount: number;
+    private connection;
+    constructor(getDb: () => DatabaseSync, loadSql: string, // must select (id, vector)
+    getVectorSql: string, // must select (vector) by id = ?
+    entity?: string | undefined);
+    /** Drop everything; next query reloads from the database. */
+    invalidate(): void;
+    private dataVersion;
+    private ensureFresh;
+    private reload;
+    private grow;
+    /**
+     * Reclaim backing memory after deletions. grow() only ever doubles capacity,
+     * so a long-lived process with churn (add then delete) keeps the matrix sized
+     * to its historical peak. When utilization drops below 25% of a non-trivial
+     * capacity, reallocate down to ~2x count so the freed slots return to the heap.
+     */
+    private maybeShrink;
+    /** Insert or replace a row's vector (same-process write hook). */
+    set(id: string, vector: number[] | Float32Array): void;
+    /** Re-add a row by reading its vector back from the database. */
+    setFromDb(id: string): void;
+    /** Remove a row (swap-with-last keeps the matrix dense). */
+    remove(id: string): void;
+    /**
+     * Score all (or a filtered subset of) rows against the query vector and
+     * return the top K above the threshold, sorted by score descending.
+     * Vectors are unit-length, so the dot product IS the cosine similarity.
+     */
+    topK(query: number[] | Float32Array, k: number, threshold: number, allowedIds?: Set<string>): TopKResult[];
+    size(): number;
+}
+export {};
+//# sourceMappingURL=vector-cache.d.ts.map

package/mcp-server/dist/services/vector-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vector-cache.d.ts","sourceRoot":"","sources":["../../src/services/vector-cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD,UAAU,UAAU;IAClB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;CACf;AAED,qBAAa,WAAW;IAepB,OAAO,CAAC,KAAK;IACb,OAAO,CAAC,OAAO;IACf,OAAO,CAAC,YAAY;IACpB,OAAO,CAAC,MAAM,CAAC;IAjBjB,OAAO,CAAC,GAAG,CAAgB;IAC3B,OAAO,CAAC,YAAY,CAA6B;IACjD,OAAO,CAAC,MAAM,CAAqC;IACnD,OAAO,CAAC,GAAG,CAAK;IAChB,OAAO,CAAC,KAAK,CAAK;IAClB,OAAO,CAAC,QAAQ,CAAK;IACrB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,eAAe,CAAM;IAC7B,OAAO,CAAC,YAAY,CAAM;IAC1B,OAAO,CAAC,UAAU,CAAS;IACpB,WAAW,SAAK;IACvB,OAAO,CAAC,UAAU,CAA6B;gBAGrC,KAAK,EAAE,MAAM,YAAY,EACzB,OAAO,EAAE,MAAM,EAAE,2BAA2B;IAC5C,YAAY,EAAE,MAAM,EAAE,iCAAiC;IACvD,MAAM,CAAC,EAAE,MAAM,YAAA;IAGzB,6DAA6D;IAC7D,UAAU,IAAI,IAAI;IAYlB,OAAO,CAAC,WAAW;IAKnB,OAAO,CAAC,WAAW;IA2BnB,OAAO,CAAC,MAAM;IAkCd,OAAO,CAAC,IAAI;IAOZ;;;;;OAKG;IACH,OAAO,CAAC,WAAW;IAWnB,kEAAkE;IAClE,GAAG,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,YAAY,GAAG,IAAI;IAmBtD,iEAAiE;IACjE,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAY3B,4DAA4D;IAC5D,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAkBxB;;;;OAIG;IACH,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,YAAY,EAAE,CAAC,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,UAAU,EAAE;IA+C1G,IAAI,IAAI,MAAM;CAIf"}

package/mcp-server/dist/services/vector-cache.js

@@ -0,0 +1,271 @@
+/**
+ * In-memory vector cache for similarity search.
+ *
+ * Holds all row vectors of one table in a single contiguous Float32Array
+ * matrix (~14MB for 9k memories at 384 dims), so a search is one dot-product
+ * sweep instead of a full-table scan with per-row BLOB decode.
+ *
+ * Coherence model:
+ * - Same-process writes patch the cache incrementally via set()/remove(),
+ *   or call invalidate() for bulk operations.
+ * - Cross-process writes are detected with `PRAGMA data_version`, which
+ *   changes whenever ANOTHER connection commits to the database file.
+ *   On change the cache fully reloads (one scan, amortized across queries).
+ */
+export class VectorCache {
+    getDb;
+    loadSql;
+    getVectorSql;
+    entity;
+    ids = [];
+    rowIndexById = new Map();
+    matrix = new Float32Array(0);
+    dim = 0;
+    count = 0;
+    capacity = 0;
+    loaded = false;
+    lastDataVersion = -1;
+    lastSequence = -1;
+    refreshing = false;
+    reloadCount = 0;
+    connection = null;
+    constructor(getDb, loadSql, // must select (id, vector)
+    getVectorSql, // must select (vector) by id = ?
+    entity) {
+        this.getDb = getDb;
+        this.loadSql = loadSql;
+        this.getVectorSql = getVectorSql;
+        this.entity = entity;
+    }
+    /** Drop everything; next query reloads from the database. */
+    invalidate() {
+        this.loaded = false;
+        this.ids = [];
+        this.rowIndexById.clear();
+        this.matrix = new Float32Array(0);
+        this.count = 0;
+        this.capacity = 0;
+        this.dim = 0;
+        this.lastDataVersion = -1;
+        this.lastSequence = -1;
+    }
+    dataVersion() {
+        const row = this.getDb().prepare('PRAGMA data_version').get();
+        return row.data_version;
+    }
+    ensureFresh() {
+        if (this.refreshing)
+            return;
+        const connection = this.getDb();
+        if (connection !== this.connection) {
+            this.invalidate();
+            this.connection = connection;
+        }
+        if (this.entity && this.loaded) {
+            this.refreshing = true;
+            try {
+                const rows = this.getDb().prepare('SELECT seq,id FROM memory_changes WHERE entity=? AND seq>? ORDER BY seq LIMIT 2049')
+                    .all(this.entity, this.lastSequence);
+                if (rows.length > 2048) {
+                    this.reload();
+                    return;
+                }
+                for (const id of new Set(rows.map(r => r.id))) {
+                    this.remove(id);
+                    this.setFromDb(id);
+                }
+                if (rows.length)
+                    this.lastSequence = rows[rows.length - 1].seq;
+                return;
+            }
+            finally {
+                this.refreshing = false;
+            }
+        }
+        if (this.loaded) {
+            // data_version only changes when another connection commits —
+            // our own writes are already applied incrementally.
+            const v = this.dataVersion();
+            if (v === this.lastDataVersion)
+                return;
+        }
+        this.reload();
+    }
+    reload() {
+        this.reloadCount++;
+        // Read the watermark BEFORE the rows. A concurrent commit will then be
+        // replayed on the next call instead of accidentally marked as observed.
+        if (this.entity)
+            this.lastSequence = Number(this.getDb().prepare('SELECT COALESCE(MAX(seq),0) AS seq FROM memory_changes WHERE entity=?').get(this.entity).seq);
+        const rows = this.getDb().prepare(this.loadSql).all();
+        this.ids = [];
+        this.rowIndexById.clear();
+        this.count = 0;
+        // Establish dimensions from the first valid row
+        this.dim = 0;
+        for (const row of rows) {
+            if (row.vector && row.vector.byteLength >= 4) {
+                this.dim = row.vector.byteLength / 4;
+                break;
+            }
+        }
+        this.capacity = Math.max(rows.length, 64);
+        this.matrix = new Float32Array(this.capacity * Math.max(this.dim, 1));
+        for (const row of rows) {
+            if (!row.vector || row.vector.byteLength !== this.dim * 4)
+                continue; // skip malformed
+            const vec = new Float32Array(row.vector.buffer, row.vector.byteOffset, this.dim);
+            this.matrix.set(vec, this.count * this.dim);
+            this.rowIndexById.set(row.id, this.count);
+            this.ids.push(row.id);
+            this.count++;
+        }
+        this.lastDataVersion = this.dataVersion();
+        this.loaded = true;
+    }
+    grow() {
+        this.capacity = Math.max(this.capacity * 2, 64);
+        const next = new Float32Array(this.capacity * Math.max(this.dim, 1));
+        next.set(this.matrix.subarray(0, this.count * this.dim));
+        this.matrix = next;
+    }
+    /**
+     * Reclaim backing memory after deletions. grow() only ever doubles capacity,
+     * so a long-lived process with churn (add then delete) keeps the matrix sized
+     * to its historical peak. When utilization drops below 25% of a non-trivial
+     * capacity, reallocate down to ~2x count so the freed slots return to the heap.
+     */
+    maybeShrink() {
+        if (this.capacity <= 64 || this.dim === 0)
+            return;
+        if (this.count >= this.capacity / 4)
+            return;
+        const nextCap = Math.max(this.count * 2, 64);
+        if (nextCap >= this.capacity)
+            return;
+        const next = new Float32Array(nextCap * this.dim);
+        next.set(this.matrix.subarray(0, this.count * this.dim));
+        this.matrix = next;
+        this.capacity = nextCap;
+    }
+    /** Insert or replace a row's vector (same-process write hook). */
+    set(id, vector) {
+        if (!this.loaded)
+            return; // nothing cached yet — next query loads fresh
+        if (this.dim === 0) {
+            this.dim = vector.length;
+            this.matrix = new Float32Array(this.capacity * this.dim);
+        }
+        if (vector.length !== this.dim) {
+            this.invalidate();
+            return;
+        }
+        let idx = this.rowIndexById.get(id);
+        if (idx === undefined) {
+            if (this.count >= this.capacity)
+                this.grow();
+            idx = this.count;
+            this.rowIndexById.set(id, idx);
+            this.ids.push(id);
+            this.count++;
+        }
+        this.matrix.set(vector instanceof Float32Array ? vector : new Float32Array(vector), idx * this.dim);
+    }
+    /** Re-add a row by reading its vector back from the database. */
+    setFromDb(id) {
+        if (!this.loaded)
+            return;
+        try {
+            const row = this.getDb().prepare(this.getVectorSql).get(id);
+            if (!row?.vector)
+                return;
+            const vec = new Float32Array(row.vector.buffer, row.vector.byteOffset, row.vector.byteLength / 4);
+            this.set(id, vec);
+        }
+        catch {
+            this.invalidate();
+        }
+    }
+    /** Remove a row (swap-with-last keeps the matrix dense). */
+    remove(id) {
+        if (!this.loaded)
+            return;
+        const idx = this.rowIndexById.get(id);
+        if (idx === undefined)
+            return;
+        const last = this.count - 1;
+        if (idx !== last) {
+            this.matrix.copyWithin(idx * this.dim, last * this.dim, (last + 1) * this.dim);
+            const movedId = this.ids[last];
+            this.ids[idx] = movedId;
+            this.rowIndexById.set(movedId, idx);
+        }
+        this.ids.pop();
+        this.rowIndexById.delete(id);
+        this.count--;
+        this.maybeShrink();
+    }
+    /**
+     * Score all (or a filtered subset of) rows against the query vector and
+     * return the top K above the threshold, sorted by score descending.
+     * Vectors are unit-length, so the dot product IS the cosine similarity.
+     */
+    topK(query, k, threshold, allowedIds) {
+        this.ensureFresh();
+        if (this.count === 0 || this.dim === 0)
+            return [];
+        const q = query instanceof Float32Array ? query : new Float32Array(query);
+        if (q.length !== this.dim || !q.every(Number.isFinite) || k < 1)
+            return [];
+        const dim = this.dim;
+        const m = this.matrix;
+        const hits = [];
+        const selected = allowedIds && allowedIds.size < this.count / 2
+            ? [...allowedIds].map(id => this.rowIndexById.get(id)).filter((r) => r !== undefined) : undefined;
+        for (let index = 0; index < (selected?.length ?? this.count); index++) {
+            const r = selected ? selected[index] : index;
+            if (allowedIds && !allowedIds.has(this.ids[r]))
+                continue;
+            const base = r * dim;
+            let dot = 0;
+            for (let i = 0; i < dim; i++)
+                dot += q[i] * m[base + i];
+            if (dot < threshold)
+                continue;
+            const hit = { id: this.ids[r], score: dot };
+            if (hits.length < k) {
+                hits.push(hit);
+                let i = hits.length - 1;
+                while (i > 0) {
+                    const parent = (i - 1) >> 1;
+                    if (hits[parent].score <= hits[i].score)
+                        break;
+                    [hits[parent], hits[i]] = [hits[i], hits[parent]];
+                    i = parent;
+                }
+            }
+            else if (dot > hits[0].score) {
+                hits[0] = hit;
+                let i = 0;
+                while (true) {
+                    let child = i * 2 + 1;
+                    if (child >= hits.length)
+                        break;
+                    if (child + 1 < hits.length && hits[child + 1].score < hits[child].score)
+                        child++;
+                    if (hits[i].score <= hits[child].score)
+                        break;
+                    [hits[i], hits[child]] = [hits[child], hits[i]];
+                    i = child;
+                }
+            }
+        }
+        hits.sort((a, b) => b.score - a.score);
+        return hits.length > k ? hits.slice(0, k) : hits;
+    }
+    size() {
+        this.ensureFresh();
+        return this.count;
+    }
+}
+//# sourceMappingURL=vector-cache.js.map

package/mcp-server/dist/services/vector-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vector-cache.js","sourceRoot":"","sources":["../../src/services/vector-cache.ts"],"names":[],"mappings":"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"}

package/mcp-server/dist/services/whiteboard-geometry.d.ts

@@ -0,0 +1,305 @@
+/**
+ * Pure whiteboard geometry shared by the MCP whiteboard tools and the Neural
+ * Interface server (`server.js` imports the compiled
+ * `dist/services/whiteboard-geometry.js`).
+ *
+ * Everything here mirrors client-side math in
+ * `neural-interface/public/shared/ui-whiteboard.js`:
+ *   - `anchorPoint`        <- `getAnchorPoint`
+ *   - `resolveArrowPoints` <- the anchor block at the top of `renderArrows`
+ *   - `SECTION_DEFAULTS`   <- `SECTION_TYPES`
+ *   - `ANCHOR_FALLBACK`    <- the `el.width || 100` / `el.height || 60` fallbacks
+ * Keep both sides in sync: a change on either side moves where arrows land.
+ *
+ * Constraints: no imports, no I/O, no Node APIs, no module side effects.
+ */
+/** `[x, y]` in whiteboard pixel space. */
+export type WbPoint = [number, number];
+/** Browser-reported drawing area. Offsets are the navbar/toolbar insets. */
+export interface WbViewport {
+    width: number;
+    height: number;
+    xOffset?: number;
+    yOffset?: number;
+}
+/** Axis-aligned box in whiteboard pixel space. */
+export interface WbRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** Persisted whiteboard element — the union of every element type's fields. */
+export interface WbElement {
+    id: string;
+    type: string;
+    x?: number;
+    y?: number;
+    width?: number;
+    height?: number;
+    content?: string;
+    items?: string[];
+    ordered?: boolean;
+    fontSize?: number;
+    color?: string;
+    bold?: boolean;
+    italic?: boolean;
+    shape?: string;
+    points?: WbPoint[];
+    pathD?: string;
+    startAnchor?: string | null;
+    endAnchor?: string | null;
+    strokeWidth?: number;
+    rotation?: number;
+    zIndex?: number;
+    dataUrl?: string;
+    dataUrlBytes?: number;
+    url?: string;
+    sectionType?: string;
+    label?: string;
+    measured?: boolean;
+    estimated?: boolean;
+    [key: string]: unknown;
+}
+/** Per-section-type defaults; identical to the client `SECTION_TYPES` table. */
+export interface WbSectionDefault {
+    w: number;
+    h: number;
+    color: string;
+    label: string;
+    icon: string;
+}
+/** Element lookup used to resolve arrow anchors: a Map or a lookup function. */
+export type WbElementLookup = Map<string, WbElement> | ((id: string) => WbElement | undefined);
+/** Positive pixel amounts by which a box exceeds a rect, per side (only sides that overflow). */
+export interface WbSideAmounts {
+    left?: number;
+    right?: number;
+    top?: number;
+    bottom?: number;
+}
+/** Options for `analyzeWhiteboard`. */
+export interface WbAnalyzeOptions {
+    focusIds?: string[];
+    maxOverlaps?: number;
+    maxOverflow?: number;
+}
+/** Result of `analyzeWhiteboard`. */
+export interface WbAnalysis {
+    usable: WbRect;
+    /** Union of all element boxes; pct of usable. */
+    bounds: (WbRect & {
+        pctWidth: number;
+        pctHeight: number;
+    }) | null;
+    overflow: {
+        id: string;
+        type: string;
+        severity: 'partial' | 'outside';
+        by: WbSideAmounts;
+    }[];
+    overflowTotal: number;
+    overlaps: {
+        a: string;
+        b: string;
+        aType: string;
+        bType: string;
+        intersection: {
+            width: number;
+            height: number;
+            area: number;
+        };
+        pctOfSmaller: number;
+    }[];
+    overlapsTotal: number;
+    overlapsTruncated: boolean;
+    containment: {
+        section: string;
+        label: string;
+        children: string[];
+        spills: {
+            id: string;
+            by: WbSideAmounts;
+        }[];
+    }[];
+    unparented: string[];
+    estimatedCount: number;
+    notes: string[];
+}
+/** Viewport assumed until the browser reports one (server.js default). */
+export declare const DEFAULT_VIEWPORT: Readonly<Required<WbViewport>>;
+/** Size given to a shape that arrives without one. */
+export declare const SHAPE_DEFAULT: Readonly<{
+    width: number;
+    height: number;
+}>;
+/** Size the client assumes for anchor targets without a (truthy) width/height. */
+export declare const ANCHOR_FALLBACK: Readonly<{
+    width: number;
+    height: number;
+}>;
+/** Shape variants accepted by `shape` elements. */
+export declare const SHAPE_TYPES: readonly ["rect", "pill", "circle", "triangle", "drawn-circle"];
+/** The 12 section types, in the client's menu order. */
+export declare const SECTION_TYPE_NAMES: readonly ["navbar", "hero", "sidebar", "content", "footer", "card", "form", "image-placeholder", "button", "text-block", "grid", "modal"];
+/** One of `SECTION_TYPE_NAMES`. */
+export type WbSectionTypeName = typeof SECTION_TYPE_NAMES[number];
+/** Every persisted element type. */
+export declare const ELEMENT_TYPES: readonly ["text", "list", "shape", "arrow", "pen", "image", "section"];
+/** Section defaults keyed by section type — same 12 entries and values as the client. */
+export declare const SECTION_DEFAULTS: Record<string, WbSectionDefault>;
+/**
+ * The drawable area as a rect: `{ x: xOffset||0, y: yOffset||0, width, height }`.
+ * Missing/invalid dimensions fall back to `DEFAULT_VIEWPORT`.
+ */
+export declare function usableRect(vp: WbViewport | null | undefined): WbRect;
+/**
+ * Estimate the rendered size of a text element before the browser measures it.
+ * JetBrains Mono advance is ~0.6em; `.wb-text` has 10px/14px padding, a 1px
+ * border and line-height 1.35. Empty content is sized like the 12-character
+ * "Type here..." placeholder. Characters are counted as code points.
+ */
+export declare function estimateTextSize(content: string | undefined, fontSize?: number): {
+    width: number;
+    height: number;
+};
+/**
+ * Estimate the rendered size of a list element before the browser measures it.
+ * Same font metrics as text, plus the 1.4em bullet indent; line-height 1.5.
+ */
+export declare function estimateListSize(items: string[] | undefined, fontSize?: number): {
+    width: number;
+    height: number;
+};
+/**
+ * Fill in missing geometry on an element in place and return the reasons applied.
+ *
+ * - text/list: re-estimated (`estimated: true`, `measured` removed) when forced,
+ *   not yet measured by the browser, or missing a dimension -> 'size:estimated'.
+ *   Browser-measured elements (`measured: true`) are left alone unless `force`.
+ * - shape: missing/non-positive width/height -> `SHAPE_DEFAULT` -> 'size:shape-default'.
+ * - section: unknown/missing `sectionType` -> 'content' -> 'section:type-default';
+ *   missing width/height/color/label filled from `SECTION_DEFAULTS`
+ *   -> 'size:section-default' when a dimension was filled.
+ * - image: missing width/height -> 'image:no-size' (nothing changed).
+ * - arrow/pen: untouched.
+ */
+export declare function ensureElementGeometry(el: WbElement, opts?: {
+    force?: boolean;
+}): string[];
+/**
+ * Exact port of the client `getAnchorPoint`: the point where a ray from the
+ * target's centre towards `(fromX, fromY)` leaves the target's box. Uses the
+ * client's `width || 100` / `height || 60` fallbacks (so 0 falls back too).
+ * Returns null for a missing target, an arrow target, or (unlike the client,
+ * which would yield NaN) non-finite coordinates.
+ */
+export declare function anchorPoint(target: WbElement | undefined | null, fromX: number, fromY: number): {
+    x: number;
+    y: number;
+} | null;
+/**
+ * Copy of `arrow.points` with anchored endpoints snapped to their targets,
+ * in the same order as the client `renderArrows`: the start endpoint is
+ * resolved first from `pts[1]`, then the end endpoint from `pts[len - 2]`.
+ * With 3+ points both neighbours are raw; with exactly 2 points the end is
+ * resolved from the already-resolved start, exactly as the client draws it.
+ * Unresolvable anchors (missing target, arrow target) keep the raw point.
+ * The input array is never mutated.
+ */
+export declare function resolveArrowPoints(arrow: WbElement, byId?: WbElementLookup): WbPoint[];
+/** Bounding box of a point list (non-finite points ignored); null when there is nothing to bound. */
+export declare function pointsBounds(points: WbPoint[] | undefined | null): WbRect | null;
+/**
+ * Axis-aligned box of an element. Rotation is ignored.
+ * - text/list: stored size, estimated when missing.
+ * - shape: stored size or `SHAPE_DEFAULT`.
+ * - section: stored size or the `SECTION_DEFAULTS` entry for its type ('content' when unknown).
+ * - image: stored size or 0x0.
+ * - arrow: bounds of `resolveArrowPoints` (anchors resolved through `byId` when given).
+ * - pen: bounds of its points.
+ * Returns null when x/y are not finite (boxed types), when there are no points
+ * (arrow/pen), or for an unknown type.
+ */
+export declare function elementBox(el: WbElement, byId?: WbElementLookup): WbRect | null;
+/** Centre of `elementBox`, or null when the element has no box. */
+export declare function elementCenter(el: WbElement, byId?: WbElementLookup): {
+    x: number;
+    y: number;
+} | null;
+/**
+ * Keep a box inside `rect` (same math as the server's add-element clamp):
+ * pull back from the right/bottom edges first, then off the left/top edges.
+ * A box larger than the rect ends up aligned to the rect's left/top.
+ */
+export declare function clampBoxToRect(box: WbRect, rect: WbRect): {
+    x: number;
+    y: number;
+    reasons: string[];
+};
+/**
+ * Translate a point list so the bbox of the points NOT in `skipIdx` (typically
+ * anchored endpoints, which get re-snapped anyway) fits inside `rect`. When
+ * every index is skipped the bbox covers all points. A bbox wider/taller than
+ * the rect is aligned to the rect's left/top. The shift is applied to ALL
+ * points; a new array is returned and `dx`/`dy` are 0 when nothing moved.
+ */
+export declare function clampPointsToRect(points: WbPoint[], rect: WbRect, skipIdx?: number[]): {
+    points: WbPoint[];
+    dx: number;
+    dy: number;
+};
+/**
+ * Convert percentage coordinates (0-100 of `frame`) to pixels, in place.
+ * x/y become `round(frame.x|y + v% of frame.width|height)`, width/height
+ * become `round(v% of frame.width|height)`, and (unless `pointsToo` is false)
+ * each point is converted like x/y. Fields that are not finite numbers are skipped.
+ */
+export declare function convertPctInPlace(target: {
+    x?: number;
+    y?: number;
+    width?: number;
+    height?: number;
+    points?: WbPoint[];
+}, frame: WbRect, opts?: {
+    pointsToo?: boolean;
+}): void;
+/** Intersection of two rects, or null when they do not overlap with positive area (touching edges do not count). */
+export declare function rectsIntersect(a: WbRect, b: WbRect): {
+    width: number;
+    height: number;
+    area: number;
+} | null;
+/** True when the point lies inside `r` (edges inclusive). */
+export declare function rectContainsPoint(r: WbRect, x: number, y: number): boolean;
+/** True when `inner` lies fully inside `outer` (edges inclusive). */
+export declare function rectContainsRect(outer: WbRect, inner: WbRect): boolean;
+/**
+ * Layout report for a whiteboard: bounds, viewport overflow, overlapping
+ * elements, section containment/spills, unparented elements and notes.
+ *
+ * - Boxes come from `elementBox` with a lookup over ALL elements (anchors resolve).
+ * - `focusIds` restricts overflow/overlap/containment/unparented entries to
+ *   those involving at least one focus id; bounds, counts of estimates and
+ *   notes stay global.
+ * - Overflow: 'outside' when the box does not intersect the usable rect,
+ *   otherwise 'partial' with rounded per-side amounts. Sorted by total amount,
+ *   capped at `maxOverflow` (default 30); `overflowTotal` is the uncapped count.
+ * - Overlaps: pairs among text/list/shape/image/section with a positive-area
+ *   intersection, skipping pairs where one is a section containing the other's
+ *   centre (that is containment, nested sections included). Sorted by area,
+ *   capped at `maxOverlaps` (default 30).
+ * - Containment: each non-section solid element belongs to the smallest section
+ *   whose box contains its centre; a section belongs to the smallest LARGER
+ *   section containing its centre. Only sections with children are listed;
+ *   `spills` are children whose box is not fully inside the section.
+ * - Notes: estimated-size count, children drawn below their section (zIndex),
+ *   and arrow anchors that reference unknown ids.
+ */
+export declare function analyzeWhiteboard(elements: WbElement[], viewport: WbViewport, opts?: WbAnalyzeOptions): WbAnalysis;
+/**
+ * Compact box label for tool output: `box=(x,y,w,h)`, with `~` before w and h
+ * when the size is an estimate, or `box=(?)` when there is no box.
+ */
+export declare function formatBox(box: WbRect | null | undefined, estimated?: boolean): string;
+//# sourceMappingURL=whiteboard-geometry.d.ts.map