@superdoc/sdk 2.5.0 → 2.7.0

package/dist/runtime/document-rpc.js

@@ -0,0 +1,312 @@
+import { randomUUID } from 'node:crypto';
+import { SuperDocCliError } from './errors.js';
+import { applyOperationParamAliases, } from './transport-common.js';
+export const DOCUMENT_RPC_FEATURES = ['document.open', 'document.invoke', 'document.save', 'document.close'];
+export const DOCUMENT_RPC_DEFAULT_CHANGE_MODE_FEATURE = 'document.open.defaultChangeMode';
+export const DOCUMENT_RPC_SOURCE_SAVE_FEATURE = 'document.save.source';
+export const DOCUMENT_RPC_REQUEST_TIMEOUT_FEATURE = 'host.request.timeoutMs';
+const DOCUMENT_RPC_OPEN_FIELDS = new Set(['doc', 'sessionId', 'runtime']);
+const DOCUMENT_RPC_SAVE_FIELDS = new Set(['sessionId', 'out', 'force', 'mode', 'inPlace']);
+const DOCUMENT_API_OPTION_FIELDS = new Set(['expectedRevision', 'changeMode', 'dryRun', 'supportCheck']);
+const DOCUMENT_API_REVISION_PREFLIGHT_OPERATIONS = new Set([
+    'doc.history.redo',
+    'doc.history.undo',
+    'doc.plan.execute',
+]);
+function unsupported(message, operationId) {
+    return new SuperDocCliError(message, {
+        code: 'DOCUMENT_RPC_INPUT_UNSUPPORTED',
+        ...(operationId === undefined ? {} : { details: { operationId } }),
+    });
+}
+function buildDocumentAuthor(user) {
+    if (user === undefined)
+        return undefined;
+    if (typeof user !== 'object' || user === null || Array.isArray(user)) {
+        throw new SuperDocCliError('user must be an object with a non-empty name.', {
+            code: 'INVALID_ARGUMENT',
+        });
+    }
+    const record = user;
+    if (typeof record.name !== 'string' || record.name.trim().length === 0) {
+        throw new SuperDocCliError('user.name must be a non-empty string.', {
+            code: 'INVALID_ARGUMENT',
+        });
+    }
+    if (record.email !== undefined && typeof record.email !== 'string') {
+        throw new SuperDocCliError('user.email must be a string.', {
+            code: 'INVALID_ARGUMENT',
+        });
+    }
+    return {
+        name: record.name,
+        ...(record.email === undefined ? {} : { email: record.email }),
+    };
+}
+export function documentRpcEnabled(env) {
+    return (env?.SUPERDOC_SDK_DOCUMENT_RPC ?? process.env.SUPERDOC_SDK_DOCUMENT_RPC) === '1';
+}
+export function supportsDocumentRpc(features) {
+    return DOCUMENT_RPC_FEATURES.every((feature) => features.has(feature));
+}
+export function canOpenWithDocumentRpc(params, options) {
+    if (options.stdinBytes !== undefined)
+        return false;
+    if (options.dryRun !== undefined || options.expectedRevision !== undefined || options.changeMode !== undefined) {
+        return false;
+    }
+    if (typeof params.doc !== 'string' || params.doc.trim().length === 0 || params.doc === '-')
+        return false;
+    if (params.runtime !== undefined && params.runtime !== 'v2')
+        return false;
+    if (params.sessionId !== undefined && (typeof params.sessionId !== 'string' || params.sessionId.length === 0)) {
+        return false;
+    }
+    return Object.entries(params).every(([key, value]) => value === undefined || DOCUMENT_RPC_OPEN_FIELDS.has(key));
+}
+export function buildDocumentOpenParams(params, user, defaultChangeMode) {
+    const sessionId = typeof params.sessionId === 'string' && params.sessionId.length > 0 ? params.sessionId : randomUUID();
+    const author = buildDocumentAuthor(user);
+    return {
+        sessionId,
+        params: {
+            sessionId,
+            path: params.doc,
+            ...(author === undefined ? {} : { author }),
+            ...(defaultChangeMode == null ? {} : { defaultChangeMode }),
+        },
+    };
+}
+export function mapDocumentOpenResult(response, sessionId, path) {
+    if (typeof response !== 'object' || response == null || Array.isArray(response)) {
+        throw new SuperDocCliError('Host returned invalid document.open result.', {
+            code: 'HOST_PROTOCOL_ERROR',
+            details: { result: response },
+        });
+    }
+    const record = response;
+    if (record.sessionId !== sessionId || typeof record.byteLength !== 'number') {
+        throw new SuperDocCliError('Host returned invalid document.open session metadata.', {
+            code: 'HOST_PROTOCOL_ERROR',
+            details: { result: response },
+        });
+    }
+    return {
+        active: true,
+        contextId: sessionId,
+        runtime: 'v2',
+        sessionType: 'local',
+        document: { path, source: 'path', byteLength: record.byteLength, revision: 0 },
+        dirty: false,
+    };
+}
+function supportsTrackedMode(operation) {
+    return operation.supportsTrackedMode === true || operation.supportsConditionalTrackedMode === true;
+}
+function documentInvokePayload(operation, params, invokeOptions) {
+    const normalizedParams = applyOperationParamAliases(operation, params);
+    if (invokeOptions.stdinBytes !== undefined) {
+        throw unsupported('Structured document RPC does not support stdinBytes.', operation.operationId);
+    }
+    if (typeof normalizedParams.out === 'string' && normalizedParams.out.length > 0) {
+        throw unsupported('Structured document RPC does not support per-operation output paths.', operation.operationId);
+    }
+    if (normalizedParams.force === true) {
+        throw unsupported('Structured document RPC does not support per-operation force.', operation.operationId);
+    }
+    const input = {};
+    const options = {};
+    const paramsByName = new Map(operation.params.map((param) => [param.name, param]));
+    for (const [name, value] of Object.entries(normalizedParams)) {
+        if (value === undefined || name === 'doc' || name === 'sessionId' || name === 'out' || name === 'force')
+            continue;
+        const param = paramsByName.get(name);
+        if (!param) {
+            throw unsupported(`Structured document RPC does not support ${operation.operationId} field ${name}.`, operation.operationId);
+        }
+        if (typeof param.documentApiInputName === 'string' && param.documentApiInputName.length > 0) {
+            input[param.documentApiInputName] = value;
+            continue;
+        }
+        if (DOCUMENT_API_OPTION_FIELDS.has(name)) {
+            options[name] = value;
+            continue;
+        }
+        throw unsupported(`Structured document RPC does not support ${operation.operationId} field ${name}.`, operation.operationId);
+    }
+    for (const name of ['expectedRevision', 'changeMode', 'dryRun']) {
+        const value = invokeOptions[name];
+        if (value === undefined || normalizedParams[name] !== undefined)
+            continue;
+        const projectedValue = name === 'expectedRevision' ? String(value) : value;
+        const param = paramsByName.get(name);
+        if (typeof param?.documentApiInputName === 'string' && param.documentApiInputName.length > 0) {
+            input[param.documentApiInputName] = projectedValue;
+        }
+        else {
+            options[name] = projectedValue;
+        }
+    }
+    if (options.changeMode !== undefined && !supportsTrackedMode(operation)) {
+        if (options.changeMode === 'tracked') {
+            throw unsupported(`Structured document RPC does not support tracked mode for ${operation.operationId}.`, operation.operationId);
+        }
+        if (options.changeMode !== 'direct') {
+            throw unsupported(`Structured document RPC received an invalid change mode for ${operation.operationId}.`, operation.operationId);
+        }
+        delete options.changeMode;
+    }
+    if (options.dryRun !== undefined && operation.supportsDryRun !== true) {
+        if (options.dryRun === true) {
+            throw unsupported(`Structured document RPC does not support dry run for ${operation.operationId}.`, operation.operationId);
+        }
+        delete options.dryRun;
+    }
+    if (options.expectedRevision !== undefined && DOCUMENT_API_REVISION_PREFLIGHT_OPERATIONS.has(operation.operationId)) {
+        throw unsupported(`Structured document RPC does not yet support expectedRevision for ${operation.operationId}.`, operation.operationId);
+    }
+    if (options.expectedRevision !== undefined && operation.mutates !== true) {
+        throw unsupported(`Structured document RPC does not support expectedRevision for ${operation.operationId}.`, operation.operationId);
+    }
+    return {
+        input,
+        ...(Object.keys(options).length === 0 ? {} : { options }),
+    };
+}
+export function buildDocumentInvokeParams(sessionId, operation, params, options, hostFeatures) {
+    if (operation.operationId === 'doc.save') {
+        if (options.stdinBytes !== undefined ||
+            options.dryRun !== undefined ||
+            options.expectedRevision !== undefined ||
+            options.changeMode !== undefined) {
+            throw unsupported('Structured document RPC does not support document.save invoke options.', operation.operationId);
+        }
+        const unknownField = Object.entries(params).find(([name, value]) => value !== undefined && !DOCUMENT_RPC_SAVE_FIELDS.has(name))?.[0];
+        if (unknownField !== undefined) {
+            throw unsupported(`Structured document RPC does not support doc.save field ${unknownField}.`, operation.operationId);
+        }
+        if (params.inPlace !== undefined && typeof params.inPlace !== 'boolean') {
+            throw unsupported('Structured document RPC requires inPlace to be a boolean.', operation.operationId);
+        }
+        if (params.inPlace === true && params.out !== undefined) {
+            throw unsupported('Structured document RPC requires either inPlace or out, not both.', operation.operationId);
+        }
+        if (params.out !== undefined && (typeof params.out !== 'string' || params.out.length === 0)) {
+            throw unsupported('Structured document RPC requires out to be a non-empty path.', operation.operationId);
+        }
+        if (params.out === undefined && hostFeatures?.has(DOCUMENT_RPC_SOURCE_SAVE_FEATURE) !== true) {
+            throw unsupported('Structured document RPC host does not support source saves.', operation.operationId);
+        }
+        return {
+            method: 'document.save',
+            params: {
+                sessionId,
+                ...(params.out === undefined ? {} : { path: params.out }),
+                ...(params.force === true ? { overwrite: true } : {}),
+                ...(params.mode === undefined ? {} : { mode: params.mode }),
+            },
+        };
+    }
+    if (operation.operationId === 'doc.close') {
+        if (options.stdinBytes !== undefined ||
+            options.dryRun !== undefined ||
+            options.expectedRevision !== undefined ||
+            options.changeMode !== undefined) {
+            throw unsupported('Structured document RPC does not support document.close invoke options.', operation.operationId);
+        }
+        return {
+            method: 'document.close',
+            params: {
+                sessionId,
+                ...(params.discard === undefined ? {} : { discard: params.discard }),
+            },
+        };
+    }
+    const documentOperation = operation;
+    if (typeof documentOperation.documentApiOperationId !== 'string' ||
+        documentOperation.documentApiOperationId.length === 0) {
+        throw unsupported(`Structured document RPC does not support ${operation.operationId}.`, operation.operationId);
+    }
+    const payload = documentInvokePayload(documentOperation, params, options);
+    return {
+        method: 'document.invoke',
+        params: {
+            sessionId,
+            operationId: documentOperation.documentApiOperationId,
+            input: payload.input,
+            ...(payload.options === undefined ? {} : { options: payload.options }),
+        },
+    };
+}
+export function documentRpcRequestSupportsResponseTimeout(operation, request) {
+    if (request.method === 'document.save')
+        return false;
+    if (request.method !== 'document.invoke')
+        return true;
+    const documentOperation = operation;
+    const requestOptions = typeof request.params.options === 'object' &&
+        request.params.options !== null &&
+        !Array.isArray(request.params.options)
+        ? request.params.options
+        : undefined;
+    if (requestOptions?.dryRun === true)
+        return true;
+    if (documentOperation.mutates === false)
+        return true;
+    return documentOperation.idempotency === 'idempotent';
+}
+export function mapDocumentLifecycleResult(operationId, response, sessionId, expectedInPlace) {
+    if (operationId !== 'doc.save' && operationId !== 'doc.close')
+        return response;
+    if (typeof response !== 'object' || response == null || Array.isArray(response)) {
+        throw new SuperDocCliError(`Host returned invalid ${operationId.slice('doc.'.length)} result.`, {
+            code: 'HOST_PROTOCOL_ERROR',
+            details: { result: response },
+        });
+    }
+    const record = response;
+    if (record.sessionId !== sessionId) {
+        throw new SuperDocCliError('Host returned a result for the wrong document session.', {
+            code: 'HOST_PROTOCOL_ERROR',
+            details: { expectedSessionId: sessionId, result: response },
+        });
+    }
+    if (operationId === 'doc.close') {
+        if (record.closed !== true || typeof record.discarded !== 'boolean') {
+            throw new SuperDocCliError('Host returned invalid document.close result.', {
+                code: 'HOST_PROTOCOL_ERROR',
+                details: { result: response },
+            });
+        }
+        return {
+            contextId: sessionId,
+            runtime: 'v2',
+            closed: true,
+            saved: false,
+            discarded: record.discarded,
+            defaultSessionCleared: false,
+        };
+    }
+    const output = record.output;
+    if (record.saved !== true ||
+        (typeof record.inPlace !== 'boolean' && !(record.inPlace === undefined && expectedInPlace === false)) ||
+        typeof output !== 'object' ||
+        output == null ||
+        Array.isArray(output) ||
+        typeof output.path !== 'string' ||
+        typeof output.byteLength !== 'number') {
+        throw new SuperDocCliError('Host returned invalid document.save result.', {
+            code: 'HOST_PROTOCOL_ERROR',
+            details: { result: response },
+        });
+    }
+    return {
+        contextId: sessionId,
+        runtime: 'v2',
+        saved: true,
+        inPlace: record.inPlace ?? false,
+        mode: record.mode,
+        output,
+        report: record.report,
+    };
+}

package/dist/runtime/embedded-cli.cjs

@@ -1,78 +1,16 @@
 'use strict';
 
-var node_fs = require('node:fs');
-var node_module = require('node:module');
-var path = require('node:path');
-var node_url = require('node:url');
 var errors = require('./errors.cjs');
+var embeddedPlatform = require('./embedded-platform.cjs');
 
-var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
-const require$1 = node_module.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('runtime/embedded-cli.cjs', document.baseURI).href)));
-const TARGET_TO_PACKAGE = {
-    'darwin-arm64': '@superdoc/sdk-darwin-arm64',
-    'darwin-x64': '@superdoc/sdk-darwin-x64',
-    'linux-x64': '@superdoc/sdk-linux-x64',
-    'linux-arm64': '@superdoc/sdk-linux-arm64',
-    'windows-x64': '@superdoc/sdk-windows-x64',
-};
-const TARGET_TO_DIR = {
-    'darwin-arm64': 'sdk-darwin-arm64',
-    'darwin-x64': 'sdk-darwin-x64',
-    'linux-x64': 'sdk-linux-x64',
-    'linux-arm64': 'sdk-linux-arm64',
-    'windows-x64': 'sdk-windows-x64',
-};
-function resolveTarget() {
-    const platform = process.platform;
-    const arch = process.arch;
-    if (platform === 'darwin' && arch === 'arm64')
-        return 'darwin-arm64';
-    if (platform === 'darwin' && arch === 'x64')
-        return 'darwin-x64';
-    if (platform === 'linux' && arch === 'x64')
-        return 'linux-x64';
-    if (platform === 'linux' && arch === 'arm64')
-        return 'linux-arm64';
-    if (platform === 'win32' && arch === 'x64')
-        return 'windows-x64';
-    return null;
-}
 function binaryNameForTarget(target) {
     return target === 'windows-x64' ? 'superdoc.exe' : 'superdoc';
 }
-function ensureExecutable(binaryPath) {
-    if (process.platform === 'win32')
-        return;
-    try {
-        node_fs.chmodSync(binaryPath, 0o755);
-    }
-    catch {
-        // Non-fatal: if chmod fails, spawn() will surface the real execution error.
-    }
-}
-function resolveFromPlatformPackage(target) {
-    const pkg = TARGET_TO_PACKAGE[target];
-    const binaryName = binaryNameForTarget(target);
-    try {
-        return require$1.resolve(`${pkg}/bin/${binaryName}`);
-    }
-    catch {
-        return null;
-    }
-}
-function resolveFromWorkspaceFallback(target) {
-    const binaryName = binaryNameForTarget(target);
-    const dirName = TARGET_TO_DIR[target];
-    const filePath = path.resolve(node_url.fileURLToPath(new URL('../../platforms', (typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('runtime/embedded-cli.cjs', document.baseURI).href)))), dirName, 'bin', binaryName);
-    if (!node_fs.existsSync(filePath))
-        return null;
-    return filePath;
-}
 /**
  * Resolve the path to the embedded SuperDoc CLI binary for the current platform.
  */
 function resolveEmbeddedCliBinary() {
-    const target = resolveTarget();
+    const target = embeddedPlatform.resolveEmbeddedTarget();
     if (!target) {
         throw new errors.SuperDocCliError('No embedded SuperDoc CLI binary is available for this platform.', {
             code: 'UNSUPPORTED_PLATFORM',
@@ -82,18 +20,17 @@ function resolveEmbeddedCliBinary() {
             },
         });
     }
-    const platformPackagePath = resolveFromPlatformPackage(target);
-    const resolvedPath = platformPackagePath ?? resolveFromWorkspaceFallback(target);
+    const resolvedPath = embeddedPlatform.resolveEmbeddedPlatformBinary(target, binaryNameForTarget(target));
     if (!resolvedPath) {
         throw new errors.SuperDocCliError('Embedded SuperDoc CLI binary is missing for this platform.', {
             code: 'CLI_BINARY_MISSING',
             details: {
                 target,
-                packageName: TARGET_TO_PACKAGE[target],
+                packageName: embeddedPlatform.embeddedPlatformPackage(target),
             },
         });
     }
-    ensureExecutable(resolvedPath);
+    embeddedPlatform.ensureEmbeddedExecutable(resolvedPath);
     return resolvedPath;
 }
 

package/dist/runtime/embedded-cli.js

@@ -1,74 +1,13 @@
-import { chmodSync, existsSync } from 'node:fs';
-import { createRequire } from 'node:module';
-import path from 'node:path';
-import { fileURLToPath } from 'node:url';
 import { SuperDocCliError } from './errors.js';
-const require = createRequire(import.meta.url);
-const TARGET_TO_PACKAGE = {
-    'darwin-arm64': '@superdoc/sdk-darwin-arm64',
-    'darwin-x64': '@superdoc/sdk-darwin-x64',
-    'linux-x64': '@superdoc/sdk-linux-x64',
-    'linux-arm64': '@superdoc/sdk-linux-arm64',
-    'windows-x64': '@superdoc/sdk-windows-x64',
-};
-const TARGET_TO_DIR = {
-    'darwin-arm64': 'sdk-darwin-arm64',
-    'darwin-x64': 'sdk-darwin-x64',
-    'linux-x64': 'sdk-linux-x64',
-    'linux-arm64': 'sdk-linux-arm64',
-    'windows-x64': 'sdk-windows-x64',
-};
-function resolveTarget() {
-    const platform = process.platform;
-    const arch = process.arch;
-    if (platform === 'darwin' && arch === 'arm64')
-        return 'darwin-arm64';
-    if (platform === 'darwin' && arch === 'x64')
-        return 'darwin-x64';
-    if (platform === 'linux' && arch === 'x64')
-        return 'linux-x64';
-    if (platform === 'linux' && arch === 'arm64')
-        return 'linux-arm64';
-    if (platform === 'win32' && arch === 'x64')
-        return 'windows-x64';
-    return null;
-}
+import { embeddedPlatformPackage, ensureEmbeddedExecutable, resolveEmbeddedPlatformBinary, resolveEmbeddedTarget, } from './embedded-platform.js';
 function binaryNameForTarget(target) {
     return target === 'windows-x64' ? 'superdoc.exe' : 'superdoc';
 }
-function ensureExecutable(binaryPath) {
-    if (process.platform === 'win32')
-        return;
-    try {
-        chmodSync(binaryPath, 0o755);
-    }
-    catch {
-        // Non-fatal: if chmod fails, spawn() will surface the real execution error.
-    }
-}
-function resolveFromPlatformPackage(target) {
-    const pkg = TARGET_TO_PACKAGE[target];
-    const binaryName = binaryNameForTarget(target);
-    try {
-        return require.resolve(`${pkg}/bin/${binaryName}`);
-    }
-    catch {
-        return null;
-    }
-}
-function resolveFromWorkspaceFallback(target) {
-    const binaryName = binaryNameForTarget(target);
-    const dirName = TARGET_TO_DIR[target];
-    const filePath = path.resolve(fileURLToPath(new URL('../../platforms', import.meta.url)), dirName, 'bin', binaryName);
-    if (!existsSync(filePath))
-        return null;
-    return filePath;
-}
 /**
  * Resolve the path to the embedded SuperDoc CLI binary for the current platform.
  */
 export function resolveEmbeddedCliBinary() {
-    const target = resolveTarget();
+    const target = resolveEmbeddedTarget();
     if (!target) {
         throw new SuperDocCliError('No embedded SuperDoc CLI binary is available for this platform.', {
             code: 'UNSUPPORTED_PLATFORM',
@@ -78,17 +17,16 @@ export function resolveEmbeddedCliBinary() {
             },
         });
     }
-    const platformPackagePath = resolveFromPlatformPackage(target);
-    const resolvedPath = platformPackagePath ?? resolveFromWorkspaceFallback(target);
+    const resolvedPath = resolveEmbeddedPlatformBinary(target, binaryNameForTarget(target));
     if (!resolvedPath) {
         throw new SuperDocCliError('Embedded SuperDoc CLI binary is missing for this platform.', {
             code: 'CLI_BINARY_MISSING',
             details: {
                 target,
-                packageName: TARGET_TO_PACKAGE[target],
+                packageName: embeddedPlatformPackage(target),
             },
         });
     }
-    ensureExecutable(resolvedPath);
+    ensureEmbeddedExecutable(resolvedPath);
     return resolvedPath;
 }

package/dist/runtime/embedded-document-host.cjs

@@ -0,0 +1,28 @@
+'use strict';
+
+var embeddedPlatform = require('./embedded-platform.cjs');
+var errors = require('./errors.cjs');
+
+function binaryNameForTarget(target) {
+    return target === 'windows-x64' ? 'superdoc-document-host.exe' : 'superdoc-document-host';
+}
+function resolveEmbeddedDocumentHostBinary() {
+    const target = embeddedPlatform.resolveEmbeddedTarget();
+    if (!target) {
+        throw new errors.SuperDocCliError('No embedded SuperDoc document host is available for this platform.', {
+            code: 'UNSUPPORTED_PLATFORM',
+            details: { platform: process.platform, arch: process.arch },
+        });
+    }
+    const resolvedPath = embeddedPlatform.resolveEmbeddedPlatformBinary(target, binaryNameForTarget(target));
+    if (!resolvedPath) {
+        throw new errors.SuperDocCliError('Embedded SuperDoc document host is missing for this platform.', {
+            code: 'DOCUMENT_HOST_BINARY_MISSING',
+            details: { target, packageName: embeddedPlatform.embeddedPlatformPackage(target) },
+        });
+    }
+    embeddedPlatform.ensureEmbeddedExecutable(resolvedPath);
+    return resolvedPath;
+}
+
+exports.resolveEmbeddedDocumentHostBinary = resolveEmbeddedDocumentHostBinary;

package/dist/runtime/embedded-document-host.d.ts

@@ -0,0 +1 @@
+export declare function resolveEmbeddedDocumentHostBinary(): string;

package/dist/runtime/embedded-document-host.js

@@ -0,0 +1,23 @@
+import { embeddedPlatformPackage, ensureEmbeddedExecutable, resolveEmbeddedPlatformBinary, resolveEmbeddedTarget, } from './embedded-platform.js';
+import { SuperDocCliError } from './errors.js';
+function binaryNameForTarget(target) {
+    return target === 'windows-x64' ? 'superdoc-document-host.exe' : 'superdoc-document-host';
+}
+export function resolveEmbeddedDocumentHostBinary() {
+    const target = resolveEmbeddedTarget();
+    if (!target) {
+        throw new SuperDocCliError('No embedded SuperDoc document host is available for this platform.', {
+            code: 'UNSUPPORTED_PLATFORM',
+            details: { platform: process.platform, arch: process.arch },
+        });
+    }
+    const resolvedPath = resolveEmbeddedPlatformBinary(target, binaryNameForTarget(target));
+    if (!resolvedPath) {
+        throw new SuperDocCliError('Embedded SuperDoc document host is missing for this platform.', {
+            code: 'DOCUMENT_HOST_BINARY_MISSING',
+            details: { target, packageName: embeddedPlatformPackage(target) },
+        });
+    }
+    ensureEmbeddedExecutable(resolvedPath);
+    return resolvedPath;
+}

package/dist/runtime/embedded-platform.cjs

@@ -0,0 +1,102 @@
+'use strict';
+
+var node_fs = require('node:fs');
+var node_module = require('node:module');
+var path = require('node:path');
+var node_url = require('node:url');
+
+var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
+const require$1 = node_module.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('runtime/embedded-platform.cjs', document.baseURI).href)));
+const TARGET_TO_PACKAGE = {
+    'darwin-arm64': '@superdoc/sdk-darwin-arm64',
+    'darwin-x64': '@superdoc/sdk-darwin-x64',
+    'linux-x64': '@superdoc/sdk-linux-x64',
+    'linux-arm64': '@superdoc/sdk-linux-arm64',
+    'windows-x64': '@superdoc/sdk-windows-x64',
+};
+const TARGET_TO_DIR = {
+    'darwin-arm64': 'sdk-darwin-arm64',
+    'darwin-x64': 'sdk-darwin-x64',
+    'linux-x64': 'sdk-linux-x64',
+    'linux-arm64': 'sdk-linux-arm64',
+    'windows-x64': 'sdk-windows-x64',
+};
+function resolveEmbeddedTarget(platform = process.platform, arch = process.arch) {
+    if (platform === 'darwin' && arch === 'arm64')
+        return 'darwin-arm64';
+    if (platform === 'darwin' && arch === 'x64')
+        return 'darwin-x64';
+    if (platform === 'linux' && arch === 'x64')
+        return 'linux-x64';
+    if (platform === 'linux' && arch === 'arm64')
+        return 'linux-arm64';
+    if (platform === 'win32' && arch === 'x64')
+        return 'windows-x64';
+    return null;
+}
+function embeddedPlatformPackage(target) {
+    return TARGET_TO_PACKAGE[target];
+}
+/**
+ * The binary shipped inside this package (`platforms/<target>/bin/`). A build
+ * that carries its own host is authoritative — it is the only copy guaranteed
+ * to match this SDK's code — so it is tried before any resolver lookup.
+ */
+function resolveFromPackageLocal(target, binaryName) {
+    const workspacePath = path.resolve(node_url.fileURLToPath(new URL('../../platforms', (typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('runtime/embedded-platform.cjs', document.baseURI).href)))), TARGET_TO_DIR[target], 'bin', binaryName);
+    return node_fs.existsSync(workspacePath) ? workspacePath : null;
+}
+/**
+ * Resolve the platform package through Node, and reject a version that is not
+ * this SDK's own.
+ *
+ * `require.resolve` falls back to NODE_PATH, which package managers set to a
+ * flat store directory (pnpm does it for every binary shim). A host binary from
+ * an unrelated SDK version installed anywhere in that store then satisfies this
+ * lookup, and the SDK silently drives a foreign engine: seen in the wild as an
+ * SDK 2.2.1 install executing a hoisted 2.0.0 host, which failed operations the
+ * matching host performs correctly. optionalDependencies pin the platform
+ * package to an exact version, so a mismatch here is never legitimate.
+ */
+function resolveFromPlatformPackage(target, binaryName) {
+    const pkg = TARGET_TO_PACKAGE[target];
+    let binaryPath;
+    try {
+        binaryPath = require$1.resolve(`${pkg}/bin/${binaryName}`);
+    }
+    catch {
+        return null;
+    }
+    try {
+        const platformVersion = require$1(require$1.resolve(`${pkg}/package.json`)).version;
+        const ownVersion = require$1(node_url.fileURLToPath(new URL('../../package.json', (typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('runtime/embedded-platform.cjs', document.baseURI).href))))).version;
+        if (platformVersion !== ownVersion)
+            return null;
+    }
+    catch {
+        // Either manifest being unreadable is itself disqualifying: an unverifiable
+        // host is exactly the case this guard exists to reject.
+        return null;
+    }
+    return binaryPath;
+}
+function resolveEmbeddedPlatformBinary(target, binaryName) {
+    // Package-local first: a self-contained build must never be overridden by
+    // whatever the module resolver happens to find on NODE_PATH.
+    return resolveFromPackageLocal(target, binaryName) ?? resolveFromPlatformPackage(target, binaryName);
+}
+function ensureEmbeddedExecutable(binaryPath) {
+    if (process.platform === 'win32')
+        return;
+    try {
+        node_fs.chmodSync(binaryPath, 0o755);
+    }
+    catch {
+        // Non-fatal: spawn() reports the actionable execution error.
+    }
+}
+
+exports.embeddedPlatformPackage = embeddedPlatformPackage;
+exports.ensureEmbeddedExecutable = ensureEmbeddedExecutable;
+exports.resolveEmbeddedPlatformBinary = resolveEmbeddedPlatformBinary;
+exports.resolveEmbeddedTarget = resolveEmbeddedTarget;