@fileverse-dev/dsheet 4.1.1-edit-mode-16 → 4.1.2

package/README.md

@@ -1,21 +1,19 @@
-# Fileverse DSheet
+# Fileverse dSheets
 
 [![NPM](https://img.shields.io/npm/v/@fileverse-dev/dsheet)](https://www.npmjs.com/package/@fileverse-dev/dsheet)
 [![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
 
-[dsheets.new](http://dsheets.new/) is your decentralised alternative to google sheets & excel. Use it to read, manipulate, and even write onchain data, in real-time. Built on the same middleware as ddocs.new, the app is privacy-first, self-sovereign, and gives you full control over your data <3 
+[dsheets.new](http://dsheets.new/) is your end-to-end encrypted alternative to Google Sheets & Excel. Use it to read, manipulate, and even write financial data, in real-time. Built on the same middleware as ddocs.new, the app is privacy-focused, sovereign, and gives you full control over your data. 
 
-## 👩‍🏭 Features:
+## 𓆣 Features include:
 - End-to-end encryption
 - Local & peer-to-peer storage
-- Query live data from APIs & smart contracts  
-- Write onchain: simulate + submit transactions (V0.3)
+- Query live data from APIs & even smart contracts
+- Enable dark mode and other color themes
 - Use a familiar spreadsheets interface & functions (VLOOKUP, INDEX, MATCH…)
-- Granular access permissions (email, wallet, ENS)
+- Granular access permissions (e.g., give view, comment, edit, suggest access to specific email addresses)
 
-[**Try Live Demo →**](https://fileverse-dsheet.vercel.app/)
-
-![image](https://github.com/user-attachments/assets/b3953811-3e02-43ac-9e8e-ee0c3923a22f)
+<img width="1532" height="974" alt="dsheetsnew" src="https://github.com/user-attachments/assets/8bd67463-e999-41f4-b414-9d017fbf9466" />
 
 
 ## Installation

package/dist/{constants-B3rfAvvz.js → constants-CRFfbkoQ.js}

@@ -1,5 +1,5 @@
-import { E as l, S as u } from "./crypto-constants-ZTlAYRUf.js";
-const h = l, S = u, _ = [
+import { E as a, S as n } from "./crypto-constants-ZTlAYRUf.js";
+const E = a, d = n, f = [
   {
     id: "0",
     name: "Sheet1",
@@ -7,7 +7,7 @@ const h = l, S = u, _ = [
     config: {},
     order: 0
   }
-], g = [
+], m = [
   "undo",
   "redo",
   "format-painter",
@@ -45,7 +45,7 @@ const h = l, S = u, _ = [
   "quick-formula",
   "dataVerification",
   "search"
-], p = [
+], u = [
   "cut",
   "copy",
   "paste",
@@ -82,7 +82,7 @@ const h = l, S = u, _ = [
   "freeze-row",
   "|",
   "clear-format"
-], C = [
+], S = [
   "cut",
   "copy",
   "paste",
@@ -119,14 +119,14 @@ const h = l, S = u, _ = [
   "freeze-column",
   "|",
   "clear-format"
-], w = {
+], _ = {
   height: null,
   isShow: !1,
   left: null,
   top: null,
   value: "",
   width: null
-}, a = "#9CA3AF", s = [
+}, l = "#5298FF", r = [
   "#30bced",
   "#6eeb83",
   "#fa69d1",
@@ -136,81 +136,24 @@ const h = l, S = u, _ = [
   "#0ad7f2",
   "#1bff39"
 ];
-function A(o) {
-  const t = /* @__PURE__ */ new Map();
-  return o.forEach((r) => {
-    const i = r == null ? void 0 : r.socketId, e = r == null ? void 0 : r.user;
-    typeof i == "string" && e && t.set(i, {
-      name: e.name ?? "",
-      color: e.color ?? a,
-      isEns: e.isEns ?? ""
-    });
-  }), t;
+function c(e) {
+  return r[e % r.length];
 }
-function L(o, t) {
-  const r = o.map((e) => {
-    const n = t.get(e);
-    return n ? {
-      clientId: e,
-      name: n.name,
-      color: n.color,
-      isEns: n.isEns,
-      isPlaceholder: !1
-    } : {
-      clientId: e,
-      name: "",
-      color: a,
-      isEns: "",
-      isPlaceholder: !0
-    };
-  });
-  r.sort((e, n) => !!e.isPlaceholder != !!n.isPlaceholder ? e.isPlaceholder ? 1 : -1 : String(e.clientId).localeCompare(String(n.clientId)));
-  const i = /* @__PURE__ */ new Set();
-  return r.filter((e) => e.isPlaceholder || !e.name ? !0 : i.has(e.name) ? !1 : (i.add(e.name), !0));
-}
-function R(o, t) {
-  const r = new Set(
-    o.filter(({ isPlaceholder: e, name: n }) => !e && n).map(({ name: e }) => e)
-  );
-  t.forEach((e, n) => {
-    r.has(n) || t.delete(n);
-  });
-  const i = /* @__PURE__ */ new Set();
-  return o.forEach((e) => {
-    if (e.isPlaceholder || !e.name) return;
-    let n = t.get(e.name);
-    (!n || i.has(n)) && (n = s.find((c) => !i.has(c)) ?? n ?? s[t.size % s.length], t.set(e.name, n)), i.add(n), e.color = n;
-  }), o;
-}
-function O(o, t) {
-  return o.slice().sort().map((r) => {
-    const i = t.get(r);
-    return i ? `${r}:${i.name}:${i.isEns}` : `${r}:?`;
-  }).join("|");
-}
-const d = "#5298FF";
-function f(o) {
-  return s[o % s.length];
-}
-function E() {
+function i() {
   return "#" + Math.floor(Math.random() * 16777215).toString(16).padStart(6, "0");
 }
-function P(o, t, r) {
-  return t || (o ? d : r != null ? f(r) : E());
+function h(e, o, t) {
+  return e ? l : o ?? (t != null ? c(t) : i());
 }
 export {
-  w as C,
-  _ as D,
-  h as E,
-  C as H,
-  S,
-  g as T,
-  R as a,
-  A as b,
-  s as c,
-  p as d,
-  d as e,
-  O as i,
-  L as m,
-  P as p
+  _ as C,
+  f as D,
+  E,
+  S as H,
+  d as S,
+  m as T,
+  r as a,
+  u as b,
+  l as c,
+  h as p
 };

package/dist/constants.d.ts

@@ -1,5 +1,5 @@
 export { ERROR_MESSAGES_FLAG, SERVICES_API_KEY, } from './editor/constants/shared-constants';
-export { COLLAB_PRESENCE_COLORS } from './sync-local/presence';
 export declare const ENS_PRESENCE_COLOR = "#5298FF";
-/** Explicit awareness color, else ENS brand color, palette, or random fallback. */
+export declare const COLLAB_PRESENCE_COLORS: readonly ["#30bced", "#6eeb83", "#fa69d1", "#ecd444", "#ee6352", "#db3041", "#0ad7f2", "#1bff39"];
+/** ENS brand color, else `color`, else palette by `clientId`, else random. */
 export declare function presenceColor(isEns: boolean | undefined, color?: string, clientId?: number): string;

package/dist/constants.js

@@ -1,8 +1,8 @@
-import { c as R, e as _, E as C, S as s, p as O } from "./constants-B3rfAvvz.js";
+import { a as R, c as _, E as C, S as a, p as s } from "./constants-CRFfbkoQ.js";
 export {
   R as COLLAB_PRESENCE_COLORS,
   _ as ENS_PRESENCE_COLOR,
   C as ERROR_MESSAGES_FLAG,
-  s as SERVICES_API_KEY,
-  O as presenceColor
+  a as SERVICES_API_KEY,
+  s as presenceColor
 };

package/dist/editor/components/editor-workbook.d.ts

@@ -1,7 +1,7 @@
 import { default as React } from 'react';
 import { SidebarPortalRegistryHandle, SidebarPortalRenderer } from '../../sheet-engine/react';
 import { ThemeKey } from '../../sheet-engine/core/theme';
-import { OnboardingHandlerType, DSheetPermissionMode } from '../types';
+import { OnboardingHandlerType } from '../types';
 import { CommentsConfig } from '../types/comments';
 
 type OnboardingHandler = OnboardingHandlerType;
@@ -24,10 +24,6 @@ interface EditorWorkbookProps {
     sidebarActivePanel?: string | null;
     sidebarPortalRegistry?: SidebarPortalRegistryHandle | null;
     sidebarPortalRenderers?: Record<string, SidebarPortalRenderer>;
-    permissionMode?: DSheetPermissionMode | null;
-    onEnterEdit?: () => void;
-    onSignInToComment?: () => void;
-    onViewerModeChange?: (mode: 'comment' | 'view') => void;
     theme?: ThemeKey;
 }
 export declare const EditorWorkbook: React.NamedExoticComponent<EditorWorkbookProps>;

package/dist/editor/components/permission-chip.d.ts

@@ -1,11 +1,7 @@
 import { default as React } from 'react';
-import { DSheetPermissionMode } from '../types';
 
 interface PermissionChipProps {
-    mode: DSheetPermissionMode;
-    onEnterEdit?: () => void;
-    onSignInToComment?: () => void;
-    onViewerModeChange?: (mode: 'comment' | 'view') => void;
+    allowComments: boolean;
 }
 export declare const PermissionChip: React.FC<PermissionChipProps>;
 export {};

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

@@ -1,7 +1,7 @@
 import { default as React } from 'react';
 import { LiveQueryData, Sheet, WorkbookInstance } from '../../sheet-engine/react';
 import { IndexeddbPersistence } from 'y-indexeddb';
-import { SheetUpdateData, DataBlockEvent, DSheetEditorHandle } from '../types';
+import { SheetUpdateData, DataBlockEvent } from '../types';
 import { CommentsConfig } from '../types/comments';
 import { ApiKeyStorage } from '../utils/api-key-storage';
 import { OpenApiKeyModalFn } from '../utils/data-block-error-handler';
@@ -32,7 +32,6 @@ export interface EditorContextType {
     }>>;
     refreshIndexedDB: () => Promise<void>;
     sheetEditorRef: React.MutableRefObject<WorkbookInstance | null>;
-    setSheetEditorRef: React.RefCallback<WorkbookInstance>;
     ydocRef: React.MutableRefObject<Y.Doc | null>;
     persistenceRef: React.MutableRefObject<IndexeddbPersistence | null>;
     sheetData: Sheet[];
@@ -46,7 +45,6 @@ export interface EditorContextType {
     setForceSheetRender: React.Dispatch<React.SetStateAction<number>>;
     syncStatus: 'initializing' | 'syncing' | 'synced' | 'error';
     collabEnabled?: boolean;
-    isLiveCollabSession: boolean;
     collabIsOwner?: boolean;
     collabState?: CollabState;
     isCollabReady?: boolean;
@@ -81,8 +79,7 @@ interface EditorProviderProps {
     onContentUpdate?: () => void;
     onChange?: (data: SheetUpdateData, encodedUpdate?: string) => void;
     collaboration?: CollaborationProps;
-    externalEditorRef?: React.Ref<DSheetEditorHandle>;
-    legacyEditorRef?: React.Ref<DSheetEditorHandle>;
+    externalEditorRef?: React.MutableRefObject<WorkbookInstance | null>;
     commentsConfig?: CommentsConfig;
     editorStateRef?: React.MutableRefObject<{
         refreshIndexedDB: () => Promise<void>;
@@ -90,10 +87,6 @@ interface EditorProviderProps {
         mergeContent: (encodedState: string) => DSheetContentSnapshot;
         terminateSession?: () => void;
         updateCollaboratorName?: (name: string) => void;
-        updateSessionTitle?: (args: {
-            encryptedTitle: string;
-            documentTitle: string;
-        }) => void;
         rehydrateAfterCollabSync?: (reason?: string) => boolean;
     } | null>;
     enableLiveQuery?: boolean;
@@ -102,8 +95,6 @@ interface EditorProviderProps {
     onDataBlockEvent?: (event: DataBlockEvent) => void;
     smartContracts?: SmartContractConfig;
     onContentSyncStatusChange?: (status: 'initializing' | 'syncing' | 'synced' | 'error') => void;
-    onCollaborationInitializationComplete?: (result: 'ready' | 'error') => void;
-    onIndexedDbError?: (error: Error) => void;
 }
 export declare const EditorProvider: React.FC<EditorProviderProps>;
 export declare const useEditor: () => EditorContextType;

package/dist/editor/dsheet-editor.d.ts

@@ -1,5 +1,4 @@
-import { default as React } from 'react';
-import { DSheetEditorHandle, DsheetProps } from './types';
+import { DsheetProps } from './types';
 
 /**
  * SpreadsheetEditor component that provides a collaborative spreadsheet interface
@@ -8,5 +7,5 @@ import { DSheetEditorHandle, DsheetProps } from './types';
  * @param props - Component properties
  * @returns The SpreadsheetEditor component
  */
-declare const SpreadsheetEditor: React.ForwardRefExoticComponent<DsheetProps & React.RefAttributes<DSheetEditorHandle>>;
+declare const SpreadsheetEditor: ({ isReadOnly, allowSheetDownload, renderNavbar, enableIndexeddbSync, dsheetId, portalContent, onContentUpdate, onChange, username, selectedTemplate, toggleTemplateSidebar, isTemplateOpen, onboardingComplete, onboardingCompleteLocalStorageKey, onboardingHandler, commentsConfig, setFetchingURLData, setShowFetchURLModal, setInputFetchURLDataBlock, sheetEditorRef: externalSheetEditorRef, onDuneChartEmbed, onSheetCountChange, isAuthorized, getDocumentTitle, updateDocumentTitle, editorStateRef, setSelectedTemplate, isNewSheet, liveQueryRefreshRate, enableLiveQuery, collaboration, customPanels, apiKeyStorage, onDataBlockEvent, smartContracts, theme, onContentSyncStatusChange, }: DsheetProps) => JSX.Element;
 export default SpreadsheetEditor;

package/dist/editor/hooks/use-collab-awareness.d.ts

@@ -1,14 +1,17 @@
 import { Awareness } from 'y-protocols/awareness';
 import { WorkbookInstance } from '../../sheet-engine/react';
+import { CollabUser } from '../../sync-local/types';
 
 /**
  * Reads remote cursor positions from Yjs awareness and keeps Fortune sheet's
  * native presence list in sync. Fortune renders colored cell borders + username
  * labels automatically via context.presences[].
  *
- * The host collaborator roster is emitted by SocketClient from the
- * authoritative server room-members list. This hook owns only cell cursors.
+ * Also emits the full collaborator list (including the local user) via
+ * `onCollaboratorsChange` so host apps can render navbar chips. This mirrors
+ * ddoc's editor-layer awareness handler, which maps awareness.states →
+ * `{ clientId, ...user }` and fires on every awareness update + once on mount.
  */
-export declare const useCollabAwareness: (awareness: Awareness | null | undefined, sheetEditorRef: React.MutableRefObject<WorkbookInstance | null>) => {
+export declare const useCollabAwareness: (awareness: Awareness | null | undefined, sheetEditorRef: React.MutableRefObject<WorkbookInstance | null>, onCollaboratorsChange?: (collaborators: CollabUser[]) => void) => {
     localColor: "#30bced" | "#6eeb83" | "#fa69d1" | "#ecd444" | "#ee6352" | "#db3041" | "#0ad7f2" | "#1bff39";
 };

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

@@ -8,7 +8,7 @@ import * as Y from 'yjs';
  * Hook for managing sheet data
  * Handles initialization, updates, and persistence of sheet data
  */
-export declare const useEditorData: (ydocRef: React.MutableRefObject<Y.Doc | null>, dsheetId: string, sheetEditorRef: React.MutableRefObject<WorkbookInstance | null>, setForceSheetRender?: React.Dispatch<React.SetStateAction<number>>, isReadOnly?: boolean, onChange?: (data: Sheet[]) => void, syncStatus?: "initializing" | "syncing" | "synced" | "error", isContentBootstrapReady?: boolean, commentData?: object, dataBlockCalcFunction?: {
+export declare const useEditorData: (ydocRef: React.MutableRefObject<Y.Doc | null>, dsheetId: string, sheetEditorRef: React.MutableRefObject<WorkbookInstance | null>, setForceSheetRender?: React.Dispatch<React.SetStateAction<number>>, portalContent?: string, isReadOnly?: boolean, onChange?: (data: Sheet[]) => void, syncStatus?: "initializing" | "syncing" | "synced" | "error", commentData?: object, dataBlockCalcFunction?: {
     [key: string]: {
         [key: string]: any;
     };
@@ -16,7 +16,7 @@ export declare const useEditorData: (ydocRef: React.MutableRefObject<Y.Doc | nul
     [key: string]: {
         [key: string]: any;
     };
-}>>, enableLiveQuery?: boolean, liveQueryRefreshRate?: number, apiKeyStorage?: ApiKeyStorage, openApiKeyModal?: OpenApiKeyModalFn, onDataBlockEvent?: (event: DataBlockEvent) => void, allowComments?: boolean, collabEnabled?: boolean) => {
+}>>, enableLiveQuery?: boolean, liveQueryRefreshRate?: number, apiKeyStorage?: ApiKeyStorage, openApiKeyModal?: OpenApiKeyModalFn, onDataBlockEvent?: (event: DataBlockEvent) => void, allowComments?: boolean, hasCollabContentInitialised?: boolean, collabEnabled?: boolean) => {
     sheetData: Sheet[];
     setSheetData: import('react').Dispatch<import('react').SetStateAction<Sheet[]>>;
     currentDataRef: import('react').MutableRefObject<Sheet[]>;

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

@@ -1,11 +1,11 @@
 import { IndexeddbPersistence } from 'y-indexeddb';
 import { CollaborationProps } from '../../sync-local/types';
 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, collaboration?: CollaborationProps, onCollabUpdate?: (fullState: string, updateChunk: string) => void) => {
     ydocRef: import('react').MutableRefObject<Y.Doc | null>;
     persistenceRef: import('react').MutableRefObject<IndexeddbPersistence | null>;
     syncStatus: "error" | "syncing" | "initializing" | "synced";
-    isContentBootstrapReady: boolean;
+    isSyncedRef: import('react').MutableRefObject<boolean>;
     refreshIndexedDB: () => Promise<void>;
     getContentSnapshot: () => import('../../persistence-utils').DSheetContentSnapshot;
     mergeContent: (encodedState: string) => import('../../persistence-utils').DSheetContentSnapshot;
@@ -13,10 +13,6 @@ export declare const useEditorSync: (dsheetId: string, enableIndexeddbSync?: boo
     isCollabReady: boolean;
     isCollabSyncing: boolean;
     terminateSession: () => void;
-    updateTitle: (args: {
-        encryptedTitle: string;
-        documentTitle: string;
-    }) => void;
     awareness: import('y-protocols/awareness.js').Awareness | null;
     hasCollabContentInitialised: boolean;
 };

package/dist/editor/types/comments.d.ts

@@ -1,5 +1,7 @@
 import { default as React } from 'react';
+import { CommentAnchorMove } from '../../sheet-engine/core/settings';
 
+export type { CommentAnchorMove };
 export interface CommentThread {
     id: string;
     key: string;
@@ -12,6 +14,8 @@ export interface CommentThread {
     replies: CommentReply[];
     isResolved?: boolean;
     isDeleted?: boolean;
+    /** IPFS/indexer hash — stable across local `comment-*` ids and on-chain uuids. */
+    contentHash?: string;
 }
 export interface CommentReply {
     id: string;
@@ -41,6 +45,11 @@ export interface CommentsConfig {
     commentsData: Record<string, CommentThread>;
     onSendComment: (key: string, textareaId: string) => void;
     onCommentAction: (action: CommentActionParams) => void;
+    /**
+     * Called after row/column drag-drop or a cell-range move so the host can
+     * remap comment keys. Use `remapCommentAnchors` from the package.
+     */
+    onCellPositionsChanged?: (move: CommentAnchorMove) => void;
     userName?: string;
     ownerAddress?: string;
     currentUserAddress?: string;
@@ -118,6 +127,8 @@ export interface CommentCellUIProps {
     dragHandler: (e: React.MouseEvent<HTMLDivElement, MouseEvent>) => void;
     isHover?: boolean;
     disabled?: boolean;
+    isAuthenticated?: boolean;
+    unauthenticatedFallback?: React.ReactNode;
 }
 export interface CommentsContentProps {
     sheetEditorRef: React.RefObject<SheetEditorRef>;

package/dist/editor/types.d.ts

@@ -10,8 +10,7 @@ import { DSheetContentSnapshot } from '../persistence';
 
 import * as Y from 'yjs';
 export type { ThemeKey } from '../sheet-engine/core/theme';
-export type DSheetPermissionMode = 'view' | 'comment' | 'edit';
-export type { CommentThread, CommentReply, CommentActionParams, CommentsConfig, } from './types/comments';
+export type { CommentThread, CommentReply, CommentActionParams, CommentsConfig, CommentAnchorMove, } from './types/comments';
 export { CommentAction } from './types/comments';
 export interface SheetUpdateData {
     data: Sheet[];
@@ -23,15 +22,6 @@ export interface EditorValues {
     openPanel: (panelId: string) => void;
     closePanel: () => void;
 }
-export type DSheetEditorHandle = WorkbookInstance & {
-    refreshIndexedDB: () => Promise<void>;
-    terminateSession: () => void;
-    updateCollaboratorName: (name: string) => void;
-    updateSessionTitle: (args: {
-        encryptedTitle: string;
-        documentTitle: string;
-    }) => void;
-};
 export interface PanelConfig {
     id: string;
     header: {
@@ -77,23 +67,9 @@ export interface DsheetProps {
     onContentUpdate?: () => void;
     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. */
-    onIndexedDbError?: (error: Error) => void;
     username?: string;
     portalContent?: string;
     isReadOnly?: boolean;
-    /** Permission status displayed above the toolbar. When omitted, read-only
-     * sheets retain the existing View/View-and-comment behavior. */
-    permissionMode?: DSheetPermissionMode;
-    /** Called when a read-only consumer asks to elevate to edit mode. The host
-     * owns access proof, loading, errors, and the resulting mode transition. */
-    onEnterEdit?: () => void;
-    /** Called when an invited commenter needs to authenticate before the host can
-     * recover comment capability. */
-    onSignInToComment?: () => void;
-    /** Lets the host toggle a recovered commenter between comment and view mode. */
-    onViewerModeChange?: (mode: 'comment' | 'view') => void;
     allowSheetDownload?: boolean;
     isTemplateOpen?: boolean;
     selectedTemplate?: string;
@@ -104,8 +80,9 @@ export interface DsheetProps {
     setForceSheetRender?: React.Dispatch<React.SetStateAction<number>>;
     commentsConfig?: CommentsConfig;
     toggleTemplateSidebar?: () => void;
-    /** Legacy ref prop. Standard React refs are also supported. */
-    sheetEditorRef?: React.Ref<DSheetEditorHandle>;
+    sheetEditorRef?: RefObject<WorkbookInstance & {
+        refreshIndexedDB: () => Promise<void>;
+    }>;
     /** Override where datablock API keys are stored (default: localStorage). */
     apiKeyStorage?: ApiKeyStorage;
     /** Optional lifecycle events for analytics / side-effects. */
@@ -116,9 +93,6 @@ export interface DsheetProps {
      * 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. */
     onContentSyncStatusChange?: (status: 'initializing' | 'syncing' | 'synced' | 'error') => void;
-    /** Fires once the first collaboration sync has been reconciled with the
-     * workbook, or when that reconciliation fails. */
-    onCollaborationInitializationComplete?: (result: 'ready' | 'error') => void;
     editorStateRef?: React.MutableRefObject<{
         refreshIndexedDB: () => Promise<void>;
         getContentSnapshot: () => DSheetContentSnapshot;

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

@@ -4,17 +4,9 @@ type CommentData = object | null | undefined;
  * the consumer-provided `commentData`.
  *
  * `ps` is a per-client, permission-gated *view overlay* — it is NOT persisted in
- * ydoc. Every path that rebuilds sheet data from ydoc (portal load, collab sync
- * remount, remote cell edits) produces cells WITHOUT `ps`, so this must run on
- * each such snapshot or the red-triangle indicator vanishes. Because it is
- * gated on the local `allowComments` permission, it must never be written back
- * to shared ydoc state — doing so would let one viewer wipe markers for all.
- *
- * Handles both shapes:
- * - Dense `sheet.data` (the live active sheet in `luckysheetfile`).
- * - Sparse `sheet.celldata` (plain snapshots from `ySheetArrayToPlain`, and
- *   inactive sheets). `initSheetData()` converts celldata → data on activation,
- *   so `ps` set on celldata carries through.
+ * ydoc (`shouldPersistCelldataCell` ignores marker-only cells). Empty cells are
+ * `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.
  */

package/dist/editor/utils/comment-anchors-ydoc.d.ts

@@ -0,0 +1,32 @@
+import * as Y from 'yjs';
+/** Sibling share key on the same Y.Doc as the sheet array. */
+export declare function getCommentAnchorsMapKey(dsheetId: string): string;
+export declare function getCommentAnchorsYMap(ydoc: Y.Doc, dsheetId: string): Y.Map<string>;
+export declare function readCommentAnchorsFromYdoc(ydoc: Y.Doc | null | undefined, dsheetId: string): Record<string, string>;
+type CommentAnchorRecord = {
+    id?: string;
+    key?: string;
+    contentHash?: string;
+};
+/**
+ * Re-key comments by identity first (id, then contentHash), then the comment's
+ * own current cell-key. Stale cell-key aliases that now belong to another
+ * thread must not steal or duplicate it.
+ */
+export declare function applyCommentAnchorMap<T extends CommentAnchorRecord>(commentsData: Record<string, T> | null | undefined, anchors: Record<string, string>): Record<string, T>;
+export declare function applyYdocCommentAnchors<T extends CommentAnchorRecord>(commentsData: Record<string, T> | object | null | undefined, ydoc: Y.Doc | null | undefined, dsheetId: string): Record<string, T>;
+/**
+ * Persist current commentId/contentHash → cell-key into ydoc so viewers/publish
+ * see the remapped positions. No-ops when the map already matches.
+ */
+export declare function writeCommentAnchorsToYdoc({ ydoc, dsheetId, commentsData, handleContentPortal, skipUnmapped, keyMoves, }: {
+    ydoc: Y.Doc | null | undefined;
+    dsheetId: string;
+    commentsData: Record<string, CommentAnchorRecord> | null | undefined;
+    handleContentPortal?: () => void;
+    /** When the map already has entries, skip comments that are not in it yet. */
+    skipUnmapped?: boolean;
+    /** old cell-key → new cell-key so indexer keys still resolve after remap. */
+    keyMoves?: Record<string, string>;
+}): void;
+export {};

package/dist/editor/utils/remap-comment-anchors.d.ts

@@ -0,0 +1,26 @@
+import { CommentAnchorMove } from '../../sheet-engine/core/settings';
+
+/**
+ * old cell-key → new cell-key, matched by comment id. Used when writing
+ * ydoc aliases so indexer keys still resolve after a remap.
+ */
+export declare function commentKeyMovesById<T extends {
+    id?: string;
+    key?: string;
+}>(before: Record<string, T>, after: Record<string, T>): Record<string, string>;
+/**
+ * Remap in-memory comment keys after a row/column drag, cell-range move,
+ * or insert/delete of rows/columns.
+ *
+ * - Row/column drag: apply the full permutation `indexMap` (no collisions).
+ * - Cells: comments in the source rectangle follow the offset; comments that
+ *   only lived in the destination are detached to `WITHOUT_CELL_<id>` so they
+ *   remain in the sidebar instead of colliding with the incoming thread.
+ * - Insert: comments at/after the insertion point shift by `count`.
+ * - Delete: comments on removed rows/cols are detached; later ones shift up/left.
+ */
+export declare function remapCommentAnchors<T extends {
+    key?: string;
+    id?: string;
+}>(commentsData: Record<string, T>, move: CommentAnchorMove): Record<string, T>;
+export type { CommentAnchorMove };