@superdoc/sdk 2.19.0-next.2 → 2.19.0-next.20

package/README.md

@@ -37,6 +37,42 @@ room sync on every call. To cut round trips further, batch related edits with
 `document.mutations.apply()` or arbitrary operations with
 `document.plan.execute()`.
 
+For read-only hosts and containers, configure a writable state directory:
+
+```js
+const client = new SuperDocClient({ stateDir: '/tmp/superdoc-state' });
+```
+
+`stateDir` takes precedence over `SUPERDOC_CLI_STATE_DIR` in the client's child
+environment. Configured directories remain after disposal. Without either
+setting, the SDK keeps the usual home directory state when it is usable;
+otherwise it allocates a private directory in the child environment's temporary
+location. `connect()` (including lazy connection on `open()`) checks that state
+can be written and throws `SuperDocCliError` with code
+`STATE_DIRECTORY_UNWRITABLE` and path details if it cannot. An invalid explicit
+setting never silently falls back.
+
+The home default is `~/.superdoc-cli/state/v1`. Each open document uses
+`<state root>/contexts/<context ID>/`, where the root is the default,
+configured `stateDir`, environment override, or SDK-owned temporary directory.
+The context contains `metadata.json`, an `original.docx` input copy, a
+`working.docx` checkpoint copy, and the host's `owner` file; operations can also
+create a temporary `lock` file. Budget writable storage for both DOCX copies.
+State does not need to live in the working directory, which can be read-only.
+Temporary fallback uses the child's `TMPDIR` (or `TMP`/`TEMP`) on Unix; that
+location must be writable. A configured state directory needs writable storage
+even when the temporary directory is read-only. Save destinations must also be
+writable; choose an explicit output path outside a read-only working directory.
+
+`close()` removes that document's context. `dispose()` removes only an
+SDK-allocated temporary root, after active operations finish and the host has
+stopped. State remains when disposal fails. If the host exits unsuccessfully, disposal
+throws `HOST_SHUTDOWN_FAILED` with the retained path in `details`; that client
+remains failed, and the retained files are available for recovery. Killing
+the SDK parent can leave temporary state behind; the operating system or host
+operator must reclaim it. A new client gets a separate private root and does
+not sweep another client's state.
+
 For token-authenticated Hocuspocus or y-websocket rooms, pass the credential as
 an option on that document's open request:
 
@@ -96,6 +132,26 @@ if (matches.total === 1) {
 }
 ```
 
+## Tracked comparison with direct style definitions
+
+For standalone V2 comparisons, `styleChangeMode: 'direct'` lets you explicitly
+carry the target style definitions while applying body edits as tracked changes:
+
+```js
+const diff = await older.diff.compare({ targetSnapshot, styleChangeMode: 'direct' });
+const result = await older.diff.apply({ diff, changeMode: 'tracked', styleChangeMode: 'direct' });
+console.log(result.styleChanges); // { changeMode: 'direct', partUris: [...] }, when styles changed
+await older.save({ out: 'comparison.docx' });
+```
+
+Set the policy on both calls: compare reports eligibility for that policy;
+apply requires its own explicit consent. Style definitions are applied directly
+and remain if the body revisions are rejected in Word. A style-only comparison
+creates no body revisions. Without this option, changed style definitions still
+block tracked apply. Unsupported numbering, settings, and other package changes
+retain their existing restrictions. Suggest-only versioned review sessions
+refuse this direct-style option.
+
 ## Tracked comparison with exact-file review
 
 The SDK's `diff.capture` and `diff.compare` describe a snapshot comparison. A

package/dist/generated/client.d.ts

@@ -26693,6 +26693,7 @@ export interface DocContentControlsDeleteParams {
             textboxId: string;
         });
     };
+    overrideDeletionLock?: boolean;
 }
 export interface DocContentControlsCopyParams {
     doc?: string;
@@ -30733,6 +30734,7 @@ export interface DocDiffCompareParams {
         };
         payload: Record<string, unknown>;
     };
+    styleChangeMode?: string;
 }
 export interface DocDiffApplyParams {
     doc?: string;
@@ -30801,6 +30803,7 @@ export interface DocDiffApplyParams {
         }>;
         payload: Record<string, unknown>;
     };
+    styleChangeMode?: string;
 }
 export interface DocExportToDocxParams {
     doc?: string;
@@ -103374,6 +103377,55 @@ export type DocSelectionCurrentResult = {
         });
         coordinateSpace?: "visible" | "tracked";
     }) | null;
+    tableSelection?: ({
+        kind: "tableCells";
+        type: "table" | "cell" | "cells";
+        tableId: string;
+        story?: ({
+            kind: "story";
+            storyType: "body";
+        }) | ({
+            kind: "story";
+            storyType: "headerFooterSlot";
+            section: {
+                kind: "section";
+                sectionId: string;
+            };
+            headerFooterKind: "header" | "footer";
+            variant: "default" | "first" | "even";
+            resolution?: "effective" | "explicit";
+            onWrite?: "materializeIfInherited" | "editResolvedPart" | "error";
+        }) | ({
+            kind: "story";
+            storyType: "headerFooterPart";
+            refId: string;
+        }) | ({
+            kind: "story";
+            storyType: "footnote";
+            noteId: string;
+        }) | ({
+            kind: "story";
+            storyType: "endnote";
+            noteId: string;
+        }) | ({
+            kind: "story";
+            storyType: "textbox";
+            textboxId: string;
+        });
+        start: {
+            rowIndex: number;
+            columnIndex: number;
+        };
+        end: {
+            rowIndex: number;
+            columnIndex: number;
+        };
+        cells: Array<{
+            nodeId: string;
+            rowIndex: number;
+            columnIndex: number;
+        }>;
+    }) | null;
     activeMarks: Array<string>;
     activeCommentIds: Array<string>;
     activeChangeIds: Array<string>;
@@ -122818,6 +122870,10 @@ export type DocDiffCompareResult = {
 };
 export type DocDiffApplyResult = {
     appliedOperations: number;
+    styleChanges?: {
+        changeMode: "direct";
+        partUris: Array<string>;
+    };
     operationReceipts: Array<({
         operationId: string;
         disposition: "review-created";
@@ -149090,6 +149146,7 @@ export interface DocContentControlsDeleteBoundParams {
             textboxId: string;
         });
     };
+    overrideDeletionLock?: boolean;
 }
 export interface DocContentControlsCopyBoundParams {
     out?: string;
@@ -152904,6 +152961,7 @@ export interface DocDiffCompareBoundParams {
         };
         payload: Record<string, unknown>;
     };
+    styleChangeMode?: string;
 }
 export interface DocDiffApplyBoundParams {
     out?: string;
@@ -152970,6 +153028,7 @@ export interface DocDiffApplyBoundParams {
         }>;
         payload: Record<string, unknown>;
     };
+    styleChangeMode?: string;
 }
 export interface DocExportToDocxBoundParams {
     mode?: string;