@ai-matrx/office 0.0.0 → 0.2.0

package/dist/univer.d.cts

@@ -0,0 +1,320 @@
+import { ICommandInfo, ImageSourceType, ImageUploadStatusType, IDisposable } from '@univerjs/core';
+import * as react from 'react';
+import { SVGAttributes } from 'react';
+import { FUniver } from '@univerjs/presets';
+
+/**
+ * The host ports of the Univer glue.
+ *
+ * The glue belongs to the package, but four things belong to the app that mounts an editor: the
+ * toast path, the signed-in person, the file store and the painted theme. The host states them
+ * once at start-up with `configureUniverHost`; the glue reads them here. State sits on a
+ * `globalThis` slot so a dual-bundled copy of the package still sees one host (dual-bundle rule).
+ * An unconfigured port THROWS naming the port (nothing fails silently).
+ */
+type UniverToastId = string | number;
+type ToastShow = (title: string, options?: {
+    description?: string;
+    duration?: number;
+}) => UniverToastId;
+interface UniverHostPorts {
+    /** The app's toast path (one toaster per page). */
+    toast: {
+        success: ToastShow;
+        info: ToastShow;
+        warning: ToastShow;
+        error: ToastShow;
+        message: ToastShow;
+        dismiss(id: UniverToastId): void;
+    };
+    /** Who is typing, or null when signed out. `metadata` is the auth user's metadata bag. */
+    getSignedInUser(): Promise<{
+        id: string;
+        email?: string | null;
+        metadata?: Record<string, unknown> | null;
+    } | null>;
+    /** The file store behind pictures on a sheet or in a document. */
+    files: {
+        upload(file: File): Promise<{
+            fileId: string;
+        }>;
+        getBlob(fileId: string): Promise<Blob>;
+    };
+    /** Tell the person a picture did not upload. */
+    notifyUploadError(error: unknown): void;
+    /** The painted colour mode, as a React hook (re-renders on a switch). */
+    useThemeMode(): "light" | "dark";
+}
+declare function configureUniverHost(ports: UniverHostPorts): void;
+declare function getUniverHost(): UniverHostPorts;
+
+/**
+ * A document's or a workbook's snapshot history as a canvas tab — the keys and toggle inputs the
+ * editors use, and the reader the two history views use. One tab per document (`document-history`,
+ * keyed by the document id) and per workbook (`workbook-history`, keyed by the workbook id).
+ *
+ * Pure: no React, no canvas package, no Univer. The two `defineCanvasKind` registrations stay with
+ * the host app (matrx-frontend `features/canvas/host`) and lazy-load the views, so this module never
+ * imports a view (the cycle the old `lib/univer/historyKinds.ts` closed).
+ */
+declare const DOCUMENT_HISTORY_KIND = "document-history";
+declare const WORKBOOK_HISTORY_KIND = "workbook-history";
+interface HistoryTabData {
+    id: string;
+    editable: boolean;
+}
+/** Structurally the host's `ToolToggleInput` (the canvas toggle the editor's History button presses). */
+interface HistoryToggleInput {
+    kind: string;
+    key: string;
+    title: string;
+    data: {
+        id: string;
+        editable: boolean;
+    };
+    followTitle: true;
+}
+/** A tab's data as a history subject, or null when it names no subject. */
+declare function readHistoryTab(data: unknown): HistoryTabData | null;
+declare function documentHistoryToggleInput(documentId: string, editable: boolean, documentName?: string | null): HistoryToggleInput;
+declare function workbookHistoryToggleInput(workbookId: string, editable: boolean, workbookName?: string | null): HistoryToggleInput;
+
+/** Univer owns React roots; synchronous dispose during React commit causes races. */
+declare function disposeUniverInstance(instance: {
+    dispose(): void;
+} | null | undefined): void;
+
+type InjectorLike$2 = {
+    get(id: unknown): unknown;
+};
+/**
+ * Tell Univer who is typing, so a comment thread is attributed to the
+ * signed-in person instead of Univer's placeholder owner.
+ *
+ * The userID MUST keep the `Owner_` prefix: Univer's built-in local
+ * permission service grants unit roles by user-id prefix (`isDevRole`), so a
+ * bare uuid gets no role and every edit is refused as "range is protected".
+ * Our own access (canActOn) decides editability; Univer must always see an
+ * owner. Guarded by identify-univer-user-keeps-owner-role.test.ts.
+ */
+declare function identifyUniverUser(injector: InjectorLike$2): Promise<void>;
+/** Univer's local permission service reads the role from this prefix. */
+declare function univerOwnerId(userId: string): string;
+
+/**
+ * isSnapshotMutation — the autosave dirty-filter for the Univer editors.
+ *
+ * D97: `onCommandExecuted` fires for EVERY command — including viewport
+ * scrolls and selection moves — so an unfiltered listener marked the doc
+ * dirty on mere scrolling and wrote a new snapshot row (version history +
+ * collab broadcast) 2.5s later. Only CommandType.MUTATION changes the data
+ * that a snapshot persists (Univer's own docs: OPERATION = "not saved to
+ * snapshot, such as modifying scroll position"). We therefore accept ONLY
+ * mutations, and additionally deny-list any mutation whose id marks it as
+ * scroll / selection / viewport bookkeeping, belt-and-braces.
+ */
+
+declare function isSnapshotMutation(command: ICommandInfo): boolean;
+declare function isWorkbookSnapshotMutation(command: ICommandInfo): boolean;
+
+/**
+ * univerImageStore — images on a sheet or in a document live in OUR file
+ * store; the Univer snapshot holds only a reference (`matrx-file:<fileId>`).
+ *
+ * Why: Univer's stock image service inlines every picture as base64 into the
+ * snapshot, so one 2 MB photo made every autosave, history row and collab
+ * mutation ~2 MB. Here `saveImage` uploads the file and hands Univer a URL-type
+ * source; Univer's URL-image downloader turns the reference back into bytes
+ * (`getBlob` → object URL) when it paints. Images already inline (BASE64
+ * sources) are untouched and keep rendering.
+ */
+
+declare const MATRX_IMAGE_PREFIX = "matrx-file:";
+declare const isMatrxImageSource: (source: string) => boolean;
+declare const matrxImageFileId: (source: string) => string;
+type ImageStorePorts = {
+    upload(file: File): Promise<{
+        fileId: string;
+    }>;
+    getBlob(fileId: string): Promise<Blob>;
+    /** Called when an upload fails, so the person is told (never silent). */
+    onUploadError(error: unknown): void;
+};
+type InjectorLike$1 = {
+    get(id: unknown): unknown;
+};
+/** Pure core: the two replacements, given ports. */
+declare function createMatrxImageStore(ports: ImageStorePorts): {
+    /** Revoke every object URL this store made (the editor is going away). */
+    dispose(): void;
+    saveImage(file: File): Promise<{
+        imageId: string;
+        imageSourceType: ImageSourceType;
+        source: string;
+        base64Cache: string;
+        status: ImageUploadStatusType;
+    }>;
+    download(url: string): Promise<string>;
+};
+/** Release the object URLs of the store wired into this Univer instance (call as the instance is disposed). */
+declare function releaseMatrxImageStore(injector: object | null | undefined): void;
+/** Wire the store into one Univer instance's image services. */
+declare function registerMatrxImageStore(injector: InjectorLike$1, ports: ImageStorePorts): void;
+
+/** The real file-store ports (the host's): upload, read back as a blob, tell the person on failure. */
+declare const matrxImagePorts: ImageStorePorts;
+/** Export: a snapshot picture source (`matrx-file:<id>` or a URL) as bytes + type, or null if unreadable. */
+declare function resolveExportImage(source: string): Promise<{
+    bytes: Uint8Array;
+    extension: "png" | "jpeg" | "gif";
+} | null>;
+/** Import: store a picture from a file, return its file id. */
+declare function uploadImportedImage(bytes: Uint8Array, extension: string): Promise<string>;
+
+/**
+ * THE ONE way to replace the whole content of an open Univer editor
+ * (workbook or document) with a snapshot that is already SAVED: a history
+ * restore, "Update from Google" / "Use Google's", and a collaborator's
+ * replacement all arrive here.
+ *
+ * Callers save first, then call `showSavedSnapshot`. The open editor for that
+ * record (registered below) swaps its content in place, drops its pending
+ * autosave (it would write the old content back over the new one), and — in
+ * a collab room — tells every peer to reload the same snapshot. A caller
+ * never touches Univer units itself: disposing the current unit by hand left
+ * Univer's selection observers pointing at nothing (`getUnitId` of null).
+ *
+ * Pure registry (no Univer import), so it is testable without booting Univer.
+ */
+type EditorRecordKind = "workbook" | "document";
+/** A snapshot row as stored: its id and the Univer body. */
+type SavedEditorSnapshot = {
+    id: string;
+    snapshot: unknown;
+};
+type EditorContentReplacer = (row: SavedEditorSnapshot) => void | Promise<void>;
+/**
+ * The open editor of a record lends its replacer while it is mounted. The
+ * newest registration wins; the returned release only removes its own.
+ */
+declare function registerOpenEditorContent(kind: EditorRecordKind, recordId: string, replace: EditorContentReplacer): () => void;
+/**
+ * Show a saved snapshot in the record's open editor (and its collab peers).
+ * Returns false when no editor of the record is open in this tab — the saved
+ * row then simply is the content the next open loads.
+ */
+declare function showSavedSnapshot(kind: EditorRecordKind, recordId: string, row: SavedEditorSnapshot): Promise<boolean>;
+/**
+ * THE CONTENT-SWAP GUARD. A swap is dispose-then-create; if the create throws, the unit is gone and
+ * the grid would stay blank. `swap(snapshot)` is the editor's own dispose+create (it disposes
+ * whatever unit is open, if any). On a throw this puts the content that was open before straight
+ * back (synchronously — never a blank grid) and says so; the editor then reloads the latest SAVED
+ * version and still raises the original error, so the person is told.
+ */
+declare function swapContentGuarded(args: {
+    swap: (snapshot: unknown) => void;
+    next: unknown;
+    /** What was open before (`workbook.save()` taken before the swap), or null when nothing was. */
+    previous: unknown | null;
+}): {
+    ok: true;
+} | {
+    ok: false;
+    error: unknown;
+    previousRestored: boolean;
+};
+
+interface IIconProps extends SVGAttributes<SVGSVGElement> {
+    /** Preserve scalable stroke widths relative to a 16×16 baseline. */
+    preserveStrokeWidth?: boolean;
+    extend?: IExtendProps;
+}
+interface IExtendProps {
+    colorChannel1?: string;
+}
+
+type InjectorLike = {
+    get(id: unknown): unknown;
+};
+/** Icons Univer's own plugins reference but do not register. */
+declare const MISSING_UNIVER_ICONS: {
+    readonly AddImageIcon: react.ForwardRefExoticComponent<IIconProps & react.RefAttributes<SVGElement>>;
+};
+declare function registerMissingUniverIcons(injector: InjectorLike): void;
+
+type UniverDependency = new (...args: never[]) => unknown;
+type UniverInjector = {
+    has(dependency: UniverDependency): boolean;
+    add(dependency: [UniverDependency]): void;
+};
+/**
+ * Register services required by process-global Univer Facade observers.
+ *
+ * Facade modules can outlive the editor type that first imported them, so a
+ * later Univer instance may receive their lifecycle callbacks without loading
+ * that type's plugins. Registration is intentionally narrow: callers name only
+ * the observer dependencies that are safe for their instance.
+ */
+declare function registerUniverFacadeDependencies(injector: UniverInjector, dependencies: readonly UniverDependency[]): void;
+
+/**
+ * Univer's notifications go through the APP's toast path — one toaster per page.
+ *
+ * Univer's own `DesktopNotificationService` mounts a second sonner `<Toaster>`
+ * into its workbench the moment it is created. sonner's toast store is global,
+ * so with the app's Toaster also mounted every toast (ours and Univer's) showed
+ * twice on a workbook or document page. Replacing the service before anything
+ * resolves it means Univer never mounts that Toaster, and what Univer has to
+ * say (clipboard permission, paste limits) reaches the person through
+ * the host's toast port like every other message (tracked, Error Inspector, Alchemy).
+ *
+ * Call right after `createUniver`, before the first unit is created.
+ */
+
+type UniverNotification = {
+    title: unknown;
+    content?: string;
+    type?: "success" | "info" | "warning" | "error" | "message" | "loading";
+    duration?: number;
+};
+interface NotificationReplaceableInjector {
+    replace?: (dependency: [unknown, unknown]) => void;
+}
+/** Show one Univer notification as an app toast; dismissing the disposable removes it. */
+declare function showUniverNotification(params: UniverNotification): IDisposable;
+declare function routeUniverNotificationsToApp(injector: NotificationReplaceableInjector | null | undefined): {
+    applied: boolean;
+    reason?: string;
+};
+
+/**
+ * Resolve a colour Univer hands its canvas — WITHOUT the dark-mode inversion.
+ *
+ * Univer 1.0 writes many of its own fills as THEME TOKENS, not colours: the
+ * page is `"gray.0"`, the desk `"gray.100"`, the page outline `"gray.200"`,
+ * default ink `"gray.900"` (engine-render 1.0.2 `DocBackground`, docs-ui
+ * `resolveDocRenderBackground`). Its `CanvasColorService` turns a token into a
+ * colour before anything reaches `ctx.fillStyle`; its `DumbCanvasColorService`
+ * does NOT — it returns `"gray.0"` as-is. A canvas IGNORES a `fillStyle` it
+ * cannot parse and keeps the previous one, which starts as `#000000`, so with
+ * the dumb service every page came out solid black and the canvas element's
+ * CSS background (`style.backgroundColor = "gray.100"`, also ignored) stayed
+ * transparent — in every browser, headed or headless, light or dark.
+ *
+ * Pure (no Univer import) so the jest test and `check:univer-doc-theme` drive
+ * the same function the editor installs.
+ */
+/**
+ * @param color  What Univer is about to paint: a theme token or a real colour.
+ * @param lookup The live theme (`ThemeService.getColorFromTheme`).
+ * @returns the token's colour from the current theme; anything else unchanged.
+ */
+declare function resolveUniverCanvasColor(color: string, lookup: (token: string) => unknown): string;
+
+/**
+ * @param apiRef  Ref holding the Univer Facade API (set once the instance boots).
+ * @param ready   True once the instance is booted and the API is usable.
+ */
+declare function useUniverDarkModeSync(apiRef: React.RefObject<FUniver | null>, ready: boolean): void;
+
+export { DOCUMENT_HISTORY_KIND, type EditorContentReplacer, type EditorRecordKind, type HistoryTabData, type HistoryToggleInput, type ImageStorePorts, MATRX_IMAGE_PREFIX, MISSING_UNIVER_ICONS, type NotificationReplaceableInjector, type SavedEditorSnapshot, type UniverHostPorts, type UniverToastId, WORKBOOK_HISTORY_KIND, configureUniverHost, createMatrxImageStore, disposeUniverInstance, documentHistoryToggleInput, getUniverHost, identifyUniverUser, isMatrxImageSource, isSnapshotMutation, isWorkbookSnapshotMutation, matrxImageFileId, matrxImagePorts, readHistoryTab, registerMatrxImageStore, registerMissingUniverIcons, registerOpenEditorContent, registerUniverFacadeDependencies, releaseMatrxImageStore, resolveExportImage, resolveUniverCanvasColor, routeUniverNotificationsToApp, showSavedSnapshot, showUniverNotification, swapContentGuarded, univerOwnerId, uploadImportedImage, useUniverDarkModeSync, workbookHistoryToggleInput };

package/dist/univer.d.ts

@@ -0,0 +1,320 @@
+import { ICommandInfo, ImageSourceType, ImageUploadStatusType, IDisposable } from '@univerjs/core';
+import * as react from 'react';
+import { SVGAttributes } from 'react';
+import { FUniver } from '@univerjs/presets';
+
+/**
+ * The host ports of the Univer glue.
+ *
+ * The glue belongs to the package, but four things belong to the app that mounts an editor: the
+ * toast path, the signed-in person, the file store and the painted theme. The host states them
+ * once at start-up with `configureUniverHost`; the glue reads them here. State sits on a
+ * `globalThis` slot so a dual-bundled copy of the package still sees one host (dual-bundle rule).
+ * An unconfigured port THROWS naming the port (nothing fails silently).
+ */
+type UniverToastId = string | number;
+type ToastShow = (title: string, options?: {
+    description?: string;
+    duration?: number;
+}) => UniverToastId;
+interface UniverHostPorts {
+    /** The app's toast path (one toaster per page). */
+    toast: {
+        success: ToastShow;
+        info: ToastShow;
+        warning: ToastShow;
+        error: ToastShow;
+        message: ToastShow;
+        dismiss(id: UniverToastId): void;
+    };
+    /** Who is typing, or null when signed out. `metadata` is the auth user's metadata bag. */
+    getSignedInUser(): Promise<{
+        id: string;
+        email?: string | null;
+        metadata?: Record<string, unknown> | null;
+    } | null>;
+    /** The file store behind pictures on a sheet or in a document. */
+    files: {
+        upload(file: File): Promise<{
+            fileId: string;
+        }>;
+        getBlob(fileId: string): Promise<Blob>;
+    };
+    /** Tell the person a picture did not upload. */
+    notifyUploadError(error: unknown): void;
+    /** The painted colour mode, as a React hook (re-renders on a switch). */
+    useThemeMode(): "light" | "dark";
+}
+declare function configureUniverHost(ports: UniverHostPorts): void;
+declare function getUniverHost(): UniverHostPorts;
+
+/**
+ * A document's or a workbook's snapshot history as a canvas tab — the keys and toggle inputs the
+ * editors use, and the reader the two history views use. One tab per document (`document-history`,
+ * keyed by the document id) and per workbook (`workbook-history`, keyed by the workbook id).
+ *
+ * Pure: no React, no canvas package, no Univer. The two `defineCanvasKind` registrations stay with
+ * the host app (matrx-frontend `features/canvas/host`) and lazy-load the views, so this module never
+ * imports a view (the cycle the old `lib/univer/historyKinds.ts` closed).
+ */
+declare const DOCUMENT_HISTORY_KIND = "document-history";
+declare const WORKBOOK_HISTORY_KIND = "workbook-history";
+interface HistoryTabData {
+    id: string;
+    editable: boolean;
+}
+/** Structurally the host's `ToolToggleInput` (the canvas toggle the editor's History button presses). */
+interface HistoryToggleInput {
+    kind: string;
+    key: string;
+    title: string;
+    data: {
+        id: string;
+        editable: boolean;
+    };
+    followTitle: true;
+}
+/** A tab's data as a history subject, or null when it names no subject. */
+declare function readHistoryTab(data: unknown): HistoryTabData | null;
+declare function documentHistoryToggleInput(documentId: string, editable: boolean, documentName?: string | null): HistoryToggleInput;
+declare function workbookHistoryToggleInput(workbookId: string, editable: boolean, workbookName?: string | null): HistoryToggleInput;
+
+/** Univer owns React roots; synchronous dispose during React commit causes races. */
+declare function disposeUniverInstance(instance: {
+    dispose(): void;
+} | null | undefined): void;
+
+type InjectorLike$2 = {
+    get(id: unknown): unknown;
+};
+/**
+ * Tell Univer who is typing, so a comment thread is attributed to the
+ * signed-in person instead of Univer's placeholder owner.
+ *
+ * The userID MUST keep the `Owner_` prefix: Univer's built-in local
+ * permission service grants unit roles by user-id prefix (`isDevRole`), so a
+ * bare uuid gets no role and every edit is refused as "range is protected".
+ * Our own access (canActOn) decides editability; Univer must always see an
+ * owner. Guarded by identify-univer-user-keeps-owner-role.test.ts.
+ */
+declare function identifyUniverUser(injector: InjectorLike$2): Promise<void>;
+/** Univer's local permission service reads the role from this prefix. */
+declare function univerOwnerId(userId: string): string;
+
+/**
+ * isSnapshotMutation — the autosave dirty-filter for the Univer editors.
+ *
+ * D97: `onCommandExecuted` fires for EVERY command — including viewport
+ * scrolls and selection moves — so an unfiltered listener marked the doc
+ * dirty on mere scrolling and wrote a new snapshot row (version history +
+ * collab broadcast) 2.5s later. Only CommandType.MUTATION changes the data
+ * that a snapshot persists (Univer's own docs: OPERATION = "not saved to
+ * snapshot, such as modifying scroll position"). We therefore accept ONLY
+ * mutations, and additionally deny-list any mutation whose id marks it as
+ * scroll / selection / viewport bookkeeping, belt-and-braces.
+ */
+
+declare function isSnapshotMutation(command: ICommandInfo): boolean;
+declare function isWorkbookSnapshotMutation(command: ICommandInfo): boolean;
+
+/**
+ * univerImageStore — images on a sheet or in a document live in OUR file
+ * store; the Univer snapshot holds only a reference (`matrx-file:<fileId>`).
+ *
+ * Why: Univer's stock image service inlines every picture as base64 into the
+ * snapshot, so one 2 MB photo made every autosave, history row and collab
+ * mutation ~2 MB. Here `saveImage` uploads the file and hands Univer a URL-type
+ * source; Univer's URL-image downloader turns the reference back into bytes
+ * (`getBlob` → object URL) when it paints. Images already inline (BASE64
+ * sources) are untouched and keep rendering.
+ */
+
+declare const MATRX_IMAGE_PREFIX = "matrx-file:";
+declare const isMatrxImageSource: (source: string) => boolean;
+declare const matrxImageFileId: (source: string) => string;
+type ImageStorePorts = {
+    upload(file: File): Promise<{
+        fileId: string;
+    }>;
+    getBlob(fileId: string): Promise<Blob>;
+    /** Called when an upload fails, so the person is told (never silent). */
+    onUploadError(error: unknown): void;
+};
+type InjectorLike$1 = {
+    get(id: unknown): unknown;
+};
+/** Pure core: the two replacements, given ports. */
+declare function createMatrxImageStore(ports: ImageStorePorts): {
+    /** Revoke every object URL this store made (the editor is going away). */
+    dispose(): void;
+    saveImage(file: File): Promise<{
+        imageId: string;
+        imageSourceType: ImageSourceType;
+        source: string;
+        base64Cache: string;
+        status: ImageUploadStatusType;
+    }>;
+    download(url: string): Promise<string>;
+};
+/** Release the object URLs of the store wired into this Univer instance (call as the instance is disposed). */
+declare function releaseMatrxImageStore(injector: object | null | undefined): void;
+/** Wire the store into one Univer instance's image services. */
+declare function registerMatrxImageStore(injector: InjectorLike$1, ports: ImageStorePorts): void;
+
+/** The real file-store ports (the host's): upload, read back as a blob, tell the person on failure. */
+declare const matrxImagePorts: ImageStorePorts;
+/** Export: a snapshot picture source (`matrx-file:<id>` or a URL) as bytes + type, or null if unreadable. */
+declare function resolveExportImage(source: string): Promise<{
+    bytes: Uint8Array;
+    extension: "png" | "jpeg" | "gif";
+} | null>;
+/** Import: store a picture from a file, return its file id. */
+declare function uploadImportedImage(bytes: Uint8Array, extension: string): Promise<string>;
+
+/**
+ * THE ONE way to replace the whole content of an open Univer editor
+ * (workbook or document) with a snapshot that is already SAVED: a history
+ * restore, "Update from Google" / "Use Google's", and a collaborator's
+ * replacement all arrive here.
+ *
+ * Callers save first, then call `showSavedSnapshot`. The open editor for that
+ * record (registered below) swaps its content in place, drops its pending
+ * autosave (it would write the old content back over the new one), and — in
+ * a collab room — tells every peer to reload the same snapshot. A caller
+ * never touches Univer units itself: disposing the current unit by hand left
+ * Univer's selection observers pointing at nothing (`getUnitId` of null).
+ *
+ * Pure registry (no Univer import), so it is testable without booting Univer.
+ */
+type EditorRecordKind = "workbook" | "document";
+/** A snapshot row as stored: its id and the Univer body. */
+type SavedEditorSnapshot = {
+    id: string;
+    snapshot: unknown;
+};
+type EditorContentReplacer = (row: SavedEditorSnapshot) => void | Promise<void>;
+/**
+ * The open editor of a record lends its replacer while it is mounted. The
+ * newest registration wins; the returned release only removes its own.
+ */
+declare function registerOpenEditorContent(kind: EditorRecordKind, recordId: string, replace: EditorContentReplacer): () => void;
+/**
+ * Show a saved snapshot in the record's open editor (and its collab peers).
+ * Returns false when no editor of the record is open in this tab — the saved
+ * row then simply is the content the next open loads.
+ */
+declare function showSavedSnapshot(kind: EditorRecordKind, recordId: string, row: SavedEditorSnapshot): Promise<boolean>;
+/**
+ * THE CONTENT-SWAP GUARD. A swap is dispose-then-create; if the create throws, the unit is gone and
+ * the grid would stay blank. `swap(snapshot)` is the editor's own dispose+create (it disposes
+ * whatever unit is open, if any). On a throw this puts the content that was open before straight
+ * back (synchronously — never a blank grid) and says so; the editor then reloads the latest SAVED
+ * version and still raises the original error, so the person is told.
+ */
+declare function swapContentGuarded(args: {
+    swap: (snapshot: unknown) => void;
+    next: unknown;
+    /** What was open before (`workbook.save()` taken before the swap), or null when nothing was. */
+    previous: unknown | null;
+}): {
+    ok: true;
+} | {
+    ok: false;
+    error: unknown;
+    previousRestored: boolean;
+};
+
+interface IIconProps extends SVGAttributes<SVGSVGElement> {
+    /** Preserve scalable stroke widths relative to a 16×16 baseline. */
+    preserveStrokeWidth?: boolean;
+    extend?: IExtendProps;
+}
+interface IExtendProps {
+    colorChannel1?: string;
+}
+
+type InjectorLike = {
+    get(id: unknown): unknown;
+};
+/** Icons Univer's own plugins reference but do not register. */
+declare const MISSING_UNIVER_ICONS: {
+    readonly AddImageIcon: react.ForwardRefExoticComponent<IIconProps & react.RefAttributes<SVGElement>>;
+};
+declare function registerMissingUniverIcons(injector: InjectorLike): void;
+
+type UniverDependency = new (...args: never[]) => unknown;
+type UniverInjector = {
+    has(dependency: UniverDependency): boolean;
+    add(dependency: [UniverDependency]): void;
+};
+/**
+ * Register services required by process-global Univer Facade observers.
+ *
+ * Facade modules can outlive the editor type that first imported them, so a
+ * later Univer instance may receive their lifecycle callbacks without loading
+ * that type's plugins. Registration is intentionally narrow: callers name only
+ * the observer dependencies that are safe for their instance.
+ */
+declare function registerUniverFacadeDependencies(injector: UniverInjector, dependencies: readonly UniverDependency[]): void;
+
+/**
+ * Univer's notifications go through the APP's toast path — one toaster per page.
+ *
+ * Univer's own `DesktopNotificationService` mounts a second sonner `<Toaster>`
+ * into its workbench the moment it is created. sonner's toast store is global,
+ * so with the app's Toaster also mounted every toast (ours and Univer's) showed
+ * twice on a workbook or document page. Replacing the service before anything
+ * resolves it means Univer never mounts that Toaster, and what Univer has to
+ * say (clipboard permission, paste limits) reaches the person through
+ * the host's toast port like every other message (tracked, Error Inspector, Alchemy).
+ *
+ * Call right after `createUniver`, before the first unit is created.
+ */
+
+type UniverNotification = {
+    title: unknown;
+    content?: string;
+    type?: "success" | "info" | "warning" | "error" | "message" | "loading";
+    duration?: number;
+};
+interface NotificationReplaceableInjector {
+    replace?: (dependency: [unknown, unknown]) => void;
+}
+/** Show one Univer notification as an app toast; dismissing the disposable removes it. */
+declare function showUniverNotification(params: UniverNotification): IDisposable;
+declare function routeUniverNotificationsToApp(injector: NotificationReplaceableInjector | null | undefined): {
+    applied: boolean;
+    reason?: string;
+};
+
+/**
+ * Resolve a colour Univer hands its canvas — WITHOUT the dark-mode inversion.
+ *
+ * Univer 1.0 writes many of its own fills as THEME TOKENS, not colours: the
+ * page is `"gray.0"`, the desk `"gray.100"`, the page outline `"gray.200"`,
+ * default ink `"gray.900"` (engine-render 1.0.2 `DocBackground`, docs-ui
+ * `resolveDocRenderBackground`). Its `CanvasColorService` turns a token into a
+ * colour before anything reaches `ctx.fillStyle`; its `DumbCanvasColorService`
+ * does NOT — it returns `"gray.0"` as-is. A canvas IGNORES a `fillStyle` it
+ * cannot parse and keeps the previous one, which starts as `#000000`, so with
+ * the dumb service every page came out solid black and the canvas element's
+ * CSS background (`style.backgroundColor = "gray.100"`, also ignored) stayed
+ * transparent — in every browser, headed or headless, light or dark.
+ *
+ * Pure (no Univer import) so the jest test and `check:univer-doc-theme` drive
+ * the same function the editor installs.
+ */
+/**
+ * @param color  What Univer is about to paint: a theme token or a real colour.
+ * @param lookup The live theme (`ThemeService.getColorFromTheme`).
+ * @returns the token's colour from the current theme; anything else unchanged.
+ */
+declare function resolveUniverCanvasColor(color: string, lookup: (token: string) => unknown): string;
+
+/**
+ * @param apiRef  Ref holding the Univer Facade API (set once the instance boots).
+ * @param ready   True once the instance is booted and the API is usable.
+ */
+declare function useUniverDarkModeSync(apiRef: React.RefObject<FUniver | null>, ready: boolean): void;
+
+export { DOCUMENT_HISTORY_KIND, type EditorContentReplacer, type EditorRecordKind, type HistoryTabData, type HistoryToggleInput, type ImageStorePorts, MATRX_IMAGE_PREFIX, MISSING_UNIVER_ICONS, type NotificationReplaceableInjector, type SavedEditorSnapshot, type UniverHostPorts, type UniverToastId, WORKBOOK_HISTORY_KIND, configureUniverHost, createMatrxImageStore, disposeUniverInstance, documentHistoryToggleInput, getUniverHost, identifyUniverUser, isMatrxImageSource, isSnapshotMutation, isWorkbookSnapshotMutation, matrxImageFileId, matrxImagePorts, readHistoryTab, registerMatrxImageStore, registerMissingUniverIcons, registerOpenEditorContent, registerUniverFacadeDependencies, releaseMatrxImageStore, resolveExportImage, resolveUniverCanvasColor, routeUniverNotificationsToApp, showSavedSnapshot, showUniverNotification, swapContentGuarded, univerOwnerId, uploadImportedImage, useUniverDarkModeSync, workbookHistoryToggleInput };