logisheets-core 1.1.0

package/dist/ops/index.d.ts

@@ -0,0 +1,155 @@
+import type { Payload, ActionEffect, SelectedData, Alignment, StPatternType, Value } from 'logisheets-web';
+import type { Client } from '../port.js';
+import { type ValidationRule, type Violation } from '../validation/index.js';
+import { type FieldColumn } from '../field/index.js';
+import { type FontStyle, type BorderBatchUpdate } from '../format/index.js';
+/**
+ * Tells WorkbookOps whether to mark transactions temp (speculative). The
+ * browser injects its global temp-mode toggle; the Node runtime leaves it at
+ * the default (always committed).
+ */
+export type TempModeProvider = () => boolean;
+/** One field of a form-backed block, resolved by the host. */
+export interface FormBlockField {
+    /** Display name. */
+    name: string;
+    /** Engine render id, allocated by the host's FieldManager. */
+    renderId: string;
+    /** Per-field value-formula template (#FIELD("X") / #KEY); '' if free-form. */
+    valueFormula?: string;
+    /** Whether the field renders via a host-drawn (DIY) overlay. */
+    diyRender: boolean;
+    /** Number format applied to the field's render info. */
+    numFmt?: string;
+}
+/**
+ * High-level workbook operations bound to one engine {@link Client}.
+ * Construct one per workbook and share it across the host.
+ */
+export declare class WorkbookOps {
+    private readonly client;
+    private readonly tempMode;
+    /** Monotonic id for the throwaway ephemeral cells used by evalFormula. */
+    private ephemeralSeq;
+    constructor(client: Client, tempMode?: TempModeProvider);
+    /**
+     * Build a transaction at the host's current temp-mode, send it, and return
+     * the engine's effect. Throws on an engine ErrorMessage so callers can use
+     * normal try/catch instead of inspecting a union.
+     */
+    private apply;
+    /** Write a value or formula into a cell. */
+    inputCell(sheetIdx: number, row: number, col: number, content: string, undoable?: boolean): Promise<ActionEffect>;
+    /** Write a value into a cell addressed within a block's coordinate space. */
+    inputBlockCell(sheetIdx: number, blockId: number, row: number, col: number, input: string, undoable?: boolean): Promise<ActionEffect>;
+    /**
+     * Write several block cells in one transaction. Used when an interaction
+     * changes a group of related cells at once (e.g. redistributing a percent
+     * allocation across a pool).
+     */
+    inputBlockCells(inputs: ReadonlyArray<{
+        sheetIdx: number;
+        blockId: number;
+        row: number;
+        col: number;
+        input: string;
+    }>, undoable?: boolean): Promise<ActionEffect>;
+    /**
+     * Set a cell's content to an image URL, optionally widening the column
+     * and/or heightening the row to fit — all in one transaction. The host
+     * computes the target `colWidth`/`rowHeight` (in engine units) and passes
+     * them only when an adjustment is actually needed.
+     */
+    setCellImage(sheetIdx: number, row: number, col: number, url: string, opts?: {
+        colWidth?: number;
+        rowHeight?: number;
+    }): Promise<ActionEffect>;
+    /** Create a new sheet named `name` at index `idx`. */
+    createSheet(name: string, idx: number): Promise<ActionEffect>;
+    /** Rename a sheet. */
+    renameSheet(oldName: string, newName: string): Promise<ActionEffect>;
+    /** Delete the sheet at index `idx`. */
+    deleteSheet(idx: number): Promise<ActionEffect>;
+    /** Set a sheet tab's color (ARGB string; empty clears it). */
+    setSheetColor(idx: number, color: string): Promise<ActionEffect>;
+    /** Insert `cnt` rows into a block, starting at block-row `start`. */
+    insertRowsInBlock(sheetIdx: number, blockId: number, start: number, cnt?: number): Promise<ActionEffect>;
+    /** Delete a block. */
+    removeBlock(sheetIdx: number, blockId: number): Promise<ActionEffect>;
+    /** Apply font styling (bold/italic/underline/strike/color/size). */
+    setFont(sheetIdx: number, data: SelectedData, update: FontStyle): Promise<void>;
+    /** Apply horizontal/vertical alignment. */
+    setAlignment(sheetIdx: number, data: SelectedData, alignment: Alignment): Promise<void>;
+    /** Toggle wrap-text. */
+    setWrapText(sheetIdx: number, data: SelectedData, wrapText: boolean): Promise<void>;
+    /** Apply a number format. */
+    setNumFmt(sheetIdx: number, data: SelectedData, numFmt: string): Promise<void>;
+    /** Apply a pattern fill (foreground/background color + pattern). */
+    setPatternFill(sheetIdx: number, data: SelectedData, opts: {
+        fgColor?: string;
+        bgColor?: string;
+        pattern?: StPatternType;
+    }): Promise<void>;
+    /** Apply borders to the selection per the batch directive. */
+    setBorder(sheetIdx: number, data: SelectedData, update: BorderBatchUpdate): Promise<void>;
+    /** Apply a generated payload list, skipping the round-trip when empty. */
+    private applyGenerated;
+    /**
+     * Create a form-backed block: the `createBlock` + `bindFormSchema` +
+     * per-field `upsertFieldRenderInfo` payloads, in one transaction.
+     *
+     * The host resolves each field first (type → FieldInfo, validation
+     * formulas, and the engine render id from its FieldManager), then hands
+     * the flattened list here. Field/formula composition and FieldManager
+     * registration stay in the host because they touch engine-side render
+     * state that isn't part of the Client seam.
+     */
+    createFormBlock(opts: {
+        sheetIdx: number;
+        blockId: number;
+        masterRow: number;
+        masterCol: number;
+        refName: string;
+        keyIdx: number;
+        fields: readonly FormBlockField[];
+    }): Promise<void>;
+    /**
+     * Apply a caller-built payload list as one transaction (at the host's
+     * temp-mode). Escape hatch for operations whose payload construction still
+     * lives in the host — e.g. the toolbar's format/border generators. Prefer
+     * a named method above when one exists; this exists so no caller has to
+     * reach past WorkbookOps to `client.handleTransaction` directly.
+     */
+    applyPayloads(payloads: readonly Payload[], undoable?: boolean): Promise<ActionEffect>;
+    /** Commit the workbook's temp (speculative) branch into the main branch. */
+    commitTempStatus(): Promise<void>;
+    /** Discard the workbook's temp (speculative) branch. */
+    cleanupTempStatus(): Promise<void>;
+    /**
+     * Establish (or refresh) the validation rule for a cell.
+     *
+     * A validation rule is an Excel formula (no leading `=`) that should
+     * evaluate to a boolean. We park it in the cell's *shadow* cell so the
+     * engine evaluates it reactively; the host reads the shadow value back and
+     * renders the result (see logisheets-core's `interpretValidation`).
+     *
+     * Lifted verbatim out of the browser's ValidationCell component so the
+     * Node runtime gets the same operation.
+     */
+    setValidationRule(sheetIdx: number, row: number, col: number, formula: string): Promise<void>;
+    /**
+     * Evaluate an Excel formula (no leading `=`) in a sheet and return its
+     * Value. Parks the formula in a throwaway ephemeral cell, reads the result
+     * back, and leaves no committed change — the same mechanism the browser
+     * uses for shadow cells, here for one-shot evaluation.
+     */
+    evalFormula(sheetIdx: number, formula: string): Promise<Value>;
+    /**
+     * Evaluate formula-based validation rules and return the violating cells.
+     * Headless batch check — the per-cell browser path uses setValidationRule +
+     * interpretValidation instead.
+     */
+    checkValidations(rules: readonly ValidationRule[]): Promise<Violation[]>;
+    /** Check required / unique / membership field constraints. */
+    checkFieldConstraints(columns: readonly FieldColumn[]): Promise<Violation[]>;
+}

package/dist/ops/index.js

@@ -0,0 +1,335 @@
+// WorkbookOps — the operation layer.
+//
+// This is the single home for high-level, engine-neutral workbook
+// *operations* (input a cell, add a sheet, insert a block row, set a
+// validation rule, ...). Each operation is an async method that does the full
+// orchestration — resolve ids, build payloads, send the transaction, surface
+// errors — on top of the injected {@link Client} seam (see ../port).
+//
+// Both hosts are thin shells over this layer:
+//   - browser app  -> injects logisheets-engine's worker-backed client
+//   - node runtime -> injects an async client built over the Node WASM engine
+//
+// Operations are written async against the full Client. The browser client is
+// already async; the Node runtime adapts its synchronous handle() into an
+// async Client, so this one implementation runs unchanged on both.
+//
+// UI side effects (refocus, toasts, event buses, closing dialogs) stay in the
+// host — only the engine-facing operation lives here.
+import { makeTransaction } from '../transaction/index.js';
+import { checkValidations as checkValidationsPure, } from '../validation/index.js';
+import { checkFieldConstraints as checkFieldConstraintsPure, } from '../field/index.js';
+import { generateFontPayload, generateAlgnmentPayload, generateWrapTextPayload, generateNumFmtPayload, generatePatternFillPayload, generateBorderPayloads, } from '../format/index.js';
+function isErrorMessage(v) {
+    return (typeof v === 'object' &&
+        v !== null &&
+        'msg' in v);
+}
+/**
+ * High-level workbook operations bound to one engine {@link Client}.
+ * Construct one per workbook and share it across the host.
+ */
+export class WorkbookOps {
+    constructor(client, tempMode = () => false) {
+        this.client = client;
+        this.tempMode = tempMode;
+        /** Monotonic id for the throwaway ephemeral cells used by evalFormula. */
+        this.ephemeralSeq = 1;
+    }
+    /**
+     * Build a transaction at the host's current temp-mode, send it, and return
+     * the engine's effect. Throws on an engine ErrorMessage so callers can use
+     * normal try/catch instead of inspecting a union.
+     */
+    async apply(payloads, undoable) {
+        const transaction = makeTransaction(payloads, undoable, this.tempMode());
+        const res = await this.client.handleTransaction({ transaction });
+        if (isErrorMessage(res)) {
+            throw new Error('Transaction failed: ' + res.msg);
+        }
+        return res;
+    }
+    // ---- cell / block input --------------------------------------------
+    /** Write a value or formula into a cell. */
+    inputCell(sheetIdx, row, col, content, undoable = true) {
+        return this.apply([{ type: 'cellInput', value: { sheetIdx, row, col, content } }], undoable);
+    }
+    /** Write a value into a cell addressed within a block's coordinate space. */
+    inputBlockCell(sheetIdx, blockId, row, col, input, undoable = true) {
+        return this.apply([
+            {
+                type: 'blockInput',
+                value: { sheetIdx, blockId, row, col, input },
+            },
+        ], undoable);
+    }
+    /**
+     * Write several block cells in one transaction. Used when an interaction
+     * changes a group of related cells at once (e.g. redistributing a percent
+     * allocation across a pool).
+     */
+    inputBlockCells(inputs, undoable = true) {
+        return this.apply(inputs.map((i) => ({ type: 'blockInput', value: i })), undoable);
+    }
+    /**
+     * Set a cell's content to an image URL, optionally widening the column
+     * and/or heightening the row to fit — all in one transaction. The host
+     * computes the target `colWidth`/`rowHeight` (in engine units) and passes
+     * them only when an adjustment is actually needed.
+     */
+    setCellImage(sheetIdx, row, col, url, opts) {
+        const payloads = [
+            { type: 'cellInput', value: { sheetIdx, row, col, content: url } },
+        ];
+        if (opts?.colWidth !== undefined) {
+            payloads.push({
+                type: 'setColWidth',
+                value: { sheetIdx, col, width: opts.colWidth },
+            });
+        }
+        if (opts?.rowHeight !== undefined) {
+            payloads.push({
+                type: 'setRowHeight',
+                value: { sheetIdx, row, height: opts.rowHeight },
+            });
+        }
+        return this.apply(payloads, true);
+    }
+    // ---- sheets ---------------------------------------------------------
+    /** Create a new sheet named `name` at index `idx`. */
+    createSheet(name, idx) {
+        return this.apply([{ type: 'createSheet', value: { idx, newName: name } }], true);
+    }
+    /** Rename a sheet. */
+    renameSheet(oldName, newName) {
+        return this.apply([{ type: 'sheetRename', value: { oldName, newName } }], true);
+    }
+    /** Delete the sheet at index `idx`. */
+    deleteSheet(idx) {
+        return this.apply([{ type: 'deleteSheet', value: { idx } }], true);
+    }
+    /** Set a sheet tab's color (ARGB string; empty clears it). */
+    setSheetColor(idx, color) {
+        return this.apply([{ type: 'setSheetColor', value: { idx, color } }], true);
+    }
+    // ---- blocks ---------------------------------------------------------
+    /** Insert `cnt` rows into a block, starting at block-row `start`. */
+    insertRowsInBlock(sheetIdx, blockId, start, cnt = 1) {
+        return this.apply([
+            {
+                type: 'insertRowsInBlock',
+                value: { sheetIdx, blockId, start, cnt },
+            },
+        ], true);
+    }
+    /** Delete a block. */
+    removeBlock(sheetIdx, blockId) {
+        return this.apply([{ type: 'removeBlock', value: { sheetIdx, id: blockId } }], true);
+    }
+    // ---- formatting -----------------------------------------------------
+    //
+    // Each method turns the current sheet + selection into style-update
+    // payloads (logic in ../format) and applies them. The host supplies the
+    // sheet index (a view concern) and the selection.
+    /** Apply font styling (bold/italic/underline/strike/color/size). */
+    async setFont(sheetIdx, data, update) {
+        await this.applyGenerated(generateFontPayload(sheetIdx, data, update));
+    }
+    /** Apply horizontal/vertical alignment. */
+    async setAlignment(sheetIdx, data, alignment) {
+        await this.applyGenerated(generateAlgnmentPayload(sheetIdx, data, alignment));
+    }
+    /** Toggle wrap-text. */
+    async setWrapText(sheetIdx, data, wrapText) {
+        await this.applyGenerated(generateWrapTextPayload(sheetIdx, data, wrapText));
+    }
+    /** Apply a number format. */
+    async setNumFmt(sheetIdx, data, numFmt) {
+        await this.applyGenerated(generateNumFmtPayload(sheetIdx, data, numFmt));
+    }
+    /** Apply a pattern fill (foreground/background color + pattern). */
+    async setPatternFill(sheetIdx, data, opts) {
+        await this.applyGenerated(generatePatternFillPayload(sheetIdx, data, opts.fgColor, opts.bgColor, opts.pattern));
+    }
+    /** Apply borders to the selection per the batch directive. */
+    async setBorder(sheetIdx, data, update) {
+        await this.applyGenerated(generateBorderPayloads(sheetIdx, data, update));
+    }
+    /** Apply a generated payload list, skipping the round-trip when empty. */
+    async applyGenerated(payloads) {
+        if (payloads.length === 0)
+            return;
+        await this.apply(payloads, true);
+    }
+    // ---- structured blocks ---------------------------------------------
+    /**
+     * Create a form-backed block: the `createBlock` + `bindFormSchema` +
+     * per-field `upsertFieldRenderInfo` payloads, in one transaction.
+     *
+     * The host resolves each field first (type → FieldInfo, validation
+     * formulas, and the engine render id from its FieldManager), then hands
+     * the flattened list here. Field/formula composition and FieldManager
+     * registration stay in the host because they touch engine-side render
+     * state that isn't part of the Client seam.
+     */
+    async createFormBlock(opts) {
+        const { sheetIdx, blockId, masterRow, masterCol, refName, keyIdx, fields, } = opts;
+        const payloads = [
+            {
+                type: 'createBlock',
+                value: {
+                    sheetIdx,
+                    id: blockId,
+                    masterRow,
+                    masterCol,
+                    rowCnt: 1,
+                    colCnt: fields.length,
+                },
+            },
+            {
+                type: 'bindFormSchema',
+                value: {
+                    refName,
+                    sheetIdx,
+                    blockId,
+                    fieldFrom: 0,
+                    row: true,
+                    keyIdx: keyIdx < 0 ? 0 : keyIdx,
+                    fields: fields.map((f) => f.name),
+                    renderIds: fields.map((f) => f.renderId),
+                    fieldFormulas: fields.map((f) => f.valueFormula ?? ''),
+                    validationFormulas: [],
+                    editabilityFormulas: [],
+                },
+            },
+            ...fields.map((f) => ({
+                type: 'upsertFieldRenderInfo',
+                value: {
+                    renderId: f.renderId,
+                    diyRender: f.diyRender,
+                    styleUpdate: { setNumFmt: f.numFmt ?? '' },
+                },
+            })),
+        ];
+        await this.apply(payloads, true);
+    }
+    // ---- generic / temp-branch -----------------------------------------
+    /**
+     * Apply a caller-built payload list as one transaction (at the host's
+     * temp-mode). Escape hatch for operations whose payload construction still
+     * lives in the host — e.g. the toolbar's format/border generators. Prefer
+     * a named method above when one exists; this exists so no caller has to
+     * reach past WorkbookOps to `client.handleTransaction` directly.
+     */
+    applyPayloads(payloads, undoable = true) {
+        return this.apply(payloads, undoable);
+    }
+    /** Commit the workbook's temp (speculative) branch into the main branch. */
+    async commitTempStatus() {
+        const res = await this.client.commitTempStatus();
+        if (isErrorMessage(res)) {
+            throw new Error('Failed to commit temp status: ' + res.msg);
+        }
+    }
+    /** Discard the workbook's temp (speculative) branch. */
+    async cleanupTempStatus() {
+        const res = await this.client.cleanupTempStatus();
+        if (isErrorMessage(res)) {
+            throw new Error('Failed to clean up temp status: ' + res.msg);
+        }
+    }
+    // ---- validation -----------------------------------------------------
+    /**
+     * Establish (or refresh) the validation rule for a cell.
+     *
+     * A validation rule is an Excel formula (no leading `=`) that should
+     * evaluate to a boolean. We park it in the cell's *shadow* cell so the
+     * engine evaluates it reactively; the host reads the shadow value back and
+     * renders the result (see logisheets-core's `interpretValidation`).
+     *
+     * Lifted verbatim out of the browser's ValidationCell component so the
+     * Node runtime gets the same operation.
+     */
+    async setValidationRule(sheetIdx, row, col, formula) {
+        const shadow = await this.client.getShadowCellId({
+            sheetIdx,
+            rowIdx: row,
+            colIdx: col,
+        });
+        if (isErrorMessage(shadow)) {
+            throw new Error('Failed to get shadow cell id: ' + shadow.msg);
+        }
+        await this.apply([
+            {
+                type: 'ephemeralCellInput',
+                value: {
+                    id: shadow.cellId.value,
+                    sheetIdx,
+                    content: `=${formula}`,
+                },
+            },
+        ], false);
+    }
+    /**
+     * Evaluate an Excel formula (no leading `=`) in a sheet and return its
+     * Value. Parks the formula in a throwaway ephemeral cell, reads the result
+     * back, and leaves no committed change — the same mechanism the browser
+     * uses for shadow cells, here for one-shot evaluation.
+     */
+    async evalFormula(sheetIdx, formula) {
+        const id = this.ephemeralSeq++;
+        await this.apply([
+            {
+                type: 'ephemeralCellInput',
+                value: { id, sheetIdx, content: '=' + formula },
+            },
+        ], false);
+        const sheetId = await this.client.getSheetId({ sheetIdx });
+        if (isErrorMessage(sheetId)) {
+            throw new Error('Failed to resolve sheet id: ' + sheetId.msg);
+        }
+        const infos = await this.client.batchGetCellInfoById({
+            ids: [{ sheetId, cellId: { type: 'ephemeralCell', value: id } }],
+        });
+        if (isErrorMessage(infos)) {
+            throw new Error('Failed to read ephemeral cell: ' + infos.msg);
+        }
+        return infos[0].value;
+    }
+    /**
+     * Evaluate formula-based validation rules and return the violating cells.
+     * Headless batch check — the per-cell browser path uses setValidationRule +
+     * interpretValidation instead.
+     */
+    async checkValidations(rules) {
+        const values = new Map();
+        for (const rule of rules) {
+            values.set(rule.formula, await this.evalFormula(rule.sheetIdx, rule.formula));
+        }
+        return checkValidationsPure(rules, (_sheetIdx, formula) => values.get(formula));
+    }
+    /** Check required / unique / membership field constraints. */
+    async checkFieldConstraints(columns) {
+        const values = new Map();
+        for (const { cells } of columns) {
+            for (const c of cells) {
+                const key = `${c.sheetIdx}:${c.row}:${c.col}`;
+                if (values.has(key))
+                    continue;
+                const v = await this.client.getValue({
+                    sheetIdx: c.sheetIdx,
+                    row: c.row,
+                    col: c.col,
+                });
+                if (isErrorMessage(v)) {
+                    throw new Error('Failed to read cell value: ' + v.msg);
+                }
+                values.set(key, v);
+            }
+        }
+        return checkFieldConstraintsPure(columns, (sheetIdx, row, col) => {
+            const v = values.get(`${sheetIdx}:${row}:${col}`);
+            return (v ?? 'empty');
+        });
+    }
+}

package/dist/permissions/index.d.ts

@@ -0,0 +1,32 @@
+declare class CallerRegistry {
+    private _entries;
+    private _blockOwners;
+    private _fieldPositions;
+    getUserUuid(): string;
+    getCraftUuid(craftId: string): string;
+    isUser(uuid: string | undefined): boolean;
+    registerBlockOwner(sheetIdx: number, blockId: number, callerUuid: string): void;
+    getBlockOwner(sheetIdx: number, blockId: number): string | undefined;
+    /**
+     * Register the field at a specific block-relative position.
+     * `axis = 'col'` — column-oriented form (one field per column);
+     * `axis = 'row'` — row-oriented form (one field per row).
+     */
+    registerFieldPosition(sheetIdx: number, blockId: number, axis: 'col' | 'row', offset: number, renderId: string): void;
+    getFieldRenderId(sheetIdx: number, blockId: number, blockRow: number, blockCol: number): string | undefined;
+    private _getOrAssign;
+}
+export declare const callerRegistry: CallerRegistry;
+/** Minimal shape needed to decide static editability — a subset of the
+ * engine's FieldInfo. `userEditable` may be a boolean or a formula string. */
+export interface FieldEditableInfo {
+    userEditable?: boolean | string;
+}
+/**
+ * Whether a field permits user edits based on its static declaration alone
+ * (ignoring any dynamic formula). `userEditable === false` blocks; `true`,
+ * `undefined`, or a formula string permits (the formula is enforced
+ * downstream via a shadow value).
+ */
+export declare function isFieldUserEditable(fi: FieldEditableInfo | undefined): boolean;
+export {};

package/dist/permissions/index.js

@@ -0,0 +1,74 @@
+// Permissions — caller identity registry + the pure editability predicate.
+//
+// The CallerRegistry is plain in-process state (no engine, no UI): it maps
+// caller identities to uuids, blocks to owners, and block-relative field
+// positions to renderIds. It's the shared foundation the App's permission glue
+// (patch.ts, field-editable.ts) builds on — moving it here makes it usable from
+// the Node runtime too.
+//
+// The engine-integration parts (monkey-patching the WorkbookClient, toast
+// feedback, resolving FieldInfo via the live engine) stay in the App: they are
+// UI/runtime glue, not portable logic.
+import { simpleUuid } from '../utils/index.js';
+const USER_KEY = '__user__';
+class CallerRegistry {
+    constructor() {
+        this._entries = new Map();
+        this._blockOwners = new Map();
+        // (sheetIdx, blockId, block-relative col) → field renderId. Populated
+        // when patch.ts observes a bindFormSchema payload. Lets the cellInput
+        // validator look up the FieldInfo for any block cell to enforce
+        // FieldInfo.userEditable.
+        this._fieldPositions = new Map();
+    }
+    getUserUuid() {
+        return this._getOrAssign(USER_KEY);
+    }
+    getCraftUuid(craftId) {
+        if (craftId === USER_KEY) {
+            throw new Error(`invalid craftId: ${craftId}`);
+        }
+        return this._getOrAssign(craftId);
+    }
+    isUser(uuid) {
+        return uuid === this._entries.get(USER_KEY);
+    }
+    registerBlockOwner(sheetIdx, blockId, callerUuid) {
+        this._blockOwners.set(`${sheetIdx}-${blockId}`, callerUuid);
+    }
+    getBlockOwner(sheetIdx, blockId) {
+        return this._blockOwners.get(`${sheetIdx}-${blockId}`);
+    }
+    /**
+     * Register the field at a specific block-relative position.
+     * `axis = 'col'` — column-oriented form (one field per column);
+     * `axis = 'row'` — row-oriented form (one field per row).
+     */
+    registerFieldPosition(sheetIdx, blockId, axis, offset, renderId) {
+        this._fieldPositions.set(`${sheetIdx}-${blockId}-${axis}-${offset}`, renderId);
+    }
+    getFieldRenderId(sheetIdx, blockId, blockRow, blockCol) {
+        // Try column-oriented form first, then row-oriented. A block
+        // shouldn't be bound to both — first hit wins.
+        return (this._fieldPositions.get(`${sheetIdx}-${blockId}-col-${blockCol}`) ??
+            this._fieldPositions.get(`${sheetIdx}-${blockId}-row-${blockRow}`));
+    }
+    _getOrAssign(key) {
+        const existing = this._entries.get(key);
+        if (existing)
+            return existing;
+        const uuid = simpleUuid();
+        this._entries.set(key, uuid);
+        return uuid;
+    }
+}
+export const callerRegistry = new CallerRegistry();
+/**
+ * Whether a field permits user edits based on its static declaration alone
+ * (ignoring any dynamic formula). `userEditable === false` blocks; `true`,
+ * `undefined`, or a formula string permits (the formula is enforced
+ * downstream via a shadow value).
+ */
+export function isFieldUserEditable(fi) {
+    return fi?.userEditable !== false;
+}

package/dist/port.d.ts

@@ -0,0 +1,9 @@
+import type { Client } from 'logisheets-web';
+export type { Client };
+/**
+ * Anything in logisheets-core that needs to reach the engine takes one of
+ * these instead of importing a concrete client. Tests pass a mock.
+ */
+export interface HasClient {
+    readonly client: Client;
+}

package/dist/port.js

@@ -0,0 +1,14 @@
+// The dependency seam.
+//
+// logisheets-core is pure logic and must not bundle a backend. It talks to
+// the engine ONLY through the `Client` interface, which it imports as a TYPE
+// from logisheets-web. `import type` is erased at compile time, so this file
+// produces NO runtime dependency on logisheets-web (or on logisheets-node).
+//
+// The concrete Client is INJECTED by the host:
+//   - browser app   -> logisheets-engine's worker-backed WorkbookClient
+//   - node runtime  -> logisheets' synchronous handle()-based client
+//
+// Both implement the same `Client` interface (node's source is a copy of
+// web's), so logisheets-core never needs to know which one it got.
+export {};

package/dist/selection/index.d.ts

@@ -0,0 +1 @@
+export * from './model.js';

package/dist/selection/index.js

@@ -0,0 +1 @@
+export * from './model.js';

package/dist/selection/model.d.ts

@@ -0,0 +1,10 @@
+export declare class SelectionModel<T> {
+    #private;
+    readonly multi: boolean;
+    readonly data: readonly T[];
+    constructor(multi?: boolean, data?: readonly T[]);
+    get selected(): readonly T[];
+    toggle(data: T): void;
+    select(data: T): void;
+    deSelect(data: T): void;
+}

package/dist/selection/model.js

@@ -0,0 +1,38 @@
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
+var _SelectionModel_selected;
+export class SelectionModel {
+    constructor(multi = false, data = []) {
+        this.multi = multi;
+        this.data = data;
+        _SelectionModel_selected.set(this, new Map());
+        data.forEach((d) => {
+            __classPrivateFieldGet(this, _SelectionModel_selected, "f").set(d, true);
+        });
+    }
+    get selected() {
+        const selecteds = [];
+        __classPrivateFieldGet(this, _SelectionModel_selected, "f").forEach((checked, d) => {
+            if (!checked)
+                return;
+            selecteds.push(d);
+        });
+        return selecteds;
+    }
+    toggle(data) {
+        if (__classPrivateFieldGet(this, _SelectionModel_selected, "f").has(data))
+            __classPrivateFieldGet(this, _SelectionModel_selected, "f").set(data, true);
+        else
+            __classPrivateFieldGet(this, _SelectionModel_selected, "f").set(data, false);
+    }
+    select(data) {
+        __classPrivateFieldGet(this, _SelectionModel_selected, "f").set(data, true);
+    }
+    deSelect(data) {
+        __classPrivateFieldGet(this, _SelectionModel_selected, "f").set(data, false);
+    }
+}
+_SelectionModel_selected = new WeakMap();