@superdoc/sdk 2.19.0-next.9 → 2.19.0

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:
 

package/dist/generated/client.d.ts

@@ -26693,6 +26693,7 @@ export interface DocContentControlsDeleteParams {
             textboxId: string;
         });
     };
+    overrideDeletionLock?: boolean;
 }
 export interface DocContentControlsCopyParams {
     doc?: string;
@@ -149145,6 +149146,7 @@ export interface DocContentControlsDeleteBoundParams {
             textboxId: string;
         });
     };
+    overrideDeletionLock?: boolean;
 }
 export interface DocContentControlsCopyBoundParams {
     out?: string;