arcane-os 0.21.0 → 0.22.1

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## 0.22.1
+
+- Change the mail gateway's default HTTPS/HTTP2 port from 8025 to 4433 in
+  the CLI and server configuration. Preserve explicit port overrides and the
+  existing occupied-port message; update current help, references and gate report.
+
+## 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,11 +19,11 @@ 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.1` SDK contract. Applications pin one exact npm
 version and lockfile; registry state is deliberately not baked into application
 artifacts.
 
-The [mail gateway](docs/reference/mail.md) serves HTTPS with HTTP/2 on port 8025,
+The [mail gateway](docs/reference/mail.md) serves HTTPS with HTTP/2 on port 4433,
 using certificate paths from `.env.json`, and defaults browser mail to
 `/v1/mail` on the current domain. Multiple applications can share
 one server with explicit allowed origins. Subscription verification is disabled

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/cli.md

@@ -48,7 +48,7 @@ meaning and cardinality rules:
 | `--workspace` | directory | Commands that select an external or integrated workspace; defaults to `.`. |
 | `--app` | app id or label | Workspace/app operations except shared scope and `verify-bundle`; optional diagnostic label for `mail serve`. |
 | `--arcane-root` | directory | `doctor`, native `build`/`run`, `native-doctor`, `native-prepare` |
-| `--host` / `--port` | host / integer 0–65535 | Browser `dev`/`run` default to HTTPS at `127.0.0.1:8000`; `mail serve` defaults to HTTPS with HTTP/2 at `0.0.0.0:8025` and accepts an explicit bind host. |
+| `--host` / `--port` | host / integer 0–65535 | Browser `dev`/`run` default to HTTPS at `127.0.0.1:8000`; `mail serve` defaults to HTTPS with HTTP/2 at `0.0.0.0:4433` and accepts an explicit bind host. |
 | `--http-port` | integer 0–65535 | Browser `dev`/`run` HTTP redirect listener; defaults to `0`, which selects an available port. |
 | `--public` | flag | `dev`; binds to `0.0.0.0` unless `--host` explicitly selects another address. |
 | `--http` | flag | `dev` only; serves source and PWA routes on one HTTP listener selected by `--port`, without TLS. |
@@ -909,7 +909,7 @@ loss after the attempt begins is ambiguous because Resend may have accepted it.
 `mail serve` starts one owned HTTPS gateway with HTTP/2:
 
 ```text
-arcane mail serve [--profile <profile>] [--from <verified-sender>] [--app <label>] [--origin <exact-origin>] [--allow-to <addresses>] [--host 0.0.0.0] [--port 8025] [--request-timeout <ms>]
+arcane mail serve [--profile <profile>] [--from <verified-sender>] [--app <label>] [--origin <exact-origin>] [--allow-to <addresses>] [--host 0.0.0.0] [--port 4433] [--request-timeout <ms>]
 ```
 
 The selected `.env.json` profile supplies only the server-side Resend API key;
@@ -932,9 +932,9 @@ opens; the TLS owner reports PEM file errors. Keep private-key material outside
 tracked source. The SDK repository already ignores `.arcane/` and `.env.json`.
 
 The selected `node-http-server` module negotiates HTTP/2 with HTTP/1.1 fallback
-on the same HTTPS port, default `8025`, with no plain-HTTP listener. Callers use
+on the same HTTPS port, default `4433`, with no plain-HTTP listener. Callers use
 a hostname covered by the certificate, such as
-`https://mail.example.com:8025/v1/mail`; `0.0.0.0` identifies the bind address.
+`https://mail.example.com:4433/v1/mail`; `0.0.0.0` identifies the bind address.
 Restart the gateway after replacing renewed certificate files. Certificate
 issuance and renewal remain with the deployment's certificate owner.
 

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/mail.md

@@ -364,10 +364,10 @@ deadline.
 Start the gateway:
 
 ```text
-npm exec -- arcane mail serve --profile mail --host 0.0.0.0 --port 8025
+npm exec -- arcane mail serve --profile mail --host 0.0.0.0 --port 4433
 ```
 
-The default listener is `0.0.0.0:8025`; `--host` and `--port` select its bind
+The default listener is `0.0.0.0:4433`; `--host` and `--port` select its bind
 address and port. The server can serve callers from multiple domains on the
 same machine. Route the page's `/v1/mail` to this listener, or configure an
 explicit shared endpoint in the caller.
@@ -376,7 +376,7 @@ explicit shared endpoint in the caller.
 `node-http-server` PEM API owns TLS and negotiates HTTP/2 or HTTP/1.1 on the
 same listener. It creates no additional plain-HTTP listener. The returned URL
 uses `https://`; `0.0.0.0` is the bind address, so callers use the deployed
-domain, for example `https://mail.example.com:8025/v1/mail`.
+domain, for example `https://mail.example.com:4433/v1/mail`.
 
 Set `MAIL_TLS_CERT_PATH` to the PEM certificate chain and `MAIL_TLS_KEY_PATH`
 to its PEM private-key file. These top-level settings belong to the listener

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/docs/reviews/mail-server-purpose-review.md

@@ -52,7 +52,7 @@ Configuration and foundational methods follow. Each baseline name is recorded so
 | `positiveInteger` | Resolves the retry delay; baseline exposes unused `allowZero`. | Y/Y/Y — Simplify. | The uncalled zero branch and its extra option/prose are removed. Current name: `readRetryDelayMs`, which resolves the actual retry-delay setting. |
 | `optionalTimeoutMs` | Reads body/provider deadlines only when supplied. | Y/Y/N — Keep. | Omitting a deadline produces no timer. Node timer-range handling prevents caller-selected delays from changing meaning. Current name remains `optionalTimeoutMs`. |
 | `normalizeRetryAfter` | Error and result constructors keep a usable retry delay. | Y/Y/N — Keep. | Retry scheduling consumes this value. It is control metadata, not a transformation of message content. Current name: `retryDelayOrZero`. |
-| `portNumber` | Startup resolves default or configured port, including ephemeral port zero. | Y/Y/Y — Remove wrapper; retain configuration value. | The HTTP owner handles actual port binding. Preserve default 8025 and explicit port zero; no extra port validator or domain policy is required. |
+| `portNumber` | Startup resolves default or configured port, including ephemeral port zero. | Y/Y/Y — Remove wrapper; retain configuration value. | The HTTP owner handles actual port binding. Use the selected default 4433 and preserve explicit port zero; no extra port validator or domain policy is required. |
 | `validateSignal` | Direct send and server options accept caller cancellation. | Y/Y/Y — Remove wrapper; retain original signal. | Native signal operations already own their contract. Cancellation controllers/listeners and the abortable adapter remain. |
 | `validateApiKey` | Provider configuration supplies the credential used by Resend Fetch. | Y/Y/Y — Remove local format validator. | CLI credential retrieval reports missing provider credentials; Fetch/provider own actual transport validity. Never echo the credential. |
 | `validateAppId` | Validates application identity using the old lowercase-slug grammar. | Y/Y/Y — Remove the grammar and closed-list/equality admission. | Per-request identity matters and remains an ordinary string. Any application may use the shared server. Read the supplied identity for subscription verification without rewriting it; no standalone wrapper is needed solely to restrict spelling. |
@@ -395,7 +395,7 @@ cancellation before writes, and CLI defaults. Local tests and checks were not ru
 ## HTTPS and HTTP/2 follow-up
 
 The user explicitly selected HTTPS with HTTP/2. The mail listener remains on
-its dedicated configured port, default 8025, with the published
+its dedicated configured port, now default 4433, with the published
 `node-http-server` module owning TLS, protocol negotiation and listener/session
 shutdown. This increment preserves the provider attempt, report content,
 subscription callback, sender selection, recipient configuration and cancellation.
@@ -423,3 +423,16 @@ JSON paths and missing TLS settings. Synthetic TLS selection is not evidence of
 an encrypted handshake. No local tests, checks, server launch, real TLS
 negotiation or provider send were performed for this follow-up review. Selected
 package and publication results belong to the delivery record.
+
+## Main mail port follow-up
+
+The user selected 4433 as the main mail-server port. Both the CLI's omitted-port
+setting and the server's programmatic default now select 4433. Explicit ports,
+including ephemeral port zero, continue through the existing configuration.
+
+The port setting passes Y/Y/N: the listener needs a bind port, deployments need
+an override, and removing either would lose required behavior. Changing the two
+defaults adds no runtime work or helper. TLS negotiation, the returned endpoint
+and the occupied-port message already use the selected port. Existing test
+source was updated for the omitted-port path; explicit-port cases were retained.
+No local tests, checks or server launch were performed for this increment.

package/package.json

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

package/src/cli/main.mjs

@@ -85,7 +85,7 @@ Usage:
   ${CLI_NAME} mail key status [profile]
   ${CLI_NAME} mail key delete [profile]
   ${CLI_NAME} mail send [--profile <profile>] [--from <address>] --report-key <id> --report-stdin [--request-timeout <ms>]
-  ${CLI_NAME} mail serve [--profile <profile>] [--from <address>] [--app <label>] [--origin <origin>] [--allow-to <addresses>] [--host 0.0.0.0] [--port 8025] [--request-timeout <ms>]
+  ${CLI_NAME} mail serve [--profile <profile>] [--from <address>] [--app <label>] [--origin <origin>] [--allow-to <addresses>] [--host 0.0.0.0] [--port 4433] [--request-timeout <ms>]
     HTTPS/HTTP2; .env.json supplies RESEND_API_KEY, MAIL_TLS_CERT_PATH, and MAIL_TLS_KEY_PATH.
 
 Development:
@@ -698,7 +698,7 @@ function operationOptions(command,parsed,cwd){
                 origin:values.origin,
                 allowTo:values['allow-to'],
                 host:values.host??'0.0.0.0',
-                port:readPort(values.port,8025),
+                port:readPort(values.port,4433),
                 requestTimeout:readMailRequestTimeout(values['request-timeout']),
             };
         }

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/mail-server.mjs

@@ -113,7 +113,7 @@ function resolveMailServerConfiguration(options={}){
         host:options.host??'0.0.0.0',
         callerAuthentication:options.verifySubscription?'subscription':'none',
         onEvent:options.onEvent,
-        port:options.port??8025,
+        port:options.port??4433,
         providerTimeoutMs:optionalTimeoutMs(options.providerTimeoutMs,'providerTimeoutMs'),
         requestIdFactory:options.requestIdFactory??randomUUID,
         retryableDelayMs:readRetryDelayMs(options.retryableDelayMs),

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;
 }