@casualoffice/sheets 0.9.0 → 0.10.0

package/dist/sheets.d.cts

@@ -1,69 +1,13 @@
 import * as react from 'react';
 import { CSSProperties } from 'react';
-import { IWorkbookData, IRange, LocaleType, ILocales, LogLevel } from '@univerjs/core';
+import { IWorkbookData, Univer, LocaleType, ILocales, LogLevel } from '@univerjs/core';
 import { defaultTheme } from '@univerjs/themes';
-import { FUniver } from '@univerjs/core/facade';
-import { o as SelectionChangedData, p as SelectionFormatStateData, T as TelemetryEventData, b as CasualErrorData, c as CommandExecuteData } from './protocol--KyBQUjU.cjs';
+import { C as CasualSheetsAPI } from './api-BI2VLYQ6.cjs';
+export { R as RangeRef, c as createCasualSheetsAPI } from './api-BI2VLYQ6.cjs';
+import { q as SelectionChangedData, r as SelectionFormatStateData, T as TelemetryEventData, b as CasualErrorData, c as CommandExecuteData } from './protocol-Cq4Cdoyi.cjs';
+import '@univerjs/core/facade';
 import './types-s_O0u6Cg.cjs';
 
-/**
- * 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.
- */
-
-/** The active selection, as a sheet-scoped range. */
-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;
-}
-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.
- */
-declare function createCasualSheetsAPI(univerAPI: FUniver): CasualSheetsAPI;
-
 interface CasualSheetsProps {
     /** Workbook snapshot to mount. Read once on initial mount; change
      *  the React `key` on this component to remount with a new
@@ -85,6 +29,13 @@ 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
@@ -93,6 +44,29 @@ 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
@@ -119,6 +93,18 @@ 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. */
@@ -126,7 +112,7 @@ interface CasualSheetsProps {
     /** Optional test id for the host container. */
     testId?: string;
 }
-declare function CasualSheets({ initialData, onReady, onChange, onChangeDebounceMs, lazyPlugins, locale, locales, logLevel, ui, theme, appearance, style, className, testId, }: CasualSheetsProps): react.JSX.Element;
+declare function CasualSheets({ initialData, onReady, onChange, onChangeDebounceMs, onSave, onExit, lazyPlugins, onBeforeCreateUnit, formula, locale, locales, logLevel, ui, theme, appearance, chrome, style, className, testId, }: CasualSheetsProps): react.JSX.Element;
 
 /** What the host-side load/save handlers consume + return. The wrapper
  *  binds these to the host's FileSource via simple adapters. */
@@ -174,4 +160,4 @@ interface CasualSheetsIframeProps {
 }
 declare const CasualSheetsIframe: react.ForwardRefExoticComponent<CasualSheetsIframeProps & react.RefAttributes<CasualSheetsIframeRef>>;
 
-export { CasualSheets, type CasualSheetsAPI, CasualSheetsIframe, type CasualSheetsIframeProps, type CasualSheetsIframeRef, type CasualSheetsProps, type HostFileBridge, type RangeRef, createCasualSheetsAPI };
+export { CasualSheets, CasualSheetsAPI, CasualSheetsIframe, type CasualSheetsIframeProps, type CasualSheetsIframeRef, type CasualSheetsProps, type HostFileBridge };

package/dist/sheets.d.ts

@@ -1,69 +1,13 @@
 import * as react from 'react';
 import { CSSProperties } from 'react';
-import { IWorkbookData, IRange, LocaleType, ILocales, LogLevel } from '@univerjs/core';
+import { IWorkbookData, Univer, LocaleType, ILocales, LogLevel } from '@univerjs/core';
 import { defaultTheme } from '@univerjs/themes';
-import { FUniver } from '@univerjs/core/facade';
-import { o as SelectionChangedData, p as SelectionFormatStateData, T as TelemetryEventData, b as CasualErrorData, c as CommandExecuteData } from './protocol-cEzy7S0i.js';
+import { C as CasualSheetsAPI } from './api-BI2VLYQ6.js';
+export { R as RangeRef, c as createCasualSheetsAPI } from './api-BI2VLYQ6.js';
+import { q as SelectionChangedData, r as SelectionFormatStateData, T as TelemetryEventData, b as CasualErrorData, c as CommandExecuteData } from './protocol-DqDaG2yG.js';
+import '@univerjs/core/facade';
 import './types-s_O0u6Cg.js';
 
-/**
- * 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.
- */
-
-/** The active selection, as a sheet-scoped range. */
-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;
-}
-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.
- */
-declare function createCasualSheetsAPI(univerAPI: FUniver): CasualSheetsAPI;
-
 interface CasualSheetsProps {
     /** Workbook snapshot to mount. Read once on initial mount; change
      *  the React `key` on this component to remount with a new
@@ -85,6 +29,13 @@ 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
@@ -93,6 +44,29 @@ 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
@@ -119,6 +93,18 @@ 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. */
@@ -126,7 +112,7 @@ interface CasualSheetsProps {
     /** Optional test id for the host container. */
     testId?: string;
 }
-declare function CasualSheets({ initialData, onReady, onChange, onChangeDebounceMs, lazyPlugins, locale, locales, logLevel, ui, theme, appearance, style, className, testId, }: CasualSheetsProps): react.JSX.Element;
+declare function CasualSheets({ initialData, onReady, onChange, onChangeDebounceMs, onSave, onExit, lazyPlugins, onBeforeCreateUnit, formula, locale, locales, logLevel, ui, theme, appearance, chrome, style, className, testId, }: CasualSheetsProps): react.JSX.Element;
 
 /** What the host-side load/save handlers consume + return. The wrapper
  *  binds these to the host's FileSource via simple adapters. */
@@ -174,4 +160,4 @@ interface CasualSheetsIframeProps {
 }
 declare const CasualSheetsIframe: react.ForwardRefExoticComponent<CasualSheetsIframeProps & react.RefAttributes<CasualSheetsIframeRef>>;
 
-export { CasualSheets, type CasualSheetsAPI, CasualSheetsIframe, type CasualSheetsIframeProps, type CasualSheetsIframeRef, type CasualSheetsProps, type HostFileBridge, type RangeRef, createCasualSheetsAPI };
+export { CasualSheets, CasualSheetsAPI, CasualSheetsIframe, type CasualSheetsIframeProps, type CasualSheetsIframeRef, type CasualSheetsProps, type HostFileBridge };

package/dist/sheets.js

@@ -3,7 +3,13 @@ var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { en
 var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
 
 // src/sheets/CasualSheets.tsx
-import { useEffect, useRef } from "react";
+import {
+  lazy,
+  Suspense,
+  useEffect,
+  useRef,
+  useState
+} from "react";
 import {
   ICommandService,
   LocaleType,
@@ -21,7 +27,7 @@ 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";
@@ -238,7 +244,13 @@ function snapshotHasHyperlinks(snapshot) {
 }
 
 // src/sheets/CasualSheets.tsx
-import { jsx } from "react/jsx-runtime";
+import { jsx, jsxs } from "react/jsx-runtime";
+var ChromeTop = lazy(
+  () => import("@casualoffice/sheets/chrome").then((m) => ({ default: m.ChromeTop }))
+);
+var ChromeBottom = lazy(
+  () => import("@casualoffice/sheets/chrome").then((m) => ({ default: m.ChromeBottom }))
+);
 var DEFAULT_STYLE = {
   width: "100%",
   height: "100%",
@@ -255,13 +267,18 @@ 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"
@@ -270,7 +287,12 @@ function CasualSheets({
   const onChangeRef = useRef(onChange);
   onChangeRef.current = onChange;
   const hasOnChange = useRef(!!onChange).current;
+  const onSaveRef = useRef(onSave);
+  onSaveRef.current = onSave;
+  const onExitRef = useRef(onExit);
+  onExitRef.current = onExit;
   const apiRef = useRef(null);
+  const [chromeApi, setChromeApi] = useState(null);
   useEffect(() => {
     const container = hostRef.current;
     if (!container) return;
@@ -281,22 +303,38 @@ function CasualSheets({
       logLevel
     });
     const uiOpts = { ...DEFAULT_UI, ...ui, container };
-    univer.registerPlugin(UniverRenderEnginePlugin);
-    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);
-    if (lazyPlugins) setUniverForLazyLoad(univer);
+    const offMain = !!formula?.worker;
     let cancelled = false;
     let changeTimer = null;
     let changeSub;
     void (async () => {
+      let RPCMainThreadPlugin = null;
+      if (offMain && formula?.worker) {
+        RPCMainThreadPlugin = (await import("@univerjs/rpc")).UniverRPCMainThreadPlugin;
+        if (cancelled) return;
+      }
+      univer.registerPlugin(UniverRenderEnginePlugin);
+      univer.registerPlugin(
+        UniverFormulaEnginePlugin,
+        offMain ? { notExecuteFormula: true } : void 0
+      );
+      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 } : void 0);
+      univer.registerPlugin(UniverSheetsUIPlugin);
+      univer.registerPlugin(
+        UniverSheetsFormulaPlugin,
+        offMain ? { notExecuteFormula: true, initialFormulaComputing: CalculationMode.NO_CALCULATION } : void 0
+      );
+      univer.registerPlugin(UniverSheetsFormulaUIPlugin);
+      univer.registerPlugin(UniverSheetsNumfmtPlugin);
+      univer.registerPlugin(UniverSheetsNumfmtUIPlugin);
+      if (lazyPlugins) setUniverForLazyLoad(univer);
+      onBeforeCreateUnit?.(univer);
       if (lazyPlugins) {
         await eagerLoadForSnapshot(univer, initialData);
         if (cancelled) return;
@@ -304,6 +342,7 @@ function CasualSheets({
       univer.createUnit(UniverInstanceType.UNIVER_SHEET, initialData);
       const api = createCasualSheetsAPI(FUniver.newAPI(univer));
       apiRef.current = api;
+      if (!cancelled && chrome !== "none") setChromeApi(api);
       applyAppearance(api, container, appearance);
       onReady?.(api);
       if (hasOnChange) {
@@ -324,7 +363,12 @@ function CasualSheets({
       cancelled = true;
       if (changeTimer) clearTimeout(changeTimer);
       changeSub?.dispose();
+      if (onExitRef.current) {
+        const snap = apiRef.current?.getSnapshot();
+        if (snap) onExitRef.current(snap);
+      }
       apiRef.current = null;
+      setChromeApi(null);
       if (lazyPlugins) setUniverForLazyLoad(null);
       const toDispose = univer;
       queueMicrotask(() => toDispose.dispose());
@@ -336,13 +380,55 @@ function CasualSheets({
     if (!api || !container) return;
     applyAppearance(api, container, appearance);
   }, [appearance]);
-  return /* @__PURE__ */ jsx(
+  const onKeyDownCapture = (e) => {
+    if ((e.metaKey || e.ctrlKey) && (e.key === "s" || e.key === "S")) {
+      e.preventDefault();
+      const snap = apiRef.current?.getSnapshot();
+      if (snap) onSaveRef.current?.(snap);
+    }
+  };
+  if (chrome === "none") {
+    return /* @__PURE__ */ jsx(
+      "div",
+      {
+        ref: hostRef,
+        onKeyDownCapture,
+        style: { ...DEFAULT_STYLE, ...style },
+        className,
+        "data-testid": testId
+      }
+    );
+  }
+  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"
+  };
+  return /* @__PURE__ */ jsxs(
     "div",
     {
-      ref: hostRef,
-      style: { ...DEFAULT_STYLE, ...style },
       className,
-      "data-testid": testId
+      "data-testid": testId,
+      onKeyDownCapture,
+      style: {
+        ...DEFAULT_STYLE,
+        ...chromeVars,
+        ...style,
+        display: "flex",
+        flexDirection: "column"
+      },
+      children: [
+        /* @__PURE__ */ jsx(Suspense, { fallback: null, children: /* @__PURE__ */ jsx(ChromeTop, { api: chromeApi }) }),
+        /* @__PURE__ */ jsx("div", { ref: hostRef, style: { flex: "1 1 auto", minHeight: 0, position: "relative" } }),
+        /* @__PURE__ */ jsx(Suspense, { fallback: null, children: /* @__PURE__ */ jsx(ChromeBottom, { api: chromeApi }) })
+      ]
     }
   );
 }
@@ -477,6 +563,12 @@ var EmbedHostTransport = class {
         }
         return;
       }
+      case "casual.save.notify":
+        this.handlers.onSaveNotify?.(env.data);
+        return;
+      case "casual.exit":
+        this.handlers.onExit?.(env.data);
+        return;
       case "casual.selection.changed":
         this.handlers.onSelectionChanged?.(env.data);
         return;