@casualoffice/sheets 0.9.0 → 0.10.0

package/src/embed/EmbedTransport.unit.test.ts

@@ -7,8 +7,8 @@
 import { strict as assert } from 'node:assert';
 import { test } from 'node:test';
 
-import { EmbedTransport, isCasualEnvelope } from './';
-import type { CasualEnvelope } from './';
+import { EmbedTransport, EmbedHostTransport, isCasualEnvelope } from './';
+import type { CasualEnvelope, SaveNotifyData, ExitData } from './';
 
 function fakeHostWindow() {
   let handler: ((ev: unknown) => void) | null = null;
@@ -135,6 +135,92 @@ test('sendHello emits an editor.hello envelope', () => {
   assert.deepEqual((env.data as { capabilities: string[] }).capabilities, ['save', 'load']);
 });
 
+test('sendSaveNotify emits a fire-and-forget save.notify with the snapshot', () => {
+  const host = fakeHostWindow();
+  const parent = fakeParent();
+  const transport = new EmbedTransport({
+    app: 'sheet',
+    hostOrigin: 'https://drive.example',
+    version: '1.0.0',
+    commit: 'abc',
+    capabilities: [],
+    parentWindow: parent,
+    hostWindow: host,
+  });
+  const snapshot = { id: 'wb1', sheets: {} };
+  transport.sendSaveNotify({ snapshot, reason: 'shortcut' });
+  assert.equal(parent.sent.length, 1);
+  const env = parent.sent[0].msg as CasualEnvelope;
+  assert.equal(env.type, 'casual.save.notify');
+  assert.equal(env.app, 'sheet');
+  // No id — it's a notification, not a request awaiting a response.
+  assert.equal(env.id, undefined);
+  assert.equal((env.data as { reason: string }).reason, 'shortcut');
+  assert.deepEqual((env.data as { snapshot: unknown }).snapshot, snapshot);
+});
+
+test('sendExit emits an exit envelope carrying the final snapshot', () => {
+  const host = fakeHostWindow();
+  const parent = fakeParent();
+  const transport = new EmbedTransport({
+    app: 'sheet',
+    hostOrigin: 'https://drive.example',
+    version: '1.0.0',
+    commit: 'abc',
+    capabilities: [],
+    parentWindow: parent,
+    hostWindow: host,
+  });
+  const snapshot = { id: 'wb1', sheets: { s1: {} } };
+  transport.sendExit({ snapshot });
+  assert.equal(parent.sent.length, 1);
+  const env = parent.sent[0].msg as CasualEnvelope;
+  assert.equal(env.type, 'casual.exit');
+  assert.equal(env.id, undefined);
+  assert.deepEqual((env.data as { snapshot: unknown }).snapshot, snapshot);
+});
+
+test('host transport dispatches save.notify + exit to its handlers', async () => {
+  const host = fakeHostWindow();
+  // The host transport gates on ev.source === iframeWindow; use a sentinel.
+  const iframeWindow = { postMessage() {} } as unknown as Window;
+  const hostTransport = new EmbedHostTransport({
+    app: 'sheet',
+    iframeWindow,
+    embedOrigin: 'https://embed.example',
+    hostWindow: host,
+  });
+  let saved: SaveNotifyData | null = null;
+  let exited: ExitData | null = null;
+  hostTransport.on({
+    onSaveNotify: (d) => {
+      saved = d;
+    },
+    onExit: (d) => {
+      exited = d;
+    },
+  });
+  host.fire({
+    origin: 'https://embed.example',
+    source: iframeWindow,
+    data: {
+      type: 'casual.save.notify',
+      app: 'sheet',
+      v: 1,
+      data: { snapshot: { id: 'wb1' }, reason: 'host' },
+    },
+  });
+  host.fire({
+    origin: 'https://embed.example',
+    source: iframeWindow,
+    data: { type: 'casual.exit', app: 'sheet', v: 1, data: { snapshot: { id: 'wb1' } } },
+  });
+  await new Promise((r) => setTimeout(r, 0));
+  assert.equal(saved!.reason, 'host');
+  assert.deepEqual(saved!.snapshot, { id: 'wb1' });
+  assert.deepEqual(exited!.snapshot, { id: 'wb1' });
+});
+
 test('destroy detaches the listener', () => {
   const host = fakeHostWindow();
   const transport = new EmbedTransport({

package/src/embed/index.ts

@@ -12,6 +12,11 @@ export {
   type EmbedTransportHandlers,
   type EmbedTransportOptions,
 } from './EmbedTransport';
+export {
+  EmbedHostTransport,
+  type EmbedHostHandlers,
+  type EmbedHostTransportOptions,
+} from './EmbedHostTransport';
 export {
   isCasualEnvelope,
   type CasualApp,
@@ -26,6 +31,8 @@ export {
   type SaveResponseData,
   type SaveResponseDataOk,
   type SaveResponseDataErr,
+  type SaveNotifyData,
+  type ExitData,
   type SelectionChangedData,
   type TelemetryEventData,
   type LockLostData,

package/src/embed/protocol.ts

@@ -87,6 +87,40 @@ export interface SaveResponseDataErr {
 
 export type SaveResponseData = SaveResponseDataOk | SaveResponseDataErr;
 
+// ---------------------------------------------------------------
+// Save / exit notifications (editor → host, fire-and-forget)
+// ---------------------------------------------------------------
+//
+// The lightweight counterpart to the bytes-carrying load/save *request*
+// pair above. These mirror the SDK's React `onSave` / `onExit` hooks one
+// for one — the "one shape, two surfaces" save/exit contract — so a host
+// that frames the iframe gets the same persistence signals a host that
+// renders `<CasualSheets>` directly does. Fire-and-forget: the editor
+// never owns storage; the host decides what to do with the snapshot.
+//
+// `casual.save.request` (above) stays the WOPI-style path for hosts that
+// want xlsx bytes + etag round-trips; these notifications are the simpler
+// "here's the current state, persist it however you like" path.
+
+/** Editor → host: the user explicitly asked to save — Ctrl/Cmd+S inside
+ *  the iframe, or the host's `casual.command.save`. Carries the full
+ *  editor snapshot as JSON (sheet app: Univer's `IWorkbookData`). Mirror
+ *  of the React `onSave` hook. v0.9+. */
+export interface SaveNotifyData {
+  /** App-specific snapshot JSON. Sheet: `IWorkbookData`. */
+  snapshot: unknown;
+  /** What triggered the save: the in-editor shortcut or a host command. */
+  reason: 'shortcut' | 'host';
+}
+
+/** Editor → host: the editor is unmounting / navigating away. Carries
+ *  the final snapshot so the host can persist on exit. Mirror of the
+ *  React `onExit` hook. v0.9+. */
+export interface ExitData {
+  /** App-specific snapshot JSON. Sheet: `IWorkbookData`. */
+  snapshot: unknown;
+}
+
 // ---------------------------------------------------------------
 // Selection + telemetry + lock (editor → host notifications)
 // ---------------------------------------------------------------

package/src/embed-runtime/index.tsx

@@ -230,6 +230,14 @@ function EmbeddedSheets({
       // iframe ships the minimal editor. Hosts that need feature plugins use
       // the React `<CasualSheets>` component directly (lazyPlugins defaults on).
       lazyPlugins={false}
+      // Phase 2 save/exit contract — the iframe surface of the same
+      // `onSave` / `onExit` hooks the React component exposes. The editor
+      // never persists; it hands the snapshot to the host over postMessage
+      // and the host decides what to do with it (WOPI, Drive, localStorage
+      // demo, …). `onSave` fires on Ctrl/Cmd+S inside the iframe; `onExit`
+      // on unmount.
+      onSave={(snapshot) => transport.sendSaveNotify({ snapshot, reason: 'shortcut' })}
+      onExit={(snapshot) => transport.sendExit({ snapshot })}
       onReady={(api) => {
         // Wire host → editor command.execute (Drive's custom toolbar
         // calls this for bold / italic / undo / …). Maps the small
@@ -246,6 +254,7 @@ function EmbeddedSheets({
         // a different module. The runtime behaviour is fine.
         const apiAny = api as unknown as {
           executeCommand(id: string, params?: object): Promise<unknown>;
+          getSnapshot(): unknown;
           univer: { getActiveWorkbook(): { getActiveSheet(): SheetLike | null } | null };
         };
         transport.on({
@@ -259,6 +268,17 @@ function EmbeddedSheets({
               /* swallow — bad command id from a stale host shouldn't crash the iframe */
             }
           },
+          // Host clicked its own "Save" button (host-rendered chrome above
+          // the iframe). Snapshot now and emit the same save notification
+          // the in-iframe Ctrl/Cmd+S path does — only the `reason` differs.
+          onCommandSave: () => {
+            try {
+              const snapshot = apiAny.getSnapshot();
+              if (snapshot) transport.sendSaveNotify({ snapshot, reason: 'host' });
+            } catch {
+              /* snapshot unavailable during boot — ignore */
+            }
+          },
         });
 
         // Editor → host: emit format state on a coarse interval. The

package/src/sheets/CasualSheets.tsx

@@ -13,11 +13,11 @@
  * snapshot already uses, idle-loaded otherwise. Pass `lazyPlugins={false}`
  * for the minimal editor.
  *
+ * Formula compute runs on the main thread by default; pass `formula={{ worker }}`
+ * to move it off-thread (the SDK then wires `UniverRPCMainThreadPlugin` to the
+ * host's worker — see the `formula` prop).
+ *
  * 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,
@@ -28,7 +28,15 @@
  * styles from this entry if the host doesn't reach the styles export.
  */
 
-import { useEffect, useRef, type CSSProperties } from 'react';
+import {
+  lazy,
+  Suspense,
+  useEffect,
+  useRef,
+  useState,
+  type CSSProperties,
+  type KeyboardEvent as ReactKeyboardEvent,
+} from 'react';
 import {
   ICommandService,
   LocaleType,
@@ -51,13 +59,27 @@ 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 { UniverSheetsFormulaPlugin, CalculationMode } from '@univerjs/sheets-formula';
 import { UniverSheetsFormulaUIPlugin } from '@univerjs/sheets-formula-ui';
 import { UniverSheetsNumfmtPlugin } from '@univerjs/sheets-numfmt';
 import { UniverSheetsNumfmtUIPlugin } from '@univerjs/sheets-numfmt-ui';
+// Type-only — erased at build, so `@univerjs/rpc` stays a runtime-optional peer
+// (loaded via dynamic import only when a formula worker is passed).
+import type { UniverRPCMainThreadPlugin as RpcMainThreadPluginType } from '@univerjs/rpc';
 
 import { createCasualSheetsAPI, type CasualSheetsAPI } from './api';
 import { eagerLoadForSnapshot, idleLoadAll, setUniverForLazyLoad } from '../univer/lazy-plugins';
+// Chrome is lazy-loaded from the `@casualoffice/sheets/chrome` subpath (NOT a
+// relative import — that would inline under this build's splitting:false). The
+// subpath is externalised in tsup, so the consumer's bundler code-splits it and
+// `chrome="none"` hosts (the default + the apps/web reference host) never load
+// the chrome chunk.
+const ChromeTop = lazy(() =>
+  import('@casualoffice/sheets/chrome').then((m) => ({ default: m.ChromeTop })),
+);
+const ChromeBottom = lazy(() =>
+  import('@casualoffice/sheets/chrome').then((m) => ({ default: m.ChromeBottom })),
+);
 
 export interface CasualSheetsProps {
   /** Workbook snapshot to mount. Read once on initial mount; change
@@ -80,6 +102,13 @@ export interface CasualSheetsProps {
   onChange?: (snapshot: IWorkbookData) => void;
   /** Debounce window for `onChange`, in ms. Default 400. */
   onChangeDebounceMs?: number;
+  /** Explicit save — fired when the user presses Ctrl/Cmd+S inside the editor
+   *  (the browser's save dialog is suppressed). The host persists the snapshot.
+   *  Part of the "host owns storage" contract: the SDK never writes a store. */
+  onSave?: (snapshot: IWorkbookData) => void;
+  /** Fired once when the editor unmounts, with the final snapshot — the host's
+   *  last chance to persist before the workbook is disposed. */
+  onExit?: (snapshot: IWorkbookData) => void;
   /** 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
@@ -88,6 +117,29 @@ export interface CasualSheetsProps {
    *  minimal editor (render + formula + numfmt only) — the embed-iframe
    *  build does this to stay a single self-contained bundle. */
   lazyPlugins?: boolean;
+  /** Escape hatch fired after the SDK registers its built-in plugins but BEFORE
+   *  the workbook unit is created — the host can `univer.registerPlugin(...)`
+   *  additional plugins here (e.g. an off-main formula worker via
+   *  `UniverRPCMainThreadPlugin`, crosshair-highlight, zen-editor). Anything
+   *  registered after `createUnit` would miss the unit's plugin-init pass, so
+   *  register-time extras must go through this hook. Power hosts (the reference
+   *  app) use it to share the SDK editor core while keeping their extra plugins;
+   *  most integrators never need it. NOT covered by semver — it hands you the
+   *  raw `Univer` instance. */
+  onBeforeCreateUnit?: (univer: Univer) => void;
+  /** Off-main formula compute. By default the formula engine runs on the MAIN
+   *  thread (fine for typical sheets, zero host setup). Provide a Web Worker (or
+   *  its URL) to move compute off-thread so paste / sort / fill on large
+   *  workbooks don't freeze the UI: the SDK then registers the formula plugins
+   *  with `notExecuteFormula` and wires `UniverRPCMainThreadPlugin` to your
+   *  worker. The host owns the worker (the SDK never bundles one — that's brittle
+   *  across bundlers) and must have `@univerjs/rpc` installed. The worker script
+   *  is the standard Univer formula worker (see the reference app's
+   *  `apps/web/src/univer/formula-worker.ts`). */
+  formula?: {
+    /** A constructed `Worker`, or a URL/string the RPC plugin loads. */
+    worker?: Worker | string;
+  };
   /** Locale identifier. Defaults to `LocaleType.EN_US`. */
   locale?: LocaleType;
   /** Locale string bundle. Optional — Univer's default English
@@ -114,6 +166,18 @@ export interface CasualSheetsProps {
    *  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';
+  /** Office chrome rendered around the grid:
+   *  - `'none'` (default): bare grid — the host supplies its own chrome.
+   *  - `'minimal'` / `'full'`: the built-in Office shell — a menu bar
+   *    (Edit/Insert/Format/Data/View), a formatting toolbar (font family/size,
+   *    bold/italic/underline/strike, text & fill colour, borders, h/v align,
+   *    wrap, merge, number formats, clear format, AutoSum), a formula bar with a
+   *    name box + function autocomplete, a worksheet tab strip (switch/add/
+   *    rename/delete), and a status bar (Average/Count/Numerical Count/Min/Max/
+   *    Sum + zoom). All driven through the facade, themed via `--cs-chrome-*`
+   *    (light/dark). `'minimal'` and `'full'` currently render the same shell;
+   *    `'full'` is where richer panels (find/replace, charts, …) will land. */
+  chrome?: 'none' | 'minimal' | 'full';
   /** Container style. Default fills the parent. */
   style?: CSSProperties;
   /** Container className for additional styling hooks. */
@@ -140,13 +204,18 @@ export function CasualSheets({
   onReady,
   onChange,
   onChangeDebounceMs = 400,
+  onSave,
+  onExit,
   lazyPlugins = true,
+  onBeforeCreateUnit,
+  formula,
   locale = LocaleType.EN_US,
   locales,
   logLevel = LogLevel.WARN,
   ui,
   theme = defaultTheme,
   appearance = 'light',
+  chrome = 'none',
   style,
   className,
   testId = 'casual-sheets',
@@ -158,9 +227,20 @@ export function CasualSheets({
   const onChangeRef = useRef(onChange);
   onChangeRef.current = onChange;
   const hasOnChange = useRef(!!onChange).current;
+  // Latest save/exit callbacks, called via refs so they fire without re-running
+  // the boot effect. onExit is read in cleanup; onSave on the Ctrl/Cmd+S handler.
+  const onSaveRef = useRef(onSave);
+  onSaveRef.current = onSave;
+  const onExitRef = useRef(onExit);
+  onExitRef.current = onExit;
   // 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);
+  // The live API as state, so the built-in chrome (FormulaBar) re-renders and
+  // subscribes once the editor is ready. Only set when chrome is shown — the
+  // bare-grid path never triggers this re-render. A single post-mount setState
+  // doesn't disturb the grid (Univer owns its canvas outside React).
+  const [chromeApi, setChromeApi] = useState<CasualSheetsAPI | null>(null);
 
   useEffect(() => {
     const container = hostRef.current;
@@ -175,36 +255,56 @@ export function CasualSheets({
 
     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);
+    // `formula.worker` → off-main compute. Default = main thread (fine for
+    // typical sheets, zero host setup).
+    const offMain = !!formula?.worker;
 
     let cancelled = false;
     let changeTimer: ReturnType<typeof setTimeout> | null = null;
     let changeSub: { dispose: () => void } | undefined;
 
     void (async () => {
+      // Plugin registration runs here (not synchronously) so the OPTIONAL RPC
+      // transport can be `await import`ed FIRST and registered in its correct
+      // slot — right after the formula engine, before sheets. Registering it out
+      // of order (or after createUnit) leaves the formula engine's worker channel
+      // unwired → cells stay 0. Dynamic import keeps `@univerjs/rpc` a true
+      // optional peer (only loaded when a worker is passed).
+      let RPCMainThreadPlugin: typeof RpcMainThreadPluginType | null = null;
+      if (offMain && formula?.worker) {
+        RPCMainThreadPlugin = (await import('@univerjs/rpc')).UniverRPCMainThreadPlugin;
+        if (cancelled) return;
+      }
+
+      univer.registerPlugin(UniverRenderEnginePlugin);
+      univer.registerPlugin(
+        UniverFormulaEnginePlugin,
+        offMain ? { notExecuteFormula: true } : undefined,
+      );
+      if (RPCMainThreadPlugin && formula?.worker) {
+        univer.registerPlugin(RPCMainThreadPlugin, { workerURL: formula.worker });
+      }
+      univer.registerPlugin(UniverUIPlugin, uiOpts);
+      univer.registerPlugin(UniverDocsPlugin);
+      univer.registerPlugin(UniverDocsUIPlugin);
+      univer.registerPlugin(UniverSheetsPlugin, offMain ? { notExecuteFormula: true } : undefined);
+      univer.registerPlugin(UniverSheetsUIPlugin);
+      univer.registerPlugin(
+        UniverSheetsFormulaPlugin,
+        offMain
+          ? { notExecuteFormula: true, initialFormulaComputing: CalculationMode.NO_CALCULATION }
+          : undefined,
+      );
+      univer.registerPlugin(UniverSheetsFormulaUIPlugin);
+      univer.registerPlugin(UniverSheetsNumfmtPlugin);
+      univer.registerPlugin(UniverSheetsNumfmtUIPlugin);
+
+      // Lazy-loader holder (the loader is @internal so a relative import shares
+      // no cross-instance state) + host plugin escape hatch — both before
+      // createUnit.
+      if (lazyPlugins) setUniverForLazyLoad(univer);
+      onBeforeCreateUnit?.(univer);
+
       // 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
@@ -218,6 +318,9 @@ export function CasualSheets({
 
       const api = createCasualSheetsAPI(FUniver.newAPI(univer));
       apiRef.current = api;
+      // Hand the live API to the built-in chrome (FormulaBar subscribes to it).
+      // Only when chrome is shown, so bare-grid consumers never re-render.
+      if (!cancelled && chrome !== 'none') setChromeApi(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).
@@ -258,7 +361,14 @@ export function CasualSheets({
       cancelled = true;
       if (changeTimer) clearTimeout(changeTimer);
       changeSub?.dispose();
+      // Last-chance persist: emit the final snapshot before the workbook is
+      // disposed (disposal is deferred via microtask below, so it's still alive).
+      if (onExitRef.current) {
+        const snap = apiRef.current?.getSnapshot();
+        if (snap) onExitRef.current(snap);
+      }
       apiRef.current = null;
+      setChromeApi(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
@@ -281,13 +391,74 @@ export function CasualSheets({
     applyAppearance(api, container, appearance);
   }, [appearance]);
 
+  // Ctrl/Cmd+S anywhere in the editor → onSave (suppress the browser dialog).
+  // Capture phase so we beat Univer's own key handling on the canvas.
+  const onKeyDownCapture = (e: ReactKeyboardEvent<HTMLDivElement>) => {
+    if ((e.metaKey || e.ctrlKey) && (e.key === 's' || e.key === 'S')) {
+      e.preventDefault();
+      const snap = apiRef.current?.getSnapshot();
+      if (snap) onSaveRef.current?.(snap);
+    }
+  };
+
+  // chrome="none" (default) keeps the exact bare-grid shape existing consumers
+  // rely on (embed-runtime, hosts that bring their own shell). Any other level
+  // wraps the grid in a flex column with the built-in chrome above it; the grid
+  // container (hostRef, where Univer mounts) fills the remaining space.
+  if (chrome === 'none') {
+    return (
+      <div
+        ref={hostRef}
+        onKeyDownCapture={onKeyDownCapture}
+        style={{ ...DEFAULT_STYLE, ...style }}
+        className={className}
+        data-testid={testId}
+      />
+    );
+  }
+
+  // The built-in chrome components read their colours from `--cs-chrome-*` CSS
+  // vars (with light fallbacks). Set them on the wrapper so the toolbar / formula
+  // bar / status bar flip with `appearance` — reactive via the prop. (Hosts can
+  // still override any of these vars themselves.)
+  // Values from @schnsrw/design-system tokens (surface-strip / text / border)
+  // — adopted directly (not as a package dep) so the chrome matches the suite.
+  const dark = appearance === 'dark';
+  const chromeVars = {
+    '--cs-chrome-bg': dark ? '#2a2e35' : '#eef1f5',
+    '--cs-chrome-fg': dark ? '#e6e6e6' : '#201f1e',
+    '--cs-chrome-muted': dark ? '#b0b3ba' : '#605e5c',
+    '--cs-chrome-border': dark ? '#32363d' : '#e6e9ee',
+    '--cs-chrome-input-bg': dark ? '#23262c' : '#ffffff',
+    '--cs-chrome-hover': dark ? 'rgba(255,255,255,0.08)' : 'rgba(0,0,0,0.06)',
+    // accent (design-system #0e7490) for active toggle states.
+    '--cs-chrome-active': dark ? 'rgba(21,151,186,0.22)' : '#e6f3f7',
+    '--cs-chrome-active-fg': dark ? '#7fd3e6' : '#0e7490',
+  } as CSSProperties;
+
   return (
     <div
-      ref={hostRef}
-      style={{ ...DEFAULT_STYLE, ...style }}
       className={className}
       data-testid={testId}
-    />
+      onKeyDownCapture={onKeyDownCapture}
+      style={{
+        ...DEFAULT_STYLE,
+        ...chromeVars,
+        ...style,
+        display: 'flex',
+        flexDirection: 'column',
+      }}
+    >
+      {/* Bars appear once their lazy chunk loads (a tick after first paint); the
+          grid host is OUTSIDE Suspense so Univer mounts immediately. */}
+      <Suspense fallback={null}>
+        <ChromeTop api={chromeApi} />
+      </Suspense>
+      <div ref={hostRef} style={{ flex: '1 1 auto', minHeight: 0, position: 'relative' }} />
+      <Suspense fallback={null}>
+        <ChromeBottom api={chromeApi} />
+      </Suspense>
+    </div>
   );
 }