arcane-os 0.51.0 → 0.51.2

package/docs/reference/inventory/runtime-modules.json

@@ -5,12 +5,12 @@
     "repository": "https://github.com/TheWizardNexus/arcane-os-sdk.git",
     "branch": "main",
     "path": "runtime/arcane",
-    "sdkVersion": "0.6.0",
+    "sdkVersion": "0.51.1",
     "protocol": "arcane/1"
   },
-  "artifactCount": 89,
-  "javascriptArtifactCount": 87,
-  "esmExportCount": 357,
+  "artifactCount": 92,
+  "javascriptArtifactCount": 90,
+  "esmExportCount": 372,
   "artifacts": [
     {
       "file": "runtime/arcane/modules/AI.js",
@@ -30,7 +30,7 @@
       "availability": "Browser + native bridge + TWiN Cloud",
       "protocol": "arcane-ai-browser-speech-configuration/1, AIProviderRuntime arcane-ai-provider/2 routes, globalThis.arcaneEvents, TWiN Cloud HTTPS, Arcane.ollama, Arcane.speech, Android WebView bridge",
       "normalization": "Complete mutable caller-owned browser speech authority, SDK-owned provider registration/replacement/disposal, explicit STT/TTS activation, normalized Whisper STT and Kokoro TTS execution with default capacities 1 and 4 respectively, explicit provider-neutral execution snapshots through status(role,{execution:true}), sticky readiness, canonical window.user readiness without compatibility-event object-identity admission or polling, exact ordered structural calls with required arguments.message, atomic nonblank all-ID tool-result sequencing, complete all-choice streaming/data validation, native Ollama structural adaptation, complete-response then all validated tool callbacks then completion ordering, observed async callbacks, Blob/File transcription, automatic repeated-formatting-mark removal from cloned outbound TTS input while caller and visible content stays exact, immediate exact-segment synthesis, per-call voice/speed capture, optional final-segment pause on the existing audio clock, optional per-call terminal playback completion, detached preparation with complete semantic DBOPFS audio reuse and same-owner pending request sharing, independent prepared playback without a model load for cached audio, ordered audio-clock scheduling, playable audio, active-generation TTS operation-failure routing, mute, and cancellation are normalized; provider/model/runtime/voice policy remains caller-owned. Both speech roles default execution.device to auto: webnn-npu when navigator.ml.createContext is exposed, then webgpu when navigator.gpu is exposed, then wasm for CPU execution. Failed backend loads clean up the pool before trying fresh Workers with the same prepared model and dtype; explicit devices never fall back. STT capacity only accepts 1; TTS accepts 1 through 4. Execution snapshots expose requestedDevice, selectedDevice, maxConcurrentRequests, and activeRequestCount for both roles; selectedDevice is null while unloaded and names the successful upstream session backend request when loaded. It does not prove every operation used the physical NPU: WebNN unsupported operations may use WASM, and compatibility depends on the browser, driver, hardware, and graph.",
-      "surface": "Browser-speech protocol/event/error/reason constants; default `AI`; read-only `providerRuntime`, `browserSpeechConfiguration`, and `browserSpeechDescriptor`; explicit `providerRuntime.status(role,{execution:true})` snapshots; `streamTTS(text,end,options={})` with optional voice, speed, pauseAfterMs, and waitForPlayback; automatic speech-input cleanup with SDK-internal preparation metadata; `prepareTTS({parts,storage,identity,signal,onState})` returning ordered segments, state, ready, getAudio(index), and cancel(); `playPreparedTTS(prepared,{signal,onState})` returning state, error, finished, pause(), resume(), and stop() with one playback lane per AI and observational state/error callbacks; configure/dispose speech, route lifecycle, declaration-validated chat/stream requests with exact ordered calls; optional streamRequest toolText:{name,field} and onToolText(text,call,displayId) for decoded selected argument text with actual call identity, distinct from ordinary prose and terminal tool execution; synthesis/transcription and playback controls; initializes from current canonical user readiness, installs `window.ai`, and projects `ai-ready` plus active-generation `ai-tts-failure`."
+      "surface": "prepareTTSPlayback(payload,signal) silently returns a real Blob or native-speech descriptor; native controls expose finished/released/state/error/pause/resume/stop, and actual release owns the playback lane. fetchTTS and durable prepareTTS report ARCANE_AI_TTS_AUDIO_EXPORT_UNAVAILABLE for native voices. Request-local model overrides remain exact and never mutate the configured model. Browser-speech protocol/event/error/reason constants; default `AI`; read-only `providerRuntime`, `browserSpeechConfiguration`, and `browserSpeechDescriptor`; explicit `providerRuntime.status(role,{execution:true})` snapshots; `streamTTS(text,end,options={})` with optional voice, speed, pauseAfterMs, and waitForPlayback; automatic speech-input cleanup with SDK-internal preparation metadata; `prepareTTS({parts,storage,identity,signal,onState})` returning ordered segments, state, ready, getAudio(index), and cancel(); `playPreparedTTS(prepared,{signal,onState})` returning state, error, finished, pause(), resume(), and stop() with one playback lane per AI and observational state/error callbacks; configure/dispose speech, route lifecycle, declaration-validated chat/stream requests with exact ordered calls; optional streamRequest toolText:{name,field} and onToolText(text,call,displayId) for decoded selected argument text with actual call identity, distinct from ordinary prose and terminal tool execution; synthesis/transcription and playback controls; initializes from current canonical user readiness, installs `window.ai`, and projects `ai-ready` plus active-generation `ai-tts-failure`."
     },
     {
       "file": "runtime/arcane/modules/AIModelSelectionController.js",
@@ -800,6 +800,31 @@
       "normalization": "Mail inputs/results normalized; transport failures mixed.",
       "surface": "default `Mail`, `resolveMailConfig()`; installs `window.mail`; `send()`."
     },
+    {
+      "file": "runtime/arcane/modules/MailApi.mjs",
+      "name": "MailApi.mjs",
+      "kind": "esm",
+      "exports": [
+        "MAIL_OUTBOX_IDEMPOTENCY_WINDOW_MS",
+        "MAIL_OUTBOX_PROTOCOL",
+        "MAIL_OUTBOX_STATES",
+        "MAIL_OUTBOX_TABLE",
+        "Mail",
+        "MailOutbox",
+        "MailTransportError",
+        "createMailOutbox",
+        "default",
+        "normalizeMailEndpoint",
+        "resolveMailConfig",
+        "sendMailReport",
+        "serializeMailReport"
+      ],
+      "summary": "Re-exports renderer Mail, durable outbox, and HTTP transport APIs through the public mail entrypoint.",
+      "availability": "Browser/native renderer; each re-export retains its owning module's host requirements",
+      "protocol": "Mail configuration and Arcane.mail.send or HTTP(S); arcane-mail-outbox/1",
+      "normalization": "Preserves the complete contracts of Mail.js, MailOutbox.mjs, and MailTransport.mjs without creating another transport or queue. Import retains Mail.js singleton installation in a browser window.",
+      "surface": "Default and named Mail, resolveMailConfig, MailOutbox/createMailOutbox and its four constants, MailTransportError, normalizeMailEndpoint, serializeMailReport, and sendMailReport."
+    },
     {
       "file": "runtime/arcane/modules/MailOutbox.mjs",
       "name": "MailOutbox.mjs",
@@ -835,6 +860,23 @@
       "normalization": "Endpoint, timeout, cancellation, network, HTTP, and response-contract errors are normalized.",
       "surface": "`MailTransportError`, `normalizeMailEndpoint()`, `serializeMailReport()`, and `sendMailReport()`."
     },
+    {
+      "file": "runtime/arcane/modules/MarkdownMedia.js",
+      "name": "MarkdownMedia.js",
+      "kind": "esm",
+      "exports": [
+        "decodeMarkdownMediaRecord",
+        "hydrateMarkdownMedia",
+        "parseMarkdownMediaReference",
+        "readMarkdownMedia",
+        "saveMarkdownMedia"
+      ],
+      "summary": "Stores complete local image records separately from Markdown and hydrates their stable references in rendered views.",
+      "availability": "Browser/native WebView with Blob, DOM, object URLs, and application-owned DBOPFS for storage operations",
+      "protocol": "arcane-media references, complete mediaType/dataUrl records, and DBOPFS",
+      "normalization": "Pure record decoding preserves complete content and singleton record layers. Hydration starts independent reads, removes unresolved local image sources before insertion, preserves successful siblings after an image failure, and owns cancellation, display URLs, and retained print resources.",
+      "surface": "saveMarkdownMedia({blob,tableName,fileName}), parseMarkdownMediaReference(reference), decodeMarkdownMediaRecord(value), readMarkdownMedia(reference), and hydrateMarkdownMedia(root,{signal}) returning ready/destroy/retain."
+    },
     {
       "file": "runtime/arcane/modules/MarkdownSpeech.js",
       "name": "MarkdownSpeech.js",
@@ -1010,7 +1052,7 @@
       "availability": "Browser or native WebView with the projected ChatEntity, DBOPFS, and a configured chat function or normalized Arcane.ai surface",
       "protocol": "Existing ChatEntity/DBOPFS methods plus provider-neutral chat request/result records",
       "normalization": "Preserves complete ordinary visible recurring provider history, one active raw structural continuation, every sanitized timestamped transcript record, and arbitrary nonempty caller-owned chat file names; commits live context atomically; falls back from optional streaming to configured non-stream transport; carries per-turn generation options while owning lifecycle callbacks; exposes complete data callbacks; accepts terminal-only structural calls; correlates every observed per-choice call against the exact validated terminal envelope before callback/persistence; atomically settles every pending ID once; and keeps malformed stored records readable without inventing or rewriting messages.",
-      "surface": "Default/named `PersistentAIChatSession`, `createPersistentAIChatSession()`; `create()`, `ai`, `chatEntity`, `fileName`, `ready()`, `history()`, `transcript()`, `settleMemory()`, `open()`, `send()`, and `stream()`. Optional constructor aiName and getter/setter accept a string; open/send/stream capture it before their first await. A nonblank application name is preserved exactly on the copied terminal message and retained assistant transcript, with the actual assistant record timestamp when available. Complete raw providerResponse stays unchanged; configured model context and memory omit the application display name. Existing history is never renamed or rewritten, and persist:false remains operation-only."
+      "surface": "Per-turn persist:false and chatEntity.persist=false retain neither request nor response after the active operation; completed send/stream results expose retained outside provider content. New durable records contain role/content/timestamp and optional application display name or public tool name/status; existing stored records remain untouched. Default/named `PersistentAIChatSession`, `createPersistentAIChatSession()`; `create()`, `ai`, `chatEntity`, `fileName`, `ready()`, `history()`, `transcript()`, `settleMemory()`, `open()`, `send()`, and `stream()`. Optional constructor aiName and getter/setter accept a string; open/send/stream capture it before their first await. A nonblank application name is preserved exactly on the copied terminal message and retained assistant transcript, with the actual assistant record timestamp when available. Complete raw providerResponse stays unchanged; configured model context and memory omit the application display name. Existing history is never renamed or rewritten, and persist:false remains operation-only."
     },
     {
       "file": "runtime/arcane/modules/PreferenceStore.js",
@@ -1042,6 +1084,19 @@
       "normalization": "Preserves complete original parts and JSON-compatible semantic context, shares pending matching work on the same owner/storage group, admits segments in order, stores complete Blobs and MIME metadata, retains successful audio after failure or cancellation, and separates generation readiness from playback.",
       "surface": "Named prepareSpeech({owner,parts,originalParts,selection,segmentation,storage,identity,signal,onState,synthesize}) returns {segments,state,ready,getAudio(index),cancel()}; applications use AI.prepareTTS and AI.playPreparedTTS so the shared AI owner retains segmentation, provider readiness, capacity, and playback."
     },
+    {
+      "file": "runtime/arcane/modules/PrintView.js",
+      "name": "PrintView.js",
+      "kind": "esm",
+      "exports": [
+        "createPrintView"
+      ],
+      "summary": "Prints complete current rendered content through one document-owned print lifecycle and shared print stylesheet.",
+      "availability": "Browser/native WebView with DOM, Fetch, and browser printing",
+      "protocol": "DOM snapshots, beforeprint/afterprint, and shared css/print.css",
+      "normalization": "Explicit requests await view-owned preparation; native Print captures synchronously. Rendered content, fonts, images, and resource retention remain complete. A true print result confirms only a requested browser dialog; snapshots and retained media survive until afterprint.",
+      "surface": "createPrintView({host,content,title,active,priority,signal,onError,retain,prepare}) returns print() and destroy(). Import awaits the required shared print stylesheet."
+    },
     {
       "file": "runtime/arcane/modules/QRCode.min.js",
       "name": "QRCode.min.js",
@@ -1194,9 +1249,9 @@
       ],
       "summary": "Preserves exact nonblank stored segment text; removes repeated formatting marks from only each outbound synthesis copy; eagerly submits complete parts to a capacity-advertising fetchTTS provider while keeping playback indexed; and retains serialized one-segment lookahead for other clients.",
       "availability": "Browser + compatible AI/native bridge",
-      "protocol": "AI.fetchTTS plus providerRuntime TTS execution capacity, or compatible serialized Arcane.speech.synthesize; globalThis.arcaneEvents, Blob URLs, audio element",
+      "protocol": "AI.prepareTTSPlayback or AI.fetchTTS plus providerRuntime TTS execution capacity, native provider.prepare, or compatible serialized Arcane.speech.synthesize; globalThis.arcaneEvents, Blob URLs/audio element, and native playback controls",
       "normalization": "Exact nonblank split/part input strings are preserved in mutable records. Each synthesis request clones that part, removes repeated formatting marks from only the outbound input, and carries SDK-internal preparation metadata to prevent a second cleanup pass. A capable provider receives complete segments immediately and owns bounded FIFO admission; URLs and playback stay in exact input order. Native/custom clients remain serialized. Canonical state dispatch precedes the optional synchronous onState callback. Cancellation, Replay recovery, Blob results, and lifecycle state are normalized; provider failures remain external.",
-      "surface": "SpeechPlayback class/default, mutable `SPEECH_VOICE_OPTIONS` records, mutable `SPEECH_VOICE_ALIASES` membership, `SPEECH_PLAYBACK_STATE_EVENT`, optional constructor `onState(detail)`, `splitSpeechText()`, canonical playback lifecycle events, cancellation, and destroy APIs."
+      "surface": "prepareTTSPlayback or direct native provider.prepare may return silent native-speech descriptors. autoplay:false stays silent; actual completion advances ordered parts and failed cancellation retains controls until released. Replay preserves completed segments and retries only missing failed generation. SpeechPlayback class/default, mutable `SPEECH_VOICE_OPTIONS` records, mutable `SPEECH_VOICE_ALIASES` membership, `SPEECH_PLAYBACK_STATE_EVENT`, optional constructor `onState(detail)`, `splitSpeechText()`, canonical playback lifecycle events, cancellation, and destroy APIs."
     },
     {
       "file": "runtime/arcane/modules/StaticDocumentCatalog.js",

package/docs/reference/protocols.md

@@ -69,8 +69,10 @@ include `arcane-os/preference-store`, `arcane-os/speech-playback`,
 `arcane-os/model-definition`, `arcane-os/conversation-timebox`,
 `arcane-os/conversation-action-items`, `arcane-os/conversation-closing-report`,
 and `arcane-os/chat-records`.
-`arcane/PreferenceStore` and `arcane/SpeechPlayback` remain their established
-browser import-map names. The additional portable `arcane-os/speech-text`
+Physical, nested and virtual layouts also retain the established
+`arcane/PreferenceStore` and `arcane/SpeechPlayback` browser names. Direct
+installed-package root apps use the package-namespaced imports. The additional
+portable `arcane-os/speech-text`
 subpath owns shared speech-input cleanup and has the same
 managed browser key. `arcane-os/mail` remains the existing Mail aggregation.
 There is
@@ -324,19 +326,20 @@ map-artifact lifecycle below remains separate.
 
 ## Browser runtime delivery
 
-External and modern integrated workspaces keep the same application URLs and a
-browser-standard import map. Each selected app owns
-`apps/<id>/modules/arcane.importmap.json`; the exact canonical JSON is also
+External and modern integrated workspaces use a browser-standard import map.
+Each selected app owns `modules/arcane.importmap.json` relative to its app root:
+the repository root for a standalone app, or `apps/<id>/` for an explicitly
+nested app. The exact canonical JSON is also
 embedded in its HTML entry as a managed `<script type="importmap"
 data-arcane-import-map>`. The map follows `<base>` and precedes module scripts,
 classic scripts, and module preloads, so application code can use stable named
 imports such as:
 
 ```javascript
-import ollama from 'arcane/Ollama';
+import ollama from 'arcane-os/modules/Ollama.js';
 ```
 
-The physical-v1 tree lives entirely beneath `arcane/`. SDK `0.5.17` projects the
+The supported physical-v1 tree lives entirely beneath `arcane/`. It projects the
 complete canonical runtime and browser runtime selected by the installed SDK
 package. Runtime dependencies stay under
 `arcane/dependencies/`; the SDK event and browser-AI closure stays under
@@ -351,9 +354,9 @@ integrated physical route uses the same ordered include list in its one route.
 Omitting only that final optional entry is compatible. Removing, reordering, or
 renaming any preceding entry changes the physical contract.
 
-The `0.5.17` map derives its complete entries from the selected runtime graph;
+The map derives its complete entries from the selected runtime graph;
 application source imports do not select a fixed entry count. The operation
-result reports `imports`, `entryCount`, and `excludedModules`; reached-file
+result reports `imports`, `documentCount`, and `excludedModules`; reached-file
 traversal remains internal. The
 managed graph exposes `arcane-os/event-manager`, `arcane-os/ai/browser-wasm`,
 `arcane-os/ai/browser-speech`, `arcane-os/preference-store`, and
@@ -371,16 +374,19 @@ The focused physical targets remain stable when their bindings are reached:
 | `arcane-os/preference-store` | `./arcane/modules/PreferenceStore.js` |
 | `arcane-os/speech-playback` | `./arcane/modules/SpeechPlayback.js` |
 | `event-pubsub` | `./arcane/sdk/dependencies/event-pubsub/index.js` |
+| `strong-type` | `./arcane/dependencies/strong-type/index.js` |
 | `./node_modules/strong-type/index.js` | `./arcane/dependencies/strong-type/index.js` |
 
-There is no `arcane-os` package-root mapping, bare `strong-type` mapping, or
-catch-all `arcane/` prefix. Classic scripts, workers, stylesheets, and other
+Direct installed routes translate these targets to their actual npm destinations,
+including aliases. There is no `arcane-os` package-root mapping or catch-all
+`arcane/` prefix. Classic scripts, workers, stylesheets, and other
 non-ESM assets use their documented URL or host loading contract rather than
 invented package bindings. Development serves the selected app plus the
 complete selected tree.
 Packaging copies the same map, app entry, and physical content into the
 [selected package output](#app-selected-package-output), defaulting to `dist/<id>`;
-targets never resolve through the consumer workspace's root `node_modules/`.
+physical targets stay beneath the selected `arcane/` routes, while direct
+installed targets retain `node_modules/<dependency>/...` inside the output.
 The two lowercase static runtime package specifiers above and the shared
 speech-text helper are exact npm package exports, so Node and managed-browser
 source can share those specifiers
@@ -390,42 +396,34 @@ without data URLs, copied modules, or a consumer-owned loader.
 The shared app-document owner derives the configured entry plus the
 deterministic admitted `.html`/`.htm` inventory from the descriptor's package
 include/exclude rules. `import-map`, development, and packaging all reuse that
-discovery. One transaction writes the artifact and the same managed
-JSON into every selected document. The result reports
-`documentPaths`, `documentCount`, and `files`: artifact first, configured entry
-second, then additional documents as `role:"document"`. The public CLI keeps
+discovery. Import-map generation prepares the complete selection, then writes
+the artifact and the same managed JSON into each selected document in order.
+The result reports
+`artifactPath`, `entryPath`, `documentPaths`, `documentCount`, the complete
+`imports` record, and `committed`. `documentPaths` lists the configured entry
+first, followed by the other selected documents. The public CLI keeps
 its existing two-option command; callers never maintain a separate page list.
 
-An external package and development server expose the runtime
-inventory at `/ARCANE_RUNTIME_PROJECTION.json`:
-
-```javascript
-{
-  schemaVersion: 1,
-  kind: 'arcane-app-runtime-projection',
-  sdkVersion,
-  pathPrefix: 'arcane/',
-  files: [{path}]
-}
-```
-
-The projection contains the complete public paths relative to its declared
-`pathPrefix:'arcane/'` (for example, `modules/...` and `sdk/...`). It does not
-expose the private `/ARCANE_APP_RELEASE.json`. Genuinely malformed projection
-data fails `ARCANE_RUNTIME_PROJECTION_INVALID`.
+The managed import map derives its complete bindings from the selected runtime
+files. Enabled PWA delivery publishes its resource inventory in
+`arcane-offline.json`; packaging records its complete file inventory in
+`ARCANE_APP_RELEASE.json`. There is no generated
+`ARCANE_RUNTIME_PROJECTION.json` endpoint in the current serving or packaging
+contract.
 
 External `validateWorkspace()` results also expose `sdkInstallation` with
 exactly `dependencyName`, `packageSource`,
 `canonicalPackageRoot`, `packageName`, `packageVersion`, `runtimeRoot`,
 and `browserRuntimeRoot`. A
-workspace may use the canonical dependency name or one exact npm alias such as
-`npm:arcane-os@0.5.17`; the physical package manifest must still identify
-exactly as `arcane-os@0.5.17`. Canonical-plus-alias duplicates, multiple aliases,
-links/junctions, indirect package roots, or version drift are reported.
-
-For external workspaces, `arcane dev` serves the projected `arcane/` root,
-including `arcane/sdk` and `arcane/dependencies`, alongside the selected
-application. Integrated workspaces retain their configured physical routes.
+workspace may use the canonical dependency name or one npm alias such as
+`npm:arcane-os@0.51.1`; the installed package manifest identifies `arcane-os`
+and supplies its actual version. The resolver requires one declaration and a
+direct physical installation with runtime and browser-runtime directories.
+The application's normal npm declaration and lockfile own version selection.
+
+For external workspaces, `arcane dev` serves the selected direct npm, virtual
+installed or physical routes alongside the selected application. Integrated
+workspaces retain their configured physical routes.
 The explicit live-source development mapping remains a separate development
 path and does not rewrite the installed projection.
 
@@ -437,21 +435,24 @@ transport and host RPC remain separate layers.
 <details>
 <summary>Refresh lifecycle and managed-file commit behavior</summary>
 
-Scaffolding (`new` and `init`) creates the map. `dev` refreshes once before
-binding. `import-map` refreshes every admitted document explicitly.
-Non-dry-run `package`, browser `build`, and paired native packaging refresh
-before collecting source. Packaging does not run tests or checks automatically.
+Root scaffolding reports the map as pending until its SDK dependency is installed;
+root `init` with an installed SDK and explicit nested scaffolds generate it.
+`dev` refreshes once before binding. `import-map` refreshes every admitted
+document explicitly. `package`, browser `build`, and paired native packaging
+consume the saved source and managed maps. Refresh maps through `import-map` or
+ordinary `dev` startup when needed. Packaging does not run tests or checks
+automatically.
 Explicit `test` and `check` operations read the existing map without rewriting it;
 `verify`, `bundle`, and browser `run` do not refresh. Dry-run packaging/build
 validates an existing map without rewriting it, and `import-map` itself has no
 supported dry-run.
 
-Generation stages the artifact and every selected HTML document beside their
-destinations and uses backups to restore the prior managed files after a
-handled pre-commit failure. Success reports `committed: true` and the complete
-managed path inventory. Cleanup failures after commit remain warnings. This is
-a handled-error transaction, not a claim of one filesystem-atomic rename for
-all files and not a durable crash journal.
+Generation prepares the artifact and every selected HTML document, checks their
+destinations, then writes the artifact followed by the documents. Cancellation
+or a write failure can leave completed writes in place. Success reports
+`committed: true` and the selected document paths. Event-delivery failure after
+successful writes is returned as degraded delivery; it does not undo those
+writes. There is no all-file rollback or durable crash journal.
 
 When tests are explicitly selected, external app tests receive an
 `arcane-test-import-map/1` context for that app's managed map. Each isolated
@@ -478,9 +479,13 @@ comes from the selected runtime and owns independent `llm`, `stt`, and
 `tts` selections. This SDK release ships browser-WASM LLM and browser
 speech provider/2 adapters and also adapts selected TWiN Cloud LLM,
 Core-backed Ollama LLM, on-device Whisper STT, and on-device Kokoro TTS routes
-into provider/2. There is no cloud speech route;
-other native, Core, or cloud routes require an externally supplied compatible
-adapter. The singleton itself is not an authentication or capability token. It
+into provider/2. Built-in speech selections use `LOCAL_SPEACH` with
+`whisper-small` for STT and `kokoro` for TTS; these local routes need no TWiN key.
+Applications may explicitly configure `createTwinCloudTTSProvider()` with their
+TWiN key for cloud TTS. Native browser recognition and synthesis providers are
+also available through `arcane-os/ai/browser-speech`; their browser-owned engines
+may use remote services. Other routes require a compatible provider adapter.
+The singleton itself is not an authentication or capability token. It
 normalizes inspection, model authority,
 load/unload/dispose, cancellation, stream cleanup, status, and startup
 barriers. Each selected provider retains its real execution requirements.
@@ -491,8 +496,9 @@ For a browser-only LLM,
 [`arcane-os/ai/browser-wasm`](ai/browser-wasm.md) exposes `createArcaneAI()`
 and an adapter into the same provider-neutral lifecycle. For browser speech,
 [`arcane-os/ai/browser-speech`](ai/browser-speech.md) creates independent
-Whisper STT and Kokoro TTS providers that register directly with the normalized
-runtime. The SDK supplies mechanism; applications retain model/runtime choice,
+Whisper STT, Kokoro TTS, native browser recognition/synthesis and explicit cloud
+TTS providers. These providers register directly with the normalized runtime.
+The SDK supplies mechanism; applications retain model/runtime choice,
 licenses, prompts, tools, voices, and disclosure policy.
 
 ### Browser-WASM LLM lifecycle

package/docs/reference/pwa.md

@@ -86,9 +86,11 @@ establish any particular installed application's browser lifecycle.
 `offline.include` and `offline.exclude` select literal paths or directory
 prefixes from the selected emitted inventory. An omitted or empty include list
 selects that inventory; exclusions subtract from it. App files use app-relative
-paths and shared runtime files use paths such as `arcane/sdk/pwa.mjs`.
-For example, selecting `modules` matches packaged
-`apps/<id>/modules/...`; emitted offline URLs keep the `apps/<id>/` prefix.
+paths. Shared runtime selections follow the configured destinations: for example,
+`node_modules/arcane-os/browser-runtime/pwa.mjs` for a direct installed route,
+or `arcane/sdk/pwa.mjs` for a physical or virtual route.
+For example, selecting `modules` matches a root app's `modules/...` or a nested
+app's `apps/<id>/modules/...`; emitted offline URLs retain that selected layout.
 The application entry and generated PWA shell records are retained. Select the
 resources needed by every offline page, including its shared modules and styles.
 The worker script itself is never an application cache entry.
@@ -120,9 +122,10 @@ Browser packaging emits these files at the selected deployment root:
 | `arcane-sw.js` | Stable worker URL with the selected offline manifest embedded in its source. |
 | `arcane-pwa.mjs` | Independent registration and installation-component bootstrap importing the SDK client. |
 
-The selected app files remain under `apps/<id>/`, with shared runtime routes
-alongside them. The SDK supplies a root `index.html` launcher when selected
-shared content has no root page. The generated PWA files stay at the deployment
+Standalone app files stay at the output root. Explicit multi-app workspaces
+retain their selected app under `apps/<id>/`, with shared runtime routes alongside
+it. The SDK supplies a root `index.html` launcher when selected content has no
+root page. The generated PWA files stay at the deployment
 root so their worker can serve the selected app and shared resources. The
 worker is registered for the deployment root independently of any app-authored
 manifest scope.
@@ -140,12 +143,13 @@ The same bootstrap starts one initially hidden `pwa-install.html` component with
 the generated manifest's app name. Component loading and worker registration
 proceed independently.
 
-The selected PWA browser delivery removes only SDK-owned `arcaneVersion` fields
+All SDK browser-resource delivery removes only SDK-owned `arcaneVersion` fields
 from actual local resource references, including the managed import map. Authored
 fields such as `v`, encoded and repeated fields, empty query segments, fragments,
 source spelling and unrelated payloads are preserved. The offline
-manifest now carries release information. Non-PWA and native delivery retain
-the [existing asset version contract](asset-versioning.md).
+manifest carries release information. Non-PWA and native packaging use the same
+[clean local resource URLs](asset-versioning.md). Native packaging does not
+generate the browser PWA worker, installation manifest or registration bootstrap.
 
 ## Development and hosting
 
@@ -157,9 +161,11 @@ Package-only applications retain their existing descriptor workflow.
 
 With the external [`installed-v1` routes](protocols.md#installed-package-browser-routes),
 the server inventories the selected SDK directly in `node_modules`. Runtime
-resources retain their public `arcane/`, `arcane/sdk/`, and
-`arcane/dependencies/strong-type/` URLs, so offline selections use those logical
-paths rather than package filesystem paths. No workspace `arcane/` tree or
+resources follow the configured destinations. Direct routes use real
+`node_modules/<dependency>/...` URLs, including an npm alias when selected.
+Earlier virtual routes retain their `arcane/`, `arcane/sdk/`, and
+`arcane/dependencies/strong-type/` destinations. Offline selections use those
+same emitted paths. No workspace `arcane/` tree or
 `arcane.lock.json` is needed. Packaging uses the same route selection and copies
 the selected resources into the portable output; existing physical projections
 remain supported.
@@ -179,7 +185,8 @@ write is needed. Edits to selected source files are picked up by the next due
 page-load check while the server remains running.
 
 For an enabled application, `arcane dev` serves the generated PWA files at the
-origin root and starts at the selected app page under `/apps/<id>/`. Use one
+origin root and starts at the selected app entry: `/index.html` for a standalone
+root app with that entry, or `/apps/<id>/<entry>` for a nested app. Use one
 selected app per development origin. The SDK uses `node-http-server` for source
 and packaged-preview serving, including conditional resource responses.
 Arcane development servers default to HTTPS, including localhost, and packaged

package/docs/reference/runtime-components.md

@@ -4,14 +4,21 @@ Arcane components are reusable HTML fragments loaded through the shared `<html-i
 
 A component file does not register its own custom element. The `<html-import>` host fetches the fragment from the same origin, attaches an open shadow root, runs its inline scripts with `this` bound to the host, and publishes `html-import-ready` or `html-import-error`. Component methods and properties are attached to that host.
 
+Import the loader through `arcane-os/modules/HTMLImport.js` and the SDK-managed
+import map. Component `href` values are asset URLs, so use the application's
+configured runtime route. The default root npm layout serves components from
+`/node_modules/arcane-os/runtime/arcane/components/`. Other `/arcane/...`
+examples on this page describe an explicitly configured physical or virtual
+route; direct npm applications use their corresponding installed-package URLs.
+
 ## Basic loading pattern
 
 ```html
 <script type="module">
-  import '/arcane/modules/HTMLImport.js';
+  import 'arcane-os/modules/HTMLImport.js';
 </script>
 
-<html-import id="widget" href="/arcane/components/weather-widget.html"></html-import>
+<html-import id="widget" href="/node_modules/arcane-os/runtime/arcane/components/weather-widget.html"></html-import>
 
 <script type="module">
   const widget = document.querySelector('#widget');

package/docs/reference/runtime-entities.md

@@ -11,6 +11,13 @@ Entity creation and serialization are usually cross-host. Methods that touch
 DOM, DBOPFS, local storage, AI, or object URLs require the corresponding browser
 or native-WebView dependency.
 
+Apps import entities with `arcane-os/entities/<file>.js`; the SDK-managed
+import map resolves these names through the selected runtime routes. Default
+root applications use their installed npm package directly. Absolute
+`/arcane/entities/...` examples below assume an explicitly configured physical
+or virtual `/arcane` route. Use the corresponding package specifier in direct
+npm applications; entity inputs and behavior are the same.
+
 ## Canonical inventory
 
 | Module | Exports | Capability | Availability / normalization |
@@ -86,12 +93,17 @@ with complete ordinary visible call, public result, and assistant content.
 storage boundary. User and assistant records contain role, complete
 visible content, and their real timestamp. An assistant record may also carry
 its application-owned display `name`. A visible tool record may
-additionally carry its public name and plain result status, while its `content`
-comes only from the tool call's required user-facing `message`. System prompts,
+additionally carry its public name and plain result status. A requested-call
+record uses the call's required user-facing `message`; a settled tool result
+uses its supplied public message. System prompts,
 reasoning, provider-extension fields, memory flags, raw tool calls, call IDs,
 argument objects, and raw tool returns never enter new DBOPFS writes.
 Messages added with `persist:false` participate only in their current operation;
 they are not retained in `messages`, `transcript`, memory extraction, or DBOPFS.
+Setting `chat.persist=false` applies the same rule to new additions: the append
+returns `false` before adding records to retained state or starting a write.
+Existing retained messages and saved history remain unchanged. An already
+accepted persistence write keeps its operation ownership and may finish.
 One complete nonblank assistant record is also a durable conversation entry, so
 a model-authored opening can be stored and survive maintenance before the first
 ordinary user turn. No synthetic user record is required or written.

package/docs/reference/runtime-modules.md

@@ -2,7 +2,17 @@
 
 Every file shipped under `runtime/arcane/modules/` appears here. Start with the capability and example; expand into [protocol and host architecture](protocols.md) only when transport detail matters.
 
-Apps import renderer ESM from `/arcane/modules/<file>`. Classic scripts, the OPFS worker, uPlot stylesheet, and vendor license are called out explicitly. Importing a module does not grant a native capability.
+Apps import renderer ESM with `arcane-os/modules/<file>`, including the `.js`
+or `.mjs` extension. The SDK-managed import map resolves that name through the
+application's selected runtime routes. Root applications use the installed
+npm package directly by default. Absolute `/arcane/modules/<file>` examples
+below describe an explicitly configured physical or virtual `/arcane` route;
+that directory is not required by a direct npm layout.
+
+Classic scripts, the OPFS worker, uPlot stylesheet, and vendor license use
+their actual configured asset URLs and are called out separately. Importing a
+module does not grant a native capability. See [installed-package browser
+routes](protocols.md#installed-package-browser-routes) for route selection.
 
 Applications own response-detail preferences, their saved values, and any
 verbosity instruction appended to the system prompt. The former
@@ -94,6 +104,7 @@ own asynchronous work, cancellation, and backpressure.
 | [`LocalAIReadiness.js`](#localaireadinessjs) | esm | Derives selected AI requirements and returns a complete readiness/recovery report across browser, desktop, and Android modes. | Browser/native hybrid | Fully normalized report and stable error codes; browsers never probe Ollama. |
 | [`LocalAIReadinessController.js`](#localaireadinesscontrollerjs) | esm | Coordinates local-AI status component checks, ensured recovery, availability projection, and teardown. | Browser/native hybrid | Normalized controller state and change events. |
 | [`Mail.js`](#mailjs) | esm | Builds complete reports and prefers the native mail capability with an explicit HTTP transport fallback. | Browser/native hybrid + cloud | Mail inputs/results normalized; transport failures mixed. |
+| [`MailApi.mjs`](#mailapimjs) | esm | Public renderer entrypoint for Mail, durable outbox, and HTTP transport APIs. | Browser/native renderer | Re-exports preserve their owning module's contracts. |
 | [`MailOutbox.mjs`](#mailoutboxmjs) | esm | Persists complete mail reports before delivery and normalizes idempotent enqueue, retry, reconciliation, and invalid-record maintenance. | Browser/native WebView or compatible injected host | Complete records, full work, cancellation, and lifecycle states normalized; storage, lock, and delivery failures coded. |
 | [`MailTransport.mjs`](#mailtransportmjs) | esm | Sends one complete mail report to a normalized HTTP(S) endpoint. | Browser/server with fetch + cloud | Normalized endpoint and transport errors; remote detail preserved. |
 | [`MarkdownMedia.js`](#markdownmediajs) | esm | Saves local Markdown images separately, decodes complete stored records, and resolves stable references in rendered views. | Browser / supported native WebView | Complete image records, concurrent display reads, cancellation, and print-owned URL lifetime. |
@@ -184,6 +195,14 @@ payload; an omitted value remains absent. The provider owns interpretation.
 This option does not switch a loaded browser-WASM model or its lifecycle:
 explicit provider/model selection and activation remain necessary there.
 
+Both object-form methods also forward an optional request-local `temperature`
+unchanged to built-in TWiN Cloud, including through its provider-runtime
+adapter. Explicit `0` is preserved; omission or `undefined` leaves the outbound
+field absent and preserves the provider default. The value is not clamped or
+saved as a preference, concurrent calls remain independent, and retries reuse
+the same value. This adds no output limit or native Ollama option mapping;
+other registered providers retain their existing interpretation of the option.
+
 Built-in cloud chat decodes an HTTP error body once as JSON or text and rejects
 with that complete value unchanged. It does not reconstruct an Error, replace
 the message, or add `providerMessage`, `status`, or an SDK failure code to the
@@ -2485,7 +2504,11 @@ Defines the same-origin `<html-import>` loader with open shadow root, inline scr
 
 ### Public surface
 
-default `HTMLImport`; registers `html-import`; `connectedCallback()` and `ready`.
+Default export: the constructor registered for `html-import`. When no
+constructor is registered, the module registers its SDK loader, whose
+`connectedCallback()` owns fragment loading and whose `ready` property reports
+completion. The browser invokes the connection callback when the host enters
+the document.
 
 Registration occurs once per custom-element registry. Imports through different
 module URLs reuse and export the registered constructor, including overlapping
@@ -2648,6 +2671,40 @@ import * as module from '/arcane/modules/Mail.js';
 console.log(Object.keys(module));
 ```
 
+## MailApi.mjs
+
+### Overview
+
+The managed-browser `arcane-os/mail` entrypoint re-exports the existing
+[`Mail.js`](#mailjs), [`MailOutbox.mjs`](#mailoutboxmjs), and
+[`MailTransport.mjs`](#mailtransportmjs) APIs. Their configuration, storage,
+delivery, errors, and lifecycle remain owned by those modules.
+
+### Public surface
+
+Exact exports: `default`, `Mail`, `resolveMailConfig`,
+`MAIL_OUTBOX_IDEMPOTENCY_WINDOW_MS`, `MAIL_OUTBOX_PROTOCOL`,
+`MAIL_OUTBOX_STATES`, `MAIL_OUTBOX_TABLE`, `MailOutbox`, `createMailOutbox`,
+`MailTransportError`, `normalizeMailEndpoint`, `sendMailReport`, and
+`serializeMailReport`.
+
+`default` and `Mail` refer to the same renderer Mail class. Import retains
+`Mail.js`'s browser singleton installation; it creates no additional queue or
+transport. Node resolves `arcane-os/mail` through the separate
+[Node mail entrypoint](mail.md).
+
+### Example
+
+```javascript
+import {resolveMailConfig} from 'arcane-os/mail';
+
+const mailConfig = resolveMailConfig(
+    {appName:'dragon-dispatch', endpoint:'https://mail.example.com/v1/mail'},
+    {document:null, location:new URL('https://dispatch.example.com/')}
+);
+console.log(mailConfig.endpoint);
+```
+
 ## MailOutbox.mjs
 
 ### Overview