superdoc 2.2.0 → 2.3.0

package/dist/superdoc/src/internal/toolbar/image-upload.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Whether a picked/dropped file is an insertable image (PNG/JPEG). Falls back
+ * to the file extension when the browser reports no MIME type.
+ * @param {File | null | undefined} file
+ * @returns {boolean}
+ */
+export function isSupportedImageFile(file: File | null | undefined): boolean;
+/**
+ * Read a File/Blob into a base64 data URI.
+ *
+ * Some browsers/OSes deliver picked files with an empty `type`; the picker
+ * accepts those by extension, but `readAsDataURL` would then produce an
+ * `application/octet-stream` data URI that `create.image` rejects. Rewrite
+ * the media type from the filename so extension-accepted files still insert.
+ * @param {Blob & { name?: string }} file
+ * @returns {Promise<string>}
+ */
+export function fileToDataUri(file: Blob & {
+    name?: string;
+}): Promise<string>;
+/**
+ * Resolve the `create.image` src for a picked file. Uses the consumer's
+ * `handleImageUpload` callback when configured (V1 contract:
+ * `(file: File) => Promise<string>`). A returned non-data URL is fetched and
+ * embedded, because `create.image` requires an embedded base64 data URI.
+ * @param {File} file
+ * @param {((file: File) => Promise<string>) | null | undefined} handleImageUpload
+ * @returns {Promise<string>}
+ */
+export function resolveImageSrc(file: File, handleImageUpload: ((file: File) => Promise<string>) | null | undefined): Promise<string>;
+/**
+ * Hidden `<input type=file>` picker bound to one toolbar instance. The input
+ * stays attached (hidden) so automation and tests can drive it; `destroy()`
+ * removes it. Picking a file calls `onPick(file)`; an unsupported type or a
+ * failed pick routes through `onError(error)`.
+ *
+ * @param {{
+ *   ownerDocument?: Document,
+ *   onPick?: (file: File) => unknown,
+ *   onError?: (error: Error) => void,
+ * }} options
+ * @returns {{ input: HTMLInputElement, open: () => void, destroy: () => void }}
+ */
+export function createImageFilePicker({ ownerDocument, onPick, onError }?: {
+    ownerDocument?: Document;
+    onPick?: (file: File) => unknown;
+    onError?: (error: Error) => void;
+}): {
+    input: HTMLInputElement;
+    open: () => void;
+    destroy: () => void;
+};
+/**
+ * Interactive image acquisition for the built-in toolbar (SD-3567).
+ *
+ * The toolbar image button routes through the shared controller command
+ * `image` → `create.image`, which requires a base64 PNG/JPEG data-URI `src`.
+ * This module owns the browser file picker and the File → data-URI
+ * conversion; the toolbar dispatches the resulting payload through the
+ * normal controller command path.
+ */
+/** Accept filter for the picker: PNG and JPEG only (V1 parity; OOXML-native formats). */
+export const IMAGE_PICKER_ACCEPT: ".png,.jpg,.jpeg,image/png,image/jpeg";

package/dist/superdoc/src/internal/toolbar/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Internal built-in toolbar surface for the V2 `superdoc` package.
+ *
+ * Internal only — these symbols are NOT part of any public package export and
+ * must not be re-exported from `src/public/*`. The compatibility catalog is the
+ * single legacy-name map; the rendered shell is the single non-`null`
+ * `superdoc.toolbar` handle that projects the V2 command controller.
+ */
+export { BUILT_IN_TOOLBAR_CATALOG, ALL_BUILT_IN_TOOLBAR_ITEM_NAMES, getBuiltInToolbarItem, listBuiltInToolbarItemsByGroup, resolveToolbarCommandId, assertCatalogAlignedWithController, type BuiltInToolbarItemEntry, type ToolbarGroup, type ToolbarItemDisposition, } from './compatibility-catalog.js';
+export { createBuiltInToolbar, BuiltInToolbar } from './built-in-toolbar.js';

package/dist/superdoc/src/main.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/superdoc/src/public/browser-document-api.d.ts

@@ -0,0 +1,53 @@
+import { DocumentApi } from '../../../document-api/src/index.js';
+type MaybePromise<T> = T | Promise<T>;
+type BrowserDocumentApiObject<T> = {
+    [K in keyof T]: BrowserDocumentApiValue<T[K]>;
+};
+type BrowserDocumentApiValue<T> = T extends (...args: infer Args) => infer Return ? ((...args: Args) => MaybePromise<Awaited<Return>>) & BrowserDocumentApiObject<T> : T extends object ? BrowserDocumentApiObject<T> : T;
+/**
+ * Browser V2 active-editor Document API facade (`superdoc.activeEditor.doc`).
+ * In the browser this surface is intentionally async-capable: callers must
+ * tolerate promise-returning reads/writes, including the default
+ * worker-backed runtime. SDK/headless callers should continue using the
+ * synchronous `@superdoc/document-api` surface directly.
+ */
+export type BrowserDocumentApi = BrowserDocumentApiObject<DocumentApi>;
+/**
+ * Every operation optional, at any depth.
+ *
+ * A callable member keeps its call signature *and* its properties, mirroring
+ * what {@link BrowserDocumentApiValue} does. Parts of the Document API are both:
+ * `capabilities` is callable and carries `get()`, so reconstructing only the call
+ * signature would make `doc.capabilities.get()` a type error on a value that
+ * supports it at runtime.
+ *
+ * Intersected rather than unioned with the property bag. A union would let a
+ * non-callable object stand in for a callable member, which also makes the
+ * member type unenforceable: `{ comments: { list: 42 } }` satisfies a
+ * props-only alternative and the type stops catching wrong operations at all.
+ */
+type DeepPartial<T> = T extends (...args: infer Args) => infer Return ? ((...args: Args) => Return) & {
+    [K in keyof T]?: DeepPartial<T[K]>;
+} : T extends object ? {
+    [K in keyof T]?: DeepPartial<T[K]>;
+} : T;
+/**
+ * What a *host* may supply as `activeEditor.doc`.
+ *
+ * A host is duck-typed: a custom adapter or a test stub is expected to carry
+ * only the operations it actually implements, and the controller resolves
+ * operations defensively at runtime rather than assuming any of them exist.
+ * Requiring the whole surface here would reject exactly the partial hosts the
+ * contract is documented to accept.
+ *
+ * `CustomCommandContext.doc` uses this same partial type, because that value is
+ * the host's own object passed straight through. It can promise no more than the
+ * host contract does. {@link BrowserDocumentApi}, the complete facade, is the
+ * type of `activeEditor.doc` on a real `Editor`.
+ *
+ * Partial, not permissive: the operations a host does declare are still
+ * checked, so a typo or a wrong member type fails instead of passing as
+ * `any`.
+ */
+export type PartialBrowserDocumentApi = DeepPartial<BrowserDocumentApi>;
+export {};

package/dist/superdoc/src/public/collaboration-upgrade-engine.d.cts

@@ -0,0 +1,26 @@
+// Generated by scripts/ensure-types.cjs. Do not edit by hand.
+import type { BuildV2CollaborationUpgradeArtifactFromBundleInput as __Cjs_BuildV2CollaborationUpgradeArtifactFromBundleInput } from './collaboration-upgrade-engine.js' with { "resolution-mode": "import" };
+import type { CollaborationUpgradeEngineInfo as __Cjs_CollaborationUpgradeEngineInfo } from './collaboration-upgrade-engine.js' with { "resolution-mode": "import" };
+import type { CompleteV2CollaborationUpgradeArtifact as __Cjs_CompleteV2CollaborationUpgradeArtifact } from './collaboration-upgrade-engine.js' with { "resolution-mode": "import" };
+import type { UpgradeBundleLimits as __Cjs_UpgradeBundleLimits } from './collaboration-upgrade-engine.js' with { "resolution-mode": "import" };
+import type { V2CollaborationUpgradeTargetValidation as __Cjs_V2CollaborationUpgradeTargetValidation } from './collaboration-upgrade-engine.js' with { "resolution-mode": "import" };
+import type { V2UpgradeArtifactLimits as __Cjs_V2UpgradeArtifactLimits } from './collaboration-upgrade-engine.js' with { "resolution-mode": "import" };
+import type { V2UpgradeOfflineValidation as __Cjs_V2UpgradeOfflineValidation } from './collaboration-upgrade-engine.js' with { "resolution-mode": "import" };
+import type { V2UpgradePackageComparison as __Cjs_V2UpgradePackageComparison } from './collaboration-upgrade-engine.js' with { "resolution-mode": "import" };
+import type { ValidateV2CollaborationUpgradeTargetInput as __Cjs_ValidateV2CollaborationUpgradeTargetInput } from './collaboration-upgrade-engine.js' with { "resolution-mode": "import" };
+export declare const buildV2CollaborationUpgradeArtifactFromBundle: typeof import('./collaboration-upgrade-engine.js', { with: { "resolution-mode": "import" } }).buildV2CollaborationUpgradeArtifactFromBundle;
+export type { __Cjs_BuildV2CollaborationUpgradeArtifactFromBundleInput as BuildV2CollaborationUpgradeArtifactFromBundleInput };
+export declare const COLLABORATION_UPGRADE_ENGINE_MINIMUM_NODE_MAJOR: typeof import('./collaboration-upgrade-engine.js', { with: { "resolution-mode": "import" } }).COLLABORATION_UPGRADE_ENGINE_MINIMUM_NODE_MAJOR;
+export declare const COLLABORATION_UPGRADE_ENGINE_PROTOCOL_VERSION: typeof import('./collaboration-upgrade-engine.js', { with: { "resolution-mode": "import" } }).COLLABORATION_UPGRADE_ENGINE_PROTOCOL_VERSION;
+export type { __Cjs_CollaborationUpgradeEngineInfo as CollaborationUpgradeEngineInfo };
+export type { __Cjs_CompleteV2CollaborationUpgradeArtifact as CompleteV2CollaborationUpgradeArtifact };
+export declare const getCollaborationUpgradeEngineInfo: typeof import('./collaboration-upgrade-engine.js', { with: { "resolution-mode": "import" } }).getCollaborationUpgradeEngineInfo;
+export declare const SUPPORTED_COLLABORATION_UPGRADE_BUNDLE_VERSIONS: typeof import('./collaboration-upgrade-engine.js', { with: { "resolution-mode": "import" } }).SUPPORTED_COLLABORATION_UPGRADE_BUNDLE_VERSIONS;
+export declare const SUPPORTED_V1_READER_CONTRACT_VERSIONS: typeof import('./collaboration-upgrade-engine.js', { with: { "resolution-mode": "import" } }).SUPPORTED_V1_READER_CONTRACT_VERSIONS;
+export type { __Cjs_UpgradeBundleLimits as UpgradeBundleLimits };
+export type { __Cjs_V2CollaborationUpgradeTargetValidation as V2CollaborationUpgradeTargetValidation };
+export type { __Cjs_V2UpgradeArtifactLimits as V2UpgradeArtifactLimits };
+export type { __Cjs_V2UpgradeOfflineValidation as V2UpgradeOfflineValidation };
+export type { __Cjs_V2UpgradePackageComparison as V2UpgradePackageComparison };
+export declare const validateV2CollaborationUpgradeTarget: typeof import('./collaboration-upgrade-engine.js', { with: { "resolution-mode": "import" } }).validateV2CollaborationUpgradeTarget;
+export type { __Cjs_ValidateV2CollaborationUpgradeTargetInput as ValidateV2CollaborationUpgradeTargetInput };

package/dist/superdoc/src/public/collaboration-upgrade-engine.d.ts

@@ -0,0 +1,130 @@
+/**
+ * SuperDoc public facade: `superdoc/collaboration-upgrade-engine`.
+ *
+ * This is a Node-only bridge used by the public v2 collaboration upgrade package.
+ * It deliberately exposes data-only inputs and outputs: no live Y.Doc, editor,
+ * provider, browser, UI, or private workspace type crosses this boundary.
+ */
+/** Compatibility protocol between the upgrade package and installed SuperDoc. */
+export declare const COLLABORATION_UPGRADE_ENGINE_PROTOCOL_VERSION: 1;
+/** Recovery-bundle versions accepted by this engine. */
+export declare const SUPPORTED_COLLABORATION_UPGRADE_BUNDLE_VERSIONS: readonly [1];
+/** Frozen final-v1 reader contracts accepted by this engine. */
+export declare const SUPPORTED_V1_READER_CONTRACT_VERSIONS: readonly [1];
+/** Minimum supported Node.js major version. */
+export declare const COLLABORATION_UPGRADE_ENGINE_MINIMUM_NODE_MAJOR: 20;
+/** Runtime compatibility metadata checked before any provider I/O. */
+export interface CollaborationUpgradeEngineInfo {
+    readonly engine: 'superdoc-v2-collaboration-upgrade';
+    readonly protocolVersion: typeof COLLABORATION_UPGRADE_ENGINE_PROTOCOL_VERSION;
+    readonly superdocVersion: string;
+    readonly roomSchemaVersion: Readonly<{
+        readonly major: number;
+        readonly minor: number;
+    }>;
+    readonly artifactVersion: 1;
+    readonly supportedBundleVersions: readonly [1];
+    readonly supportedV1ReaderContractVersions: readonly [1];
+    readonly minimumNodeMajor: typeof COLLABORATION_UPGRADE_ENGINE_MINIMUM_NODE_MAJOR;
+}
+/** Limits applied while inspecting a recovery bundle. */
+export interface UpgradeBundleLimits {
+    readonly maxBundleBytes?: number;
+    readonly maxEntryCount?: number;
+    readonly maxEntryBytes?: number;
+    readonly maxTotalUncompressedBytes?: number;
+    readonly maxCompressionRatio?: number;
+    readonly maxManifestBytes?: number;
+}
+/** Limits applied while building a self-contained v2 update. */
+export interface V2UpgradeArtifactLimits {
+    readonly maxCarrierDocxBytes?: number;
+    readonly maxEncodedUpdateBytes?: number;
+    readonly maxContentUnits?: number;
+}
+/** Package-fidelity comparison produced by a fresh v2 reopen. */
+export interface V2UpgradePackageComparison {
+    readonly equal: boolean;
+    readonly expectedPartCount: number;
+    readonly actualPartCount: number;
+    readonly missingParts: ReadonlyArray<string>;
+    readonly unexpectedParts: ReadonlyArray<string>;
+    readonly changedParts: ReadonlyArray<string>;
+    readonly semanticChangedParts: ReadonlyArray<string>;
+    readonly protectedChangedParts: ReadonlyArray<string>;
+}
+/** Offline proof generated together with a v2 target update. */
+export interface V2UpgradeOfflineValidation {
+    readonly ok: true;
+    readonly binaryMode: 'inline';
+    readonly classification: 'v2-committed';
+    readonly contentDigest: string;
+    readonly contentUnitCount: number;
+    readonly rebuiltUpdateSha256: string;
+    readonly builderExportSha256: string;
+    readonly freshExportSha256: string;
+    readonly carrierToFreshPackage: V2UpgradePackageComparison;
+    readonly builderToFreshPackage: V2UpgradePackageComparison;
+}
+/** Complete provider-free v2 target produced from a validated recovery bundle. */
+export interface CompleteV2CollaborationUpgradeArtifact {
+    readonly schemaVersion: 1;
+    readonly migrationId: string;
+    readonly targetRootId: string;
+    readonly providerRoomName: string;
+    readonly sourceCarrierSha256: string;
+    readonly normalizedCarrierSha256: string;
+    readonly updateSha256: string;
+    readonly updateByteLength: number;
+    /** A defensive copy is returned by the underlying artifact. */
+    readonly update: Uint8Array;
+    readonly contentDigest: string;
+    readonly contentUnitIds: ReadonlyArray<string>;
+    readonly validation: V2UpgradeOfflineValidation;
+}
+/** Input for constructing a self-contained v2 target from a v1 recovery bundle. */
+export interface BuildV2CollaborationUpgradeArtifactFromBundleInput {
+    readonly bundle: Uint8Array;
+    readonly expectedBundleSha256?: string;
+    readonly targetRootId: string;
+    readonly migrationToolVersion: string;
+    readonly filename?: string | null;
+    readonly bundleLimits?: UpgradeBundleLimits;
+    readonly artifactLimits?: V2UpgradeArtifactLimits;
+}
+/** Input for validating target bytes read back through a fresh provider client. */
+export interface ValidateV2CollaborationUpgradeTargetInput {
+    readonly bundle: Uint8Array;
+    readonly expectedBundleSha256?: string;
+    readonly bundleLimits?: UpgradeBundleLimits;
+    readonly update: Uint8Array;
+    readonly targetRootId: string;
+    readonly expectedUpdateSha256: string;
+    readonly expectedContentDigest: string;
+    readonly migrationToolVersion: string;
+    /** Optional unrelated DOCX shell proving the update is self-contained. */
+    readonly reopenBuffer?: Uint8Array;
+}
+/** Fresh-client validation result for bytes read back from target persistence. */
+export interface V2CollaborationUpgradeTargetValidation {
+    readonly ok: true;
+    readonly updateSha256: string;
+    readonly contentDigest: string;
+    readonly freshExportSha256: string;
+    readonly carrierToFreshPackage: V2UpgradePackageComparison;
+}
+/** Return immutable metadata used to reject incompatible engines preflight. */
+export declare function getCollaborationUpgradeEngineInfo(): CollaborationUpgradeEngineInfo;
+/**
+ * Build and offline-validate one self-contained v2 collaboration update.
+ *
+ * This function performs no provider I/O and never mutates the v1 source room.
+ */
+export declare function buildV2CollaborationUpgradeArtifactFromBundle(input: BuildV2CollaborationUpgradeArtifactFromBundleInput): Promise<CompleteV2CollaborationUpgradeArtifact>;
+/**
+ * Validate target bytes after a provider reads them through a fresh client.
+ *
+ * Provenance and carrier bytes are derived from the authenticated recovery
+ * bundle rather than accepted as independent caller assertions.
+ */
+export declare function validateV2CollaborationUpgradeTarget(input: ValidateV2CollaborationUpgradeTargetInput): Promise<V2CollaborationUpgradeTargetValidation>;