logisheets-core 1.15.0 → 1.16.0

package/README.md

@@ -35,8 +35,8 @@ declare const client: Client // supplied by the host (browser worker or Node)
 const ops = new WorkbookOps(client)
 
 await ops.inputCell(0, 0, 0, 'Hello')          // sheet 0, cell A1
-await ops.createSheet(1, 'Summary')
-await ops.setSheetColor(0, '#4472C4')
+await ops.createSheet('Summary', 1)
+await ops.setSheetColor(0, 'FF4472C4') // ARGB hex, no '#'
 ```
 
 `WorkbookOps` covers cell input (including block cells and cell images), sheet

package/dist/craft/events.js

@@ -60,7 +60,8 @@ export function dispatchCraftCanvasEvent(evt) {
         return { handled: false };
     try {
         const r = handler(evt);
-        const handled = r === true || (typeof r === 'object' && r !== null && r.handled === true);
+        const handled = r === true ||
+            (typeof r === 'object' && r !== null && r.handled === true);
         return { handled };
     }
     catch (e) {

package/dist/craft/manifest.d.ts

@@ -1,10 +1,13 @@
+/** Where a craft's code lives. Resolved by a host's `CraftRegistry`. */
 export interface CraftManifest {
     /**
-     * The path of the runtime JS file
+     * Locator of the headless runtime JS, interpreted by the registry (a URL
+     * for logisheets-runtime's HttpCraftRegistry). Empty means the craft has
+     * no runtime and a headless host skips it.
      */
     readonly rtJs: string;
     /**
-     * The path of the html url which is used in web
+     * URL of the craft's browser UI page (loaded in the craft panel iframe).
      */
     readonly html: string;
 }

package/dist/craft/runtime.d.ts

@@ -31,7 +31,16 @@ export type MaybePromise<T> = T | Promise<T>;
  *   onResponse  the response has been produced and is about to be returned
  */
 export interface CraftRuntime<S extends CraftState = CraftState, W = unknown> {
+    /**
+     * Rehydrate from the state the craft saved. Returning an `ErrorMessage`
+     * makes the host skip this craft. `s` is the parsed state object; the
+     * host passes the SAME object to every later hook.
+     */
     onLoad: (s: S, wb: W) => MaybePromise<Result<void>>;
+    /**
+     * Write the request's inputs into the workbook. Return an `ErrorMessage`
+     * (or throw) to object; the host then rejects the request.
+     */
     onRequest: (req: JsonRpcRequest, s: S, wb: W) => MaybePromise<Result<void>>;
     /**
      * Called once an RPC request's inputs have been written into the workbook
@@ -42,5 +51,10 @@ export interface CraftRuntime<S extends CraftState = CraftState, W = unknown> {
      * input. Optional: a craft with no validation needs simply omits it.
      */
     onValidate?: (s: S, wb: W) => MaybePromise<Result<readonly Violation[]>>;
+    /**
+     * Fill `resp` (typically `resp.result`) from the workbook. It is mutated
+     * in place: the host returns the same object. Return an `ErrorMessage`
+     * (or throw) to turn the reply into an error.
+     */
     onResponse: (resp: JsonRpcResponse, s: S, wb: W) => MaybePromise<Result<void>>;
 }

package/dist/craft/state.d.ts

@@ -1,5 +1,17 @@
+/** Push a craft's serialized state (replaces the previous one). Called from
+ *  the iframe-injected `setCraftState`; `craftId` is captured per-iframe by
+ *  the host. An empty `craftId` is ignored. Not written to the engine until
+ *  the host next saves the file. */
 export declare function setCraftState(craftId: string, json: string): void;
+/** A craft's last-known state (e.g. the one rehydrated from the loaded
+ *  workbook), or undefined if the craft never stored anything. */
 export declare function getCraftState(craftId: string): string | undefined;
+/** Forget a craft's state; the next save omits it. */
 export declare function clearCraftState(craftId: string): void;
+/** Snapshot every craft's state, for the host to fold into the AppData
+ *  envelope's `craftStates` on save. */
 export declare function getPersistentCraftStates(): Record<string, string>;
+/** Rehydrate from a previously-persisted snapshot. Replaces the current
+ *  contents, so a freshly-loaded workbook doesn't inherit state from a prior
+ *  one; non-string entries are dropped. Pass `undefined` to reset. */
 export declare function loadPersistentCraftStates(data: unknown): void;

package/dist/craft/state.js

@@ -12,31 +12,35 @@
 // undo/redo Status (it rides AppData, a side channel on the workbook), so
 // writing it never pollutes edit history.
 const craftStates = new Map();
-// Push a craft's serialized state. Called from the iframe-injected
-// `setCraftState`; `craftId` is captured per-iframe by the host.
+/** Push a craft's serialized state (replaces the previous one). Called from
+ *  the iframe-injected `setCraftState`; `craftId` is captured per-iframe by
+ *  the host. An empty `craftId` is ignored. Not written to the engine until
+ *  the host next saves the file. */
 export function setCraftState(craftId, json) {
     if (!craftId)
         return;
     craftStates.set(craftId, json);
 }
-// Read a craft's last-known state (e.g. the one rehydrated from the loaded
-// workbook). Returns undefined if the craft never stored anything.
+/** A craft's last-known state (e.g. the one rehydrated from the loaded
+ *  workbook), or undefined if the craft never stored anything. */
 export function getCraftState(craftId) {
     return craftStates.get(craftId);
 }
+/** Forget a craft's state; the next save omits it. */
 export function clearCraftState(craftId) {
     craftStates.delete(craftId);
 }
-// Snapshot every craft's state for persistence into the AppData envelope.
+/** Snapshot every craft's state, for the host to fold into the AppData
+ *  envelope's `craftStates` on save. */
 export function getPersistentCraftStates() {
     const out = {};
     for (const [craftId, json] of craftStates)
         out[craftId] = json;
     return out;
 }
-// Rehydrate the store from a previously-persisted snapshot. Replaces the
-// current contents so a freshly-loaded workbook doesn't inherit stale state
-// from a prior one.
+/** Rehydrate from a previously-persisted snapshot. Replaces the current
+ *  contents, so a freshly-loaded workbook doesn't inherit state from a prior
+ *  one; non-string entries are dropped. Pass `undefined` to reset. */
 export function loadPersistentCraftStates(data) {
     craftStates.clear();
     if (!data || typeof data !== 'object')

package/dist/craft-interactions/index.d.ts

@@ -7,11 +7,16 @@ export interface RadioBinding {
     col: number;
     value: string;
 }
+/** Listen for ANY change to the interaction store (every widget kind, not
+ *  just radios). Returns an unsubscribe function. */
 export declare function subscribeRadioBindings(listener: () => void): () => void;
 export declare function registerRadioBinding(binding: RadioBinding): void;
 export declare function unregisterRadioBinding(binding: Pick<RadioBinding, 'groupId' | 'blockId' | 'row' | 'col'>): void;
+/** Remove a group's radio bindings and selection, or every group's when
+ *  `groupId` is omitted. */
 export declare function clearRadioBindings(groupId?: string): void;
 export declare function getRadioBindings(): readonly RadioBinding[];
+/** The `value` of the group's selected binding, if any. */
 export declare function getRadioSelection(groupId: string): string | undefined;
 export declare function setRadioSelection(groupId: string, value: string): void;
 export interface MultiSelectBinding {
@@ -27,9 +32,13 @@ export declare function registerMultiSelectBinding(binding: MultiSelectBinding):
 export declare function unregisterMultiSelectBinding(binding: Pick<MultiSelectBinding, 'groupId' | 'blockId' | 'row' | 'col'>): void;
 export declare function clearMultiSelectBindings(groupId?: string): void;
 export declare function getMultiSelectBindings(): readonly MultiSelectBinding[];
+/** Cap a group's selections (negative clamps to 0). Until set, a group has
+ *  no cap when toggling, though {@link getMultiSelectMax} reports 0. */
 export declare function setMultiSelectMax(groupId: string, max: number): void;
 export declare function getMultiSelectMax(groupId: string): number;
 export declare function getMultiSelectSelections(groupId: string): string[];
+/** Select `value` if unselected and under the cap, deselect it if
+ *  selected. A select past the cap is silently ignored. */
 export declare function toggleMultiSelectValue(groupId: string, value: string): void;
 export interface PointAllocatorBinding {
     type: 'pointAllocator';
@@ -49,6 +58,8 @@ export declare function registerPointAllocator(binding: PointAllocatorBinding):
 export declare function unregisterPointAllocator(binding: Pick<PointAllocatorBinding, 'groupId' | 'blockId' | 'row' | 'col'>): void;
 export declare function clearPointAllocators(groupId?: string): void;
 export declare function getPointAllocatorBindings(): readonly PointAllocatorBinding[];
+/** Set a group's point budget (negative clamps to 0). Shrinking it does not
+ *  take back points already allocated, so `remaining` can go negative. */
 export declare function setPointPool(groupId: string, total: number): void;
 export declare function getPointPool(groupId: string): {
     total: number;
@@ -73,6 +84,8 @@ export declare function registerNumberSlider(binding: NumberSliderBinding): void
 export declare function unregisterNumberSlider(binding: Pick<NumberSliderBinding, 'groupId' | 'blockId' | 'row' | 'col'>): void;
 export declare function clearNumberSliders(groupId?: string): void;
 export declare function getNumberSliderBindings(): readonly NumberSliderBinding[];
+/** Add `delta` points to one cell (negative removes), clamped so the group
+ *  never exceeds its pool and a cell never goes below 0. */
 export declare function adjustPointAllocation(binding: Pick<PointAllocatorBinding, 'groupId' | 'blockId' | 'row' | 'col'>, delta: number): void;
 export interface PercentAllocatorBinding {
     type: 'percentAllocator';
@@ -135,6 +148,10 @@ interface PersistedShape {
     numberSliderBindings: NumberSliderBinding[];
     percentBindings: PercentAllocatorBinding[];
 }
+/** Snapshot every binding and user selection, for the host to fold into the
+ *  AppData envelope's `craftInteractions` on save. */
 export declare function getPersistentInteractions(): PersistedShape;
+/** Replace the whole store from a snapshot (as written by
+ *  {@link getPersistentInteractions}); malformed entries are dropped. */
 export declare function loadPersistentInteractions(data: unknown): void;
 export {};

package/dist/craft-interactions/index.js

@@ -1,3 +1,23 @@
+// Craft interactions — host-drawn widgets bound to block cells.
+//
+// A craft registers bindings (radio, multi-select, point allocator, number
+// slider, percent allocator); the host draws an overlay on each bound cell and
+// records what the user picks. The browser injects these functions onto the
+// craft iframe (`window.registerRadio`, `window.getRadioSelection`, ...; see
+// the app's craft-interaction layer), and the craft reads results back on
+// demand. Nothing here writes to the workbook.
+//
+// Conventions for every binding:
+//   - `row` / `col` are BLOCK-relative, counted from the block's master cell,
+//     so a binding follows its block when the block moves.
+//   - A binding is keyed by (groupId, blockId, row, col); registering the same
+//     key again replaces it. `sheetIdx` is NOT part of the key, so the same
+//     key on two sheets collides.
+//   - State is one module-level store per process; subscribers
+//     ({@link subscribeRadioBindings}) hear about every change of every kind.
+//   - Radio / multi-select / point selections live HERE, not in cells, and
+//     persist through {@link getPersistentInteractions} on save. Slider and
+//     percent values live in the cells themselves.
 const radioBindings = new Map();
 const groupSelections = new Map();
 const storeListeners = new Set();
@@ -8,6 +28,8 @@ function notifyStore() {
     for (const l of storeListeners)
         l();
 }
+/** Listen for ANY change to the interaction store (every widget kind, not
+ *  just radios). Returns an unsubscribe function. */
 export function subscribeRadioBindings(listener) {
     storeListeners.add(listener);
     return () => {
@@ -22,6 +44,8 @@ export function unregisterRadioBinding(binding) {
     radioBindings.delete(bindingKey(binding));
     notifyStore();
 }
+/** Remove a group's radio bindings and selection, or every group's when
+ *  `groupId` is omitted. */
 export function clearRadioBindings(groupId) {
     if (groupId === undefined) {
         radioBindings.clear();
@@ -39,6 +63,7 @@ export function clearRadioBindings(groupId) {
 export function getRadioBindings() {
     return Array.from(radioBindings.values());
 }
+/** The `value` of the group's selected binding, if any. */
 export function getRadioSelection(groupId) {
     return groupSelections.get(groupId);
 }
@@ -79,6 +104,8 @@ export function clearMultiSelectBindings(groupId) {
 export function getMultiSelectBindings() {
     return Array.from(multiSelectBindings.values());
 }
+/** Cap a group's selections (negative clamps to 0). Until set, a group has
+ *  no cap when toggling, though {@link getMultiSelectMax} reports 0. */
 export function setMultiSelectMax(groupId, max) {
     multiSelectMax.set(groupId, Math.max(0, max));
     notifyStore();
@@ -89,6 +116,8 @@ export function getMultiSelectMax(groupId) {
 export function getMultiSelectSelections(groupId) {
     return Array.from(multiSelectSelections.get(groupId) ?? []);
 }
+/** Select `value` if unselected and under the cap, deselect it if
+ *  selected. A select past the cap is silently ignored. */
 export function toggleMultiSelectValue(groupId, value) {
     let set = multiSelectSelections.get(groupId);
     if (!set) {
@@ -151,6 +180,8 @@ export function clearPointAllocators(groupId) {
 export function getPointAllocatorBindings() {
     return Array.from(pointBindings.values());
 }
+/** Set a group's point budget (negative clamps to 0). Shrinking it does not
+ *  take back points already allocated, so `remaining` can go negative. */
 export function setPointPool(groupId, total) {
     pointPoolTotals.set(groupId, Math.max(0, total));
     notifyStore();
@@ -203,6 +234,8 @@ export function clearNumberSliders(groupId) {
 export function getNumberSliderBindings() {
     return Array.from(numberSliderBindings.values());
 }
+/** Add `delta` points to one cell (negative removes), clamped so the group
+ *  never exceeds its pool and a cell never goes below 0. */
 export function adjustPointAllocation(binding, delta) {
     const { groupId, blockId, row, col } = binding;
     let m = pointAllocations.get(groupId);
@@ -328,6 +361,8 @@ export function redistributePercent(current, targetIdx, deltaPct) {
     }
     return next;
 }
+/** Snapshot every binding and user selection, for the host to fold into the
+ *  AppData envelope's `craftInteractions` on save. */
 export function getPersistentInteractions() {
     const out = {
         radioBindings: Array.from(radioBindings.values()),
@@ -361,6 +396,8 @@ export function getPersistentInteractions() {
     }
     return out;
 }
+/** Replace the whole store from a snapshot (as written by
+ *  {@link getPersistentInteractions}); malformed entries are dropped. */
 export function loadPersistentInteractions(data) {
     // Always clear first, then repopulate from whatever the workbook carried.
     // Passing undefined/null (a workbook with no interaction state) therefore

package/dist/format/index.d.ts

@@ -1,23 +1,58 @@
 import type { Alignment, Payload, StPatternType, StBorderStyle, SelectedData } from 'logisheets-web';
+/** A partial font change: only the fields present are applied. */
 export interface FontStyle {
     bold?: boolean;
+    /** `true` sets a single underline, `false` removes it. */
     underline?: boolean;
     italic?: boolean;
+    /**
+     * 8-hex-digit ARGB with NO `#`, e.g. `'FF1976D2'`. Passed to the engine
+     * unchanged: a `#RRGGBB` or 6-digit value yields no color and silently
+     * does not render. `''` is ignored rather than clearing the color.
+     */
     color?: string;
+    /** Point size. `0` is ignored. */
     size?: number;
     strike?: boolean;
     /** Font family name, e.g. "Arial", "Times New Roman", "Microsoft YaHei". */
     name?: string;
 }
+/**
+ * Font payloads for the selection: one `cellStyleUpdate` per cell of a cell
+ * range, or one `lineStyleUpdate` for a row/column selection. `[]` when
+ * nothing is selected.
+ */
 export declare function generateFontPayload(sheetIdx: number, data: SelectedData, update: FontStyle): readonly Payload[];
+/** Alignment payloads for the selection (same shape rules as
+ *  {@link generateFontPayload}). */
 export declare function generateAlgnmentPayload(sheetIdx: number, data: SelectedData, alignment: Alignment): readonly Payload[];
 export declare function generateWrapTextPayload(sheetIdx: number, data: SelectedData, wrapText: boolean): readonly Payload[];
 export declare function generateNumFmtPayload(sheetIdx: number, data: SelectedData, numFmt: string): readonly Payload[];
+/**
+ * Pattern-fill payloads for the selection. Unlike font and border colors,
+ * these take hex strings (`'#RRGGBB'`, `'RRGGBB'` or `'AARRGGBB'`, alpha
+ * dropped) and convert them to the engine's `{red, green, blue}` 0-255
+ * objects. Omitted / empty colors leave that part of the fill unchanged.
+ */
 export declare function generatePatternFillPayload(sheetIdx: number, data: SelectedData, fgColor?: string, bgColor?: string, pattern?: StPatternType): readonly Payload[];
 export type BatchUpdateType = 'all' | 'top' | 'bottom' | 'left' | 'right' | 'horizontal' | 'vertical' | 'outer' | 'inner' | 'clear';
+/** Which edges of the selection to set, and how. */
 export interface BorderBatchUpdate {
+    /** Which edges: one side, all/outer/inner, or the inner horizontal or
+     *  vertical lines. `clear` currently generates no payloads at all. */
     batch: BatchUpdateType;
+    /** 8-hex-digit ARGB, e.g. `'FF000000'`. A leading `#` is stripped and
+     *  the value upper-cased, but a 6-digit value is NOT expanded and will
+     *  not render. */
     color?: string;
     borderType?: StBorderStyle;
 }
+/**
+ * Border payloads for the selection. Setting an edge also clears the facing
+ * edge of the neighbouring cell (its bottom for a top edge, and so on), so
+ * two conflicting borders never share one grid line.
+ *
+ * Mutates `update.color` in place (strips `#`, upper-cases); pass a copy if
+ * the caller keeps the object.
+ */
 export declare function generateBorderPayloads(sheetIdx: number, data: SelectedData, update: BorderBatchUpdate): readonly Payload[];

package/dist/format/index.js

@@ -18,6 +18,9 @@ function selectedCellRange(v) {
 function selectedLines(v) {
     return v.data?.ty === 'line' ? v.data.d : undefined;
 }
+// Fills are the one place the engine takes an `{red, green, blue}` object
+// rather than an ARGB string, so the fill generator converts here. Accepts
+// `#RRGGBB`, `RRGGBB` or 8-digit ARGB (alpha dropped).
 function hexToColor(hex) {
     let h = hex.startsWith('#') ? hex.slice(1) : hex;
     // ARGB format (8 chars): skip the first 2 alpha chars
@@ -35,6 +38,11 @@ function cellStyle(sheetIdx, row, col, ty) {
 function lineStyle(sheetIdx, from, to, row, ty) {
     return { type: 'lineStyleUpdate', value: { sheetIdx, from, to, row, ty } };
 }
+/**
+ * Font payloads for the selection: one `cellStyleUpdate` per cell of a cell
+ * range, or one `lineStyleUpdate` for a row/column selection. `[]` when
+ * nothing is selected.
+ */
 export function generateFontPayload(sheetIdx, data, update) {
     if (!data.data)
         return [];
@@ -79,6 +87,8 @@ export function generateFontPayload(sheetIdx, data, update) {
         lineTy.setFontName = update.name;
     return [lineStyle(sheetIdx, d.start, d.end, d.type === 'row', lineTy)];
 }
+/** Alignment payloads for the selection (same shape rules as
+ *  {@link generateFontPayload}). */
 export function generateAlgnmentPayload(sheetIdx, data, alignment) {
     return generateForSelection(sheetIdx, data, { setAlignment: alignment });
 }
@@ -88,6 +98,12 @@ export function generateWrapTextPayload(sheetIdx, data, wrapText) {
 export function generateNumFmtPayload(sheetIdx, data, numFmt) {
     return generateForSelection(sheetIdx, data, { setNumFmt: numFmt });
 }
+/**
+ * Pattern-fill payloads for the selection. Unlike font and border colors,
+ * these take hex strings (`'#RRGGBB'`, `'RRGGBB'` or `'AARRGGBB'`, alpha
+ * dropped) and convert them to the engine's `{red, green, blue}` 0-255
+ * objects. Omitted / empty colors leave that part of the fill unchanged.
+ */
 export function generatePatternFillPayload(sheetIdx, data, fgColor, bgColor, pattern) {
     const fill = {};
     if (fgColor)
@@ -113,6 +129,14 @@ function generateForSelection(sheetIdx, data, ty) {
     const d = data.data.d;
     return [lineStyle(sheetIdx, d.start, d.end, d.type === 'row', ty)];
 }
+/**
+ * Border payloads for the selection. Setting an edge also clears the facing
+ * edge of the neighbouring cell (its bottom for a top edge, and so on), so
+ * two conflicting borders never share one grid line.
+ *
+ * Mutates `update.color` in place (strips `#`, upper-cases); pass a copy if
+ * the caller keeps the object.
+ */
 export function generateBorderPayloads(sheetIdx, data, update) {
     if (update.color) {
         if (update.color.startsWith('#'))

package/dist/index.js

@@ -2,7 +2,25 @@
 //
 // Runs unchanged in the browser app and in a Node runtime. It depends on
 // logisheets-web for TYPES only (see ./port); the concrete engine Client is
-// injected by the host.
+// injected by the host: logisheets-engine's worker client in the browser,
+// logisheets-runtime's `handle()` proxy on Node. ESM only.
+//
+// Main exports:
+//   - WorkbookOps (./ops): the high-level operation layer. Every engine-facing
+//     operation a host offers (cell input, sheets, blocks, form schemas,
+//     analysis blocks, pivots, formatting, validation) lives here once.
+//   - format generators (./format): pure selection -> style payload builders.
+//   - craft contracts (./craft): CraftRuntime (the headless craft hooks),
+//     craft state (per-document, rides AppData), craft storage (per-device),
+//     canvas-input routing, the JSON-RPC wire types.
+//   - craft interactions (./craft-interactions): host-drawn widgets (radio,
+//     multi-select, allocators, sliders) crafts bind to block cells.
+//   - validation, field authoring model, Value helpers, permissions registry,
+//     string / A1 / type-guard utilities.
+//
+// Module-level stores (craft state, storage backend, interactions, active
+// craft, callerRegistry) are process singletons: one workbook per host
+// process is assumed. A Node host serving several workbooks shares them.
 export * from './port.js';
 export * from './ops/index.js';
 export * from './format/index.js';

package/dist/ops/index.d.ts

@@ -218,6 +218,23 @@ export interface PivotRefresh {
 /**
  * High-level workbook operations bound to one engine {@link Client}.
  * Construct one per workbook and share it across the host.
+ *
+ * Indexes are 0-based; `sheetIdx` is the tab position. Block-relative
+ * `row`/`col` count from the block's master (top-left) cell.
+ *
+ * Failure contract, read before relying on a write:
+ *  - An operation THROWS (rejects) when the engine answers a call with an
+ *    `ErrorMessage`, and when this layer refuses its inputs (documented per
+ *    method).
+ *  - An operation does NOT throw when the engine refuses the edit itself.
+ *    The engine reports that as an `ActionEffect` with
+ *    `status.type === 'err'` (reason in `errorMessage`) and applies nothing.
+ *    Methods returning `Promise<ActionEffect>` hand that effect back: check
+ *    `status`. Methods returning `Promise<void>` or a summary DROP it, so a
+ *    refused transaction looks like success there.
+ *
+ * Every transaction is built at the injected {@link TempModeProvider}'s
+ * current value, so in the browser's temp mode these writes are speculative.
  */
 export declare class WorkbookOps {
     private readonly client;
@@ -228,7 +245,9 @@ export declare class WorkbookOps {
     /**
      * 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.
+     * normal try/catch instead of inspecting a union. An engine REJECTION is
+     * not an ErrorMessage: it comes back as the effect with `status.type ===
+     * 'err'` and is returned, not thrown.
      */
     private apply;
     /** Write a value or formula into a cell. */
@@ -263,7 +282,11 @@ export declare class WorkbookOps {
     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). */
+    /**
+     * Set a sheet tab's color: 8-hex ARGB with no `#` (e.g. `'FF4472C4'`),
+     * or `''` to clear. Stored verbatim and written to the file's `tabColor`;
+     * nothing validates or normalises 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>;
@@ -298,7 +321,8 @@ export declare class WorkbookOps {
      * re-`bindFormSchema` is needed.
      */
     moveBlockLine(sheetIdx: number, blockId: number, from: number, to: number, isRow?: boolean, undoable?: boolean): Promise<ActionEffect>;
-    /** Apply font styling (bold/italic/underline/strike/color/size). */
+    /** Apply font styling (bold/italic/underline/strike/color/size). The
+     *  color is 8-hex ARGB with no `#`, see {@link FontStyle}. */
     setFont(sheetIdx: number, data: SelectedData, update: FontStyle): Promise<void>;
     /** Apply horizontal/vertical alignment. */
     setAlignment(sheetIdx: number, data: SelectedData, alignment: Alignment): Promise<void>;
@@ -306,13 +330,16 @@ export declare class WorkbookOps {
     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). */
+    /** Apply a pattern fill (foreground/background color + pattern). Colors
+     *  are hex strings here (`'#RRGGBB'`, `'RRGGBB'` or `'AARRGGBB'`), turned
+     *  into the engine's `{red, green, blue}` objects; alpha is dropped. */
     setPatternFill(sheetIdx: number, data: SelectedData, opts: {
         fgColor?: string;
         bgColor?: string;
         pattern?: StPatternType;
     }): Promise<void>;
-    /** Apply borders to the selection per the batch directive. */
+    /** Apply borders to the selection per the batch directive. The color is
+     *  8-hex ARGB (a leading `#` is stripped), see {@link BorderBatchUpdate}. */
     setBorder(sheetIdx: number, data: SelectedData, update: BorderBatchUpdate): Promise<void>;
     /** Apply a generated payload list, skipping the round-trip when empty. */
     private applyGenerated;
@@ -708,6 +735,11 @@ export declare class WorkbookOps {
      * 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.
+     *
+     * Each call takes a NEW ephemeral id (from 1, per WorkbookOps instance)
+     * and never removes the cell, so the cells accumulate, and keep
+     * recomputing, for the life of the loaded workbook. A rejected write is not
+     * detected: the read-back then yields whatever the slot holds.
      */
     evalFormula(sheetIdx: number, formula: string): Promise<Value>;
     /**

package/dist/ops/index.js

@@ -146,6 +146,23 @@ function toSchemaFieldSpec(f) {
 /**
  * High-level workbook operations bound to one engine {@link Client}.
  * Construct one per workbook and share it across the host.
+ *
+ * Indexes are 0-based; `sheetIdx` is the tab position. Block-relative
+ * `row`/`col` count from the block's master (top-left) cell.
+ *
+ * Failure contract, read before relying on a write:
+ *  - An operation THROWS (rejects) when the engine answers a call with an
+ *    `ErrorMessage`, and when this layer refuses its inputs (documented per
+ *    method).
+ *  - An operation does NOT throw when the engine refuses the edit itself.
+ *    The engine reports that as an `ActionEffect` with
+ *    `status.type === 'err'` (reason in `errorMessage`) and applies nothing.
+ *    Methods returning `Promise<ActionEffect>` hand that effect back: check
+ *    `status`. Methods returning `Promise<void>` or a summary DROP it, so a
+ *    refused transaction looks like success there.
+ *
+ * Every transaction is built at the injected {@link TempModeProvider}'s
+ * current value, so in the browser's temp mode these writes are speculative.
  */
 export class WorkbookOps {
     constructor(client, tempMode = () => false) {
@@ -157,7 +174,9 @@ export class WorkbookOps {
     /**
      * 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.
+     * normal try/catch instead of inspecting a union. An engine REJECTION is
+     * not an ErrorMessage: it comes back as the effect with `status.type ===
+     * 'err'` and is returned, not thrown.
      */
     async apply(payloads, undoable) {
         const transaction = makeTransaction(payloads, undoable, this.tempMode());
@@ -226,7 +245,11 @@ export class WorkbookOps {
     deleteSheet(idx) {
         return this.apply([{ type: 'deleteSheet', value: { idx } }], true);
     }
-    /** Set a sheet tab's color (ARGB string; empty clears it). */
+    /**
+     * Set a sheet tab's color: 8-hex ARGB with no `#` (e.g. `'FF4472C4'`),
+     * or `''` to clear. Stored verbatim and written to the file's `tabColor`;
+     * nothing validates or normalises it.
+     */
     setSheetColor(idx, color) {
         return this.apply([{ type: 'setSheetColor', value: { idx, color } }], true);
     }
@@ -313,7 +336,8 @@ export class WorkbookOps {
     // 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). */
+    /** Apply font styling (bold/italic/underline/strike/color/size). The
+     *  color is 8-hex ARGB with no `#`, see {@link FontStyle}. */
     async setFont(sheetIdx, data, update) {
         await this.applyGenerated(generateFontPayload(sheetIdx, data, update));
     }
@@ -329,11 +353,14 @@ export class WorkbookOps {
     async setNumFmt(sheetIdx, data, numFmt) {
         await this.applyGenerated(generateNumFmtPayload(sheetIdx, data, numFmt));
     }
-    /** Apply a pattern fill (foreground/background color + pattern). */
+    /** Apply a pattern fill (foreground/background color + pattern). Colors
+     *  are hex strings here (`'#RRGGBB'`, `'RRGGBB'` or `'AARRGGBB'`), turned
+     *  into the engine's `{red, green, blue}` objects; alpha is dropped. */
     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. */
+    /** Apply borders to the selection per the batch directive. The color is
+     *  8-hex ARGB (a leading `#` is stripped), see {@link BorderBatchUpdate}. */
     async setBorder(sheetIdx, data, update) {
         await this.applyGenerated(generateBorderPayloads(sheetIdx, data, update));
     }
@@ -1367,6 +1394,11 @@ export class WorkbookOps {
      * 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.
+     *
+     * Each call takes a NEW ephemeral id (from 1, per WorkbookOps instance)
+     * and never removes the cell, so the cells accumulate, and keep
+     * recomputing, for the life of the loaded workbook. A rejected write is not
+     * detected: the read-back then yields whatever the slot holds.
      */
     async evalFormula(sheetIdx, formula) {
         const id = this.ephemeralSeq++;

package/dist/permissions/index.d.ts

@@ -1,8 +1,17 @@
+/**
+ * Session-scoped caller identities. The user and each craft get a random uuid
+ * on first ask; a host tags each write with it and later maps it back (via
+ * {@link resolveActor}) to the actor the engine's `mayModifyBlock` expects.
+ * Nothing here persists: uuids and owner records are gone on reload, which
+ * is why block ownership that must survive lives on the engine's block.
+ */
 declare class CallerRegistry {
     private _entries;
     private _blockOwners;
     private _fieldPositions;
+    /** The user's uuid for this session. */
     getUserUuid(): string;
+    /** A craft's uuid for this session. Throws for the reserved user key. */
     getCraftUuid(craftId: string): string;
     isUser(uuid: string | undefined): boolean;
     /**
@@ -21,6 +30,8 @@ declare class CallerRegistry {
         type: 'craft';
         craftId: string;
     } | undefined;
+    /** Record which caller created a block. In-memory only; keyed by
+     *  `sheetIdx`, so it goes stale when sheets move. */
     registerBlockOwner(sheetIdx: number, blockId: number, callerUuid: string): void;
     getBlockOwner(sheetIdx: number, blockId: number): string | undefined;
     /**
@@ -32,5 +43,6 @@ declare class CallerRegistry {
     getFieldRenderId(sheetIdx: number, blockId: number, blockRow: number, blockCol: number): string | undefined;
     private _getOrAssign;
 }
+/** The process-wide registry. */
 export declare const callerRegistry: CallerRegistry;
 export {};

package/dist/permissions/index.js

@@ -1,4 +1,4 @@
-// Permissions — caller identity registry + the pure editability predicate.
+// Permissions — the caller identity registry.
 //
 // The CallerRegistry is plain in-process state (no engine, no UI): it maps
 // caller identities to uuids, blocks to owners, and block-relative field
@@ -11,19 +11,28 @@
 // UI/runtime glue, not portable logic.
 import { simpleUuid } from '../utils/index.js';
 const USER_KEY = '__user__';
+/**
+ * Session-scoped caller identities. The user and each craft get a random uuid
+ * on first ask; a host tags each write with it and later maps it back (via
+ * {@link resolveActor}) to the actor the engine's `mayModifyBlock` expects.
+ * Nothing here persists: uuids and owner records are gone on reload, which
+ * is why block ownership that must survive lives on the engine's block.
+ */
 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.
+        // (sheetIdx, blockId, axis, block-relative offset) → field renderId.
+        // Populated when the app's patch.ts observes a bindFormSchema payload.
+        // It used to back the host-side `userEditable` check; that rule now lives
+        // on the engine schema, and nothing outside tests reads this map.
         this._fieldPositions = new Map();
     }
+    /** The user's uuid for this session. */
     getUserUuid() {
         return this._getOrAssign(USER_KEY);
     }
+    /** A craft's uuid for this session. Throws for the reserved user key. */
     getCraftUuid(craftId) {
         if (craftId === USER_KEY) {
             throw new Error(`invalid craftId: ${craftId}`);
@@ -55,6 +64,8 @@ class CallerRegistry {
         }
         return undefined;
     }
+    /** Record which caller created a block. In-memory only; keyed by
+     *  `sheetIdx`, so it goes stale when sheets move. */
     registerBlockOwner(sheetIdx, blockId, callerUuid) {
         this._blockOwners.set(`${sheetIdx}-${blockId}`, callerUuid);
     }
@@ -84,6 +95,7 @@ class CallerRegistry {
         return uuid;
     }
 }
+/** The process-wide registry. */
 export const callerRegistry = new CallerRegistry();
 // `FieldEditableInfo` and `isFieldUserEditable` used to live here, reading a tri-state `userEditable`
 // boolean off the host's own field store. The field's write policy is declared

package/dist/port.js

@@ -7,8 +7,10 @@
 //
 // The concrete Client is INJECTED by the host:
 //   - browser app   -> logisheets-engine's worker-backed WorkbookClient
-//   - node runtime  -> logisheets' synchronous handle()-based client
+//   - node runtime  -> logisheets-runtime's Proxy over the Node WASM handle(),
+//                      with each synchronous result wrapped in a Promise
 //
-// 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.
+// Both implement the same `Client` interface, so logisheets-core never needs
+// to know which one it got. (The Node proxy leaves the `register*` callback
+// members unimplemented; core code must not depend on them.)
 export {};

package/dist/utils/a1notation.d.ts

@@ -1,4 +1,11 @@
+/** Whether `value` is a cell (`B3`) or range (`A1:C9`) reference,
+ *  case-insensitive. No `$`, no sheet prefix. */
 export declare function isA1notation(value: unknown): boolean;
+/**
+ * Parse a cell or range reference into 0-based indexes: `cs`/`rs` are the
+ * start column/row, `ce`/`re` the end (present for a range only).
+ * `undefined` when the text is not in {@link isA1notation}'s form.
+ */
 export declare function parseA1notation(value: string): {
     cs: number;
     rs: number;

package/dist/utils/a1notation.js

@@ -3,12 +3,18 @@ import { upperCase } from '../strings/index.js';
 import { isString } from '../type-guard/index.js';
 const a1notationReg = /^(?<cs>[A-Z]+)(?<rs>\d+)(:(?<ce>[A-Z]+)(?<re>\d+))?$/i;
 const notationReq = /^[A-Z]/;
+/** Whether `value` is a cell (`B3`) or range (`A1:C9`) reference,
+ *  case-insensitive. No `$`, no sheet prefix. */
 export function isA1notation(value) {
     if (!isString(value))
         return false;
     return a1notationReg.test(upperCase(value));
 }
-// zero-based
+/**
+ * Parse a cell or range reference into 0-based indexes: `cs`/`rs` are the
+ * start column/row, `ce`/`re` the end (present for a range only).
+ * `undefined` when the text is not in {@link isA1notation}'s form.
+ */
 export function parseA1notation(value) {
     const result = upperCase(value).match(a1notationReg);
     if (!result?.groups)

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "logisheets-core",
-    "version": "1.15.0",
+    "version": "1.16.0",
     "description": "UI-free LogiSheets logic — runs in the browser or on Node. Depends on logisheets-web only for types; the engine Client is injected by the host.",
     "main": "./dist/index.js",
     "module": "./dist/index.js",
@@ -63,7 +63,7 @@
     },
     "homepage": "https://github.com/logisky/LogiSheets",
     "peerDependencies": {
-        "logisheets-web": "^1.15.0"
+        "logisheets-web": "^1.16.0"
     },
     "devDependencies": {
         "@types/node": "^18",