@casualoffice/sheets 0.11.0 → 0.12.0

package/src/collab/attachCollab.ts

@@ -25,7 +25,7 @@ import type { IWorkbookData } from '@univerjs/core';
 import type { FUniver } from '@univerjs/core/facade';
 import type { CasualSheetsAPI } from '../sheets/api';
 import { startBridge, type BridgeHandle } from './bridge';
-import { buildWsUrl } from './ws-url';
+import { buildWsUrl, type WsUrlShare } from './ws-url';
 
 /** 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
@@ -64,8 +64,14 @@ export interface AttachCollabOptions {
    *  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'`. */
+  /** `view` joins read-only. Defaults to `'write'`. Ignored by the server
+   *  when a `share` token is supplied — the token is authoritative. */
   role?: CollabRole;
+  /** Secure share-link capability (sharing-model §6.1). When `share.share`
+   *  is set, the role is omitted from the WS URL and the server resolves it
+   *  from the token (bound to this room at mint time). `share.sp` carries
+   *  the optional join password for a password-protected token. */
+  share?: WsUrlShare;
   /**
    * Called when a peer's compaction snapshot arrives — the host swaps the
    * workbook (typically `api.loadSnapshot(wb)`). MAY return a promise; the
@@ -103,7 +109,7 @@ export function attachCollab(api: CollabAttachable, opts: AttachCollabOptions):
   // Match the reference host: drop the reconnect timeout to 10 s so a dropped
   // socket surfaces as `offline` quickly rather than after the 30 s default.
   const ws = new HocuspocusProviderWebsocket({
-    url: buildWsUrl(opts.server, opts.room, role, opts.password),
+    url: buildWsUrl(opts.server, opts.room, role, opts.password, opts.share),
     messageReconnectTimeout: 10_000,
   });
   const provider = new HocuspocusProvider({

package/src/collab/index.ts

@@ -18,6 +18,9 @@ export {
   type CollabRole,
   type CollabConnectionStatus,
 } from './attachCollab';
+// Secure share-link capability shape (sharing-model §6.1) — referenced by
+// AttachCollabOptions.share.
+export { type WsUrlShare } from './ws-url';
 
 // The mutation bridge — the framework-agnostic core (subscribes to
 // onMutationExecutedForCollab, replays with fromCollab, guards __splitChunk__).

package/src/collab/ws-url.ts

@@ -4,17 +4,47 @@
  * `node:test` without dragging in the Univer ESM graph.
  */
 
-/** Build the room WS URL: `<server>?room=<id>[&p=<pw>]&role=<role>`. */
+/** Extra capability params carried on the WS upgrade for secure share
+ *  links (sharing-model §6.1). */
+export type WsUrlShare = {
+  /** Secure share-link token. When present the server is authoritative
+   *  for the role — it resolves the token to a role + a bound room, so
+   *  the client must NOT also assert `role=` (the server ignores a
+   *  client `?role=` when a token is present; sending one is just
+   *  spoofable noise). */
+  share?: string;
+  /** Optional join password paired with a password-protected share
+   *  token (`?sp=`). Distinct from the anonymous-room `?p=` password. */
+  sp?: string;
+};
+
+/**
+ * Build the room WS URL.
+ *
+ *   - No share token: `<server>?room=<id>[&p=<pw>]&role=<role>` — the
+ *     anonymous-room path; byte-identical to before.
+ *   - With a `share` token: `<server>?room=<id>[&p=<pw>]&share=<token>[&sp=<pw>]`.
+ *     `role=` is deliberately omitted — the server resolves the role
+ *     from the token, so shipping a spoofable client role is pointless.
+ */
 export function buildWsUrl(
   server: string,
   room: string,
   role: 'view' | 'write',
   password?: string,
+  share?: WsUrlShare,
 ): string {
   const sep = server.includes('?') ? '&' : '?';
-  return (
+  const base =
     `${server}${sep}room=${encodeURIComponent(room)}` +
-    `${password ? `&p=${encodeURIComponent(password)}` : ''}` +
-    `&role=${encodeURIComponent(role)}`
-  );
+    `${password ? `&p=${encodeURIComponent(password)}` : ''}`;
+  const token = share?.share;
+  if (token) {
+    return (
+      base +
+      `&share=${encodeURIComponent(token)}` +
+      `${share?.sp ? `&sp=${encodeURIComponent(share.sp)}` : ''}`
+    );
+  }
+  return base + `&role=${encodeURIComponent(role)}`;
 }

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

@@ -33,3 +33,58 @@ test('buildWsUrl percent-encodes the room id', () => {
     'wss://h/yjs?room=a%20b%2Fc&role=write',
   );
 });
+
+// ── Secure share-link tokens (sharing-model §6.1) ──────────────────────────
+
+test('buildWsUrl with a share token forwards share= and OMITS role=', () => {
+  // The server is authoritative for the role when a token is present, so the
+  // spoofable client role must not be on the URL — even though `role` is
+  // still passed positionally. A `write` here must NOT leak through.
+  assert.equal(
+    buildWsUrl('wss://h/yjs', 'room1', 'write', undefined, { share: 'tok123' }),
+    'wss://h/yjs?room=room1&share=tok123',
+  );
+});
+
+test('buildWsUrl with a share token forwards sp= (join password) when set', () => {
+  assert.equal(
+    buildWsUrl('wss://h/yjs', 'room1', 'view', undefined, { share: 'tok123', sp: 'p@ss/word' }),
+    'wss://h/yjs?room=room1&share=tok123&sp=p%40ss%2Fword',
+  );
+});
+
+test('buildWsUrl percent-encodes the share token', () => {
+  assert.equal(
+    buildWsUrl('wss://h/yjs', 'room1', 'view', undefined, { share: 'a b/c' }),
+    'wss://h/yjs?room=room1&share=a%20b%2Fc',
+  );
+});
+
+test('buildWsUrl keeps a room password alongside a share token', () => {
+  assert.equal(
+    buildWsUrl('wss://h/yjs', 'room1', 'write', 'roompw', { share: 'tok' }),
+    'wss://h/yjs?room=room1&p=roompw&share=tok',
+  );
+});
+
+test('buildWsUrl is byte-identical to the no-token form when share is undefined', () => {
+  // The explicit-undefined call site (e.g. attachCollab forwarding an absent
+  // opts.share) must produce exactly what the old 4-arg call produced.
+  assert.equal(
+    buildWsUrl('wss://h/yjs', 'room1', 'write', undefined, undefined),
+    buildWsUrl('wss://h/yjs', 'room1', 'write'),
+  );
+  assert.equal(
+    buildWsUrl('wss://h/yjs', 'room1', 'view', 'pw', undefined),
+    buildWsUrl('wss://h/yjs', 'room1', 'view', 'pw'),
+  );
+});
+
+test('buildWsUrl ignores an empty share token (falls back to role=)', () => {
+  // A defensive case: `{ share: '' }` is not a real token, so we must not
+  // emit `share=` with an empty value and drop the role.
+  assert.equal(
+    buildWsUrl('wss://h/yjs', 'room1', 'write', undefined, { share: '' }),
+    'wss://h/yjs?room=room1&role=write',
+  );
+});

package/src/embed-runtime/embed.html

@@ -5,16 +5,30 @@
     <meta name="viewport" content="width=device-width, initial-scale=1" />
     <title>Casual Sheets (embed)</title>
     <style>
-      html, body { margin: 0; padding: 0; height: 100%; background: #fff; overflow: hidden; }
-      #casual-embed-root { width: 100%; height: 100%; }
+      html,
+      body {
+        margin: 0;
+        padding: 0;
+        height: 100%;
+        background: #fff;
+        overflow: hidden;
+      }
+      #casual-embed-root {
+        width: 100%;
+        height: 100%;
+      }
       /* Preview-mode chrome hiding — v0.5.x ties these to component
          props; v0.5.0 lands the wire end-to-end and uses CSS gates. */
-      [data-view-mode="preview"] [data-toolbar],
-      [data-view-mode="preview"] [data-formula-bar],
-      [data-view-mode="preview"] [data-status-bar],
-      [data-view-mode="preview"] [data-sheet-tabs] { display: none !important; }
+      [data-view-mode='preview'] [data-toolbar],
+      [data-view-mode='preview'] [data-formula-bar],
+      [data-view-mode='preview'] [data-status-bar],
+      [data-view-mode='preview'] [data-sheet-tabs] {
+        display: none !important;
+      }
     </style>
-    <link rel="stylesheet" href="./embed-runtime.css" />
+    <!-- No external stylesheet: tsup's `injectStyle` inlines Univer's CSS
+         into embed-runtime.js, which appends it as a <style> tag at runtime.
+         A <link> here would just 404 (no .css is emitted). -->
   </head>
   <body>
     <div id="casual-embed-root"></div>

package/src/embed-runtime/index.tsx

@@ -23,7 +23,9 @@ import { createRoot } from 'react-dom/client';
 import { EmbedTransport } from '../embed/EmbedTransport';
 import type { CasualApp } from '../embed/protocol';
 import { CasualSheets } from '../sheets/CasualSheets';
+import { applyReadOnly, getEditable } from '../sheets/read-only';
 import { xlsxToWorkbookData } from '../xlsx';
+import { EMBED_LOCALES } from './locale';
 import type { IWorkbookData } from '@univerjs/core';
 
 interface EmbedUrlConfig {
@@ -224,6 +226,13 @@ function EmbeddedSheets({
       key={viewMode}
       initialData={data}
       ui={ui}
+      // Seed the en-US string bundle. Without `locales`, Univer's
+      // LocaleService throws "Locale not initialized" and the workbench
+      // canvas never paints (data still loads, so a snapshot round-trips,
+      // but the grid is blank). The React `<CasualSheets>` host path gets
+      // this from the host's `locales` prop; the iframe has no host to
+      // pass one, so the self-contained runtime bundles a minimal set.
+      locales={EMBED_LOCALES}
       // The embed runtime is bundled as ONE self-contained file (tsup
       // `noExternal: /.*/`). Lazy plugins would emit per-feature dynamic
       // chunks into dist/embed/, breaking that single-file deployment, so the
@@ -239,6 +248,41 @@ function EmbeddedSheets({
       onSave={(snapshot) => transport.sendSaveNotify({ snapshot, reason: 'shortcut' })}
       onExit={(snapshot) => transport.sendExit({ snapshot })}
       onReady={(api) => {
+        // Expose the imperative API on the iframe window so hosts can
+        // introspect/debug the embedded editor (and e2e can drive it). Mirrors
+        // the React component's `window.__univerAPI` seam.
+        (globalThis as unknown as { __casualEmbedApi?: unknown }).__casualEmbedApi = api;
+        // Debug seam: report the live workbook-editable permission so hosts/e2e
+        // can confirm preview is genuinely read-only (not just chromeless).
+        (
+          globalThis as unknown as { __casualEmbedEditable?: () => boolean | undefined }
+        ).__casualEmbedEditable = () => {
+          const uid = api.getSnapshot()?.id;
+          return uid ? getEditable(api.univer, uid) : undefined;
+        };
+        // Preview = genuinely READ-ONLY. Hiding the chrome (above) isn't
+        // enough — Univer's cell editor still opens on dbl-click / F2. Flip the
+        // workbook's edit permission off so preview can't be typed into. The
+        // mount remounts on viewMode change (key={viewMode}), so editor mode
+        // simply never applies this.
+        //
+        // Defer to a rAF: applied synchronously in onReady the flag loses a
+        // race — sheets-ui initialises WorkbookEditablePermission to `true`
+        // during unit setup AFTER onReady fires, clobbering our `false` (a
+        // behavioural embed test caught preview still accepting keystrokes).
+        // The app's collab view-only path waits a rAF for the same reason
+        // (CollabDriver.tsx), so the permission point exists and we
+        // updatePermissionPoint(false) over the settled default.
+        if (viewMode === 'preview') {
+          requestAnimationFrame(() => {
+            const unitId = api.getSnapshot()?.id;
+            if (unitId)
+              applyReadOnly(api.univer, unitId, () => {
+                const g = globalThis as unknown as { __casualEmbedBlocked?: number };
+                g.__casualEmbedBlocked = (g.__casualEmbedBlocked ?? 0) + 1;
+              });
+          });
+        }
         // Wire host → editor command.execute (Drive's custom toolbar
         // calls this for bold / italic / undo / …). Maps the small
         // protocol union to the Univer command id the FUniver facade

package/src/embed-runtime/locale.ts

@@ -0,0 +1,38 @@
+/**
+ * Minimal en-US locale bundle for the in-iframe runtime.
+ *
+ * The embed runtime mounts the MINIMAL editor (`lazyPlugins={false}`):
+ * render + formula engines, UI, docs/docs-ui, sheets, sheets-ui,
+ * sheets-formula-ui, numfmt (+ ui). Univer's `LocaleService` throws
+ * `Locale not initialized` and the workbench canvas never paints if the
+ * `locales` map is empty — so we MUST seed the string bundle for exactly
+ * those plugins. (The React `<CasualSheets>` host path supplies its own
+ * `locales` prop; the iframe has no host to pass one, so it bundles this.)
+ *
+ * Kept narrow on purpose: only the plugins the minimal runtime registers.
+ * Adding strings for plugins it never loads is dead weight in the
+ * self-contained iframe bundle.
+ */
+
+import { LocaleType, Tools } from '@univerjs/core';
+
+import UniverSheetsEnUS from '@univerjs/sheets/locale/en-US';
+import UniverSheetsUIEnUS from '@univerjs/sheets-ui/locale/en-US';
+import UniverSheetsFormulaUIEnUS from '@univerjs/sheets-formula-ui/locale/en-US';
+import UniverSheetsNumfmtUIEnUS from '@univerjs/sheets-numfmt-ui/locale/en-US';
+import UniverDocsUIEnUS from '@univerjs/docs-ui/locale/en-US';
+import UniverUIEnUS from '@univerjs/ui/locale/en-US';
+
+const enUS = Tools.deepMerge(
+  {},
+  UniverUIEnUS,
+  UniverDocsUIEnUS,
+  UniverSheetsEnUS,
+  UniverSheetsUIEnUS,
+  UniverSheetsFormulaUIEnUS,
+  UniverSheetsNumfmtUIEnUS,
+);
+
+export const EMBED_LOCALES = {
+  [LocaleType.EN_US]: enUS,
+};

package/src/sheets/CasualSheetsIframe.tsx

@@ -44,8 +44,9 @@ export interface CasualSheetsIframeRef {
   setViewMode(mode: 'preview' | 'editor'): void;
   iframe(): HTMLIFrameElement | null;
   /** Dispatch a formatting / navigation command (bold, italic, undo, …)
-   *  against the iframe's active selection. v0.6+. */
-  executeCommand(command: CommandExecuteData['command']): void;
+   *  against the iframe's active selection. `args` carries command payloads
+   *  (e.g. font family/size, colour) — forwarded over the protocol. v0.6+. */
+  executeCommand(command: CommandExecuteData['command'], args?: CommandExecuteData['args']): void;
 }
 
 export interface CasualSheetsIframeProps {
@@ -194,7 +195,8 @@ export const CasualSheetsIframe = forwardRef<CasualSheetsIframeRef, CasualSheets
       apiRef.current = {
         setViewMode: (mode) => transportRef.current?.sendSetViewMode({ viewMode: mode }),
         iframe: () => iframeRef.current,
-        executeCommand: (command) => transportRef.current?.sendCommandExecute({ command }),
+        executeCommand: (command, args) =>
+          transportRef.current?.sendCommandExecute({ command, args }),
       };
     }
 

package/src/sheets/index.ts

@@ -3,6 +3,7 @@
  */
 export { CasualSheets, type CasualSheetsProps } from './CasualSheets';
 export { createCasualSheetsAPI, type CasualSheetsAPI, type RangeRef } from './api';
+export { applyReadOnly, getEditable } from './read-only';
 export {
   CasualSheetsIframe,
   type CasualSheetsIframeProps,

package/src/sheets/read-only.ts

@@ -0,0 +1,106 @@
+import { CustomCommandExecutionError, ICommandService, IPermissionService } from '@univerjs/core';
+import type { FUniver } from '@univerjs/core/facade';
+import { WorkbookEditablePermission } from '@univerjs/sheets';
+
+/**
+ * Command ids that MUTATE a sheet — opening the cell editor, writing values,
+ * styling, structural edits, clipboard paste. The read-only veto cancels any
+ * command whose id matches. Navigation (selection, scroll, zoom, sheet switch),
+ * copy, and undo/redo deliberately fall through so preview stays usable.
+ *
+ * `set-cell-edit-visible` / `set-activate-cell-edit` are the editor-open
+ * operations — blocking them is what actually stops keyboard typing, since the
+ * cell editor never opens. The rest stop programmatic / paste / menu mutations.
+ */
+const READONLY_BLOCK =
+  /(set-cell-edit-visible|set-activate-cell-edit|set-range-values|set-style|set-bold|set-italic|set-underline|set-strike|set-font|set-background|set-text|set-horizontal|set-vertical|set-wrap|set-rotation|set-border|set-number-format|insert-|delete-|remove-|clear-selection|cut-content|paste|move-range|move-rows|move-cols|merge|split|add-worksheet|set-worksheet-name|set-worksheet-row|set-worksheet-col|auto-fill|reorder|set-defined-name|set-tab-color|set-frozen-cancel)/;
+
+/**
+ * Make a workbook genuinely READ-ONLY.
+ *
+ * Two layers, because they cover different host setups:
+ *
+ *  1. **Command veto** (`beforeCommandExecuted` → throw
+ *     `CustomCommandExecutionError`) — cancels every mutating command. This is
+ *     the load-bearing layer for the iframe embed, whose minimal plugin set does
+ *     NOT enforce `WorkbookEditablePermission` (verified: the editor still
+ *     accepts edits with the permission flipped off).
+ *  2. **Permission flip** (`WorkbookEditablePermission` → false) — on the full
+ *     `<CasualSheets>` host path this also greys out mutating menu items and
+ *     stops the editor opening; harmless where unenforced.
+ *
+ * Returns a disposer that removes the veto and restores the prior editable
+ * state (for callers that toggle a live unit between preview/editor).
+ */
+export function applyReadOnly(
+  univerApi: FUniver,
+  unitId: string,
+  onBlock?: (commandId: string) => void,
+): () => void {
+  const injector = (univerApi as unknown as { _injector?: { get(t: unknown): unknown } })._injector;
+
+  // Layer 1: veto mutating commands — the only layer the minimal embed enforces.
+  const cmd = injector?.get(ICommandService) as
+    | { beforeCommandExecuted(l: (info: { id: string }) => void): { dispose(): void } }
+    | undefined;
+  const vetoDisposable = cmd?.beforeCommandExecuted((info) => {
+    if (READONLY_BLOCK.test(info.id)) {
+      onBlock?.(info.id);
+      throw new CustomCommandExecutionError(`read-only: blocked ${info.id}`);
+    }
+  });
+
+  // Layer 2: permission flip (best-effort; load-bearing only on full hosts).
+  const svc = injector?.get(IPermissionService) as
+    | {
+        addPermissionPoint(p: unknown): boolean;
+        updatePermissionPoint(id: string, value: unknown): void;
+        getPermissionPoint(id: string): { value: unknown } | undefined;
+      }
+    | undefined;
+
+  // Constructing the point yields the deterministic id Univer derives for the
+  // workbook-edit permission; we don't keep the instance otherwise.
+  const id = new WorkbookEditablePermission(unitId).id;
+  let prev: unknown;
+  if (svc) {
+    try {
+      const existing = svc.getPermissionPoint(id);
+      if (existing) {
+        prev = existing.value;
+        svc.updatePermissionPoint(id, false);
+      } else {
+        const point = new WorkbookEditablePermission(unitId);
+        point.value = false;
+        svc.addPermissionPoint(point);
+      }
+    } catch {
+      /* best-effort — the veto above is the load-bearing layer */
+    }
+  }
+
+  return () => {
+    vetoDisposable?.dispose();
+    try {
+      svc?.updatePermissionPoint(id, prev === undefined ? true : prev);
+    } catch {
+      /* swallow */
+    }
+  };
+}
+
+/**
+ * Read the current `WorkbookEditablePermission` value for a unit — `true`
+ * (editable), `false` (read-only), or `undefined` if the point isn't
+ * registered yet. Lets hosts/tests confirm {@link applyReadOnly} took.
+ */
+export function getEditable(univerApi: FUniver, unitId: string): boolean | undefined {
+  const injector = (univerApi as unknown as { _injector?: { get(t: unknown): unknown } })._injector;
+  const svc = injector?.get(IPermissionService) as
+    | { getPermissionPoint(id: string): { value: unknown } | undefined }
+    | undefined;
+  if (!svc) return undefined;
+  const id = new WorkbookEditablePermission(unitId).id;
+  const point = svc.getPermissionPoint(id);
+  return point ? (point.value as boolean) : undefined;
+}