arcane-os 0.21.0 → 0.22.0

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 0.22.0
+
+- Export `generateDocumentImportMaps()` from `arcane-os` for explicitly selected
+  host HTML documents and an existing materialized runtime. Generate each
+  document's SDK import URLs from its authored base without app discovery or
+  imposing an application layout.
+- Preserve complete authored HTML, resource URLs, custom import maps and script
+  loading order while updating only SDK-managed map blocks. Encode runtime
+  filenames and rebase both targets and URL compatibility keys.
+- Inventory the selected runtime once per batch, prepare every document before
+  writing, and expose ordered write events, cancellation and event-delivery
+  failures. Document the public API and add focused behavioral test source.
+- Preserve the platform's existing cancellation code in the import-map and
+  runtime-inventory paths, including ordinary `AbortController.abort()`.
+
 ## 0.21.0
 
 - Serve mail over HTTPS with HTTP/2 through the published `node-http-server`

package/README.md

@@ -19,7 +19,7 @@ version-locked SDK runtime, while an integrated Arcane checkout uses its live
 `arcane/` runtime. Both profiles preserve the same app URLs, theme, packaging,
 event, cancellation, and browser run contracts.
 
-This checkout defines the `0.21.0` SDK contract. Applications pin one exact npm
+This checkout defines the `0.22.0` SDK contract. Applications pin one exact npm
 version and lockfile; registry state is deliberately not baked into application
 artifacts.
 

package/docs/architecture.md

@@ -74,6 +74,16 @@ migration; the current tree has no OS-to-SDK synchronization path.
 
 ## Workspace profiles
 
+Hosts with an existing HTML layout can call the root-exported
+[`generateDocumentImportMaps()`](reference/sdk-api.md#generatedocumentimportmaps)
+with a document root, explicit page paths, and an already materialized runtime.
+This SDK-owned operation builds the shared map once and renders each page's
+URLs from its authored base, preserving page content and script order. It
+updates only SDK-managed inline maps; the host owns document selection,
+runtime materialization, serving, and coordination with other writers. This
+path requires no application descriptor or `apps/<id>/` layout and leaves the
+app-scoped toolchain operation unchanged.
+
 An external workspace maps the exact runtime shipped by its locked `arcane-os`
 dependency. An Arcane OS checkout is an integrated SDK consumer, not the owner
 of portable runtime source. For live shared development, the explicit

package/docs/reference/inventory/package-api.json

@@ -6,7 +6,7 @@
     "minimumVersion": "22.23.2 for Node entrypoints",
     "moduleSystem": "ESM"
   },
-  "memberCount": 209,
+  "memberCount": 210,
   "members": [
     {
       "id": "root:APP_BUNDLE_DESCRIPTOR_NAME",
@@ -772,6 +772,22 @@
       "protocol": "Node ESM",
       "normalization": "ArcaneError and JSON-safe error normalization"
     },
+    {
+      "id": "root:generateDocumentImportMaps",
+      "name": "generateDocumentImportMaps",
+      "displayName": "generateDocumentImportMaps()",
+      "kind": "function",
+      "signature": "async generateDocumentImportMaps({documentRoot, runtimeRoot, documents, version=SDK_VERSION, deploymentUrl, signal, onEvent}={})",
+      "entrypoints": [
+        "arcane-os"
+      ],
+      "primaryImport": "arcane-os",
+      "group": "Runtime and app descriptors",
+      "summary": "Writes SDK-managed inline import maps for explicit host documents using an existing materialized runtime and each document's authored base.",
+      "availability": "Node on Windows, Linux, and macOS",
+      "protocol": "Explicit host documents",
+      "normalization": "Absolute filesystem result paths, document-relative browser maps, ordered write events, cancellation, and degraded event-delivery reporting"
+    },
     {
       "id": "root:getSdkBrowserRuntimeRoot",
       "name": "getSdkBrowserRuntimeRoot",

package/docs/reference/protocols.md

@@ -47,7 +47,7 @@ These protocols normalize orchestration and results. They do not normalize a
 Windows EXE, Linux DEB, Android APK, and portable directory into the same
 artifact kind.
 
-Managed browser imports have three supported control-plane entrypoints. The CLI
+App-scoped managed browser imports have three supported control-plane entrypoints. The CLI
 uses `arcane import-map`; Node callers use
 `executeOperation('import-map', options)` or
 `createToolchain(defaults).importMap(options)`. These are three routes to the
@@ -70,6 +70,9 @@ subpath owns shared speech-input cleanup and has the same
 managed browser key. There is
 no exported `importMapApplication()` function, `generateImportMap()` function, or
 `arcane-os/import-map` package subpath.
+Explicit host document lists use the separate root-exported
+[`generateDocumentImportMaps()`](sdk-api.md#generatedocumentimportmaps) API
+described below; they do not enter app discovery.
 
 The application dependency boundary is conditional. Only an application that
 actually consumes Arcane declares one exact published `arcane-os` version in
@@ -147,6 +150,27 @@ unsafe structure and grants no Core capability or provider authority.
 See [EventManager and time-travel review](event-manager.md) for the callable
 surface, DOM privacy defaults, playback modes, and recovery behavior.
 
+## Explicit host documents
+
+`generateDocumentImportMaps()` accepts one document root, an existing
+materialized runtime root, and explicit document-root-relative paths. It
+inventories the runtime and constructs the shared browser map once per call,
+then resolves each document's map against its first href-bearing base or its
+own URL. An absolute or root-relative base, or a relative base traversing above
+the document root, requires the caller's directory `deploymentUrl`; target-only
+bases leave URL resolution unchanged.
+
+The operation preserves authored content, resource URLs, custom import maps,
+and script order, updating only SDK-managed inline map blocks. It prepares all
+documents before sequential writes and reports `import-map.documents.started`,
+`import-map.write.progress`, and `import-map.documents.completed`. Cancellation
+can leave completed document writes in place. Successful writes remain
+successful when event delivery fails, with a degraded-delivery record in the
+return value. Runtime materialization, serving, and writer coordination remain
+with the caller. See the [API guide](sdk-api.md#generatedocumentimportmaps) for
+the complete inputs, results, errors, and example. The app-scoped discovery and
+map-artifact lifecycle below remains separate.
+
 ## Browser runtime delivery
 
 External and modern integrated workspaces keep the same application URLs and a

package/docs/reference/sdk-api.md

@@ -153,6 +153,7 @@ browser map are cataloged separately in [Runtime modules](runtime-modules.md).
 | `executeNativeBuildPlan()` | function | `arcane-os` | Targets, native plans, and providers | Node; selected browser/native target or provider as documented |
 | `executeOperation()` | function | `arcane-os` | Headless toolchain operations | Node; selected operation may produce browser or native output |
 | `fail()` | function | `arcane-os` | Errors | Node |
+| `generateDocumentImportMaps()` | function | `arcane-os` | Runtime and app descriptors | Node; explicit documents and an existing materialized runtime |
 | `getSdkBrowserRuntimeRoot()` | function | `arcane-os` | Runtime and app descriptors | Node |
 | `getSdkRoot()` | function | `arcane-os` | Runtime and app descriptors | Node |
 | `getTargetAdapter()` | function | `arcane-os` | Targets, native plans, and providers | Node; selected browser/native target or provider as documented |
@@ -1137,6 +1138,161 @@ import {APP_DESCRIPTOR_SCHEMA_VERSION} from 'arcane-os';
 console.log(APP_DESCRIPTOR_SCHEMA_VERSION);
 ```
 
+## generateDocumentImportMaps()
+
+### Overview
+
+Writes SDK-managed inline browser import maps into explicitly selected HTML
+documents. Hosts can keep their existing page layout and use an already
+materialized Arcane runtime without an app descriptor, app discovery, or an
+`apps/<id>/` directory. The existing app-scoped `arcane import-map` operation
+continues to own descriptor-selected application pages and its map artifact.
+
+### Signature and result
+
+```text
+async generateDocumentImportMaps({
+    documentRoot,
+    runtimeRoot = path.join(documentRoot, 'arcane'),
+    documents,
+    version = SDK_VERSION,
+    deploymentUrl,
+    signal,
+    onEvent
+} = {})
+```
+
+Import it from `arcane-os`.
+
+| Input | Contract |
+| --- | --- |
+| `documentRoot` | Required filesystem directory containing the selected documents. Returned root paths are absolute. |
+| `runtimeRoot` | Existing materialized runtime directory containing `modules/`, `entities/`, `sdk/`, and its other selected content. Defaults to `arcane/` under `documentRoot`. Pass an absolute path when selecting another directory; relative root arguments resolve from the current working directory. |
+| `documents` | Required nonempty array of document-root-relative file paths, such as `['shell/home.html', 'settings.html']`. Use forward slashes and normalized paths without a leading `./` or parent traversal. Duplicate paths are processed once, in first-selected order. |
+| `version` | Version used in generated import-map targets and URL compatibility keys. Defaults to the installed SDK's `SDK_VERSION`; `null` selects unversioned map URLs. Authored resource URLs outside the managed map stay unchanged. |
+| `deploymentUrl` | Optional absolute directory URL ending in `/` that corresponds to `documentRoot`, such as `https://example.com/control/`. Required when a selected document has an absolute or root-relative base URL, or a relative base that traverses above `documentRoot`. |
+| `signal` | Optional `AbortSignal`, observed during inventory, document preparation, and before each write. |
+| `onEvent` | Optional named callback receiving the ordered events below. An asynchronous callback is awaited before the operation continues. |
+
+The resolved result contains:
+
+```text
+{
+    documentRoot,
+    runtimeRoot,
+    documentPaths,
+    documentCount,
+    documents: [{path, filePath, imports}],
+    committed: true
+}
+```
+
+`documentPaths` and each `filePath` are absolute filesystem paths. Each `path`
+is relative to `documentRoot`; `imports` is the complete map rendered for that
+document. The operation inventories the runtime once, builds the shared map
+once, and reads the selected documents with up to four concurrent readers.
+It renders every document before writing any of them, then writes in selected
+order. `committed: true` means all selected writes completed; the batch is not
+an atomic filesystem transaction.
+
+### Document URLs and authored content
+
+The first `<base>` with an `href` determines each document's effective base.
+A target-only base, such as `<base target="_blank">`, does not change URL
+resolution. With no base, `shell/home.html` resolves the default runtime through
+`../arcane/`. With `<base href="../">`, the same page resolves it through
+`./arcane/`. Generated URLs include the selected version when one is supplied.
+
+The host serves the runtime at the same relative location as `runtimeRoot`
+has to `documentRoot`. `deploymentUrl` supplies that directory's public URL
+when an authored base needs an origin or deployment path to resolve correctly.
+For example, `https://example.com/control/` corresponds to `documentRoot`, so
+its default runtime is served at `https://example.com/control/arcane/`.
+Cross-origin bases produce absolute runtime map URLs. Without `deploymentUrl`,
+an absolute or root-relative base causes a `TypeError` before any document is
+written. A relative base that traverses above `documentRoot` also requires
+`deploymentUrl`, even if later path segments return into the physical directory:
+the filesystem's parent names do not establish public deployment paths.
+The two filesystem roots must share a volume.
+
+The generator replaces only SDK-marked `<script type="importmap"
+data-arcane-import-map>` ranges, consolidating multiple SDK blocks into one.
+It preserves complete authored HTML around those ranges, including whitespace,
+resource URLs, custom import maps, and the attributes and order of classic,
+module, `async`, and `defer` scripts. Custom maps remain separate and are not
+merged into the SDK map. The managed block follows the effective base and
+precedes executable scripts and module preloads. An authored base that follows
+one of those loads is reported as `ARCANE_IMPORT_MAP_INVALID` before writes.
+
+This operation writes only the selected HTML files. The caller owns runtime
+materialization, document selection, serving, and coordination with other
+document writers. It creates no map sidecar, copies no runtime content, and
+starts no build or browser.
+
+### Events, errors, and cancellation
+
+| Event | Fields |
+| --- | --- |
+| `import-map.documents.started` | `documentRoot`, `runtimeRoot`, and the complete `documentPaths` selection. |
+| `import-map.write.progress` | `paths`: all absolute document paths successfully written so far. |
+| `import-map.documents.completed` | The successful result fields, including `committed: true`. |
+
+If an event callback throws or rejects, generation continues. A successful
+return additionally reports `eventDelivery: {status: 'degraded', errorCode:
+'ARCANE_EVENT_DELIVERY_FAILED', message}` for the first callback failure.
+
+Invalid options can throw `TypeError`; document/map structure failures use
+`ARCANE_IMPORT_MAP_INVALID`, runtime inventory failures use
+`ARCANE_RUNTIME_INVALID`, and filesystem failures propagate. All started
+preparation reads settle before rejection; multiple failures are
+reported together in an `AggregateError`. Cancellation
+rejects with the signal's error reason when supplied, otherwise an operation
+cancellation error; an error lacking a code receives `ARCANE_CANCELLED`.
+Preparation failures occur before writes. Cancellation or a filesystem failure
+during writing can leave earlier completed files updated; the operation does
+not roll those files back. An in-flight filesystem write completes before the
+next cancellation boundary.
+
+### Availability and normalization
+
+**Node on Windows, Linux, and macOS.** Filesystem paths are resolved with the
+host path API; browser import URLs use forward slashes and URL encoding. Deep
+protocol: [Explicit host documents](protocols.md#explicit-host-documents).
+
+### Example
+
+A dragon observatory keeps its control page at `shell/home.html`, settings at
+`settings.html`, and its selected Arcane runtime at `arcane/`. Run this from
+that document root after materializing the runtime:
+
+```javascript
+import {generateDocumentImportMaps} from 'arcane-os';
+
+const controller = new AbortController();
+
+function reportImportMapEvent(event) {
+    console.log(event);
+}
+
+const result = await generateDocumentImportMaps(
+    {
+        documentRoot: process.cwd(),
+        documents: ['shell/home.html', 'settings.html'],
+        signal: controller.signal,
+        onEvent: reportImportMapEvent
+    }
+);
+
+for (const document of result.documents) {
+    console.log(document.path, document.imports['arcane/AI']);
+}
+```
+
+Change the explicit document list to update another host page. If either page
+uses `<base href="/control/">`, add
+`deploymentUrl: 'https://example.com/control/'` to the options. Both pages keep
+their authored layout and receive map URLs appropriate to their own base.
+
 ## getSdkBrowserRuntimeRoot()
 
 ### Overview

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arcane-os",
-  "version": "0.21.0",
+  "version": "0.22.0",
   "description": "Arcane OS JavaScript SDK, project-local CLI, browser runtime, and repository-portable application packager.",
   "type": "module",
   "main": "./src/index.mjs",

package/src/import-map.mjs

@@ -3,6 +3,7 @@ import {lstat,mkdir,readFile as readFileFromDisk,readdir,realpath,writeFile} fro
 import path from 'node:path';
 import {pathToFileURL} from 'node:url';
 import {SDK_VERSION} from './constants.mjs';
+import {listRuntimeFiles} from './runtime.mjs';
 
 const is = new Is(false);
 
@@ -39,7 +40,7 @@ function fail(message,code='ARCANE_IMPORT_MAP_INVALID'){
 function throwIfAborted(signal){
     if(!signal?.aborted)return;
     const error=signal.reason instanceof Error?signal.reason:new Error('Operation cancelled.');
-    error.code=error.code||'ARCANE_CANCELLED';
+    if(error.code===undefined)error.code='ARCANE_CANCELLED';
     throw error;
 }
 
@@ -1296,9 +1297,16 @@ function validateInventory(files){
     return exact;
 }
 
-export async function buildImportMap({files,signal,version=SDK_VERSION}={}){
+function encodedUrlPath(relative) {
+    return relative.split('/').map(encodeURIComponent).join('/');
+}
+
+export async function buildImportMap({files,signal,version=SDK_VERSION,encodePaths=false}={}){
     throwIfAborted(signal);
     const inventory=validateInventory(files);
+    function runtimeTarget(relative) {
+        return `./arcane/${encodePaths ? encodedUrlPath(relative) : relative}`;
+    }
     const modules=[...inventory]
         .filter(relative=>relative.startsWith('modules/')
             &&!relative.slice('modules/'.length).includes('/')
@@ -1308,7 +1316,7 @@ export async function buildImportMap({files,signal,version=SDK_VERSION}={}){
     for(const relative of modules){
         throwIfAborted(signal);
         const name=path.posix.basename(relative).replace(JAVASCRIPT_EXTENSION,'');
-        registerSpecifier(namedRegistry,`arcane/${name}`,`./arcane/${relative}`);
+        registerSpecifier(namedRegistry,`arcane/${name}`,runtimeTarget(relative));
     }
     const entities=[...inventory].filter(relative=>relative.startsWith('entities/')
         &&!relative.slice('entities/'.length).includes('/')
@@ -1316,7 +1324,7 @@ export async function buildImportMap({files,signal,version=SDK_VERSION}={}){
     for(const relative of entities){
         throwIfAborted(signal);
         const name=path.posix.basename(relative).replace(JAVASCRIPT_EXTENSION,'');
-        registerSpecifier(namedRegistry,`arcane/entities/${name}`,`./arcane/${relative}`);
+        registerSpecifier(namedRegistry,`arcane/entities/${name}`,runtimeTarget(relative));
     }
     for(const [specifier,relative] of STATIC_RUNTIME_PACKAGE_IMPORTS){
         if(inventory.has(relative)){
@@ -1363,7 +1371,8 @@ export async function buildImportMap({files,signal,version=SDK_VERSION}={}){
     }
     for(const relative of [...inventory].sort(compareText)){
         if(JAVASCRIPT_EXTENSION.test(relative)){
-            registerSpecifier(namedRegistry,`./arcane/${relative}`,`./arcane/${relative}`);
+            const target=runtimeTarget(relative);
+            registerSpecifier(namedRegistry,target,target);
         }
     }
     const imports={};
@@ -2062,8 +2071,7 @@ function removeManagedBlocks(html,blocks){
     return result;
 }
 
-function firstModulePosition(html){
-    const structure=scanHtmlStructure(html);
+function firstModulePosition(html,structure=scanHtmlStructure(html)){
     let first=-1;
     for(const script of structure.scripts){
         const attributes=parseTagAttributes(script.open);
@@ -2434,6 +2442,312 @@ export async function readApplicationTestImportMapContext({
     });
 }
 
+function documentImportMapStructure(html) {
+    const structure = scanHtmlStructure(html);
+    const managed = [];
+    const executableTypes = new Set(
+        [
+            '', 'module', 'application/ecmascript', 'application/javascript',
+            'application/x-ecmascript', 'application/x-javascript',
+            'text/ecmascript', 'text/javascript', 'text/javascript1.0',
+            'text/javascript1.1', 'text/javascript1.2', 'text/javascript1.3',
+            'text/javascript1.4', 'text/javascript1.5', 'text/jscript',
+            'text/livescript', 'text/x-ecmascript', 'text/x-javascript'
+        ]
+    );
+    let firstLoad = firstModulePosition(html, structure);
+    let base = null;
+    for (const element of structure.bases) {
+        const attributes = parseTagAttributes(element.open);
+        if (!attributes.has('href')) continue;
+        base = {
+            ...element,
+            href:structuralAttribute(attributes, 'href', 'base')
+        };
+        break;
+    }
+    for (const script of structure.scripts) {
+        const attributes = parseTagAttributes(script.open);
+        const type = scriptType(attributes);
+        if (type === 'importmap' && attributes.has(MANAGED_IMPORT_MAP_ATTRIBUTE)) {
+            if (!script.closed) fail('Document contains an unterminated SDK import-map script.');
+            managed.push(script);
+        }
+        if (executableTypes.has(type) && (firstLoad < 0 || script.start < firstLoad)) {
+            firstLoad = script.start;
+        }
+    }
+    if (base && firstLoad >= 0 && base.end > firstLoad) {
+        fail('Document base must precede executable scripts and modulepreloads.');
+    }
+    return {
+        structure,
+        managed,
+        firstLoad,
+        base
+    };
+}
+
+function documentRelativeUrl(target, base) {
+    if (target.protocol !== base.protocol || target.host !== base.host) return target.href;
+    const directory = new URL('.', base);
+    const baseSegments = directory.pathname.split('/');
+    baseSegments.pop();
+    const targetSegments = target.pathname.split('/');
+    let shared = 0;
+    while (shared < baseSegments.length && shared < targetSegments.length - 1
+        && baseSegments[shared] === targetSegments[shared]) {
+        shared += 1;
+    }
+    // URL paths retain empty segments; filesystem relative() would collapse them.
+    const relative = [
+        ...new Array(baseSegments.length - shared).fill('..'),
+        ...targetSegments.slice(shared)
+    ].join('/');
+    const pathname = relative.startsWith('./') || relative.startsWith('../')
+        ? relative : `./${relative}`;
+    return `${pathname}${target.search}${target.hash}`;
+}
+
+function documentImports(imports, context, baseHref, relative) {
+    const documentUrl = new URL(encodedUrlPath(relative), context.deployment);
+    // Match URL parser normalization only for resolving the base; preserve authored HTML.
+    const baseAddress = (baseHref ?? '').replace(/[\t\r\n]/gu, '').replace(
+        /^[\u0000-\u0020]+|[\u0000-\u0020]+$/gu,
+        ''
+    );
+    if (!context.explicitDeployment && /^(?:[\\/]|[A-Za-z][A-Za-z0-9+.-]*:)/u.test(baseAddress)) {
+        throw new TypeError('An absolute or root-relative document base requires deploymentUrl.');
+    }
+    if (!context.explicitDeployment) {
+        let depth = relative.split('/').length - 1;
+        const basePath = baseAddress.split(/[?#]/u)[0].replaceAll('\\', '/');
+        for (const part of basePath.split('/')) {
+            const segment = part.replace(/%2e/giu, '.');
+            if (segment === '..') {
+                if (depth === 0) {
+                    throw new TypeError('A document base traversing above documentRoot requires deploymentUrl.');
+                }
+                depth -= 1;
+            } else if (segment !== '.') {
+                depth += 1;
+            }
+        }
+    }
+    const base = baseHref === undefined ? documentUrl : new URL(baseHref, documentUrl);
+    function rebaseUrl(value) {
+        if (value.startsWith('./arcane/')) {
+            return documentRelativeUrl(new URL(value.substring('./arcane/'.length), context.runtime), base);
+        }
+        if (value.startsWith('./node_modules/')) {
+            return documentRelativeUrl(new URL(value, context.deployment), base);
+        }
+        return value;
+    }
+    const rebased = {};
+    for (const [specifier, target] of Object.entries(imports)) {
+        rebased[rebaseUrl(specifier)] = rebaseUrl(target);
+    }
+    return rebased;
+}
+
+function renderDocumentImportMap(html, imports, state) {
+    const {structure, managed, firstLoad, base} = state;
+    const newline = html.includes('\r\n') ? '\r\n' : '\n';
+    const json = JSON.stringify({imports}, null, 2).replaceAll('<', '\\u003c');
+    const block = `<script type="importmap" ${MANAGED_IMPORT_MAP_ATTRIBUTE}>${newline}${json}${newline}</script>`;
+    const firstManaged = managed[0];
+    const replaceInPlace = firstManaged
+        && (!base || firstManaged.start >= base.end)
+        && (firstLoad < 0 || firstManaged.start < firstLoad);
+    const edits = managed.map(
+        function replaceSdkMap(script, index) {
+            return {
+                start:script.start,
+                end:script.end,
+                value:replaceInPlace && index === 0 ? block : ''
+            };
+        }
+    );
+    if (!replaceInPlace) {
+        const candidate = firstLoad >= 0 ? firstLoad
+            : structure.headClose >= 0 ? structure.headClose
+                : structure.bodyClose >= 0 ? structure.bodyClose : html.length;
+        const insertion = Math.max(candidate, base?.end ?? 0);
+        edits.push(
+            {
+                start:insertion,
+                end:insertion,
+                value:block
+            }
+        );
+    }
+    // Exact script ranges are SDK-owned; surrounding whitespace and author maps are not.
+    return applyReferenceEdits(html, edits);
+}
+
+/** Generate SDK maps for explicitly selected documents without imposing an app layout. */
+export async function generateDocumentImportMaps({
+    documentRoot,
+    runtimeRoot,
+    documents,
+    version = SDK_VERSION,
+    deploymentUrl,
+    signal,
+    onEvent
+} = {}) {
+    if (!is.string(documentRoot) || !documentRoot.trim()) {
+        throw new TypeError('generateDocumentImportMaps documentRoot must be a nonempty string.');
+    }
+    if (!is.array(documents) || documents.length === 0) {
+        throw new TypeError('generateDocumentImportMaps documents must be a nonempty array of relative paths.');
+    }
+    throwIfAborted(signal);
+    const root = path.resolve(documentRoot);
+    const runtime = path.resolve(runtimeRoot ?? path.join(root, 'arcane'));
+    const selected = [...new Set(documents.map(
+        function documentPath(value) {
+            return safeRelativePath(value, 'document path');
+        }
+    ))];
+    const deployment = deploymentUrl === undefined
+        ? pathToFileURL(`${root}${path.sep}`) : new URL(deploymentUrl);
+    if (!deployment.pathname.endsWith('/')) {
+        throw new TypeError('deploymentUrl must name a directory URL ending in /.');
+    }
+    const relativeRuntime = path.relative(root, runtime).split(path.sep).join('/');
+    if (path.isAbsolute(path.relative(root, runtime))) {
+        throw new TypeError('documentRoot and runtimeRoot must share a filesystem volume.');
+    }
+    const context = {
+        deployment,
+        runtime:new URL(relativeRuntime ? `${encodedUrlPath(relativeRuntime)}/` : './', deployment),
+        explicitDeployment:deploymentUrl !== undefined
+    };
+    const documentPaths = selected.map(
+        function resolveDocumentPath(relative) {
+            return path.join(root, ...relative.split('/'));
+        }
+    );
+    let eventError = await emit(
+        onEvent,
+        {
+            type:'import-map.documents.started',
+            documentRoot:root,
+            runtimeRoot:runtime,
+            documentPaths
+        }
+    );
+    const documentStates = new Array(selected.length);
+    const pending = selected.entries();
+    async function readDocuments() {
+        for (const [index, relative] of pending) {
+            throwIfAborted(signal);
+            const html = await readFileFromDisk(documentPaths[index], 'utf8');
+            throwIfAborted(signal);
+            documentStates[index] = {
+                path:relative,
+                filePath:documentPaths[index],
+                html,
+                state:documentImportMapStructure(html)
+            };
+        }
+    }
+    const readers = Array.from(
+        {length:Math.min(4, selected.length)},
+        readDocuments
+    );
+    const outcomes = await Promise.allSettled(
+        [
+            listRuntimeFiles(
+                {
+                    runtimeRoot:runtime,
+                    signal
+                }
+            ),
+            ...readers
+        ]
+    );
+    throwIfAborted(signal);
+    const errors = outcomes.filter(
+        function failedRead(outcome) {
+            return outcome.status === 'rejected';
+        }
+    ).map(
+        function readError(outcome) {
+            return outcome.reason;
+        }
+    );
+    if (errors.length === 1) throw errors[0];
+    if (errors.length > 1) throw new AggregateError(errors, 'Document import-map preparation failed.');
+    const built = await buildImportMap(
+        {
+            files:outcomes[0].value,
+            signal,
+            version,
+            encodePaths:true
+        }
+    );
+    const rendered = documentStates.map(
+        function renderSelectedDocument(document) {
+            throwIfAborted(signal);
+            const imports = documentImports(built.imports, context, document.state.base?.href, document.path);
+            return {
+                path:document.path,
+                filePath:document.filePath,
+                imports,
+                html:renderDocumentImportMap(document.html, imports, document.state)
+            };
+        }
+    );
+    const paths = [];
+    for (const document of rendered) {
+        throwIfAborted(signal);
+        await writeFile(document.filePath, document.html, 'utf8');
+        paths.push(document.filePath);
+        const deliveryError = await emit(
+            onEvent,
+            {
+                type:'import-map.write.progress',
+                paths:[...paths]
+            }
+        );
+        eventError ??= deliveryError;
+    }
+    const result = {
+        documentRoot:root,
+        runtimeRoot:runtime,
+        documentPaths,
+        documentCount:documentPaths.length,
+        documents:rendered.map(
+            function documentResult(document) {
+                return {
+                    path:document.path,
+                    filePath:document.filePath,
+                    imports:document.imports
+                };
+            }
+        ),
+        committed:true
+    };
+    const completedError = await emit(
+        onEvent,
+        {
+            type:'import-map.documents.completed',
+            ...result
+        }
+    );
+    eventError ??= completedError;
+    if (eventError) {
+        result.eventDelivery = {
+            status:'degraded',
+            errorCode:'ARCANE_EVENT_DELIVERY_FAILED',
+            message:String(eventError?.message ?? eventError)
+        };
+    }
+    return result;
+}
+
 async function generateImportMapUnlocked({
     workspaceRoot,
     appId,

package/src/index.mjs

@@ -135,6 +135,7 @@ export {
     readSdkBrowserRuntimeFile
 } from './sdk-browser-runtime.mjs';
 export {materializeWorkspaceRuntimeContent} from './workspace-runtime.mjs';
+export {generateDocumentImportMaps} from './import-map.mjs';
 export {
     discoverApps,
     inspectWorkspaceProfile,

package/src/runtime.mjs

@@ -17,7 +17,7 @@ function fail(message,code='ARCANE_RUNTIME_INVALID'){
 function throwIfAborted(signal){
     if(!signal?.aborted)return;
     const error=signal.reason instanceof Error?signal.reason:new Error('Operation cancelled.');
-    error.code=error.code||'ARCANE_CANCELLED';
+    if(error.code===undefined)error.code='ARCANE_CANCELLED';
     throw error;
 }