@casualoffice/sheets 0.9.0 → 0.10.0

package/dist/collab.d.ts

@@ -0,0 +1,248 @@
+import * as Y from 'yjs';
+import { HocuspocusProvider } from '@hocuspocus/provider';
+import { IWorkbookData } from '@univerjs/core';
+import { FUniver } from '@univerjs/core/facade';
+import { C as CasualSheetsAPI } from './api-BI2VLYQ6.js';
+
+type ReplayClassification = 'transient' | 'permanent';
+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.
+ */
+declare function classifyReplayError(err: unknown): ReplayClassification;
+
+type Awareness = {
+    getStates(): Map<number, any>;
+};
+/**
+ * Allowlist of mutation ids we sync. Listed explicitly to keep
+ * undocumented / version-volatile mutations out of the log — anything
+ * not here just stays local. Easier to add new ids than to debug a
+ * silent corruption from a mutation that secretly references local
+ * state (selections, render skeletons, etc.).
+ */
+declare const SYNCED_MUTATIONS: ReadonlySet<string>;
+/** Mutation ids for which the bridge captures undo params before the
+ *  redo runs. Used by the HistoryPanel's revert action. Restricted to
+ *  cell-level mutations because the existing Univer factories cover
+ *  them and they're the dominant case for "undo my edit"; structural
+ *  ops (insert-row / move-range / sort) need their own factories and
+ *  are out of scope for v1 revert.
+ */
+declare const REVERTABLE_MUTATIONS: ReadonlySet<string>;
+type BridgeHandle = {
+    /** Underlying Yjs document — exposed so tests / devtools can introspect. */
+    doc: Y.Doc;
+    /** Stop listening and detach. */
+    dispose: () => void;
+    /**
+     * How many remote mutations have thrown during replay since the
+     * bridge started. Each one is a candidate divergence — the local
+     * state didn't accept the peer's change, so the two state vectors
+     * are now off by at least that mutation. The CollabDriver
+     * subscribes (see `subscribeReplayFailures`) so the indicator can
+     * warn the user before they discover it the hard way.
+     */
+    getReplayFailures: () => number;
+    /**
+     * Subscribe to replay-failure count changes. Fires after every
+     * increment with the new total. Returns a teardown that unhooks
+     * the subscriber. No initial-value fire — caller can read
+     * `getReplayFailures()` once at subscribe time if they need it.
+     */
+    subscribeReplayFailures: (cb: (count: number) => void) => () => void;
+    /**
+     * Snapshot of the dead-letter ring buffer — mutations that
+     * exhausted retries (transient class) or failed immediately
+     * (permanent class). Capped at DEAD_LETTER_CAP entries; oldest
+     * evicts on overflow. UI consumes this to render the per-failure
+     * detail panel.
+     */
+    getReplayDeadLetter: () => readonly ReplayFailureRecord[];
+    /**
+     * Subscribe to dead-letter changes. Fires after every push with a
+     * fresh array (reference change — React state updates see it).
+     * Returns a teardown.
+     */
+    subscribeReplayDeadLetter: (cb: (entries: readonly ReplayFailureRecord[]) => void) => () => void;
+};
+type BridgeOptions = {
+    /**
+     * `view` clients only RECEIVE remote updates — local mutations don't
+     * append to the log, so peers never see them. Client-side gate only;
+     * a determined user can run the bridge in write mode by editing the
+     * URL. Server-side enforcement is a follow-up hardening pass.
+     */
+    role?: 'view' | 'write';
+    /**
+     * Provider's Yjs awareness. Used (a) to determine which peer is the
+     * designated compactor (lowest known clientId — deterministic and
+     * race-free) and (b) so view-only clients don't try to compact. If
+     * omitted, compaction is disabled.
+     */
+    awareness?: Awareness;
+    /**
+     * Hand a fresh workbook snapshot to the host when a compaction
+     * record arrives from a peer. The bridge can't call
+     * `replaceWorkbook` directly (it lives in React state); the host
+     * (`CollabDriver`) wires this through.
+     *
+     * MAY return a promise. Replay of subsequent op-log entries is
+     * paused until the promise resolves — without that, mutations
+     * land on the OLD unit before Univer's async unit-swap completes,
+     * which silently forks state on late joiners.
+     */
+    onSnapshotReceived?: (wb: IWorkbookData) => void | Promise<void>;
+};
+declare function startBridge(api: FUniver, doc: Y.Doc, opts?: BridgeOptions): BridgeHandle;
+
+/**
+ * attachCollab — opt-in real-time co-editing for `<CasualSheets>`.
+ *
+ * The editor ships **collab-unaware**: it boots, edits, and persists with no
+ * knowledge of rooms or peers. A host that wants co-editing calls
+ * `attachCollab(api, { room, server })` once after `onReady` and gets back a
+ * detach handle. That's the entire public surface — everything else (presence
+ * UI, password prompts, room preflight, reconnect banners) is the host's to
+ * build on top of the returned `provider` / `doc`.
+ *
+ * Transport: Yjs + Hocuspocus, exactly as the reference host (`apps/web`) uses
+ * it. The non-negotiable Univer hooks live in `./bridge` — it subscribes to
+ * `ICommandService.onMutationExecutedForCollab`, applies remote mutations with
+ * `IExecutionOptions.fromCollab` (echo-loop prevention), and guards
+ * `params.__splitChunk__`.
+ *
+ * Persistence note: Yjs/Hocuspocus is the **realtime transport only**. The
+ * authoritative document is still saved by the host via WOPI / its own backend
+ * (the save/exit event contract) — collab does not turn the SDK into a store.
+ */
+
+/** Either the SDK's imperative API (`onReady`) or the bare FUniver facade.
+ *  Collab only needs the facade, so a host that holds the raw FUniver (the
+ *  reference app does) can attach without constructing a CasualSheetsAPI. */
+type CollabAttachable = CasualSheetsAPI | FUniver;
+/** `write` peers broadcast their edits; `view` peers only receive. The
+ *  client-side gate is belt-and-braces — real enforcement is the server's
+ *  `role` check on the WS upgrade. */
+type CollabRole = 'view' | 'write';
+/** Coarse connection state mapped from Hocuspocus's provider status. */
+type CollabConnectionStatus = 'connecting' | 'live' | 'offline';
+interface AttachCollabOptions {
+    /** Room / document id. Becomes the Hocuspocus document name. */
+    room: string;
+    /** Base WebSocket URL of the collab server, e.g. `wss://host/yjs`. */
+    server: string;
+    /** Room password, if the server gates the room. Sent on the WS URL as
+     *  `p=…` so the upgrade handler can validate before the protocol handshake. */
+    password?: string;
+    /** Auth token for the Hocuspocus handshake. The provider only sends its
+     *  auth submessage when this is truthy; servers with an `onAuthenticate`
+     *  hook keep the connection queued without it. Defaults to `'anon'` (the
+     *  reference server's hook only reads the `role` query param). */
+    token?: string;
+    /** `view` joins read-only. Defaults to `'write'`. */
+    role?: CollabRole;
+    /**
+     * Called when a peer's compaction snapshot arrives — the host swaps the
+     * workbook (typically `api.loadSnapshot(wb)`). MAY return a promise; the
+     * bridge pauses op-log replay until it resolves so later mutations don't
+     * land on the pre-swap unit.
+     */
+    onSnapshot?: (wb: IWorkbookData) => void | Promise<void>;
+    /** Connection-status transitions — drive a status pill / offline banner. */
+    onStatus?: (status: CollabConnectionStatus) => void;
+}
+interface CollabHandle {
+    /** The underlying Yjs document — introspection / devtools / extra maps. */
+    readonly doc: Y.Doc;
+    /** The Hocuspocus provider — `awareness` for presence, `on('status')`, etc. */
+    readonly provider: HocuspocusProvider;
+    /** The mutation bridge — replay-failure diagnostics live here. */
+    readonly bridge: BridgeHandle;
+    /** Last known connection status. */
+    status(): CollabConnectionStatus;
+    /** Detach: tear down bridge + provider + doc. Idempotent. */
+    detach(): void;
+}
+/**
+ * Attach real-time collab to a live editor. Call once after `onReady`.
+ * Returns a {@link CollabHandle}; call `.detach()` to leave the room
+ * (and always before the editor unmounts).
+ */
+declare function attachCollab(api: CollabAttachable, opts: AttachCollabOptions): CollabHandle;
+
+/**
+ * Pure helpers extracted from bridge.ts so they're testable without
+ * pulling Univer / Yjs / Vite-only globals into a Node test runner.
+ *
+ * Anything stateless and Univer-free that bridge.ts needs should live
+ * here. Stateful bridge logic (Yjs observers, command service hooks,
+ * compaction) stays in bridge.ts itself.
+ */
+/**
+ * Substitute `localUnitId` for every `unitId` string property anywhere
+ * in `value` — including nested objects and arrays — and return a
+ * structurally cloned copy. Returns the input by reference when no
+ * change is needed, so callers can identity-compare before re-encoding.
+ *
+ * Walks plain objects and arrays only. Class instances are left alone
+ * because Univer mutation params are required to be JSON-friendly.
+ */
+/**
+ * Drawing mutations (sheets-drawing + drawing plugins) carry an
+ * `op` field that's a json1 patch — a positional array whose first
+ * element is the unitId. `deepRewriteUnitId` only rewrites the
+ * `unitId` KEY in objects; the json1 path is a bare array of strings
+ * so the unitId at position 0 stays as the OWNER's id and the apply
+ * fails on the joiner with no useful message ("Error" at
+ * json1.type.apply).
+ *
+ * This walks the op shape — single JSONOp (array of mixed strings +
+ * numbers + a final mutation component object) OR JSONOpList (array
+ * of JSONOps) — and substitutes the leading unitId where it matches.
+ * Returns a fresh structure on change so peers can identity-compare.
+ *
+ * Scope deliberately narrow: only checks element [0] of each op
+ * (where the unitId always lives in our path schema). A deeper
+ * path-rewrite would invent semantics the Univer source doesn't
+ * document.
+ */
+declare function rewriteJson1OpPathUnitId(op: unknown, oldUnitId: string, newUnitId: string): unknown;
+declare function deepRewriteUnitId(value: unknown, localUnitId: string): unknown;
+
+export { type AttachCollabOptions, type BridgeHandle, type BridgeOptions, type CollabAttachable, type CollabConnectionStatus, type CollabHandle, type CollabRole, REVERTABLE_MUTATIONS, type ReplayClassification, type ReplayFailureRecord, SYNCED_MUTATIONS, attachCollab, classifyReplayError, deepRewriteUnitId, rewriteJson1OpPathUnitId, startBridge };