@fileverse-dev/dsheet 4.1.22 → 4.1.23-stabilise-package-3

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/editor-workbook.d.ts

@@ -21,6 +21,10 @@ interface EditorWorkbookProps {
     dsheetId: string;
     onDuneChartEmbed?: () => void;
     onSheetCountChange?: (sheetCount: number) => void;
+    onCopySheetLink?: (args: {
+        sheetId: string;
+        sheetName: string;
+    }) => void;
     sidebarActivePanel?: string | null;
     sidebarPortalRegistry?: SidebarPortalRegistryHandle | null;
     sidebarPortalRenderers?: Record<string, SidebarPortalRenderer>;
@@ -29,6 +33,8 @@ interface EditorWorkbookProps {
     onSignInToComment?: () => void;
     onViewerModeChange?: (mode: 'comment' | 'view') => void;
     theme?: ThemeKey;
+    showToolbar?: boolean;
+    showFormulaBar?: boolean;
 }
 export declare const EditorWorkbook: React.NamedExoticComponent<EditorWorkbookProps>;
 export {};

package/dist/editor/components/sidebar/editor-right-sidebar.d.ts

@@ -15,6 +15,8 @@ interface EditorRightSidebarProps {
     onClose: () => void;
     /** Read/preview mode hides the toolbar, so the sidebar starts higher. */
     isReadOnly?: boolean;
+    showNavbar?: boolean;
+    showToolbar?: boolean;
 }
-export declare const EditorRightSidebar: ({ isOpen, activePanelConfig, onClose, isReadOnly, }: EditorRightSidebarProps) => import("react/jsx-runtime").JSX.Element;
+export declare const EditorRightSidebar: ({ isOpen, activePanelConfig, onClose, isReadOnly, showNavbar, showToolbar, }: EditorRightSidebarProps) => import("react/jsx-runtime").JSX.Element;
 export {};

package/dist/editor/components/sidebar/sidebar-offsets.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Right sidebar position below the editor chrome. Read/preview mode keeps
+ * its existing offsets (the sidebar overlays the toolbar there).
+ */
+export declare const getRightSidebarOffsets: ({ isReadOnly, showNavbar, showToolbar, }: {
+    isReadOnly?: boolean;
+    showNavbar?: boolean;
+    showToolbar?: boolean;
+}) => {
+    top: string;
+    height: string;
+};

package/dist/editor/components/sidebar/sidebar-offsets.test.d.ts

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

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,6 +34,7 @@ export interface EditorContextType {
         };
     }>>;
     refreshIndexedDB: () => Promise<void>;
+    rebuildLocalStore: () => Promise<void>;
     sheetEditorRef: React.MutableRefObject<WorkbookInstance | null>;
     setSheetEditorRef: React.RefCallback<WorkbookInstance>;
     ydocRef: React.MutableRefObject<Y.Doc | null>;
@@ -39,6 +43,8 @@ export interface EditorContextType {
     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;
@@ -80,6 +86,7 @@ interface EditorProviderProps {
     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-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) => {
     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/types.d.ts

@@ -5,10 +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';
@@ -25,12 +28,34 @@ 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: {
         encryptedTitle: string;
         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;
@@ -68,6 +93,13 @@ export interface DsheetProps {
     setFetchingURLData?: (fetching: boolean) => void;
     setInputFetchURLDataBlock?: React.Dispatch<React.SetStateAction<string>>;
     renderNavbar?: (editorValues?: EditorValues) => JSX.Element;
+    /** Mount the navbar slot. `renderNavbar` still runs when hidden, so host
+     * side effects inside it keep working. Default true. */
+    showNavbar?: boolean;
+    /** Show the sheet toolbar. Default true. */
+    showToolbar?: boolean;
+    /** Show the formula bar. Default true. */
+    showFormulaBar?: boolean;
     enableIndexeddbSync?: boolean;
     dsheetId: string;
     /**
@@ -75,10 +107,27 @@ export interface DsheetProps {
      * 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;
@@ -112,6 +161,10 @@ export interface DsheetProps {
     onDataBlockEvent?: (event: DataBlockEvent) => void;
     onDuneChartEmbed?: () => void;
     onSheetCountChange?: (sheetCount: number) => void;
+    onCopySheetLink?: (args: {
+        sheetId: string;
+        sheetName: string;
+    }) => void;
     /** Fires whenever local content-sync status changes. Host apps should gate
      * collab start/resume on 'synced' — starting before local content is fully
      * synced is what let the RTC layer bind to a stale doc in the past. */

package/dist/editor/utils/activate-sheet-for-link.d.ts

@@ -0,0 +1,3 @@
+import { Context } from '../../sheet-engine/core';
+
+export declare function activateSheetForLink(draft: Context, sheetId: string): void;

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

@@ -0,0 +1,21 @@
+import { WorkbookInstance } from '../../sheet-engine/react';
+
+export type ActiveSheetKeeper = {
+    /**
+     * Call on every Workbook ref attach. `mountKey` must change whenever the
+     * Workbook is remounted (i.e. mirror the Workbook's React `key`).
+     */
+    onAttach: (workbook: WorkbookInstance | null, mountKey: unknown) => void;
+};
+/**
+ * Fortune remounts the Workbook whenever the editor bumps its render key
+ * (collab rehydration, template apply, imports), and a fresh mount resets the
+ * active sheet to the first visible one. Remember the active sheet across
+ * attaches and restore it once per mount, as soon as the new mount has sheets.
+ *
+ * The restore runs synchronously inside the ref callback (React commit phase).
+ * That only enqueues a Workbook state update (same as setState in
+ * useLayoutEffect), and it goes through the same setContext path as clicking a
+ * sheet tab.
+ */
+export declare function createActiveSheetKeeper(): ActiveSheetKeeper;

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">;
+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/navigate-to-sheet.d.ts

@@ -0,0 +1,22 @@
+export type NavigableContext = {
+    currentSheetId?: string;
+    luckysheetfile?: Array<{
+        id?: string;
+        hide?: number;
+    } | null | undefined>;
+};
+export type NavigableEditor = {
+    getWorkbookContext?: () => NavigableContext | null | undefined;
+    getWorkbookSetContext?: () => ((recipe: (draft: unknown) => void) => void) | null | undefined;
+};
+export type NavigateToSheetOptions = {
+    /** How long to wait for the workbook and sheet to load. Default 10s. */
+    timeoutMs?: number;
+};
+/**
+ * Wait until the workbook has loaded a sheet with `sheetId`, then switch to it.
+ * Resolves `false` (never throws) when the sheet is missing after the timeout,
+ * hidden, or the switch fails. `getEditor` must return the latest instance on
+ * every call because Fortune regenerates its handle on each context change.
+ */
+export declare function navigateToSheet<TDraft>(getEditor: () => NavigableEditor | null | undefined, sheetId: string, activate: (draft: TDraft, sheetId: string) => void, { timeoutMs }?: NavigateToSheetOptions): Promise<boolean>;

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,57 @@ 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.
+ *
+ * The guard is begun once, right before `run`, and ended after paint, so each
+ * remount owns exactly one begin and one end. It is NOT held while the timer
+ * is merely pending or deferred by a cell edit: `remoteUpdateRef` makes
+ * handleChange and the data-block work in afterUpdateCell drop local work, so
+ * holding it across an edit would drop the user's typed edit. (The cell write
+ * in afterUpdateCell and the commit-time write do not check it.) What must not
+ * run while a remount is pending is the engine → Yjs echo hooks, which diff
+ * the old grid against Yjs: they check `shouldSkipEchoWrite`. 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 is kept; the remount runs once the edit ends.
+ */
+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). The guard is only
+ * held while `run` executes and until paint afterwards, so there is nothing
+ * to release here.
+ */
+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 {};