@fileverse-dev/dsheet 4.1.23 → 4.1.24-stabilise-package-2

package/README.md

@@ -86,6 +86,7 @@ function App() {
 | `isCollaborative` | `boolean` | `false` | Enable collaborative features |
 | `enableWebrtc` | `boolean` | `true` | Enable WebRTC for P2P collaboration |
 | `enableIndexeddbSync` | `boolean` | `true` | Enable local IndexedDB persistence |
+| `onIndexedDbError` | `(error: Error) => void` | - | Called when local persistence fails, or when the first read of the local store does not finish within 15 s. The editor continues with the in-memory document; call `rebuildLocalStore()` to recreate the store |
 | `isTemplateOpen` | `boolean` | - | Template sidebar state |
 | `selectedTemplate` | `string` | - | Selected template identifier |
 | `onboardingComplete` | `boolean` | - | Onboarding completion status |
@@ -115,6 +116,15 @@ function App() {
 | `setInputFetchURLDataBlock` | `Dispatch<SetStateAction<string>>` | URL input state setter |
 | `setForceSheetRender` | `Dispatch<SetStateAction<number>>` | Force re-render trigger |
 
+### Editor handle methods
+
+`sheetEditorRef` is a `DSheetEditorHandle`: the workbook instance plus these methods.
+
+| Method | Description |
+|--------|-------------|
+| `rebuildLocalStore()` | `Promise<void>`. Deletes this sheet's IndexedDB database and rewrites it from the live document, so local edits are kept. A no-op when read-only or when `enableIndexeddbSync` is off. Rejects if the rebuild fails, the new store does not sync within 15 s, or a refresh or unmount supersedes it. Concurrent calls share one rebuild. |
+| `getContentFingerprint()` | `string \| null`. Changes on every document change, deletes included; compare with `===` only. `null` until local persistence has synced. |
+
 ## Examples
 
 ### Read-Only Viewer

package/dist/editor/components/skeleton-loader.d.ts

@@ -3,7 +3,8 @@ export declare const SkeletonToolbar: ({ isReadOnly, }: {
     isReadOnly: boolean | undefined;
 }) => import("react/jsx-runtime").JSX.Element;
 export declare const SkeletonGrid: () => import("react/jsx-runtime").JSX.Element;
-declare const SkeletonLoader: ({ isReadOnly, }: {
+declare const SkeletonLoader: ({ isReadOnly, active, }: {
     isReadOnly: boolean | undefined;
+    active?: boolean;
 }) => import("react/jsx-runtime").JSX.Element;
 export default SkeletonLoader;

package/dist/editor/contexts/editor-context.d.ts

@@ -10,6 +10,7 @@ import { UseSmartContractReturn } from '../hooks/use-smart-contract';
 import { CollaborationProps, CollabState, CollabUser } from '../../sync-local/types';
 import { Awareness } from 'y-protocols/awareness';
 import { DSheetContentSnapshot } from '../../persistence';
+import { DSheetContentChange } from '../utils/content-change';
 
 import * as Y from 'yjs';
 export interface EditorContextType {
@@ -20,6 +21,8 @@ export interface EditorContextType {
     getDocumentTitle?: (dsheetId: string) => Promise<string>;
     updateDocumentTitle?: (title: string) => void;
     isAuthorized: boolean;
+    /** True once the sheet's meta.format is above what this client supports. */
+    formatLocked?: boolean;
     dataBlockCalcFunction: {
         [key: string]: {
             [key: string]: any;
@@ -31,14 +34,19 @@ export interface EditorContextType {
         };
     }>>;
     refreshIndexedDB: () => Promise<void>;
+    rebuildLocalStore: () => Promise<void>;
     sheetEditorRef: React.MutableRefObject<WorkbookInstance | null>;
     setSheetEditorRef: React.RefCallback<WorkbookInstance>;
+    /** Call when the active sheet changes or sheets appear; lets the keeper remember or restore it. */
+    notifyActiveSheetChange: () => void;
     ydocRef: React.MutableRefObject<Y.Doc | null>;
     persistenceRef: React.MutableRefObject<IndexeddbPersistence | null>;
     sheetData: Sheet[];
     setSheetData: React.Dispatch<React.SetStateAction<Sheet[]>>;
     currentDataRef: React.MutableRefObject<Sheet[]>;
     remoteUpdateRef: React.MutableRefObject<boolean>;
+    /** True while a peer's structural edit waits to remount the grid. */
+    structuralRemountPendingRef: React.MutableRefObject<boolean>;
     handleChange: (data: Sheet[]) => void;
     initialiseLiveQueryData: (data: Sheet[]) => void;
     loading: boolean;
@@ -75,11 +83,13 @@ interface EditorProviderProps {
     isAuthorized: boolean;
     children: React.ReactNode;
     dsheetId: string;
+    localStoreId?: string;
     username?: string;
     portalContent?: string;
     enableIndexeddbSync?: boolean;
     isReadOnly?: boolean;
     onContentUpdate?: () => void;
+    onContentChange?: (change: DSheetContentChange) => void;
     onChange?: (data: SheetUpdateData, encodedUpdate?: string) => void;
     collaboration?: CollaborationProps;
     externalEditorRef?: React.Ref<DSheetEditorHandle>;

package/dist/editor/hooks/use-celldata-compaction.d.ts

@@ -1,7 +1,12 @@
 import { MutableRefObject, RefObject } from 'react';
 import { WorkbookInstance, Sheet } from '../../sheet-engine/react';
+import { planYdocCompaction } from '../utils/compact-committed-celldata';
 
-import type * as Y from 'yjs';
+import * as Y from 'yjs';
+/** Wait before a refused or stopped run is tried again. */
+export declare const COMPACTION_RETRY_MS = 30000;
+/** Tries after the first run; the compaction is also retried on a later open. */
+export declare const COMPACTION_MAX_RETRIES = 10;
 type UseCelldataCompactionArgs = {
     dsheetId: string;
     ydocRef: RefObject<Y.Doc | null>;
@@ -12,11 +17,48 @@ type UseCelldataCompactionArgs = {
     isDataLoaded: boolean;
     isReadOnly: boolean;
     remoteUpdateRef: MutableRefObject<boolean>;
+    /** True while a structural remote change waits to remount the Workbook. */
+    structuralRemountPendingRef?: MutableRefObject<boolean>;
     collabSyncing: boolean;
 };
+/**
+ * False while a remote apply is running, while a structural remount is pending
+ * (the engine still has the old grid and the Yjs document has the new one) or
+ * while collaboration is still syncing.
+ */
+export declare function canRunCompaction(refs: {
+    remoteUpdateRef: MutableRefObject<boolean>;
+    structuralRemountPendingRef?: MutableRefObject<boolean>;
+}, collabSyncing: boolean): boolean;
+/**
+ * Runs `attempt` and, when it asks for a retry (the gate was closed, or a run
+ * stopped because the document changed), calls `retry` after `delayMs`, up to
+ * `maxRetries` times. Without it a refused run waited for the next open, so
+ * compaction made one chunk of progress per open (PR 466 N10).
+ */
+export declare function createCompactionRetrier({ attempt, retry, delayMs, maxRetries, setTimer, clearTimer, }: {
+    attempt: () => Promise<'done' | 'retry'>;
+    retry: () => void;
+    delayMs?: number;
+    maxRetries?: number;
+    setTimer?: (cb: () => void, ms: number) => ReturnType<typeof setTimeout>;
+    clearTimer?: (handle: ReturnType<typeof setTimeout>) => void;
+}): {
+    run(): Promise<void>;
+    cancel(): void;
+};
+/**
+ * Applies the plan chunk by chunk, yielding between chunks. The plan was made
+ * from the document as it was, and one change in it, the whole-value
+ * borderInfo write, would overwrite a newer value. So the run stops, leaving
+ * the compaction unfinished (it is retried on a later open), as soon as the
+ * document differs from what the previous chunk left. Returns true when every
+ * chunk was applied.
+ */
+export declare function applyCompactionChangesInChunks(ydoc: Y.Doc, dsheetId: string, changes: ReturnType<typeof planYdocCompaction>['changes'], handleOnChangePortalUpdate: () => void, isCancelled: () => boolean, sheetEditorRef: RefObject<WorkbookInstance | null>, chunkSize?: number): Promise<boolean>;
 /**
  * One-shot background compaction (celldata + borderInfo). Completion is stored
  * on the anchor sheet's config in Yjs so it syncs across devices.
  */
-export declare function useCelldataCompaction({ dsheetId, ydocRef, sheetEditorRef, currentDataRef, handleOnChangePortalUpdate, syncStatus, isDataLoaded, isReadOnly, remoteUpdateRef, collabSyncing, }: UseCelldataCompactionArgs): void;
+export declare function useCelldataCompaction({ dsheetId, ydocRef, sheetEditorRef, currentDataRef, handleOnChangePortalUpdate, syncStatus, isDataLoaded, isReadOnly, remoteUpdateRef, structuralRemountPendingRef, collabSyncing, }: UseCelldataCompactionArgs): void;
 export {};

package/dist/editor/hooks/use-celldata-compaction.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/editor/hooks/use-editor-data.d.ts

@@ -21,6 +21,7 @@ export declare const useEditorData: (ydocRef: React.MutableRefObject<Y.Doc | nul
     setSheetData: import('react').Dispatch<import('react').SetStateAction<Sheet[]>>;
     currentDataRef: import('react').MutableRefObject<Sheet[]>;
     remoteUpdateRef: import('react').MutableRefObject<boolean>;
+    structuralRemountPendingRef: import('react').MutableRefObject<boolean>;
     isDataLoaded: boolean;
     setIsDataLoaded: import('react').Dispatch<import('react').SetStateAction<boolean>>;
     handleChange: (_data: Sheet[]) => void;

package/dist/editor/hooks/use-editor-sync.d.ts

@@ -1,13 +1,17 @@
 import { IndexeddbPersistence } from 'y-indexeddb';
 import { CollaborationProps } from '../../sync-local/types';
+import { DSheetContentChange } from '../utils/content-change';
 import * as Y from 'yjs';
-export declare const useEditorSync: (dsheetId: string, enableIndexeddbSync?: boolean, isReadOnly?: boolean, portalContent?: string, collaboration?: CollaborationProps, onCollabUpdate?: (fullState: string, updateChunk: string) => void, onIndexedDbError?: (error: Error) => void) => {
+export declare const useEditorSync: (dsheetId: string, enableIndexeddbSync?: boolean, isReadOnly?: boolean, portalContent?: string, collaboration?: CollaborationProps, onRemoteApplied?: (update: Uint8Array) => void, onIndexedDbError?: (error: Error) => void, localStoreId?: string) => {
     ydocRef: import('react').MutableRefObject<Y.Doc | null>;
     persistenceRef: import('react').MutableRefObject<IndexeddbPersistence | null>;
     syncStatus: "error" | "syncing" | "initializing" | "synced";
     isContentBootstrapReady: boolean;
     refreshIndexedDB: () => Promise<void>;
+    rebuildLocalStore: () => Promise<void>;
     getContentSnapshot: () => import('../../persistence-utils').DSheetContentSnapshot;
+    getContentFingerprint: () => string | null;
+    getContentChange: () => DSheetContentChange;
     mergeContent: (encodedState: string) => import('../../persistence-utils').DSheetContentSnapshot;
     collabState: import('../..').CollabState;
     isCollabReady: boolean;

package/dist/editor/hooks/use-editor-sync.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/editor/types.d.ts

@@ -5,11 +5,13 @@ import { CollaborationProps } from '../sync-local/types';
 import { CommentsConfig } from './types/comments';
 import { SmartContractConfig } from './types/smart-contract';
 import { ApiKeyStorage } from './utils/api-key-storage';
+import { DSheetContentChange } from './utils/content-change';
 import { ThemeKey } from '../sheet-engine/core/theme';
 import { DSheetContentSnapshot } from '../persistence';
 import { NavigateToSheetOptions } from './utils/navigate-to-sheet';
 
 import * as Y from 'yjs';
+export type { DSheetContentChange } from './utils/content-change';
 export type { ThemeKey } from '../sheet-engine/core/theme';
 export type DSheetPermissionMode = 'view' | 'comment' | 'edit';
 export type { CommentThread, CommentReply, CommentActionParams, CommentsConfig, CommentAnchorMove, } from './types/comments';
@@ -26,6 +28,20 @@ export interface EditorValues {
 }
 export type DSheetEditorHandle = WorkbookInstance & {
     refreshIndexedDB: () => Promise<void>;
+    /**
+     * Delete this sheet's IndexedDB database and rewrite it from the live
+     * document (same Y.Doc, never replaced), so local edits are kept. Resolves
+     * once the new store has synced. Resolves as a no-op when the editor is
+     * read-only, local persistence is disabled or there is no sheet id. Rejects
+     * if the rebuild fails, if the new store does not sync within 15 s, or if a
+     * refresh/unmount supersedes it. Concurrent calls share one rebuild.
+     *
+     * A bootstrap that is still waiting on an unreadable store (the case this
+     * heals) is abandoned after 3 s: the rebuild then finishes the bootstrap
+     * itself, merging the published content into the document, so the editor
+     * leaves "syncing" once the rebuild resolves.
+     */
+    rebuildLocalStore: () => Promise<void>;
     terminateSession: () => void;
     updateCollaboratorName: (name: string) => void;
     updateSessionTitle: (args: {
@@ -33,6 +49,13 @@ export type DSheetEditorHandle = WorkbookInstance & {
         documentTitle: string;
     }) => void;
     navigateToSheet: (sheetId: string, opts?: NavigateToSheetOptions) => Promise<boolean>;
+    /**
+     * Content fingerprint: base64 state vector + ":" + deleted count. Changes
+     * on every change, deletes included; compare with === only. null until
+     * y-indexeddb is attached and synced; use fingerprintFromUpdate of the
+     * IndexedDB body then.
+     */
+    getContentFingerprint: () => string | null;
 };
 export interface PanelConfig {
     id: string;
@@ -79,15 +102,35 @@ export interface DsheetProps {
     showFormulaBar?: boolean;
     enableIndexeddbSync?: boolean;
     dsheetId: string;
+    /** Names the local IndexedDB database and labels content snapshots
+     * (default `dsheetId`). `dsheetId` stays the Yjs root key. */
+    localStoreId?: string;
     /**
      * Cheap change signal for hosts that persist sheet bodies through Yjs.
      * Unlike `onChange`, this does not build a plain sheet or encode the Y.Doc.
      */
     onContentUpdate?: () => void;
+    /**
+     * Cheap change signal (Stabilize A1): `hasContent`, `userEdited` and the
+     * content `fingerprint`, computed without encoding the Y.Doc. At most one
+     * call per second (trailing), flushed on pagehide, beforeunload and unmount.
+     * Read full state on demand with `editorStateRef.getContentSnapshot()`.
+     */
+    onContentChange?: (change: DSheetContentChange) => void;
+    /**
+     * @deprecated Encodes the whole Y.Doc and rebuilds a plain workbook per
+     * call. Use `onContentChange` and read full state on demand. Called at most
+     * once per second (trailing), flushed only on unload and unmount. The latest
+     * `onChange` you pass is the one called, so an inline function is safe: a new
+     * identity does not cancel a pending call.
+     */
     onChange?: (updateData: SheetUpdateData, encodedUpdate?: string) => void;
     collaboration?: CollaborationProps;
     /** Called when local IndexedDB persistence fails. The editor and durable
-     * collaboration continue using the in-memory Y.Doc, matching dDoc. */
+     * collaboration continue using the in-memory Y.Doc, matching dDoc. Also
+     * called when the first read of the local store does not finish within 15 s
+     * (the editor then continues without local persistence, and
+     * `rebuildLocalStore()` can recreate the store). */
     onIndexedDbError?: (error: Error) => void;
     username?: string;
     portalContent?: string;

package/dist/editor/utils/active-sheet-keeper.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/editor/utils/after-update-cell.d.ts

@@ -50,7 +50,13 @@ interface AfterUpdateCellParams {
     collabEnabled?: boolean;
     collabIsOwner?: boolean;
     remoteUpdateRef?: React.MutableRefObject<boolean>;
+    /** True while a peer's structural edit waits to remount the grid. */
+    structuralRemountPendingRef?: React.MutableRefObject<boolean>;
     localUserEditRef?: React.MutableRefObject<boolean>;
+    /** Sheet that held the cell at commit time; falls back to the current sheet. */
+    sheetId?: string;
+    /** The caller writes the cell to Yjs itself (paste and fill batch writes). */
+    skipPersist?: boolean;
 }
 /** True when data-block formulas (API / smart contract) should run for this edit. */
 export declare const shouldExecuteDataBlocks: (params: {

package/dist/editor/utils/after-update-cell.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/editor/utils/apply-comment-markers.d.ts

@@ -8,7 +8,9 @@ type CommentData = object | null | undefined;
  * `null`, so a tiny `{ ps }` object is created in the live view only so the
  * triangle can render. Row/column drag still owns real cell data.
  *
- * Mutates in place and returns the same array.
+ * Updates the given arrays in place and returns them. Sparse celldata entries
+ * are replaced with copies, never written into, because they may be Yjs
+ * content (see ySheetArrayToPlain).
  */
 export declare const applyCommentMarkers: <T>(sheets: T | null | undefined, commentData: CommentData, allowComments: boolean | undefined) => T | null | undefined;
 export {};

package/dist/editor/utils/apply-comment-markers.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/editor/utils/calc-chain-ydoc-update.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/editor/utils/content-change.d.ts

@@ -0,0 +1,48 @@
+import * as Y from 'yjs';
+/**
+ * Cheap change signal for hosts (Stabilize A1). Built from the live Y.Doc
+ * without encoding it; full state stays available through
+ * editorStateRef.getContentSnapshot().
+ */
+export type DSheetContentChange = {
+    /** Same meaning as dsheets.new `isEmptySheet(...) === false`. */
+    hasContent: boolean;
+    /** A local user edit has happened since this editor mounted. */
+    userEdited: boolean;
+    /**
+     * base64 state vector + ":" + deleted count. Changes on every change,
+     * deletes included; compare with === only. null until y-indexeddb is
+     * attached and synced.
+     */
+    fingerprint: string | null;
+};
+/** Default-workbook seed and legacy migration: content, but not a user edit. */
+export declare const INIT_ORIGIN = "init";
+/** Idle celldata compaction: rewrites storage, not a user edit. */
+export declare const COMPACTION_ORIGIN = "compaction";
+/**
+ * Mirrors dsheets.new `isEmptySheet` (components/dsheet-editor/editor-utils.ts):
+ * no sheets → empty; more than one sheet → content; otherwise content when
+ * sheet 0 has any config key or any celldata entry. Stops at the first live
+ * entry, so it does not walk the sheet.
+ */
+export declare function computeHasContent(doc: Y.Doc, dsheetId: string): boolean;
+export type UserEditTracker = {
+    userEdited(): boolean;
+    dispose(): void;
+};
+/**
+ * Turns on at the first transaction that changes the document and whose
+ * origin is not a known non-user origin or the IndexedDB provider.
+ */
+export declare function attachUserEditTracker(doc: Y.Doc, getIndexeddbOrigin: () => unknown): UserEditTracker;
+export declare const CONTENT_CHANGE_WAIT_MS = 1000;
+/**
+ * At most one host call per second (trailing only); local and remote changes
+ * share the throttle. The change is built when the call fires, never per edit.
+ */
+export declare function createContentChangeNotifier(getChange: () => DSheetContentChange, getHandler: () => ((change: DSheetContentChange) => void) | undefined, waitMs?: number): {
+    notify: () => void;
+    flush: () => void;
+    cancel: () => any;
+};

package/dist/editor/utils/content-change.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/editor/utils/content-fingerprint.d.ts

@@ -0,0 +1,37 @@
+import * as Y from 'yjs';
+/**
+ * Cheap "did the document change" signal (Stabilize A1 / D6).
+ *
+ * fingerprint = base64(state vector) + ":" + deletedCount
+ *
+ * A state vector alone misses delete-only transactions (clearing a filter,
+ * dropdown, conditional format, sub-sheet or named range; undo of a typed
+ * value), because a Yjs delete adds no item. deletedCount is the total length
+ * of all deleted ranges in the document, kept as a running count so no full
+ * scan is needed per check. Compare fingerprints with === only.
+ */
+export type ContentFingerprintTracker = {
+    getFingerprint(): string;
+    getDeletedCount(): number;
+    dispose(): void;
+};
+/**
+ * Attach when the Y.Doc is created, before any provider writes to it, so the
+ * count is built from transactions. Attaching later costs one full scan.
+ */
+export declare function attachContentFingerprint(doc: Y.Doc): ContentFingerprintTracker;
+/**
+ * Same value as a live tracker, for a stored body or a merge of raw rows.
+ * Builds a temporary document and scans its delete set, as getDsheetStateVector
+ * builds one. Reading the delete ranges from the encoded update instead
+ * (Y.decodeUpdate) misses GC structs that arrive without a delete range, e.g.
+ * a row written when the document received a compacted body.
+ */
+export declare function fingerprintFromUpdate(update: Uint8Array): string;
+/**
+ * Same value as a live tracker, computed from a document by one scan of its
+ * delete set (under 1.5 ms at 100k cells). Used by the body reads, which
+ * already build a document from every IndexedDB row, so GC structs that
+ * arrived without a delete range are counted.
+ */
+export declare function fingerprintFromDocument(doc: Y.Doc): string;

package/dist/editor/utils/content-fingerprint.test.d.ts

@@ -0,0 +1 @@
+

package/dist/editor/utils/editor-handle.d.ts

@@ -2,7 +2,7 @@ import { Ref } from 'react';
 import { WorkbookInstance } from '../../sheet-engine/react';
 import { DSheetEditorHandle } from '../types';
 
-export type DSheetEditorMethods = Pick<DSheetEditorHandle, "refreshIndexedDB" | "terminateSession" | "updateCollaboratorName" | "updateSessionTitle" | "navigateToSheet">;
+export type DSheetEditorMethods = Pick<DSheetEditorHandle, "refreshIndexedDB" | "rebuildLocalStore" | "terminateSession" | "updateCollaboratorName" | "updateSessionTitle" | "navigateToSheet" | "getContentFingerprint">;
 /**
  * Compose Fortune's regenerated imperative handle with dSheet lifecycle methods.
  * React callback refs invoke this again after every Workbook remount, so both

package/dist/editor/utils/format-gate.d.ts

@@ -0,0 +1,27 @@
+import * as Y from 'yjs';
+/** Highest `meta.format` this client can write. */
+export declare const SUPPORTED_FORMAT = 1;
+/** Shown to the user once the sheet is locked. */
+export declare const FORMAT_LOCKED_MESSAGE = "This sheet was updated. Reload to continue.";
+/**
+ * Format of the sheet in `doc`. A missing map or key means 1, and so does a
+ * value that is not a number. Does not create the map when it is absent.
+ */
+export declare function readFormatVersion(doc: Y.Doc, dsheetId: string): number;
+/**
+ * True once a watched sheet of `doc` has shown a format above SUPPORTED_FORMAT.
+ * With `dsheetId` it answers for that sheet only, and also reads the doc, so
+ * it holds before the watch starts. Without it, true if any sheet is locked.
+ */
+export declare function isFormatLocked(doc: Y.Doc | null | undefined, dsheetId?: string): boolean;
+/**
+ * Make the grid read-only in the same tick the lock is seen. The Yjs writers
+ * stop at once (isFormatLocked), but the grid became read-only only after the
+ * workbook data changed identity and the Workbook init effect ran: a commit in
+ * between showed in the grid, never reached Yjs, and was gone on reload.
+ * The Workbook init effect sets the same flag from the prop afterwards.
+ */
+export declare function lockWorkbookReadOnly(workbook: {
+    getWorkbookSetContext?: () => unknown;
+} | null | undefined): boolean;
+export declare function watchFormatGate(doc: Y.Doc, dsheetId: string, onLocked: (format: number) => void): () => void;

package/dist/editor/utils/format-gate.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/editor/utils/legacy-on-change.d.ts

@@ -0,0 +1,20 @@
+/** The legacy `onChange` argument pair: plain sheet data and the encoded doc. */
+export type LegacyOnChangeArgs = {
+    data: unknown;
+    update: string;
+};
+export declare const LEGACY_ON_CHANGE_WAIT_MS = 1000;
+/**
+ * Trailing-only throttle for the host's legacy `onChange`.
+ *
+ * The host's handler is read when the throttle fires, not when it is created.
+ * A host that passes a new inline `onChange` on every render must not rebuild
+ * this throttle: rebuilding cancels the pending call, so an edit followed
+ * within the wait by a re-render never reached the host's save.
+ * `buildArgs` runs only when there is a handler, because it encodes the whole
+ * document.
+ */
+export declare function createLegacyOnChangeThrottle<TData>(getOnChange: () => ((data: TData, update: string) => void) | undefined, buildArgs: () => {
+    data: TData;
+    update: string;
+} | null, waitMs?: number): any;

package/dist/editor/utils/legacy-on-change.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/editor/utils/patch-plain-celldata.d.ts

@@ -0,0 +1,19 @@
+export type PlainCelldataEntry = {
+    r: number;
+    c: number;
+    v: unknown;
+};
+export type CelldataPatch = {
+    key: string;
+    action: 'delete' | 'update';
+    v?: unknown;
+};
+/**
+ * Apply a remote batch of cell changes to a sheet's plain celldata array in
+ * place. Keys are `r_c` and unique within a batch.
+ *
+ * One pass over celldata finds every patched cell (A5): O(entries + changes)
+ * instead of a findIndex per changed key. The lookup is by row then column
+ * number, so the pass allocates nothing per entry.
+ */
+export declare function patchPlainCelldata(celldata: PlainCelldataEntry[], patches: Iterable<CelldataPatch>): void;

package/dist/editor/utils/patch-plain-celldata.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/editor/utils/rebuild-indexeddb-store.d.ts

@@ -0,0 +1,19 @@
+import { IndexeddbPersistence } from 'y-indexeddb';
+import type * as Y from 'yjs';
+/**
+ * D3: rebuild the local IndexedDB store from the live document.
+ *
+ * Destroys `current`, deletes the database, then attaches a new provider to
+ * the SAME live Y.Doc, so y-indexeddb writes the full current state as one
+ * fresh row. `onCreated` runs right after the new provider is constructed,
+ * before it has synced, so the caller can track it and attach listeners. The Y.Doc is never replaced or cleared. Unlike delete-and-reopen
+ * (heal), edits that exist only in the live doc are kept.
+ *
+ * The wait for the new provider is bounded: `whenSynced` never rejects, and a
+ * provider destroyed before its first read (a bootstrap restarting meanwhile)
+ * never syncs. It rejects on `timeoutMs` or once `isCurrent()` is false.
+ */
+export declare function rebuildIndexedDbStore(dsheetId: string, doc: Y.Doc, current: IndexeddbPersistence | null, onCreated?: (provider: IndexeddbPersistence) => void, syncOptions?: {
+    timeoutMs?: number;
+    isCurrent?: () => boolean;
+}): Promise<IndexeddbPersistence>;

package/dist/editor/utils/rebuild-indexeddb-store.failure.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/editor/utils/rebuild-indexeddb-store.test.d.ts

@@ -0,0 +1 @@
+

package/dist/editor/utils/remote-apply-guard.d.ts

@@ -11,9 +11,54 @@ export type RemoteApplyGuardRefs = {
     remoteApplyDepthRef: MutableRefObject<number>;
     remoteUpdateRef: MutableRefObject<boolean>;
 };
+/**
+ * True when an engine → Yjs echo hook (calcChain, conditional formats, ...)
+ * must stay quiet: a remote apply is running, or a structural remount is
+ * pending. While one is pending the engine still has the grid from before the
+ * peer's insert or delete, so a diff of its metadata against Yjs would write
+ * the old coordinates over the peer's (and delete the peer's calcChain
+ * entries). Cell commits are not echo hooks and are not held back by this.
+ */
+export declare function shouldSkipEchoWrite(refs: {
+    remoteUpdateRef: MutableRefObject<boolean>;
+    structuralRemountPendingRef?: MutableRefObject<boolean>;
+}): boolean;
 export declare function syncRemoteUpdateFlag(refs: RemoteApplyGuardRefs): void;
 export declare function beginRemoteApply(refs: RemoteApplyGuardRefs): void;
 export declare function endRemoteApply(refs: RemoteApplyGuardRefs): void;
 export declare function runUnderRemoteApply(refs: RemoteApplyGuardRefs, fn: () => void): void;
+export type StructuralRemountRefs = RemoteApplyGuardRefs & {
+    pendingRef: MutableRefObject<boolean>;
+    timerRef: MutableRefObject<number | null>;
+};
+/**
+ * Debounced structural remount under the remote-apply guard.
+ *
+ * Each pending remount owns exactly one begin and one end (B1): the guard is
+ * begun when the remount becomes pending (no remount was pending before),
+ * held while the timer is pending or deferred by a cell edit (B3), and ended
+ * after paint once `run` has finished. Events that land while one is pending
+ * only re-arm its timer.
+ *
+ * While `isEditing()` is true at fire time the timer re-arms (250 ms) and the
+ * pending flag and guard depth are kept; the remount runs once the edit ends.
+ * The typed cell itself is still written: the commit-time write and the cell
+ * write in afterUpdateCell do not check the guard.
+ */
+export declare function scheduleStructuralRemount(refs: StructuralRemountRefs, run: () => void, delayMs?: number, isEditing?: () => boolean): void;
+/** Re-arm interval while a cell edit blocks the remount. */
+export declare const STRUCTURAL_REMOUNT_EDIT_RETRY_MS = 250;
+/**
+ * Drop a pending structural remount (observer teardown) and release the
+ * guard begun for it.
+ */
+export declare function cancelStructuralRemount(refs: StructuralRemountRefs): void;
+/**
+ * Run `fn` under the guard and keep it until paint (a remount follows). If
+ * `fn` throws, the guard is ended at once and the error is rethrown: a begin
+ * with no matching end leaves the depth above zero, and `handleChange` then
+ * drops every local write until reload.
+ */
+export declare function runRemoteApplyUntilPaint<T>(refs: RemoteApplyGuardRefs, fn: () => T): T;
 /** End after Workbook remount hooks have flushed (2 rAF ≈ one paint). */
 export declare function endRemoteApplyAfterPaint(refs: RemoteApplyGuardRefs): void;

package/dist/editor/utils/remote-apply-guard.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/editor/utils/sheet-ydoc-sync-utils.d.ts

@@ -2,19 +2,29 @@ import { WorkbookInstance } from '../../sheet-engine/react';
 import { SheetChangePath } from './update-ydoc';
 
 import * as Y from 'yjs';
+export { readYdocSheetField } from './update-ydoc';
+/** Sheet fields the per-feature Yjs hooks sync. */
+export declare const SYNCED_SHEET_FIELDS: readonly ["calcChain", "config", "dataVerification", "luckysheet_conditionformat_save", "hyperlink", "filter", "filter_select", "liveQueryList", "dataBlockCalcFunction"];
 type SyncContext = {
     currentSheetId: string;
+    /** Only `field` is populated: the value stored in Yjs. */
     oldSheet: Record<string, any>;
+    /** The engine's current value of `field` for the active sheet. */
+    newValue: any;
+    /** The engine's active sheet, for checks against its cells. */
+    engineSheet: Record<string, any> | undefined;
     ydoc: Y.Doc;
 };
 /**
- * Build a stable sync context from current editor sheet and Yjs snapshot.
- * This keeps all field-level sync handlers aligned on the same baseline.
+ * Old (Yjs) and new (engine) value of one field of the active sheet (A3).
+ * Reads only that field: no whole-workbook conversion, and no getSheet(),
+ * which rebuilds celldata from the dense grid.
  */
-export declare const getSheetYdocSyncContext: ({ sheetEditorRef, ydocRef, dsheetId, }: {
+export declare const getSheetYdocSyncContext: ({ sheetEditorRef, ydocRef, dsheetId, field, }: {
     sheetEditorRef: React.RefObject<WorkbookInstance | null>;
     ydocRef: React.RefObject<Y.Doc | null>;
     dsheetId: string;
+    field: string;
 }) => SyncContext | null;
 export declare const buildMapFieldChanges: ({ sheetId, fieldPath, oldData, newData, }: {
     sheetId: string;
@@ -28,4 +38,3 @@ export declare const applyYdocSheetChanges: ({ ydoc, dsheetId, changes, handleCo
     changes: SheetChangePath[];
     handleContentPortal?: any;
 }) => void;
-export {};

package/dist/editor/utils/sheet-ydoc-sync-utils.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/editor/utils/structural-edit-formula-sync.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/editor/utils/structural-edit-other-tabs.test.d.ts

@@ -0,0 +1 @@
+export {};