@svgrid/enterprise 3.1.21 → 3.1.23

package/dist/review/SvReviewPanel.svelte.d.ts

@@ -0,0 +1,16 @@
+import { type ReviewMessages } from './messages.js';
+import type { Review, ReviewOutcome } from './model.svelte.js';
+type $$ComponentProps = {
+    review: Review<any>;
+    /** The heading; default `messages.title`. */
+    title?: string;
+    /** Wording for this panel, over the review's own `messages`. */
+    messages?: Partial<ReviewMessages>;
+    /** Ask before deciding more than this many proposals at once. */
+    confirmOver?: number;
+    /** Called after each decision with what happened. */
+    onDecide?: (outcome: ReviewOutcome) => void;
+};
+declare const SvReviewPanel: import("svelte").Component<$$ComponentProps, {}, "">;
+type SvReviewPanel = ReturnType<typeof SvReviewPanel>;
+export default SvReviewPanel;

package/dist/review/adapters.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Producers: turn what the AI helpers and imports return into proposals.
+ *
+ * The AI helpers key predictions by `rowIndex`, an index into `api.getData()`
+ * as it was when the helper read it. A sort, a filter or an edit during the
+ * await does not move data indices, but an insert or a new `data` array does,
+ * so the adapters resolve indices against a snapshot taken BEFORE the call,
+ * then key each proposal by row id. Indices the helper was not asked about,
+ * or that fall outside the snapshot, are dropped and counted.
+ */
+import { type AIClassifyOptions, type AIClassifyResult, type AISmartFillOptions, type AISmartFillResult } from '@svgrid/grid';
+import type { ReviewGridApi } from './model.svelte.js';
+import type { ProposalInput, ProposalSource } from './types.js';
+type RowIdApi = Pick<ReviewGridApi, 'getOption'>;
+export type AdapterResult = {
+    source: ProposalSource;
+    title: string;
+    proposals: ProposalInput[];
+    /** Predictions dropped: an index outside the request or the snapshot. */
+    dropped: number;
+};
+/** Blank cells of `field`: what `aiSmartFill` targets when given no indices. */
+export declare const blankTargets: (snapshot: ReadonlyArray<unknown>, field: string) => number[];
+export declare function fromSmartFill<TData>(result: AISmartFillResult, snapshot: ReadonlyArray<TData>, opts: {
+    api: RowIdApi;
+    targets?: ReadonlyArray<number>;
+    source?: ProposalSource;
+}): AdapterResult;
+export declare function fromClassify<TData>(result: AIClassifyResult, snapshot: ReadonlyArray<TData>, opts: {
+    api: RowIdApi;
+    targets?: ReadonlyArray<number>;
+    source?: ProposalSource;
+}): AdapterResult;
+/**
+ * Diff incoming rows (an import, a sync) against the grid's data by `key`:
+ * one proposal per field that differs. Incoming rows with no match, and
+ * fields not in `fields` when it is given, are not proposed; unmatched rows
+ * are returned so the app can show them (adding rows comes in a later release).
+ */
+export declare function fromRows<TData>(incoming: ReadonlyArray<Partial<TData>>, opts: {
+    api: Pick<ReviewGridApi, 'getOption' | 'getData'>;
+    key: keyof TData & string;
+    source: ProposalSource;
+    title?: string;
+    fields?: ReadonlyArray<keyof TData & string>;
+}): AdapterResult & {
+    unmatched: Array<Partial<TData>>;
+};
+type Addable = {
+    add(input: {
+        source: ProposalSource;
+        title?: string;
+        proposals: ReadonlyArray<ProposalInput>;
+    }): unknown;
+};
+/** Snapshot, run `aiSmartFill`, and add the result to `review` as proposals. */
+export declare function reviewSmartFill(review: Addable, api: ReviewGridApi, opts: AISmartFillOptions): Promise<AdapterResult>;
+/** Snapshot, run `aiClassify`, and add the result to `review` as proposals. */
+export declare function reviewClassify(review: Addable, api: ReviewGridApi, opts: AIClassifyOptions): Promise<AdapterResult>;
+/**
+ * Lift a `createStagedEditing` buffer into proposals, to route a person's
+ * staged edits to someone else for approval instead of committing them.
+ *
+ * Staged editing has already written its values into the grid, and a
+ * proposal is checked against the value it saw (`before`). So revert the
+ * stage first (`stage.revert(...)`), then add these: the cells hold the
+ * original values again and the proposals carry the staged ones.
+ */
+export declare function fromStaged(changes: ReadonlyArray<{
+    rowId: string;
+    columnId: string;
+    original: unknown;
+    staged: unknown;
+}>, opts: {
+    api: Pick<ReviewGridApi, 'getColumns'>;
+    source: ProposalSource;
+    title?: string;
+}): AdapterResult;
+export {};

package/dist/review/adapters.js

@@ -0,0 +1,119 @@
+/**
+ * Producers: turn what the AI helpers and imports return into proposals.
+ *
+ * The AI helpers key predictions by `rowIndex`, an index into `api.getData()`
+ * as it was when the helper read it. A sort, a filter or an edit during the
+ * await does not move data indices, but an insert or a new `data` array does,
+ * so the adapters resolve indices against a snapshot taken BEFORE the call,
+ * then key each proposal by row id. Indices the helper was not asked about,
+ * or that fall outside the snapshot, are dropped and counted.
+ */
+import { aiClassify, aiSmartFill, } from '@svgrid/grid';
+import { isBlank, sameValue } from './equal.js';
+function rowIdOf(api) {
+    const fn = api.getOption('getRowId');
+    if (!fn)
+        throw new Error('[svgrid review] the grid needs a getRowId prop');
+    return fn;
+}
+function fromPredictions(predictions, field, snapshot, targets, api, reason) {
+    const id = rowIdOf(api);
+    const asked = new Set(targets);
+    const seen = new Set();
+    const proposals = [];
+    let dropped = 0;
+    for (const pr of predictions) {
+        const i = pr.rowIndex;
+        const row = snapshot[i];
+        if (!Number.isInteger(i) || !asked.has(i) || row === undefined || seen.has(i)) {
+            dropped++;
+            continue;
+        }
+        seen.add(i);
+        const before = row[field];
+        if (sameValue(before, pr.value))
+            continue;
+        proposals.push({ rowId: id(row, i), field, before, after: pr.value, confidence: pr.confidence, reason });
+    }
+    return { proposals, dropped };
+}
+/** Blank cells of `field`: what `aiSmartFill` targets when given no indices. */
+export const blankTargets = (snapshot, field) => snapshot.flatMap((row, i) => (isBlank(row[field]) ? [i] : []));
+export function fromSmartFill(result, snapshot, opts) {
+    const targets = opts.targets ?? blankTargets(snapshot, result.field);
+    const { proposals, dropped } = fromPredictions(result.predictions, result.field, snapshot, targets, opts.api, result.rationale || undefined);
+    const source = opts.source ?? { kind: 'ai', id: `smart-fill:${result.field}`, label: 'Smart fill' };
+    return { source, title: `Smart fill: ${result.field}`, proposals, dropped };
+}
+export function fromClassify(result, snapshot, opts) {
+    const targets = opts.targets ?? snapshot.map((_, i) => i);
+    const { proposals, dropped } = fromPredictions(result.predictions, result.outputField, snapshot, targets, opts.api, `classified from ${result.inputField}`);
+    const source = opts.source ?? { kind: 'ai', id: `classify:${result.outputField}`, label: 'Classify' };
+    return { source, title: `Classify: ${result.outputField}`, proposals, dropped };
+}
+/**
+ * Diff incoming rows (an import, a sync) against the grid's data by `key`:
+ * one proposal per field that differs. Incoming rows with no match, and
+ * fields not in `fields` when it is given, are not proposed; unmatched rows
+ * are returned so the app can show them (adding rows comes in a later release).
+ */
+export function fromRows(incoming, opts) {
+    const id = rowIdOf(opts.api);
+    const data = opts.api.getData();
+    const byKey = new Map();
+    data.forEach((row, index) => byKey.set(row[opts.key], { row, index }));
+    const proposals = [];
+    const unmatched = [];
+    for (const next of incoming) {
+        const hit = byKey.get(next[opts.key]);
+        if (!hit) {
+            unmatched.push(next);
+            continue;
+        }
+        const rowId = id(hit.row, hit.index);
+        const fields = opts.fields ?? Object.keys(next);
+        for (const field of fields) {
+            if (field === opts.key || !(field in next))
+                continue;
+            const before = hit.row[field];
+            const after = next[field];
+            if (!sameValue(before, after))
+                proposals.push({ rowId, field, before, after });
+        }
+    }
+    return { source: opts.source, title: opts.title ?? opts.source.label, proposals, dropped: 0, unmatched };
+}
+/** Snapshot, run `aiSmartFill`, and add the result to `review` as proposals. */
+export async function reviewSmartFill(review, api, opts) {
+    const snapshot = api.getData().slice();
+    const targets = opts.targetRowIndices ?? blankTargets(snapshot, opts.field);
+    const result = await aiSmartFill(api, { ...opts, targetRowIndices: [...targets] });
+    const set = fromSmartFill(result, snapshot, { api, targets });
+    review.add(set);
+    return set;
+}
+/** Snapshot, run `aiClassify`, and add the result to `review` as proposals. */
+export async function reviewClassify(review, api, opts) {
+    const snapshot = api.getData().slice();
+    const targets = opts.targetRowIndices ?? snapshot.map((_, i) => i);
+    const result = await aiClassify(api, { ...opts, targetRowIndices: [...targets] });
+    const set = fromClassify(result, snapshot, { api, targets });
+    review.add(set);
+    return set;
+}
+/**
+ * Lift a `createStagedEditing` buffer into proposals, to route a person's
+ * staged edits to someone else for approval instead of committing them.
+ *
+ * Staged editing has already written its values into the grid, and a
+ * proposal is checked against the value it saw (`before`). So revert the
+ * stage first (`stage.revert(...)`), then add these: the cells hold the
+ * original values again and the proposals carry the staged ones.
+ */
+export function fromStaged(changes, opts) {
+    const fieldOf = new Map(opts.api.getColumns().map((c) => [c.id, c.field ?? c.id]));
+    const proposals = changes
+        .filter((c) => !sameValue(c.original, c.staged))
+        .map((c) => ({ rowId: c.rowId, field: fieldOf.get(c.columnId) ?? c.columnId, before: c.original, after: c.staged }));
+    return { source: opts.source, title: opts.title ?? opts.source.label, proposals, dropped: 0 };
+}

package/dist/review/agent.d.ts

@@ -0,0 +1,52 @@
+import type { ReviewGridApi } from './model.svelte.js';
+import type { Proposal, ProposalGroup, ProposalInput, ProposalSource } from './types.js';
+export type GridTool = {
+    name: string;
+    description: string;
+    /** JSON Schema of the input object. */
+    inputSchema: Record<string, unknown>;
+    execute: (input: any) => Promise<unknown>;
+};
+type ToolReview = {
+    add(input: {
+        source: ProposalSource;
+        title?: string;
+        proposals: ReadonlyArray<ProposalInput>;
+    }): {
+        id: string;
+        proposals: Proposal[];
+    };
+    groups(): ProposalGroup[];
+    conflicts(): Proposal[];
+    proposals(): Proposal[];
+};
+type ToolApi = Pick<ReviewGridApi, 'getData' | 'getColumns' | 'getOption'>;
+export type GridToolsOptions = {
+    review: ToolReview;
+    /** The grid api, or a getter for it. */
+    api: ToolApi | (() => ToolApi | null | undefined);
+    /** Who the proposals are from. Default: an agent named "Agent". */
+    source?: ProposalSource;
+    /** Fields the agent may propose edits to. Default: every column with a field. */
+    fields?: ReadonlyArray<string>;
+    /** Most rows one query returns. Default 200. */
+    maxRows?: number;
+    /** Prefix for tool names. Default 'grid_'. */
+    prefix?: string;
+    /** Most edits one grid_propose_edits call may carry. Default 500. */
+    maxEdits?: number;
+};
+export declare function createGridTools(opts: GridToolsOptions): GridTool[];
+/**
+ * Register tools with the browser's WebMCP API, so an agent driving the page
+ * can call them. Experimental: WebMCP is a draft (`document.modelContext`,
+ * earlier `navigator.modelContext`), and this does nothing where it is
+ * missing. Abort `signal`, or call `unregister`, to remove them.
+ */
+export declare function registerWebMcpTools(tools: ReadonlyArray<GridTool>, opts?: {
+    signal?: AbortSignal;
+}): {
+    supported: boolean;
+    unregister: () => void;
+};
+export {};

package/dist/review/agent.js

@@ -0,0 +1,232 @@
+/**
+ * Tools an AI agent can call to work on a grid's data, where every write is a
+ * proposal in a change review and a person decides. No tool writes the data.
+ *
+ * `createGridTools` returns plain tool definitions (name, description, JSON
+ * schema, execute) for any tool-use loop: an LLM SDK, an MCP server of your
+ * own, or the browser through `registerWebMcpTools`.
+ *
+ * ```ts
+ * const tools = createGridTools({ review, api: () => api, fields: ['region', 'phone'] })
+ * registerWebMcpTools(tools)  // experimental: browsers with WebMCP
+ * ```
+ */
+import { isBlank, sameValue } from './equal.js';
+const OPS = ['equals', 'notEquals', 'contains', 'blank', 'notBlank', 'gt', 'lt'];
+function matches(v, w) {
+    switch (w.op) {
+        case 'equals': return sameValue(v, w.value);
+        case 'notEquals': return !sameValue(v, w.value);
+        case 'contains': return String(v ?? '').toLowerCase().includes(String(w.value ?? '').toLowerCase());
+        case 'blank': return isBlank(v);
+        case 'notBlank': return !isBlank(v);
+        case 'gt': return v != null && v > w.value;
+        case 'lt': return v != null && v < w.value;
+    }
+}
+/**
+ * Why a value does not fit its column, or null. A model can send a string for
+ * a number or an object for a text cell; those are skipped, not proposed.
+ */
+function wrongType(type, current, value) {
+    if (value === null || value === undefined || value === '')
+        return null; // clearing a cell
+    if (Array.isArray(current))
+        return Array.isArray(value) ? null : 'expects a list';
+    if (typeof value === 'object')
+        return 'expects a single value, not an object or a list';
+    if (type === 'number' && (typeof value !== 'number' || !Number.isFinite(value)))
+        return 'expects a number';
+    if (type === 'boolean' && typeof value !== 'boolean')
+        return 'expects true or false';
+    if ((type === 'date' || type === 'dateString') && (typeof value !== 'string' || Number.isNaN(Date.parse(value))))
+        return 'expects a date (YYYY-MM-DD)';
+    return null;
+}
+export function createGridTools(opts) {
+    const prefix = opts.prefix ?? 'grid_';
+    const source = opts.source ?? { kind: 'agent', id: 'agent', label: 'Agent' };
+    const maxRows = opts.maxRows ?? 200;
+    const maxEdits = opts.maxEdits ?? 500;
+    const api = () => {
+        const a = typeof opts.api === 'function' ? opts.api() : opts.api;
+        if (!a)
+            throw new Error('the grid is not ready yet');
+        return a;
+    };
+    const rowIdOf = (a) => {
+        const fn = a.getOption('getRowId');
+        if (!fn)
+            throw new Error('the grid needs a getRowId prop');
+        return fn;
+    };
+    const columns = (a) => a.getColumns().filter((c) => c.field);
+    const writable = (a) => new Set(opts.fields ?? columns(a).map((c) => c.field));
+    const describe = {
+        name: `${prefix}describe`,
+        description: 'Describe the table: its columns (field, header, data type), how many rows it has, and which fields you may propose edits to. ' +
+            'Edits you propose are not applied: a person reviews them in groups and accepts or rejects them.',
+        inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+        async execute() {
+            const a = api();
+            const canWrite = writable(a);
+            return {
+                rowCount: a.getData().length,
+                columns: columns(a).map((c) => ({ field: c.field, header: c.header, type: c.cellDataType ?? 'text', writable: canWrite.has(c.field) })),
+            };
+        },
+    };
+    const query = {
+        name: `${prefix}query_rows`,
+        description: `Read rows of the table. Filter with "where" (all conditions must hold), pick fields, page with offset/limit (at most ${maxRows}). ` +
+            'Every row comes with its rowId, which grid_propose_edits needs.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                where: {
+                    type: 'array',
+                    items: {
+                        type: 'object',
+                        properties: { field: { type: 'string' }, op: { type: 'string', enum: OPS }, value: {} },
+                        required: ['field', 'op'],
+                    },
+                },
+                fields: { type: 'array', items: { type: 'string' } },
+                offset: { type: 'integer', minimum: 0 },
+                limit: { type: 'integer', minimum: 1, maximum: maxRows },
+            },
+            additionalProperties: false,
+        },
+        async execute(input = {}) {
+            const a = api();
+            const id = rowIdOf(a);
+            const known = new Set(columns(a).map((c) => c.field));
+            for (const w of input.where ?? []) {
+                if (!known.has(w.field))
+                    throw new Error(`unknown field "${w.field}"`);
+                if (!OPS.includes(w.op))
+                    throw new Error(`unknown op "${w.op}"`);
+            }
+            const fields = (input.fields ?? [...known]).filter((f) => known.has(f));
+            const hits = a.getData().flatMap((row, i) => (input.where ?? []).every((w) => matches(row[w.field], w)) ? [{ row, i }] : []);
+            // The schema says integers; a model can still send "10" or -5.
+            const offset = Math.max(0, Math.trunc(Number(input.offset) || 0));
+            const limit = Math.min(Math.max(1, Math.trunc(Number(input.limit) || maxRows)), maxRows);
+            return {
+                total: hits.length,
+                offset,
+                rows: hits.slice(offset, offset + limit).map(({ row, i }) => ({
+                    rowId: String(id(row, i)),
+                    ...Object.fromEntries(fields.map((f) => [f, row[f]])),
+                })),
+            };
+        },
+    };
+    const propose = {
+        name: `${prefix}propose_edits`,
+        description: 'Propose new values for cells. Nothing is written: each edit becomes a proposal a person reviews. ' +
+            'Give a short reason per edit, and a confidence from 0 to 1 when you are unsure. ' +
+            'Edits to unknown rows, to fields you may not edit, or that change nothing are skipped and reported.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                title: { type: 'string', description: 'What this batch does, in a few words.' },
+                edits: {
+                    type: 'array',
+                    minItems: 1,
+                    maxItems: maxEdits,
+                    items: {
+                        type: 'object',
+                        properties: {
+                            rowId: { type: 'string' },
+                            field: { type: 'string' },
+                            value: {},
+                            reason: { type: 'string' },
+                            confidence: { type: 'number', minimum: 0, maximum: 1 },
+                        },
+                        required: ['rowId', 'field', 'value'],
+                    },
+                },
+            },
+            required: ['edits'],
+            additionalProperties: false,
+        },
+        async execute(input) {
+            const a = api();
+            const edits = Array.isArray(input?.edits) ? input.edits : [];
+            if (edits.length > maxEdits)
+                throw new Error(`at most ${maxEdits} edits per call; send the rest in another call`);
+            const id = rowIdOf(a);
+            const canWrite = writable(a);
+            const typeOf = new Map(a.getColumns().filter((c) => c.field).map((c) => [c.field, c.cellDataType ?? 'text']));
+            const rows = new Map(a.getData().map((row, i) => [String(id(row, i)), row]));
+            const skipped = [];
+            const proposals = [];
+            edits.forEach((e, index) => {
+                const row = rows.get(String(e?.rowId));
+                if (!row)
+                    return skipped.push({ index, why: `no row with rowId "${e?.rowId}"` });
+                if (!canWrite.has(e.field))
+                    return skipped.push({ index, why: `field "${e.field}" is not writable` });
+                const why = wrongType(typeOf.get(e.field), row[e.field], e.value);
+                if (why)
+                    return skipped.push({ index, why: `${e.field} ${why}` });
+                if (sameValue(row[e.field], e.value))
+                    return skipped.push({ index, why: 'the cell already holds this value' });
+                const confidence = typeof e.confidence === 'number' ? Math.min(1, Math.max(0, e.confidence)) : undefined;
+                proposals.push({ rowId: String(e.rowId), field: e.field, before: row[e.field], after: e.value, reason: e.reason, confidence });
+            });
+            const set = proposals.length ? opts.review.add({ source, title: input.title, proposals }) : null;
+            return {
+                proposed: set?.proposals.length ?? 0,
+                setId: set?.id ?? null,
+                skipped,
+                note: 'Proposed, not applied. A person will review these; call grid_review_status to see what was decided.',
+            };
+        },
+    };
+    const status = {
+        name: `${prefix}review_status`,
+        description: 'What happened to your proposals: how many are still pending, accepted, rejected, or stale (the cell changed before review), ' +
+            'and the pending groups as the reviewer sees them.',
+        inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+        async execute() {
+            const mine = opts.review.proposals().filter((p) => p.source.id === source.id);
+            const count = (s) => mine.filter((p) => p.status === s).length;
+            return {
+                pending: count('pending'),
+                accepted: count('accepted'),
+                rejected: count('rejected'),
+                stale: count('stale'),
+                conflicts: count('conflict'),
+                groups: opts.review.groups().filter((g) => g.sourceId === source.id).map((g) => ({ label: g.label, kind: g.kind, count: g.count })),
+            };
+        },
+    };
+    return [describe, query, propose, status];
+}
+/**
+ * Register tools with the browser's WebMCP API, so an agent driving the page
+ * can call them. Experimental: WebMCP is a draft (`document.modelContext`,
+ * earlier `navigator.modelContext`), and this does nothing where it is
+ * missing. Abort `signal`, or call `unregister`, to remove them.
+ */
+export function registerWebMcpTools(tools, opts = {}) {
+    const g = globalThis;
+    const mc = (g.document?.modelContext ?? g.navigator?.modelContext);
+    if (typeof mc?.registerTool !== 'function')
+        return { supported: false, unregister() { } };
+    const controller = new AbortController();
+    opts.signal?.addEventListener('abort', () => controller.abort(), { once: true });
+    for (const t of tools) {
+        const registered = mc.registerTool({
+            name: t.name,
+            description: t.description,
+            inputSchema: t.inputSchema,
+            execute: async (input) => ({ content: [{ type: 'text', text: JSON.stringify(await t.execute(input ?? {})) }] }),
+        }, { signal: controller.signal });
+        // A rejected registration (a duplicate name, a permission) must not break the page.
+        Promise.resolve(registered).catch(() => { });
+    }
+    return { supported: true, unregister: () => controller.abort() };
+}

package/dist/review/card-marks.svelte.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Pending proposals on board and gallery cards. A card renderer gets the grid's
+ * rows and its `getRowId`, not the grid api, so a review registers itself by
+ * that function (the same object it reads through `api.getOption`; SvGrid
+ * Base keeps one per table) and a card asks for its row's mark.
+ *
+ * Small and on its own: the board and gallery import it without the review
+ * module. The registry is reactive: a card drawn before its review registered
+ * (the grid api arrives after the first draw) draws again when it does.
+ */
+export type CardMark = {
+    count: number;
+    /** "2 proposed", in the review's wording. */
+    label: string;
+    /** "Region -> EMEA, Phone -> 555-123-4567", for the card's title. */
+    text: string;
+};
+/** A pending proposal in one cell, as a cell mark shows it. */
+export type CellProposal = {
+    after: unknown;
+    source: string;
+    reason?: string;
+    /** The review's wording: "{source} proposes {value}" and the text for a blank value. */
+    proposes: string;
+    empty: string;
+};
+type Source = {
+    cardMark(rowId: string): CardMark | null;
+    cellProposal(rowId: string, field: string): CellProposal | null;
+    /** Whether a row object is one of this review's grid rows. */
+    owns(row: unknown): boolean;
+};
+/** Called by a review once its grid's `getRowId` is known. */
+export declare function registerCardMarks(getRowId: object, source: Source): void;
+/**
+ * The pending proposal in a grid cell, or null. `row` is the row object,
+ * `rowId` the grid's id for it; used by the cell mark of rich cells.
+ */
+export declare function cellProposalFor(getRowId: object | undefined, row: unknown, rowId: string, field: string): CellProposal | null;
+/** The mark for a card's row, or null (no review on this grid, or nothing pending). */
+export declare function cardMarkFor(getRowId: ((row: any, index: number) => string) | undefined, row: unknown, index: number): CardMark | null;
+export {};

package/dist/review/card-marks.svelte.js

@@ -0,0 +1,51 @@
+/**
+ * Pending proposals on board and gallery cards. A card renderer gets the grid's
+ * rows and its `getRowId`, not the grid api, so a review registers itself by
+ * that function (the same object it reads through `api.getOption`; SvGrid
+ * Base keeps one per table) and a card asks for its row's mark.
+ *
+ * Small and on its own: the board and gallery import it without the review
+ * module. The registry is reactive: a card drawn before its review registered
+ * (the grid api arrives after the first draw) draws again when it does.
+ */
+// Several grids can share one getRowId function (Svelte hoists a static inline
+// arrow), so a function maps to every review that registered it, and a card
+// takes its mark from the review whose grid holds its row.
+const sources = new WeakMap();
+let generation = $state(0);
+/** Called by a review once its grid's `getRowId` is known. */
+export function registerCardMarks(getRowId, source) {
+    const list = sources.get(getRowId) ?? new Set();
+    list.add(source);
+    sources.set(getRowId, list);
+    // Registration runs while the grid reads its columns or formats, where state
+    // must not change; the cards hear about it a microtask later.
+    queueMicrotask(() => (generation += 1));
+}
+/**
+ * The pending proposal in a grid cell, or null. `row` is the row object,
+ * `rowId` the grid's id for it; used by the cell mark of rich cells.
+ */
+export function cellProposalFor(getRowId, row, rowId, field) {
+    void generation;
+    const list = getRowId ? sources.get(getRowId) : undefined;
+    if (!list)
+        return null;
+    for (const source of list)
+        if (source.owns(row))
+            return source.cellProposal(rowId, field);
+    return null;
+}
+/** The mark for a card's row, or null (no review on this grid, or nothing pending). */
+export function cardMarkFor(getRowId, row, index) {
+    void generation;
+    if (!getRowId)
+        return null;
+    const list = sources.get(getRowId);
+    if (!list)
+        return null;
+    for (const source of list)
+        if (source.owns(row))
+            return source.cardMark(String(getRowId(row, index)));
+    return null;
+}

package/dist/review/cluster.d.ts

@@ -0,0 +1,26 @@
+import { type ReviewMessages } from './messages.js';
+import type { Proposal, ProposalGroup } from './types.js';
+export type ClusterOptions = {
+    /** Wording of the group labels (the `label*`, `case*`, `punct*` keys); English by default. */
+    messages?: Partial<ReviewMessages>;
+    /** The header to show for a field in group labels. Default: the field itself. */
+    fieldLabel?: (field: string) => string;
+    /** Fewest members a `scale` group needs. Default 5. */
+    minScale?: number;
+    /** Below this, a judgment group sorts with the risky ones. Default 0.6. */
+    lowConfidence?: number;
+};
+export declare function clusterProposals(proposals: ReadonlyArray<Proposal>, opts?: ClusterOptions): ProposalGroup[];
+/** A key that tells values apart by type as well as content. */
+export declare function keyOf(v: unknown): string;
+/**
+ * Spaces a reader cannot see, drawn as `·`: leading and trailing ones and runs
+ * of two or more. A trim proposal otherwise reads "Acme -> Acme".
+ */
+export declare function visibleSpaces(s: string): string;
+/**
+ * A value as a group label shows it: short, `(empty)` for blank, spaces
+ * visible. A string is quoted only where the quotes tell something: around
+ * spaces at its ends, or when it reads as a number, a boolean or the blank mark.
+ */
+export declare function showValue(v: unknown, empty?: string): string;