@casualoffice/sheets 0.9.0

package/src/sheets/CasualSheets.tsx

@@ -0,0 +1,319 @@
+/**
+ * CasualSheets — minimal React wrapper around Univer Sheets.
+ *
+ * Boots Univer with the eager plugin set (render + formula engine +
+ * UI + docs + sheets + sheets-ui + sheets-formula + numfmt), mounts a
+ * single workbook unit from `initialData`, and hands the host the
+ * `CasualSheetsAPI` imperative ref via `onReady` (raw FUniver facade
+ * available at `api.univer`).
+ *
+ * Feature plugins (conditional formatting, data validation, drawings,
+ * sort, filter, hyperlinks, tables, comments, find/replace) load lazily
+ * by default (`lazyPlugins`): eagerly before mount for whatever the
+ * snapshot already uses, idle-loaded otherwise. Pass `lazyPlugins={false}`
+ * for the minimal editor.
+ *
+ * Intentionally NOT included (host can layer on top via FUniver):
+ *   - Formula compute via Web Worker — `notExecuteFormula: false`
+ *     is the default; the formula engine runs on the main thread.
+ *     Host wires `UniverRPCMainThreadPlugin` + a worker URL itself
+ *     if it wants the off-main path.
+ *   - Snapshot swap (this component mounts a snapshot once; change
+ *     the React `key` to remount with a fresh snapshot).
+ *   - Paste-merge hooks, dev helpers, zoom-shortcut overrides,
+ *     facade extensions — all app concerns.
+ *
+ * Styles: host must import `@casualoffice/sheets/styles.css`
+ * (or the per-plugin CSS) once at app boot. Tree-shaking strips the
+ * styles from this entry if the host doesn't reach the styles export.
+ */
+
+import { useEffect, useRef, type CSSProperties } from 'react';
+import {
+  ICommandService,
+  LocaleType,
+  LogLevel,
+  ThemeService,
+  Univer,
+  UniverInstanceType,
+  type ICommandInfo,
+  type IExecutionOptions,
+  type IWorkbookData,
+  type ILocales,
+} from '@univerjs/core';
+import { FUniver } from '@univerjs/core/facade';
+import { defaultTheme } from '@univerjs/themes';
+
+import { UniverRenderEnginePlugin } from '@univerjs/engine-render';
+import { UniverFormulaEnginePlugin } from '@univerjs/engine-formula';
+import { UniverUIPlugin } from '@univerjs/ui';
+import { UniverDocsPlugin } from '@univerjs/docs';
+import { UniverDocsUIPlugin } from '@univerjs/docs-ui';
+import { UniverSheetsPlugin } from '@univerjs/sheets';
+import { UniverSheetsUIPlugin } from '@univerjs/sheets-ui';
+import { UniverSheetsFormulaPlugin } from '@univerjs/sheets-formula';
+import { UniverSheetsFormulaUIPlugin } from '@univerjs/sheets-formula-ui';
+import { UniverSheetsNumfmtPlugin } from '@univerjs/sheets-numfmt';
+import { UniverSheetsNumfmtUIPlugin } from '@univerjs/sheets-numfmt-ui';
+
+import { createCasualSheetsAPI, type CasualSheetsAPI } from './api';
+import { eagerLoadForSnapshot, idleLoadAll, setUniverForLazyLoad } from '../univer/lazy-plugins';
+
+export interface CasualSheetsProps {
+  /** Workbook snapshot to mount. Read once on initial mount; change
+   *  the React `key` on this component to remount with a new
+   *  workbook. */
+  initialData: IWorkbookData;
+  /** Called after the workbook unit is created. Hands back the
+   *  `CasualSheetsAPI` imperative ref — the SDK's stable integration
+   *  surface (snapshot I/O, xlsx import, selection, command dispatch).
+   *  The raw FUniver facade is on `api.univer` as the escape hatch. */
+  onReady?: (api: CasualSheetsAPI) => void;
+  /** Debounced stream of workbook snapshots, emitted after edits
+   *  settle. This is the "host persists it" half of the Excalidraw
+   *  model — the editor stays storage-unaware and the host writes the
+   *  snapshot wherever it likes (localStorage, server, …). Driven by
+   *  Univer's mutation hook (`onMutationExecutedForCollab`), not UI
+   *  events, so it captures every edit including programmatic ones.
+   *  May fire for background/structural mutations too; treat each call
+   *  as "current state, persist if you care". */
+  onChange?: (snapshot: IWorkbookData) => void;
+  /** Debounce window for `onChange`, in ms. Default 400. */
+  onChangeDebounceMs?: number;
+  /** Lazy-load the feature plugins (conditional formatting, data
+   *  validation, hyperlinks, notes, tables, comments, drawings, sort,
+   *  filter, find/replace). Default `true`: plugins whose data is in
+   *  `initialData` load eagerly before mount (so nothing is dropped on
+   *  open), the rest idle-load after first paint. Set `false` for the
+   *  minimal editor (render + formula + numfmt only) — the embed-iframe
+   *  build does this to stay a single self-contained bundle. */
+  lazyPlugins?: boolean;
+  /** Locale identifier. Defaults to `LocaleType.EN_US`. */
+  locale?: LocaleType;
+  /** Locale string bundle. Optional — Univer's default English
+   *  strings load if omitted. */
+  locales?: ILocales;
+  /** Univer log level. Defaults to `LogLevel.WARN`. */
+  logLevel?: LogLevel;
+  /** Univer chrome toggles. Defaults: header / toolbar / footer off,
+   *  context menu on — matches Casual Sheets' embedded shape. */
+  ui?: {
+    header?: boolean;
+    toolbar?: boolean;
+    footer?: boolean;
+    contextMenu?: boolean;
+  };
+  /** Override the Univer theme object (colour palette). Defaults to
+   *  Univer's `defaultTheme`. Distinct from `appearance` (light/dark). */
+  theme?: typeof defaultTheme;
+  /** Light or dark mode. Reactive — flipping it re-themes the live
+   *  editor via `ThemeService.setDarkMode` (canvas colours, notifications,
+   *  and Univer's own `univer-dark` class). Defaults to light.
+   *  Note: Univer's Workbench applies the `univer-dark` class to the
+   *  document root (`<html>`) itself, so dark mode is page-global by
+   *  Univer's design — a host that embeds the editor inside a light page
+   *  should scope the editor or accept the global dark CSS. */
+  appearance?: 'light' | 'dark';
+  /** Container style. Default fills the parent. */
+  style?: CSSProperties;
+  /** Container className for additional styling hooks. */
+  className?: string;
+  /** Optional test id for the host container. */
+  testId?: string;
+}
+
+const DEFAULT_STYLE: CSSProperties = {
+  width: '100%',
+  height: '100%',
+  position: 'relative',
+};
+
+const DEFAULT_UI = {
+  header: false,
+  toolbar: false,
+  footer: false,
+  contextMenu: true,
+};
+
+export function CasualSheets({
+  initialData,
+  onReady,
+  onChange,
+  onChangeDebounceMs = 400,
+  lazyPlugins = true,
+  locale = LocaleType.EN_US,
+  locales,
+  logLevel = LogLevel.WARN,
+  ui,
+  theme = defaultTheme,
+  appearance = 'light',
+  style,
+  className,
+  testId = 'casual-sheets',
+}: CasualSheetsProps) {
+  const hostRef = useRef<HTMLDivElement>(null);
+  // Keep the latest onChange callable without re-subscribing (the effect
+  // mounts once). The subscription itself is only wired when onChange was
+  // present at mount.
+  const onChangeRef = useRef(onChange);
+  onChangeRef.current = onChange;
+  const hasOnChange = useRef(!!onChange).current;
+  // The live FUniver facade, captured at mount so the reactive appearance
+  // effect can reach Univer's ThemeService without re-running boot.
+  const apiRef = useRef<CasualSheetsAPI | null>(null);
+
+  useEffect(() => {
+    const container = hostRef.current;
+    if (!container) return;
+
+    const univer = new Univer({
+      theme,
+      locale,
+      locales,
+      logLevel,
+    });
+
+    const uiOpts = { ...DEFAULT_UI, ...ui, container };
+
+    univer.registerPlugin(UniverRenderEnginePlugin);
+    // Formula compute runs on the MAIN THREAD (no RPC worker). The library build
+    // externalises @univerjs (see tsup.config.ts), so the host provides a single
+    // redi/@univerjs copy — the duplicate-redi that previously made the formula
+    // plugins fail (and which the SDK worked around by dropping them) is gone.
+    // apps/web offloads compute to a worker for perf on huge sheets, but a worker
+    // shipped inside a published package is brittle to bundle in arbitrary hosts;
+    // main-thread keeps the SDK editor self-contained. SDK restructure Batch 2.
+    univer.registerPlugin(UniverFormulaEnginePlugin);
+    univer.registerPlugin(UniverUIPlugin, uiOpts);
+    univer.registerPlugin(UniverDocsPlugin);
+    univer.registerPlugin(UniverDocsUIPlugin);
+    univer.registerPlugin(UniverSheetsPlugin);
+    univer.registerPlugin(UniverSheetsUIPlugin);
+    univer.registerPlugin(UniverSheetsFormulaPlugin);
+    univer.registerPlugin(UniverSheetsFormulaUIPlugin);
+    univer.registerPlugin(UniverSheetsNumfmtPlugin);
+    univer.registerPlugin(UniverSheetsNumfmtUIPlugin);
+
+    // Register the lazy-loader's holder so the eager/idle loaders can reach this
+    // univer. CasualSheets uses its own (bundled) copy of the loader — the
+    // exported `@casualoffice/sheets/univer` is @internal and only the host app's
+    // legacy UniverSheet consumes it, so there's no cross-instance state to share.
+    if (lazyPlugins) setUniverForLazyLoad(univer);
+
+    let cancelled = false;
+    let changeTimer: ReturnType<typeof setTimeout> | null = null;
+    let changeSub: { dispose: () => void } | undefined;
+
+    void (async () => {
+      // Eager-load any feature plugin whose data already lives in initialData
+      // (CF rules, tables, hyperlinks, …) BEFORE createUnit — Univer's resource
+      // manager silently drops keys for plugins that aren't registered when it
+      // reads the snapshot. Skipped entirely when lazyPlugins is false.
+      if (lazyPlugins) {
+        await eagerLoadForSnapshot(univer, initialData);
+        if (cancelled) return;
+      }
+
+      univer.createUnit(UniverInstanceType.UNIVER_SHEET, initialData);
+
+      const api = createCasualSheetsAPI(FUniver.newAPI(univer));
+      apiRef.current = api;
+      // Apply the initial appearance now that the editor exists (the reactive
+      // effect below also runs on mount, but apiRef may not be set yet when it
+      // first fires — this guarantees dark mode from the first paint).
+      applyAppearance(api, container, appearance);
+      onReady?.(api);
+
+      // Debounced snapshot stream → onChange. Subscribed AFTER createUnit so the
+      // initial unit-creation mutations don't fire a spurious first emit. Uses the
+      // mutation hook (CLAUDE.md hard rule), never UI events.
+      if (hasOnChange) {
+        const injector = (api.univer as unknown as { _injector?: { get(t: unknown): unknown } })
+          ._injector;
+        const cmdSvc = injector?.get(ICommandService) as
+          | {
+              onMutationExecutedForCollab: (
+                l: (info: ICommandInfo, options?: IExecutionOptions) => void,
+              ) => { dispose: () => void };
+            }
+          | undefined;
+        changeSub = cmdSvc?.onMutationExecutedForCollab(() => {
+          if (changeTimer) clearTimeout(changeTimer);
+          changeTimer = setTimeout(() => {
+            const snap = api.getSnapshot();
+            if (snap) onChangeRef.current?.(snap);
+          }, onChangeDebounceMs);
+        });
+        // If we unmounted during the eager-load await, cleanup already ran with
+        // changeSub still undefined — dispose this late subscription.
+        if (cancelled) changeSub?.dispose();
+      }
+
+      // Idle-load the remaining feature plugins so Insert / Data / Format actions
+      // are ready when the user reaches them.
+      if (lazyPlugins) idleLoadAll(univer);
+    })();
+
+    return () => {
+      cancelled = true;
+      if (changeTimer) clearTimeout(changeTimer);
+      changeSub?.dispose();
+      apiRef.current = null;
+      if (lazyPlugins) setUniverForLazyLoad(null);
+      // Defer disposal off the React render phase — Univer owns its
+      // own React root, and a synchronous unmount mid-render warns
+      // and leaves the canvas detached.
+      const toDispose = univer;
+      queueMicrotask(() => toDispose.dispose());
+    };
+    // initialData is intentionally NOT in the dep array — the wrapper
+    // mounts the snapshot once. Hosts that need to swap workbooks
+    // change the React `key` to force a remount.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  // Reactive appearance. Runs after the boot effect (apiRef populated on first
+  // mount) and re-runs whenever `appearance` flips, re-theming the live editor.
+  useEffect(() => {
+    const api = apiRef.current;
+    const container = hostRef.current;
+    if (!api || !container) return;
+    applyAppearance(api, container, appearance);
+  }, [appearance]);
+
+  return (
+    <div
+      ref={hostRef}
+      style={{ ...DEFAULT_STYLE, ...style }}
+      className={className}
+      data-testid={testId}
+    />
+  );
+}
+
+/**
+ * Apply light/dark to a live editor. `ThemeService.setDarkMode` is the source of
+ * truth — it flips the canvas colours, the internals that subscribe to
+ * `darkMode$` (notifications, message containers), AND Univer's Workbench toggles
+ * the `univer-dark` class on the document root for its compiled dark CSS. We also
+ * mirror the class onto the editor container as race-insurance (the Workbench
+ * effect can land a frame after ours). Mirrors the app's ThemeBridge.
+ */
+function applyAppearance(
+  api: CasualSheetsAPI,
+  container: HTMLElement,
+  appearance: 'light' | 'dark',
+): void {
+  const dark = appearance === 'dark';
+  container.classList.toggle('univer-dark', dark);
+  try {
+    const injector = (api.univer as unknown as { _injector?: { get(t: unknown): unknown } })
+      ._injector;
+    const themeService = injector?.get(ThemeService) as
+      | { setDarkMode(b: boolean): void; darkMode: boolean }
+      | undefined;
+    if (themeService && themeService.darkMode !== dark) themeService.setDarkMode(dark);
+  } catch {
+    /* ThemeService unavailable — the class toggle still themes visible chrome */
+  }
+}

package/src/sheets/CasualSheetsIframe.tsx

@@ -0,0 +1,220 @@
+/**
+ * CasualSheetsIframe — the iframe-mounting variant of `<CasualSheets>`.
+ * Sheet sibling of `@casualoffice/docs`'s `<CasualEditorIframe>`;
+ * see doc 16 in the parent repo.
+ *
+ * Differs from CasualEditorIframe in one place: the embed URL params
+ * carry `app=sheet` and the embed-runtime inside the iframe knows to
+ * convert raw xlsx bytes into an `IWorkbookData` snapshot via
+ * `xlsxToWorkbookData` before mounting `<CasualSheets>`.
+ *
+ * Public surface intentionally identical to CasualSheets. v0.6 will
+ * rename CasualSheetsIframe → CasualSheets and the existing direct-
+ * mount component → CasualSheetsDirect.
+ */
+
+import {
+  forwardRef,
+  useCallback,
+  useEffect,
+  useRef,
+  type CSSProperties,
+  type MutableRefObject,
+} from 'react';
+
+import { EmbedHostTransport } from '../embed/EmbedHostTransport';
+import type {
+  CasualErrorData,
+  CommandExecuteData,
+  LoadResponseData,
+  SaveResponseData,
+  SelectionChangedData,
+  SelectionFormatStateData,
+  TelemetryEventData,
+} from '../embed/protocol';
+
+/** What the host-side load/save handlers consume + return. The wrapper
+ *  binds these to the host's FileSource via simple adapters. */
+export interface HostFileBridge {
+  open(docId: string): Promise<{ bytes: ArrayBuffer; name: string; etag?: string }>;
+  save?(docId: string, bytes: ArrayBuffer, opts?: { etag?: string }): Promise<{ etag: string }>;
+}
+
+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;
+}
+
+export interface CasualSheetsIframeProps {
+  /** Host-side bytes bridge. The wrapper round-trips load / save to the
+   *  iframe through postMessage; bytes never live in the iframe's origin
+   *  except in-memory while the workbook is open. */
+  fileSource: HostFileBridge;
+  docId: string;
+  /** Default `editor`. Live changes push casual.command.set.viewmode. */
+  viewMode?: 'preview' | 'editor';
+  /** Default `/embed/sheets`. Consumer copies the SDK's
+   *  `dist/embed/{embed.html, embed-runtime.js, embed-runtime.css}`
+   *  to this path. */
+  embedBasePath?: string;
+  onSelectionChanged?: (data: SelectionChangedData) => void;
+  /** Fires when the active cell's format flags change (bold, italic,
+   *  …). Drive's custom toolbar reflects this state in the button
+   *  "pressed" indicators. v0.6+. */
+  onSelectionFormatState?: (data: SelectionFormatStateData) => void;
+  onTelemetry?: (data: TelemetryEventData) => void;
+  onError?: (data: CasualErrorData) => void;
+  style?: CSSProperties;
+  className?: string;
+  testId?: string;
+}
+
+const DEFAULT_STYLE: CSSProperties = {
+  width: '100%',
+  height: '100%',
+  border: 'none',
+  display: 'block',
+};
+
+export const CasualSheetsIframe = forwardRef<CasualSheetsIframeRef, CasualSheetsIframeProps>(
+  function CasualSheetsIframe(props, ref) {
+    const {
+      fileSource,
+      docId,
+      viewMode = 'editor',
+      embedBasePath = '/embed/sheets',
+      onSelectionChanged,
+      onSelectionFormatState,
+      onTelemetry,
+      onError,
+      style,
+      className,
+      testId = 'casual-sheets-iframe',
+    } = props;
+
+    const iframeRef = useRef<HTMLIFrameElement | null>(null);
+    const transportRef = useRef<EmbedHostTransport | null>(null);
+    const fileSourceRef = useRef(fileSource);
+    fileSourceRef.current = fileSource;
+
+    const onLoad = useCallback(async (req: { docId: string }): Promise<LoadResponseData> => {
+      try {
+        const { bytes, name, etag } = await fileSourceRef.current.open(req.docId);
+        return {
+          ok: true,
+          bytes,
+          fileName: name,
+          ...(etag !== undefined ? { etag } : {}),
+        };
+      } catch (err) {
+        return {
+          ok: false,
+          code: 'open_failed',
+          message: err instanceof Error ? err.message : String(err),
+        };
+      }
+    }, []);
+
+    const onSave = useCallback(
+      async (req: {
+        docId: string;
+        bytes: ArrayBuffer;
+        baseEtag?: string;
+      }): Promise<SaveResponseData> => {
+        try {
+          if (!fileSourceRef.current.save) {
+            return {
+              ok: false,
+              code: 'save_unsupported',
+              message: 'host fileSource does not implement save',
+            };
+          }
+          const opts = req.baseEtag !== undefined ? { etag: req.baseEtag } : undefined;
+          const { etag } = await fileSourceRef.current.save(req.docId, req.bytes, opts);
+          return { ok: true, etag };
+        } catch (err) {
+          return {
+            ok: false,
+            code: 'save_failed',
+            message: err instanceof Error ? err.message : String(err),
+          };
+        }
+      },
+      [],
+    );
+
+    const onIframeLoad = useCallback(() => {
+      const iframe = iframeRef.current;
+      if (!iframe?.contentWindow) return;
+      transportRef.current?.destroy();
+      const transport = new EmbedHostTransport({
+        app: 'sheet',
+        iframeWindow: iframe.contentWindow,
+        embedOrigin: window.location.origin,
+      });
+      transport.on({
+        onLoadRequest: onLoad,
+        onSaveRequest: onSave,
+        ...(onSelectionChanged ? { onSelectionChanged } : {}),
+        ...(onSelectionFormatState ? { onSelectionFormatState } : {}),
+        ...(onTelemetry ? { onTelemetry } : {}),
+        ...(onError ? { onError } : {}),
+        onEditorReady: () => {
+          transport.sendHostHello({ capabilities: ['load', 'save'] });
+          transport.sendSetViewMode({ viewMode });
+        },
+      });
+      transportRef.current = transport;
+    }, [
+      onLoad,
+      onSave,
+      onSelectionChanged,
+      onSelectionFormatState,
+      onTelemetry,
+      onError,
+      viewMode,
+    ]);
+
+    useEffect(() => {
+      transportRef.current?.sendSetViewMode({ viewMode });
+    }, [viewMode]);
+
+    useEffect(() => {
+      return () => {
+        transportRef.current?.destroy();
+        transportRef.current = null;
+      };
+    }, []);
+
+    if (ref) {
+      const apiRef = ref as MutableRefObject<CasualSheetsIframeRef | null>;
+      apiRef.current = {
+        setViewMode: (mode) => transportRef.current?.sendSetViewMode({ viewMode: mode }),
+        iframe: () => iframeRef.current,
+        executeCommand: (command) => transportRef.current?.sendCommandExecute({ command }),
+      };
+    }
+
+    const url =
+      `${embedBasePath}/embed.html` +
+      `?app=sheet` +
+      `&docId=${encodeURIComponent(docId)}` +
+      `&viewMode=${viewMode}`;
+
+    return (
+      <iframe
+        ref={iframeRef}
+        src={url}
+        onLoad={onIframeLoad}
+        title="Casual Sheets"
+        sandbox="allow-scripts allow-same-origin allow-downloads allow-modals"
+        style={{ ...DEFAULT_STYLE, ...style }}
+        className={className}
+        data-testid={testId}
+      />
+    );
+  },
+);

package/src/sheets/api.ts

@@ -0,0 +1,108 @@
+/**
+ * CasualSheetsAPI — the imperative ref handed to a host via `<CasualSheets onReady>`.
+ *
+ * This is the SDK's stable integration surface (Excalidraw's model: props +
+ * imperative ref). Hosts drive the editor through these methods rather than
+ * reaching into Univer directly; `api.univer` is the documented escape hatch and
+ * is explicitly NOT covered by semver — everything else here is.
+ *
+ * Scope of THIS batch (SDK restructure, Phase 1 step 3):
+ *   getSnapshot / loadSnapshot / getSelection / executeCommand / univer
+ *
+ * Deferred to later, clearly-scoped batches (kept off the type until they work,
+ * so the surface never advertises a method that throws):
+ *   - importXlsx / exportXlsx — the xlsx I/O batch. importXlsx must NOT be a
+ *     plain `import('../xlsx')` here: the main tsup config is `splitting:false`,
+ *     so a dynamic import gets inlined and balloons the editor entry from ~11KB
+ *     to ~200KB of parser code for hosts that never open a file. The xlsx-I/O
+ *     batch wires it as its own chunk (and lifts the export converter out of
+ *     apps/web — the SDK xlsx module is import-only today).
+ *   - attachCollab — belongs to the storage/collab adapter phase (Phase 2);
+ *     the editor ships collab-unaware until then.
+ */
+
+// Side-effect import: registers the Sheets FUniver mixins
+// (getActiveWorkbook / createWorkbook / FWorkbook.save / FRange.getRange / …)
+// onto the core FUniver facade — both the runtime methods AND the TypeScript
+// type augmentation this file relies on. Without it, FUniver is the bare core
+// facade and these methods exist neither at type-check nor at runtime.
+import '@univerjs/sheets/facade';
+import { ThemeService } from '@univerjs/core';
+import type { FUniver } from '@univerjs/core/facade';
+import type { IRange, IWorkbookData } from '@univerjs/core';
+
+/** The active selection, as a sheet-scoped range. */
+export interface RangeRef {
+  /** Workbook unit id the selection belongs to. */
+  unitId: string;
+  /** Worksheet (sub-unit) id the selection belongs to. */
+  sheetId: string;
+  /** `{ startRow, startColumn, endRow, endColumn }`. */
+  range: IRange;
+}
+
+export interface CasualSheetsAPI {
+  /** Current workbook as an `IWorkbookData` snapshot. `null` before the unit
+   *  is created (shouldn't happen after `onReady`, but typed defensively). */
+  getSnapshot(): IWorkbookData | null;
+  /** Replace the workbook with a new snapshot. Disposes the current unit and
+   *  mounts `data` as a fresh one. */
+  loadSnapshot(data: IWorkbookData): void;
+  /** The active selection, or `null` when there is none. */
+  getSelection(): RangeRef | null;
+  /** Dispatch a Univer command by id. Resolves to the command's boolean
+   *  result. */
+  executeCommand(id: string, params?: object): Promise<boolean>;
+  /** Imperative light/dark switch — the API equivalent of the reactive
+   *  `appearance` prop. Flips Univer's `ThemeService.setDarkMode` (canvas
+   *  colours + the `univer-dark` class Univer applies to the document root). */
+  setTheme(appearance: 'light' | 'dark'): void;
+  /** The FUniver facade — documented escape hatch, NOT covered by semver. */
+  univer: FUniver;
+}
+
+/**
+ * Build the imperative API over a live FUniver facade. The wrapper holds no
+ * state of its own — every call reads the current active workbook, so it stays
+ * correct across `loadSnapshot` swaps without the host re-acquiring the ref.
+ */
+export function createCasualSheetsAPI(univerAPI: FUniver): CasualSheetsAPI {
+  return {
+    univer: univerAPI,
+
+    getSnapshot() {
+      return univerAPI.getActiveWorkbook()?.save() ?? null;
+    },
+
+    loadSnapshot(data) {
+      const current = univerAPI.getActiveWorkbook();
+      if (current) univerAPI.disposeUnit(current.getId());
+      univerAPI.createWorkbook(data);
+    },
+
+    getSelection() {
+      const wb = univerAPI.getActiveWorkbook();
+      const range = wb?.getActiveRange();
+      if (!wb || !range) return null;
+      return {
+        unitId: wb.getId(),
+        sheetId: wb.getActiveSheet().getSheetId(),
+        range: range.getRange(),
+      };
+    },
+
+    executeCommand(id, params) {
+      return univerAPI.executeCommand(id, params) as Promise<boolean>;
+    },
+
+    setTheme(appearance) {
+      const dark = appearance === 'dark';
+      const injector = (univerAPI as unknown as { _injector?: { get(t: unknown): unknown } })
+        ._injector;
+      const themeService = injector?.get(ThemeService) as
+        | { setDarkMode(b: boolean): void; darkMode: boolean }
+        | undefined;
+      if (themeService && themeService.darkMode !== dark) themeService.setDarkMode(dark);
+    },
+  };
+}

package/src/sheets/index.ts

@@ -0,0 +1,11 @@
+/**
+ * Sheets surface — React wrappers around Univer Sheets.
+ */
+export { CasualSheets, type CasualSheetsProps } from './CasualSheets';
+export { createCasualSheetsAPI, type CasualSheetsAPI, type RangeRef } from './api';
+export {
+  CasualSheetsIframe,
+  type CasualSheetsIframeProps,
+  type CasualSheetsIframeRef,
+  type HostFileBridge,
+} from './CasualSheetsIframe';