@casualoffice/sheets 0.9.0

package/src/signing/types.ts

@@ -0,0 +1,89 @@
+/**
+ * Signing types — mirror the iframe-protocol envelopes from
+ * `docs/internal/13-iframe-protocol.md` so the SDK and iframe
+ * deliveries can hand the same payloads back and forth.
+ *
+ * Uniform across `app: 'docs' | 'sheet'`. Only the `anchor`
+ * discriminator changes.
+ */
+
+export type SignatureMethod = 'drawn' | 'typed' | 'uploaded';
+
+export type SignatureMode = 'sequential' | 'concurrent';
+
+/**
+ * Doc-anchored field — paragraph id from the editor's `w14:paraId`,
+ * with an optional sub-paragraph search for placing the signature
+ * inside a phrase rather than a whole block.
+ */
+export interface DocAnchor {
+  kind: 'doc';
+  paraId: string;
+  search?: string;
+}
+
+/** Sheet-anchored field — `sheet` name + A1-style `cell` ref. */
+export interface SheetAnchor {
+  kind: 'sheet';
+  sheet: string;
+  cell: string;
+}
+
+export type SignatureAnchor = DocAnchor | SheetAnchor;
+
+export interface SignatureField {
+  /** Per-field id supplied by the host; echoed on every progress event. */
+  fieldId: string;
+  /** Label rendered next to the field — "Employee signature", etc. */
+  label: string;
+  /** Required fields must complete before `onComplete` fires. */
+  required: boolean;
+  /** Where the signature lands in the document. */
+  anchor: SignatureAnchor;
+  /** Allowed signature methods. */
+  methods: SignatureMethod[];
+  /** Optional signer identity the host knows about. */
+  signer?: { name?: string; email?: string };
+}
+
+/** Payload emitted when a signer completes one field. */
+export interface SignedFieldPayload {
+  fieldId: string;
+  method: SignatureMethod;
+  /** Raw signature material — PNG for drawn, UTF-8 string-as-bytes for typed, host-attested bytes for uploaded. */
+  bytes: ArrayBuffer;
+  mime: string;
+  /** Client wall-clock at completion; host typically pairs with a server timestamp. */
+  signedAt: string;
+  /** Optional placement hint a host generating a flat PDF can use. */
+  placement?: { page: number; xPct: number; yPct: number };
+}
+
+/** Payload emitted when all required fields are signed. */
+export interface SignatureCompletePayload {
+  fieldIds: string[];
+  /** Document bytes WITH stamps applied — note (v1): the editor
+   *  returns the unmodified document and a `fields` map so the
+   *  HOST stamps the final bytes. v2 lands editor-side stamping. */
+  bytes: ArrayBuffer;
+  fields: Record<string, SignedFieldPayload>;
+}
+
+export type CancelReason = 'signer_cancelled' | 'session_expired' | 'host_aborted';
+
+/**
+ * Configuration the host hands the editor when opening a signing
+ * session. Maps 1:1 to the iframe `signature.request` envelope.
+ */
+export interface SigningSessionConfig {
+  fields: SignatureField[];
+  mode: SignatureMode;
+  /** Optional banner the editor renders at the top of the pane. */
+  banner?: string;
+  /** Fires once per field as the signer completes it. */
+  onFieldSigned?: (payload: SignedFieldPayload) => void | Promise<void>;
+  /** Fires after every required field is signed. */
+  onComplete?: (payload: SignatureCompletePayload) => void | Promise<void>;
+  /** Fires when either side aborts the session. */
+  onCancel?: (payload: { reason: CancelReason }) => void;
+}

package/src/styles.ts

@@ -0,0 +1,16 @@
+/**
+ * Univer plugin CSS — side-effect-only imports for the eager plugin
+ * set CasualSheets boots. Hosts import this once at app boot:
+ *
+ *   import '@casualoffice/sheets/styles';
+ *
+ * If the host adds lazy plugins (sort, filter, drawing, comments,
+ * conditional formatting, …) it imports the corresponding CSS
+ * separately — those plugins ship their own /lib/index.css.
+ */
+import '@univerjs/design/lib/index.css';
+import '@univerjs/ui/lib/index.css';
+import '@univerjs/docs-ui/lib/index.css';
+import '@univerjs/sheets-ui/lib/index.css';
+import '@univerjs/sheets-formula-ui/lib/index.css';
+import '@univerjs/sheets-numfmt-ui/lib/index.css';

package/src/univer/index.ts

@@ -0,0 +1,17 @@
+/**
+ * Internal Univer wiring shared by the SDK editor and the host app.
+ *
+ * Phase 1 (Batch 1) of the SDK migration lifts the lazy plugin loader out of
+ * `apps/web` so the editor can eventually run entirely from `@casualoffice/sheets`.
+ * It's pure Univer/DI code (no React context, FileSource, collab, or routing) with
+ * module-level singleton state, so the host and the SDK must resolve this one
+ * module instance. Later batches add the facade-coupled helpers (dev-helpers,
+ * paste-merge-hook, zoom override) + the editor core. See
+ * `docs/SDK_MIGRATION_PIPELINE.md` Phase 1.
+ *
+ * @internal — not part of the SDK's semver surface; consumers use `<CasualSheets>`.
+ */
+
+// Lazy plugin loader (CF, DV, hyperlink, note, table, thread-comment, drawing,
+// sort, filter, find-replace) + the module-level Univer holder.
+export * from './lazy-plugins';

package/src/univer/lazy-plugins.ts

@@ -0,0 +1,280 @@
+import type { Univer, IWorkbookData } from '@univerjs/core';
+
+/**
+ * Lazy plugin loading — pipeline Stage 4. The cheap plugins (render,
+ * formula, sheets, sheets-ui, numfmt, docs) stay eager because every
+ * workbook needs them. The heavy / feature-specific plugins (CF, DV,
+ * hyperlink, table, note, thread-comment, drawing, sort, filter,
+ * find-replace) load on demand:
+ *
+ *   1. Eagerly when a snapshot is about to mount and we detect the
+ *      plugin's resource key on it (e.g. `SHEET_CONDITIONAL_FORMATTING_PLUGIN`
+ *      in `data.resources`). This is the safety net: missing this would
+ *      silently drop plugin data on file open.
+ *   2. Lazily when the user reaches for the feature — opens the Data
+ *      tab (sort/filter), hits Ctrl+F (find-replace), uses the Insert
+ *      tab (drawing), etc. The shell hooks `ensurePlugin(...)` into
+ *      these triggers and awaits before the action runs.
+ *
+ * Each loader returns the plugins-to-register in the correct order
+ * (base before UI, same as `plugins.ts`). Registration order matters
+ * in Univer; the loaders bundle a small group together to keep that
+ * locality explicit.
+ */
+
+export type LazyPluginGroup =
+  | 'cf'
+  | 'dv'
+  | 'hyperlink'
+  | 'note'
+  | 'table'
+  | 'threadComment'
+  | 'drawing'
+  | 'sort'
+  | 'filter'
+  | 'findReplace';
+
+type Loader = () => Promise<Array<[unknown, unknown?]>>;
+
+const LOADERS: Record<LazyPluginGroup, Loader> = {
+  cf: async () => {
+    const [base, ui] = await Promise.all([
+      import('@univerjs/sheets-conditional-formatting'),
+      import('@univerjs/sheets-conditional-formatting-ui'),
+    ]);
+    return [
+      [base.UniverSheetsConditionalFormattingPlugin],
+      [ui.UniverSheetsConditionalFormattingUIPlugin],
+    ];
+  },
+  dv: async () => {
+    const [base, ui] = await Promise.all([
+      import('@univerjs/sheets-data-validation'),
+      import('@univerjs/sheets-data-validation-ui'),
+    ]);
+    return [
+      [base.UniverSheetsDataValidationPlugin],
+      [ui.UniverSheetsDataValidationUIPlugin],
+    ];
+  },
+  hyperlink: async () => {
+    const [base, ui] = await Promise.all([
+      import('@univerjs/sheets-hyper-link'),
+      import('@univerjs/sheets-hyper-link-ui'),
+    ]);
+    return [
+      [base.UniverSheetsHyperLinkPlugin],
+      [ui.UniverSheetsHyperLinkUIPlugin],
+    ];
+  },
+  note: async () => {
+    const [base, ui] = await Promise.all([
+      import('@univerjs/sheets-note'),
+      import('@univerjs/sheets-note-ui'),
+    ]);
+    return [[base.UniverSheetsNotePlugin], [ui.UniverSheetsNoteUIPlugin]];
+  },
+  table: async () => {
+    const [base, ui] = await Promise.all([
+      import('@univerjs/sheets-table'),
+      import('@univerjs/sheets-table-ui'),
+    ]);
+    return [[base.UniverSheetsTablePlugin], [ui.UniverSheetsTableUIPlugin]];
+  },
+  threadComment: async () => {
+    const [tc, tcUi, sheetsTc, sheetsTcUi] = await Promise.all([
+      import('@univerjs/thread-comment'),
+      import('@univerjs/thread-comment-ui'),
+      import('@univerjs/sheets-thread-comment'),
+      import('@univerjs/sheets-thread-comment-ui'),
+    ]);
+    return [
+      [tc.UniverThreadCommentPlugin],
+      [tcUi.UniverThreadCommentUIPlugin],
+      [sheetsTc.UniverSheetsThreadCommentPlugin],
+      [sheetsTcUi.UniverSheetsThreadCommentUIPlugin],
+    ];
+  },
+  drawing: async () => {
+    const [d, dUi, sd, sdUi] = await Promise.all([
+      import('@univerjs/drawing'),
+      import('@univerjs/drawing-ui'),
+      import('@univerjs/sheets-drawing'),
+      import('@univerjs/sheets-drawing-ui'),
+      // Side-effect imports: install FWorksheet.insertImage / getImages /
+      // updateImages on the facade prototype. Without these, code that
+      // reaches in via the FUniver facade (e2e specs, future shell glue)
+      // sees an undefined method even though the plugin is registered.
+      import('@univerjs/sheets-drawing/facade'),
+      import('@univerjs/sheets-drawing-ui/facade'),
+    ]);
+    return [
+      [d.UniverDrawingPlugin],
+      [dUi.UniverDrawingUIPlugin],
+      [sd.UniverSheetsDrawingPlugin],
+      [sdUi.UniverSheetsDrawingUIPlugin],
+    ];
+  },
+  sort: async () => {
+    const [base, ui] = await Promise.all([
+      import('@univerjs/sheets-sort'),
+      import('@univerjs/sheets-sort-ui'),
+    ]);
+    return [[base.UniverSheetsSortPlugin], [ui.UniverSheetsSortUIPlugin]];
+  },
+  filter: async () => {
+    const [base, ui] = await Promise.all([
+      import('@univerjs/sheets-filter'),
+      import('@univerjs/sheets-filter-ui'),
+    ]);
+    return [[base.UniverSheetsFilterPlugin], [ui.UniverSheetsFilterUIPlugin]];
+  },
+  findReplace: async () => {
+    const [base, sheets] = await Promise.all([
+      import('@univerjs/find-replace'),
+      import('@univerjs/sheets-find-replace'),
+    ]);
+    return [[base.UniverFindReplacePlugin], [sheets.UniverSheetsFindReplacePlugin]];
+  },
+};
+
+/**
+ * Map from a Univer `data.resources[].name` to the lazy group that owns
+ * it. Used by `eagerLoadForSnapshot` to pre-register plugins whose
+ * state already lives on the workbook so file-open never silently
+ * drops a CF rule / table / drawing / etc.
+ */
+const RESOURCE_NAME_TO_GROUP: Record<string, LazyPluginGroup> = {
+  SHEET_CONDITIONAL_FORMATTING_PLUGIN: 'cf',
+  SHEET_DATA_VALIDATION_PLUGIN: 'dv',
+  SHEET_HYPER_LINK_PLUGIN: 'hyperlink',
+  SHEET_NOTE_PLUGIN: 'note',
+  SHEET_TABLE_PLUGIN: 'table',
+  SHEET_THREAD_COMMENT_BASE_PLUGIN: 'threadComment',
+  SHEET_DRAWING_PLUGIN: 'drawing',
+  SHEET_SORT_PLUGIN: 'sort',
+  SHEET_FILTER_PLUGIN: 'filter',
+};
+
+const loaded = new Set<LazyPluginGroup>();
+const inflight = new Map<LazyPluginGroup, Promise<void>>();
+
+/**
+ * Module-level reference to the live Univer instance, set by
+ * `UniverSheet.tsx` immediately after `new Univer()`. Lets shell code
+ * call `ensurePluginByName(group)` without plumbing the Univer
+ * instance through React context (the FUniver facade doesn't expose
+ * its host). Cleared on dispose so callers fail loudly if they hit
+ * the lazy path after teardown.
+ */
+let currentUniver: Univer | null = null;
+
+export function setUniverForLazyLoad(univer: Univer | null): void {
+  currentUniver = univer;
+}
+
+/**
+ * Idempotent: subsequent calls for the same group resolve immediately
+ * if the plugin is already loaded; concurrent calls share the same
+ * in-flight promise so we never double-register.
+ */
+export function ensurePlugin(univer: Univer, group: LazyPluginGroup): Promise<void> {
+  if (loaded.has(group)) return Promise.resolve();
+  const existing = inflight.get(group);
+  if (existing) return existing;
+  const loader = LOADERS[group];
+  if (!loader) return Promise.resolve();
+  const p = loader().then((plugins) => {
+    for (const [PluginCtor, config] of plugins) {
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      univer.registerPlugin(PluginCtor as any, config);
+    }
+    loaded.add(group);
+    inflight.delete(group);
+  });
+  inflight.set(group, p);
+  return p;
+}
+
+/**
+ * Shell-friendly variant of `ensurePlugin` that pulls the Univer
+ * instance from the module-level holder set by `UniverSheet.tsx`. Use
+ * this anywhere we only have the FUniver facade (toolbar callbacks,
+ * panel handlers). Returns a resolved promise if the holder is empty —
+ * the worst case is a no-op, never a throw.
+ */
+export function ensurePluginByName(group: LazyPluginGroup): Promise<void> {
+  if (loaded.has(group)) return Promise.resolve();
+  if (!currentUniver) return Promise.resolve();
+  return ensurePlugin(currentUniver, group);
+}
+
+/**
+ * Walk a snapshot for plugin-owned resources + side-channel hyperlinks
+ * and eagerly load every group that's referenced. Returns a promise
+ * the caller MUST await before `createUnit` — Univer's resource manager
+ * silently discards keys for plugins that aren't yet registered.
+ */
+export async function eagerLoadForSnapshot(univer: Univer, snapshot: IWorkbookData): Promise<void> {
+  const groups = new Set<LazyPluginGroup>();
+  const resources = snapshot.resources ?? [];
+  for (const r of resources) {
+    const g = RESOURCE_NAME_TO_GROUP[r.name];
+    if (g) groups.add(g);
+  }
+  // Hyperlinks live inline in cell.p (Stage 5) — the hyperlink plugin
+  // still owns click handling / context-menu actions, so eager-load
+  // when any cell has a HYPERLINK customRange.
+  if (snapshotHasHyperlinks(snapshot)) groups.add('hyperlink');
+  await Promise.all(Array.from(groups).map((g) => ensurePlugin(univer, g)));
+}
+
+/**
+ * Idle-load every remaining lazy group AFTER Univer is mounted. The
+ * bundle split (each group ships as its own chunk) is the persistent
+ * boot-time win — the initial paint doesn't pay for them. This
+ * idle-load just ensures they're all eventually registered so a user
+ * clicking "Insert > Table" doesn't hit a no-op.
+ *
+ * Loads in parallel via `requestIdleCallback` so they don't compete
+ * with the first paint, falling back to `setTimeout(0)` in browsers
+ * without rIC (Safari).
+ */
+export function idleLoadAll(univer: Univer): void {
+  const groups = Object.keys(LOADERS) as LazyPluginGroup[];
+  schedule(() => {
+    for (const g of groups) {
+      void ensurePlugin(univer, g);
+    }
+  });
+}
+
+function schedule(fn: () => void): void {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const ric = (globalThis as any).requestIdleCallback as
+    | ((cb: () => void, opts?: { timeout: number }) => number)
+    | undefined;
+  if (ric) ric(fn, { timeout: 500 });
+  else setTimeout(fn, 0);
+}
+
+function snapshotHasHyperlinks(snapshot: IWorkbookData): boolean {
+  const sheetOrder = snapshot.sheetOrder ?? [];
+  for (const sid of sheetOrder) {
+    const sheet = snapshot.sheets?.[sid];
+    if (!sheet?.cellData) continue;
+    const cellData = sheet.cellData as Record<
+      string,
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      Record<string, { p?: any }>
+    >;
+    for (const r of Object.keys(cellData)) {
+      const row = cellData[r];
+      for (const c of Object.keys(row)) {
+        const ranges = row[c]?.p?.body?.customRanges ?? [];
+        if (ranges.some((cr: { rangeType?: number }) => cr.rangeType === 0)) return true;
+      }
+    }
+  }
+  return false;
+}

package/src/xlsx/_perf.ts

@@ -0,0 +1,14 @@
+/**
+ * Tiny perf shim — drop-in replacement for apps/web's `../perf` so the
+ * SDK doesn't have to pull in a User Timing dependency. The host can
+ * wrap individual SDK calls with its own timing if it wants spans;
+ * inside the SDK they're cheap no-op forwards.
+ */
+
+export function timeIt<T>(_label: string, fn: () => T): T {
+  return fn();
+}
+
+export async function timeItAsync<T>(_label: string, fn: () => Promise<T>): Promise<T> {
+  return fn();
+}

package/src/xlsx/_snapshot-constants.ts

@@ -0,0 +1,15 @@
+/**
+ * Snapshot defaults pulled out of apps/web/src/snapshot.ts so the
+ * SDK's xlsx parser doesn't have to import that whole module. Keep
+ * these in sync with the host snapshot module if the defaults drift.
+ *
+ * UNIVER_VERSION must match the runtime Univer the host boots — the
+ * appVersion field on the IWorkbookData snapshot is checked at unit
+ * mount and a mismatch warns in dev. Sheet apps' `../snapshot` reads
+ * the version from the workspace's @univerjs/core dep; we hardcode
+ * the same minor here because the SDK declares @univerjs/* as
+ * `^0.24.0` peer.
+ */
+export const INITIAL_ROWS = 1024;
+export const INITIAL_COLUMNS = 26;
+export const UNIVER_VERSION = '0.24.0';

package/src/xlsx/comments-resource.ts

@@ -0,0 +1,209 @@
+import type ExcelJS from 'exceljs';
+import type { IWorkbookData } from '@univerjs/core';
+
+/**
+ * xlsx-native `cell.note` ⇄ Univer `thread-comment` resource bridge.
+ *
+ * Comments in xlsx live on the cell itself (`xl/comments<N>.xml`).
+ * Univer's thread-comment plugin stores them in a workbook-level
+ * resource keyed by sheet id under the name below — same
+ * registration pattern as defined-names. Each side of the round-trip
+ * has to translate to the shape the other one expects:
+ *
+ *   xlsx cell.note (string | { texts: [{ text }] })
+ *     ⇅
+ *   { dataStream: "<text>\r\n" }  (Univer IDocumentBody minimal form)
+ *
+ * Why this exists separately from the parser/exporter modules:
+ *   1. Two-sided code lives next to itself so the inverse stays
+ *      obvious. The audit test fails the moment one side drifts.
+ *   2. The `IThreadComment` row builder is non-trivial and reused
+ *      verbatim on both sides — extracting it keeps parse-impl and
+ *      export-impl from carrying near-duplicate shape definitions.
+ */
+
+// Mirrors vendor/univer/packages/thread-comment/src/controllers/tc-resource.controller.ts:25
+// — the resource registration name the plugin's controller subscribes
+// to at workbook load. Hard-coding instead of importing avoids pulling
+// the plugin into the xlsx worker bundle (thread-comment ships UI deps
+// that don't tree-shake cleanly in a Worker context).
+export const THREAD_COMMENT_RESOURCE = 'SHEET_UNIVER_THREAD_COMMENT_PLUGIN';
+
+// Minimal subset of Univer's `IThreadComment` we synthesise. The
+// plugin populates the rest (children, mentions, resolved) on
+// subsequent edits; xlsx-native comments don't carry any of them.
+export type SynthComment = {
+  id: string;
+  threadId: string;
+  ref: string;        // "B2" style
+  dT: string;         // ISO date
+  personId: string;
+  text: { dataStream: string };
+  unitId: string;
+  subUnitId: string;
+  // children: [] on import — Univer's controller tolerates this
+  // because `addComment` of a root with no children is the normal
+  // create path.
+  children?: never[];
+};
+
+const PERSON_FROM_XLSX = 'imported';
+
+function colToLetters(n: number): string {
+  let out = '';
+  let v = n;
+  while (v >= 0) {
+    out = String.fromCharCode(65 + (v % 26)) + out;
+    v = Math.floor(v / 26) - 1;
+  }
+  return out;
+}
+
+function refOf(row: number, column: number): string {
+  return `${colToLetters(column)}${row + 1}`;
+}
+
+function noteToString(note: unknown): string | null {
+  if (typeof note === 'string') return note.trim() ? note : null;
+  if (note && typeof note === 'object') {
+    // ExcelJS's expanded shape: { texts: [{ text }] }. Fall back to
+    // `.text` if a single-string variant came back through some
+    // odder code path.
+    const texts = (note as { texts?: Array<{ text?: string }> }).texts;
+    if (Array.isArray(texts)) {
+      const joined = texts.map((t) => t?.text ?? '').join('');
+      return joined.trim() ? joined : null;
+    }
+  }
+  return null;
+}
+
+/**
+ * Walk every worksheet and collect xlsx-native `cell.note` entries
+ * into a Univer thread-comment resource payload. The synthesised IDs
+ * and dates aren't stable — re-opening the same file produces new
+ * ones — which is fine for the use cases we care about (comments
+ * survive the round-trip; nobody is referring to them by id).
+ */
+export function readCommentsFromXlsx(
+  wb: ExcelJS.Workbook,
+  unitId: string,
+  sheetIdForExcel: (excelId: number) => string,
+): Record<string, SynthComment[]> {
+  const out: Record<string, SynthComment[]> = {};
+  let seq = 0;
+  const nowIso = new Date().toISOString();
+
+  for (const ws of wb.worksheets) {
+    const subUnitId = sheetIdForExcel(ws.id);
+    const bucket: SynthComment[] = [];
+    ws.eachRow({ includeEmpty: false }, (row, rowNumber) => {
+      row.eachCell({ includeEmpty: false }, (cell, colNumber) => {
+        // ExcelJS exposes notes on cells with comments — the field is
+        // missing entirely on the vast majority of cells, so iterating
+        // every cell is cheap.
+        const note = (cell as unknown as { note?: unknown }).note;
+        const text = noteToString(note);
+        if (!text) return;
+        const id = `xc-${unitId}-${seq++}`;
+        bucket.push({
+          id,
+          threadId: id,           // single-comment thread; thread id = root id
+          ref: refOf(rowNumber - 1, colNumber - 1),
+          dT: nowIso,
+          personId: PERSON_FROM_XLSX,
+          // Univer's body convention terminates with `\r\n` (one paragraph).
+          // Without it the cursor in the panel jumps a column on first
+          // open of the comment.
+          text: { dataStream: `${text}\r\n` },
+          unitId,
+          subUnitId,
+          children: [],
+        });
+      });
+    });
+    if (bucket.length > 0) out[subUnitId] = bucket;
+  }
+
+  return out;
+}
+
+/**
+ * Merge a synthesised comment payload into the workbook's `resources`
+ * array. Skipped when the workbook already carries a thread-comment
+ * resource from our hidden sidecar (`__casual_sheets_resources__`) —
+ * that one has the full plugin shape; we shouldn't clobber it with a
+ * lossy xlsx-native re-derivation.
+ */
+export function mergeCommentsIntoResources(
+  resources: IWorkbookData['resources'],
+  comments: Record<string, SynthComment[]>,
+): IWorkbookData['resources'] {
+  if (Object.keys(comments).length === 0) return resources;
+  const existing = resources?.find((r) => r.name === THREAD_COMMENT_RESOURCE);
+  if (existing) return resources;
+  const next = [...(resources ?? [])];
+  next.push({
+    name: THREAD_COMMENT_RESOURCE,
+    data: JSON.stringify(comments),
+  });
+  return next;
+}
+
+/**
+ * Read the thread-comment resource off a snapshot. Tolerant of older
+ * / missing / malformed payloads — those cases return `{}` so the
+ * exporter just skips writing notes rather than throwing on save.
+ */
+export function readCommentsFromSnapshot(
+  data: IWorkbookData,
+): Record<string, SynthComment[]> {
+  const entry = data.resources?.find((r) => r.name === THREAD_COMMENT_RESOURCE);
+  if (!entry?.data) return {};
+  try {
+    const parsed = JSON.parse(entry.data) as Record<string, unknown>;
+    if (!parsed || typeof parsed !== 'object') return {};
+    const out: Record<string, SynthComment[]> = {};
+    for (const [sheetId, value] of Object.entries(parsed)) {
+      if (!Array.isArray(value)) continue;
+      const bucket: SynthComment[] = [];
+      for (const c of value) {
+        if (!c || typeof c !== 'object') continue;
+        const obj = c as Record<string, unknown>;
+        const text = (obj.text as { dataStream?: string } | undefined)?.dataStream;
+        const ref = typeof obj.ref === 'string' ? obj.ref : null;
+        if (!ref || typeof text !== 'string') continue;
+        bucket.push(c as SynthComment);
+      }
+      if (bucket.length > 0) out[sheetId] = bucket;
+    }
+    return out;
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Extract the plain string from a Univer comment body. Strips the
+ * trailing `\r\n` (or `\n`) that the body convention appends so the
+ * xlsx-side note doesn't show as a blank line below the text in
+ * Excel's pop-up.
+ */
+export function commentBodyToString(body: SynthComment['text']): string {
+  const s = body?.dataStream ?? '';
+  return s.replace(/[\r\n]+$/, '');
+}
+
+/**
+ * Parse an "A1"-style ref back to a zero-based (row, col). Falls back
+ * to (-1, -1) on malformed input — exporter callers should skip in
+ * that case.
+ */
+export function refToRowCol(ref: string): { row: number; column: number } {
+  const m = /^([A-Z]+)(\d+)$/.exec(ref);
+  if (!m) return { row: -1, column: -1 };
+  const letters = m[1];
+  let col = 0;
+  for (let i = 0; i < letters.length; i++) col = col * 26 + (letters.charCodeAt(i) - 64);
+  return { row: Number(m[2]) - 1, column: col - 1 };
+}

package/src/xlsx/constants.ts

@@ -0,0 +1,9 @@
+/**
+ * Name of a hidden worksheet we use to stash JSON we can't represent
+ * natively in xlsx (Univer plugin state — e.g. table definitions, outline
+ * groups). On open we recognize and consume it, never showing it to the
+ * user. Defined in its own module so both the parser worker and the
+ * exporter worker can import it without dragging the other one's
+ * ExcelJS code into their bundle.
+ */
+export const RESOURCES_SHEET = '__casual_sheets_resources__';