@casualoffice/sheets 0.9.0 → 0.10.0

package/src/collab/bridge.unit.test.ts

@@ -0,0 +1,160 @@
+/**
+ * Pure-function unit tests for the bridge helpers. Runs under
+ * `node --import tsx` via `node:test`; no extra test runner installed.
+ *
+ * Stateful bridge logic (Yjs observers, command-service hooks, compaction)
+ * is covered by tests/e2e/coedit-*.spec.ts. This file only covers the
+ * pure stuff that doesn't need a Univer instance.
+ *
+ * Run with: `pnpm test:unit`
+ */
+import { strict as assert } from 'node:assert';
+import { test } from 'node:test';
+
+import { deepRewriteUnitId } from './bridge-helpers';
+
+test('deepRewriteUnitId rewrites top-level unitId', () => {
+  const params = { unitId: 'sender-id', subUnitId: 'sheet-1', value: 'A' };
+  const out = deepRewriteUnitId(params, 'local-id') as typeof params;
+  assert.equal(out.unitId, 'local-id');
+  assert.equal(out.subUnitId, 'sheet-1');
+  assert.notEqual(out, params, 'should return a clone when changes happen');
+});
+
+test('deepRewriteUnitId rewrites nested unitId (range.unitId)', () => {
+  const params = {
+    range: { unitId: 'sender-id', startRow: 0, startColumn: 0 },
+    rangeData: [{ unitId: 'sender-id', sr: 0 }],
+  };
+  const out = deepRewriteUnitId(params, 'local-id') as {
+    range: { unitId: string };
+    rangeData: Array<{ unitId: string }>;
+  };
+  assert.equal(out.range.unitId, 'local-id');
+  assert.equal(out.rangeData[0].unitId, 'local-id');
+});
+
+test('deepRewriteUnitId rewrites unitId inside array entries', () => {
+  const params = {
+    moves: [
+      { source: { unitId: 'sender-id' }, target: { unitId: 'sender-id' } },
+      { source: { unitId: 'sender-id' } },
+    ],
+  };
+  const out = deepRewriteUnitId(params, 'local-id') as {
+    moves: Array<{ source: { unitId: string }; target?: { unitId: string } }>;
+  };
+  assert.equal(out.moves[0].source.unitId, 'local-id');
+  assert.equal(out.moves[0].target?.unitId, 'local-id');
+  assert.equal(out.moves[1].source.unitId, 'local-id');
+});
+
+test('deepRewriteUnitId returns input unchanged when no unitId present', () => {
+  const params = { subUnitId: 'sheet-1', cellValue: { 0: { 0: { v: 1 } } } };
+  const out = deepRewriteUnitId(params, 'local-id');
+  assert.strictEqual(out, params, 'should return same reference when nothing changes');
+});
+
+test('deepRewriteUnitId leaves unitId unchanged when already local', () => {
+  const params = { unitId: 'local-id', other: 1 };
+  const out = deepRewriteUnitId(params, 'local-id');
+  assert.strictEqual(out, params);
+});
+
+test('deepRewriteUnitId does not descend into class instances', () => {
+  class Custom {
+    unitId = 'sender-id';
+  }
+  const inst = new Custom();
+  const params = { wrap: inst };
+  const out = deepRewriteUnitId(params, 'local-id') as { wrap: Custom };
+  // Class instances are not plain objects, so the walker stops at the
+  // boundary — the unitId stays as-is. Univer mutation params are
+  // required to be JSON-friendly plain objects; anything carrying a
+  // class instance is out of scope for the bridge.
+  assert.equal(out.wrap.unitId, 'sender-id');
+});
+
+test('deepRewriteUnitId handles deeply nested unitId chains', () => {
+  const params = {
+    a: { b: { c: { d: { unitId: 'sender-id' } } } },
+  };
+  const out = deepRewriteUnitId(params, 'local-id') as {
+    a: { b: { c: { d: { unitId: string } } } };
+  };
+  assert.equal(out.a.b.c.d.unitId, 'local-id');
+});
+
+test('deepRewriteUnitId preserves null and primitive leaves', () => {
+  const params = {
+    unitId: 'sender-id',
+    nullField: null,
+    boolField: true,
+    numField: 42,
+    strField: 'hello',
+  };
+  const out = deepRewriteUnitId(params, 'local-id') as Record<string, unknown>;
+  assert.equal(out.unitId, 'local-id');
+  assert.equal(out.nullField, null);
+  assert.equal(out.boolField, true);
+  assert.equal(out.numField, 42);
+  assert.equal(out.strField, 'hello');
+});
+
+/* ── rewriteJson1OpPathUnitId — Stream F1 drawing-sync fix ───────── */
+
+import { rewriteJson1OpPathUnitId } from './bridge-helpers';
+
+test('rewriteJson1OpPathUnitId swaps leading unitId in a single JSONOp', () => {
+  // Realistic shape from `sheet.mutation.set-drawing-apply`:
+  // path-prefix...trailing-component. Trailing component is an
+  // object describing the mutation (insert {i: ...}, remove {r: 0},
+  // edit {ed: ...}).
+  const op = ['owner-wb', 'sheet-1', 'data', 'drawing-7', { i: { drawingId: 'drawing-7' } }];
+  const out = rewriteJson1OpPathUnitId(op, 'owner-wb', 'joiner-wb') as unknown[];
+  assert.equal(out[0], 'joiner-wb');
+  assert.equal(out[1], 'sheet-1');
+  assert.equal(out[2], 'data');
+  assert.equal(out[3], 'drawing-7');
+  // Trailing component should be preserved by reference (we shallow-copy).
+  assert.deepEqual(out[4], { i: { drawingId: 'drawing-7' } });
+});
+
+test('rewriteJson1OpPathUnitId walks a JSONOpList (op of ops)', () => {
+  const opList = [
+    ['owner-wb', 'sheet-1', 'data', 'd-1', { i: { x: 1 } }],
+    ['owner-wb', 'sheet-1', 'order', 0, { i: 'd-1' }],
+  ];
+  const out = rewriteJson1OpPathUnitId(opList, 'owner-wb', 'joiner-wb') as unknown[][];
+  assert.equal(out.length, 2);
+  assert.equal(out[0][0], 'joiner-wb');
+  assert.equal(out[1][0], 'joiner-wb');
+});
+
+test('rewriteJson1OpPathUnitId returns input unchanged when no match at [0]', () => {
+  // E.g. some other plugin's json1 op that doesn't lead with unitId.
+  const op = ['something-else', 'whatever', { i: 1 }];
+  const out = rewriteJson1OpPathUnitId(op, 'owner-wb', 'joiner-wb');
+  assert.equal(out, op); // identity — no copy made when nothing to do
+});
+
+test('rewriteJson1OpPathUnitId is a no-op when old === new', () => {
+  const op = ['same-wb', 'sheet-1', 'data', 'd-1', { i: { x: 1 } }];
+  const out = rewriteJson1OpPathUnitId(op, 'same-wb', 'same-wb');
+  assert.equal(out, op);
+});
+
+test('rewriteJson1OpPathUnitId is a no-op for non-array input', () => {
+  assert.equal(rewriteJson1OpPathUnitId(null, 'a', 'b'), null);
+  assert.equal(rewriteJson1OpPathUnitId(undefined, 'a', 'b'), undefined);
+  assert.equal(rewriteJson1OpPathUnitId('string', 'a', 'b'), 'string');
+  assert.equal(rewriteJson1OpPathUnitId(42, 'a', 'b'), 42);
+});
+
+test('rewriteJson1OpPathUnitId preserves a single-element op-list edge case', () => {
+  // JSONOpList with one entry — detection key is "first element is array".
+  const opList = [['owner-wb', 'sheet-1', 'data', 'd-1', { i: 1 }]];
+  const out = rewriteJson1OpPathUnitId(opList, 'owner-wb', 'joiner-wb') as unknown[][];
+  assert.equal(out.length, 1);
+  assert.equal(out[0][0], 'joiner-wb');
+});

package/src/collab/index.ts

@@ -0,0 +1,38 @@
+/**
+ * `@casualoffice/sheets/collab` — opt-in real-time co-editing.
+ *
+ * The editor is collab-unaware until a host calls `attachCollab(api, opts)`.
+ * Yjs + Hocuspocus is the realtime transport; authoritative persistence stays
+ * host-side (WOPI / backend) via the save/exit event contract.
+ *
+ * Requires the host to provide `yjs` and `@hocuspocus/provider` (peer deps) so
+ * there's a single Yjs instance in the graph — two copies break `Y.Doc`
+ * identity and awareness.
+ */
+
+export {
+  attachCollab,
+  type AttachCollabOptions,
+  type CollabAttachable,
+  type CollabHandle,
+  type CollabRole,
+  type CollabConnectionStatus,
+} from './attachCollab';
+
+// The mutation bridge — the framework-agnostic core (subscribes to
+// onMutationExecutedForCollab, replays with fromCollab, guards __splitChunk__).
+// Exposed for hosts that drive their own provider/doc lifecycle instead of
+// using attachCollab's batteries-included transport.
+export {
+  startBridge,
+  type BridgeHandle,
+  type BridgeOptions,
+  SYNCED_MUTATIONS,
+  REVERTABLE_MUTATIONS,
+} from './bridge';
+export {
+  type ReplayFailureRecord,
+  type ReplayClassification,
+  classifyReplayError,
+} from './replay-retry';
+export { deepRewriteUnitId, rewriteJson1OpPathUnitId } from './bridge-helpers';

package/src/collab/replay-retry.ts

@@ -0,0 +1,137 @@
+/**
+ * Replay-failure retry classifier + scheduler.
+ *
+ * Pure helpers used by the Yjs bridge to recover from transient
+ * mutation-replay failures (most often dynamic-import chunk-load
+ * errors during the lazy-plugin gate) without conflating them with
+ * permanent failures (malformed mutation params, unknown command id).
+ *
+ * Decoupled from bridge.ts so we can unit-test the classification +
+ * backoff logic without standing up a full Yjs doc + Univer engine.
+ *
+ * See docs/PRODUCTION_PIPELINE.md → Stream A1 for design context.
+ */
+
+/** Maximum retry attempts for transient failures. */
+export const TRANSIENT_RETRY_DELAYS_MS = [300, 900, 2700] as const;
+
+/** Maximum entries kept in the dead-letter ring buffer. */
+export const DEAD_LETTER_CAP = 20;
+
+export type ReplayClassification = 'transient' | 'permanent';
+
+export interface ReplayFailureRecord {
+  /** Mutation id (e.g. 'sheet.mutation.set-range-values'). */
+  id: string;
+  /** Mutation params at time of failure (unfiltered; may be large). */
+  params: unknown;
+  /** Last error's message (string-coerced for log/UI safety). */
+  lastError: string;
+  /** Total attempts made (1 = first try, no retries). */
+  attempts: number;
+  /** ms-since-epoch of the FIRST failure for this record. */
+  firstFailedAt: number;
+  /** ms-since-epoch of the most recent failure for this record. */
+  lastFailedAt: number;
+  /** Whether the classifier called this transient or permanent. */
+  classification: ReplayClassification;
+}
+
+/**
+ * Decide whether a replay error is worth retrying.
+ *
+ * Transient class: dynamic-import / chunk-load failures. These come
+ * from the lazy-plugin gate fetching a webpack chunk over the
+ * network; a flap on the user's connection drops the fetch and the
+ * lazy `import()` rejects with one of several distinct shapes:
+ *
+ *   - Webpack 5: `ChunkLoadError` with name === 'ChunkLoadError'
+ *   - Webpack 4 / vite: 'Loading chunk N failed.'
+ *   - Vite / native ESM: 'Failed to fetch dynamically imported module'
+ *   - Native fetch under offline: 'NetworkError when attempting to fetch'
+ *
+ * All four resolve on retry once the network recovers. Everything
+ * else (executeCommand rejections from bad params, missing handlers,
+ * out-of-bounds ranges) is permanent — retrying just burns the same
+ * stack trace N more times.
+ *
+ * Conservative bias: when in doubt, classify permanent. A false
+ * negative (transient → permanent) costs us a dead-letter entry the
+ * user can re-trigger by reloading; a false positive (permanent →
+ * transient) wastes 4 s of retries on a known-broken mutation.
+ */
+export function classifyReplayError(err: unknown): ReplayClassification {
+  if (err == null) return 'permanent';
+
+  // Error instances: check name first (ChunkLoadError sets this even
+  // though it's not on stock Error), then message.
+  const e = err as { name?: unknown; message?: unknown };
+  const name = typeof e.name === 'string' ? e.name : '';
+  const message = typeof e.message === 'string' ? e.message : String(err);
+
+  if (name === 'ChunkLoadError') return 'transient';
+
+  const lower = message.toLowerCase();
+  if (lower.includes('loading chunk') && lower.includes('failed')) {
+    return 'transient';
+  }
+  if (lower.includes('failed to fetch dynamically imported')) {
+    return 'transient';
+  }
+  if (lower.includes('networkerror when attempting to fetch')) {
+    return 'transient';
+  }
+  // Generic 'network request failed' from some bundler error wrappers.
+  if (lower.includes('network request failed')) return 'transient';
+
+  return 'permanent';
+}
+
+/**
+ * Run `task` with up to `delays.length` retries. The first attempt is
+ * immediate; each subsequent attempt waits `delays[i-1]` ms.
+ *
+ * Resolves with the task's value on the first success. Rejects with
+ * the LAST error after all attempts fail.
+ *
+ * `shouldRetry` is called between attempts. If it returns false, the
+ * loop bails immediately with the current error — this lets the
+ * caller switch to permanent-failure handling mid-sequence (e.g. if
+ * a follow-up error reveals the real problem was permanent all along).
+ */
+export async function withRetry<T>(
+  task: () => Promise<T>,
+  delays: readonly number[],
+  shouldRetry: (err: unknown, attemptsSoFar: number) => boolean = () => true,
+  sleep: (ms: number) => Promise<void> = (ms) => new Promise((r) => setTimeout(r, ms)),
+): Promise<T> {
+  let lastErr: unknown;
+  for (let i = 0; i <= delays.length; i += 1) {
+    try {
+      return await task();
+    } catch (err) {
+      lastErr = err;
+      const attempts = i + 1;
+      if (i >= delays.length) break;
+      if (!shouldRetry(err, attempts)) break;
+      await sleep(delays[i]);
+    }
+  }
+  throw lastErr;
+}
+
+/**
+ * Ring buffer for dead-letter records. Append-only; oldest entry
+ * evicts on overflow. Caller owns the backing array — we return a
+ * new array on push so React state updates can see the change by
+ * reference.
+ */
+export function pushDeadLetter(
+  buffer: readonly ReplayFailureRecord[],
+  rec: ReplayFailureRecord,
+  cap: number = DEAD_LETTER_CAP,
+): ReplayFailureRecord[] {
+  const next =
+    buffer.length >= cap ? [...buffer.slice(buffer.length - cap + 1), rec] : [...buffer, rec];
+  return next;
+}

package/src/collab/replay-retry.unit.test.ts

@@ -0,0 +1,223 @@
+/**
+ * Pure-state tests for the replay-retry classifier + scheduler. The
+ * bridge owns the integration (which depends on a live Yjs doc +
+ * Univer engine); these tests pin the failure-class boundary so the
+ * "what counts as transient" decision is checked-in instead of buried
+ * in production code.
+ *
+ * Run with: `pnpm test:unit`
+ */
+import { strict as assert } from 'node:assert';
+import { test } from 'node:test';
+
+import {
+  classifyReplayError,
+  DEAD_LETTER_CAP,
+  pushDeadLetter,
+  TRANSIENT_RETRY_DELAYS_MS,
+  withRetry,
+  type ReplayFailureRecord,
+} from './replay-retry';
+
+/* ── classifyReplayError ──────────────────────────────────────────── */
+
+test('ChunkLoadError by name is transient', () => {
+  const err = Object.assign(new Error('Loading chunk 7 failed.'), {
+    name: 'ChunkLoadError',
+  });
+  assert.equal(classifyReplayError(err), 'transient');
+});
+
+test('webpack "Loading chunk N failed" message is transient', () => {
+  // Bare Error with no special name — only the message tells us.
+  assert.equal(classifyReplayError(new Error('Loading chunk 42 failed.')), 'transient');
+});
+
+test('vite "failed to fetch dynamically imported module" is transient', () => {
+  assert.equal(
+    classifyReplayError(new Error('Failed to fetch dynamically imported module: /assets/cf.js')),
+    'transient',
+  );
+});
+
+test('NetworkError when attempting to fetch is transient', () => {
+  assert.equal(
+    classifyReplayError(new Error('NetworkError when attempting to fetch resource.')),
+    'transient',
+  );
+});
+
+test('generic "network request failed" is transient', () => {
+  assert.equal(classifyReplayError(new Error('Network request failed')), 'transient');
+});
+
+test('malformed-params TypeError is permanent', () => {
+  // Realistic shape: Univer's set-range-values throws TypeError when
+  // params.value is undefined.
+  assert.equal(
+    classifyReplayError(new TypeError("Cannot read properties of undefined (reading 'v')")),
+    'permanent',
+  );
+});
+
+test('unknown command id Error is permanent', () => {
+  assert.equal(
+    classifyReplayError(new Error('No command handler registered for "made.up.mutation"')),
+    'permanent',
+  );
+});
+
+test('null / undefined / number errors classify permanent (defensive)', () => {
+  assert.equal(classifyReplayError(null), 'permanent');
+  assert.equal(classifyReplayError(undefined), 'permanent');
+  assert.equal(classifyReplayError(42), 'permanent');
+});
+
+test('case-insensitive: "LOADING CHUNK 1 FAILED" is transient', () => {
+  // The classifier lowercases before matching so we don't miss a
+  // bundler that screams its errors. Realistic case for some
+  // production-mode bundle wrappers.
+  assert.equal(classifyReplayError(new Error('LOADING CHUNK 1 FAILED.')), 'transient');
+});
+
+/* ── withRetry ──────────────────────────────────────────────────── */
+
+test('withRetry resolves on first try when task succeeds', async () => {
+  let calls = 0;
+  const value = await withRetry(
+    () => {
+      calls += 1;
+      return Promise.resolve('ok');
+    },
+    [10, 20],
+    () => true,
+    () => Promise.resolve(),
+  );
+  assert.equal(value, 'ok');
+  assert.equal(calls, 1);
+});
+
+test('withRetry retries until a later attempt succeeds', async () => {
+  let calls = 0;
+  const value = await withRetry(
+    () => {
+      calls += 1;
+      if (calls < 3) return Promise.reject(new Error('chunk load failed'));
+      return Promise.resolve('eventually');
+    },
+    [10, 20, 30],
+    () => true,
+    () => Promise.resolve(),
+  );
+  assert.equal(value, 'eventually');
+  assert.equal(calls, 3);
+});
+
+test('withRetry exhausts all attempts then rejects with last error', async () => {
+  let calls = 0;
+  await assert.rejects(
+    withRetry(
+      () => {
+        calls += 1;
+        return Promise.reject(new Error(`attempt ${calls}`));
+      },
+      [10, 20, 30],
+      () => true,
+      () => Promise.resolve(),
+    ),
+    { message: 'attempt 4' }, // 1 initial + 3 retries = 4 calls
+  );
+  assert.equal(calls, 4);
+});
+
+test('withRetry bails early when shouldRetry returns false', async () => {
+  let calls = 0;
+  await assert.rejects(
+    withRetry(
+      () => {
+        calls += 1;
+        return Promise.reject(new Error('permanent'));
+      },
+      [10, 20, 30],
+      () => false, // never retry
+      () => Promise.resolve(),
+    ),
+    { message: 'permanent' },
+  );
+  assert.equal(calls, 1);
+});
+
+test('withRetry actually awaits the sleep delays (in order)', async () => {
+  const slept: number[] = [];
+  let calls = 0;
+  await assert.rejects(
+    withRetry(
+      () => {
+        calls += 1;
+        return Promise.reject(new Error('fail'));
+      },
+      [50, 150, 450],
+      () => true,
+      (ms) => {
+        slept.push(ms);
+        return Promise.resolve();
+      },
+    ),
+  );
+  assert.deepEqual(slept, [50, 150, 450]);
+  assert.equal(calls, 4);
+});
+
+/* ── pushDeadLetter ─────────────────────────────────────────────── */
+
+function makeRec(id: string): ReplayFailureRecord {
+  return {
+    id,
+    params: { foo: 1 },
+    lastError: 'boom',
+    attempts: 1,
+    firstFailedAt: 0,
+    lastFailedAt: 0,
+    classification: 'permanent',
+  };
+}
+
+test('pushDeadLetter appends below cap', () => {
+  const buf = pushDeadLetter([], makeRec('a'));
+  assert.equal(buf.length, 1);
+  assert.equal(buf[0].id, 'a');
+});
+
+test('pushDeadLetter evicts oldest when at cap', () => {
+  const small = 3;
+  let buf: readonly ReplayFailureRecord[] = [];
+  for (const id of ['a', 'b', 'c', 'd', 'e']) {
+    buf = pushDeadLetter(buf, makeRec(id), small);
+  }
+  assert.equal(buf.length, 3);
+  assert.deepEqual(
+    buf.map((r) => r.id),
+    ['c', 'd', 'e'],
+  );
+});
+
+test('pushDeadLetter returns a new array (reference change)', () => {
+  // The CollabIndicator subscribes by reference — we MUST return a
+  // fresh array, not mutate in place.
+  const original: readonly ReplayFailureRecord[] = [makeRec('a')];
+  const next = pushDeadLetter(original, makeRec('b'));
+  assert.notEqual(next, original);
+  assert.equal(original.length, 1);
+  assert.equal(next.length, 2);
+});
+
+test('TRANSIENT_RETRY_DELAYS_MS is the documented schedule', () => {
+  // Pin the schedule. If this changes, audit the indicator copy +
+  // CO-EDITING.md so the user-visible "should recover within ~4 s"
+  // claim stays accurate.
+  assert.deepEqual([...TRANSIENT_RETRY_DELAYS_MS], [300, 900, 2700]);
+});
+
+test('DEAD_LETTER_CAP is 20', () => {
+  assert.equal(DEAD_LETTER_CAP, 20);
+});

package/src/collab/ws-url.ts

@@ -0,0 +1,20 @@
+/**
+ * Pure WS-URL composition for attachCollab. Kept in its own module — free of
+ * any `@univerjs` / `@hocuspocus` imports — so it's unit-testable under
+ * `node:test` without dragging in the Univer ESM graph.
+ */
+
+/** Build the room WS URL: `<server>?room=<id>[&p=<pw>]&role=<role>`. */
+export function buildWsUrl(
+  server: string,
+  room: string,
+  role: 'view' | 'write',
+  password?: string,
+): string {
+  const sep = server.includes('?') ? '&' : '?';
+  return (
+    `${server}${sep}room=${encodeURIComponent(room)}` +
+    `${password ? `&p=${encodeURIComponent(password)}` : ''}` +
+    `&role=${encodeURIComponent(role)}`
+  );
+}

package/src/collab/ws-url.unit.test.ts

@@ -0,0 +1,35 @@
+/**
+ * Unit coverage for attachCollab's URL composition — the one bit of our own
+ * logic that doesn't require a live WebSocket. The provider/bridge wiring is
+ * exercised end-to-end by the reference host's `tests/e2e/coedit-*.spec.ts`
+ * (which now drives the moved bridge through `@casualoffice/sheets/collab`).
+ */
+import { strict as assert } from 'node:assert';
+import { test } from 'node:test';
+
+import { buildWsUrl } from './ws-url';
+
+test('buildWsUrl appends room + role with a leading ? on a bare server', () => {
+  assert.equal(buildWsUrl('wss://h/yjs', 'room1', 'write'), 'wss://h/yjs?room=room1&role=write');
+});
+
+test('buildWsUrl uses & when the server URL already has a query', () => {
+  assert.equal(
+    buildWsUrl('wss://h/yjs?token=x', 'room1', 'view'),
+    'wss://h/yjs?token=x&room=room1&role=view',
+  );
+});
+
+test('buildWsUrl includes the password only when provided, before role', () => {
+  assert.equal(
+    buildWsUrl('wss://h/yjs', 'room1', 'write', 'p@ss/word'),
+    'wss://h/yjs?room=room1&p=p%40ss%2Fword&role=write',
+  );
+});
+
+test('buildWsUrl percent-encodes the room id', () => {
+  assert.equal(
+    buildWsUrl('wss://h/yjs', 'a b/c', 'write'),
+    'wss://h/yjs?room=a%20b%2Fc&role=write',
+  );
+});

package/src/embed/EmbedHostTransport.ts

@@ -26,6 +26,8 @@ import {
   type LoadResponseData,
   type SaveRequestData,
   type SaveResponseData,
+  type SaveNotifyData,
+  type ExitData,
   type SelectionChangedData,
   type SignatureCancelData,
   type SignatureCompleteData,
@@ -49,8 +51,15 @@ export interface EmbedHostHandlers {
   onEditorReady?: (data: EditorHelloData) => void;
   /** Editor requests bytes for `docId`. */
   onLoadRequest?: (data: LoadRequestData) => Promise<LoadResponseData> | LoadResponseData;
-  /** Editor requests a save. */
+  /** Editor requests a save (WOPI-style, carries xlsx bytes). */
   onSaveRequest?: (data: SaveRequestData) => Promise<SaveResponseData> | SaveResponseData;
+  /** Editor fired its lightweight save notification (Ctrl/Cmd+S or a
+   *  host save command). Carries the full snapshot JSON; fire-and-forget.
+   *  Mirror of the React `onSave` hook. */
+  onSaveNotify?: (data: SaveNotifyData) => void;
+  /** Editor is unmounting; carries the final snapshot. Mirror of the
+   *  React `onExit` hook. */
+  onExit?: (data: ExitData) => void;
   onSelectionChanged?: (data: SelectionChangedData) => void;
   onSelectionFormatState?: (data: SelectionFormatStateData) => void;
   onTelemetry?: (data: TelemetryEventData) => void;
@@ -182,6 +191,12 @@ export class EmbedHostTransport {
         }
         return;
       }
+      case 'casual.save.notify':
+        this.handlers.onSaveNotify?.(env.data as SaveNotifyData);
+        return;
+      case 'casual.exit':
+        this.handlers.onExit?.(env.data as ExitData);
+        return;
       case 'casual.selection.changed':
         this.handlers.onSelectionChanged?.(env.data as SelectionChangedData);
         return;

package/src/embed/EmbedTransport.ts

@@ -22,6 +22,8 @@ import {
   type LoadRequestData,
   type SaveRequestData,
   type SaveResponseData,
+  type SaveNotifyData,
+  type ExitData,
   type SelectionChangedData,
   type TelemetryEventData,
   type CommandSetReadOnlyData,
@@ -145,6 +147,20 @@ export class EmbedTransport {
     return this.request<SaveResponseData>('casual.save.request', req, timeoutMs, [req.bytes]);
   }
 
+  /** Editor → Host: the user asked to save (Ctrl/Cmd+S or a host save
+   *  command). Fire-and-forget snapshot notification — the lightweight
+   *  mirror of the React `onSave` hook. The host persists however it
+   *  likes; no response is awaited. */
+  sendSaveNotify(data: SaveNotifyData): void {
+    this.post('casual.save.notify', data);
+  }
+
+  /** Editor → Host: the editor is unmounting. Carries the final snapshot
+   *  so the host can persist on exit. Mirror of the React `onExit` hook. */
+  sendExit(data: ExitData): void {
+    this.post('casual.exit', data);
+  }
+
   /** Editor → Host: selection moved. Fire-and-forget. */
   sendSelectionChanged(data: SelectionChangedData): void {
     this.post('casual.selection.changed', data);