arcane-os 0.51.1 → 0.52.0

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

@@ -51,16 +51,12 @@ App-scoped managed browser imports have three supported control-plane entrypoint
 uses `arcane import-map`; Node callers use
 `executeOperation('import-map', options)` or
 `createToolchain(defaults).importMap(options)`. These are three routes to the
-same app-scoped operation, not three import-map formats. Each route discovers
-the selected descriptor's directly navigable admitted `.html`/`.htm` documents
-through the package include/exclude rules and writes one canonical map to the
-artifact plus every such document. The current marker is exactly one matching
-`meta[name="arcane-app-id"]`; an unmarked secondary page with an active `base`
-remains admitted under the current secondary-document rule. Wrong or duplicate
-explicit identity fails, and the selected page then must pass exact path-relative
-base validation.
-Included HTML with neither signal is a component fragment and remains a
-complete package file.
+same app-scoped operation, not three import-map formats. Each route uses the
+[application document selection](#application-document-selection) shared by
+inspection, development and packaging, and writes one canonical map to the
+artifact plus every selected document. Each selected page retains the existing
+path-relative base requirement. Included component fragments remain complete
+package files and keep their existing component processing.
 Public lowercase runtime subpaths resolve directly to canonical runtime-module
 namespaces from both Node package exports and managed browser keys. These
 include `arcane-os/preference-store`, `arcane-os/speech-playback`,
@@ -69,8 +65,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
@@ -96,6 +94,48 @@ materializes the complete required SDK runtime,
 browser-runtime, and managed-import-map closure inside that app's own artifact.
 No application polls for SDK changes.
 
+## Application document selection
+
+An authored schema-2 `arcane-app.json` may select the HTML pages that receive
+application-document processing through `package.documents`:
+
+```json
+{
+  "package": {
+    "entry": "index.html",
+    "include": ["index.html", "pages", "originals", "modules", "css"],
+    "documents": ["index.html", "pages/viewer.html"]
+  }
+}
+```
+
+This is a package excerpt. Each `documents` member is a literal app-root-relative
+`.html` or `.htm` file path, not a directory or glob. Every selected document
+must already be present in the app's included, non-excluded files. The entry is
+always selected first, followed by the other selected paths in deterministic
+lexical order without duplicates. An empty list selects only the entry. The
+authored `documents` declaration remains as supplied, including `[]`.
+
+Omitting `documents` preserves automatic discovery: the SDK selects the entry
+and included secondary HTML pages with an active `<base>`. A
+`meta[name="arcane-app-id"]` marker does not select a page. Selected pages retain
+the existing requirement for one path-correct active base.
+
+The schema-1 `arcane-package.json` field is `documents` at the top level.
+Descriptor projection and synthesis preserve an omitted property as omitted
+and an authored empty list as `[]`. Package-only applications may author that
+schema-1 field directly. Ordinary inspect, import-map, dev and package operations
+use the same declaration; there is no document-selection CLI flag.
+
+Document selection controls application-document scanning, base handling,
+managed import maps and PWA injection. It does not change `include`/`exclude`,
+serving, package membership or offline resource selection. With an explicit
+list, other included HTML documents retain their exact content, even when a
+selected page references them through an iframe. They remain available as
+included resources without receiving application-document processing.
+Component processing and shared runtime-resource traversal retain their existing
+behavior. Offline inclusion still follows the app's PWA resource selection.
+
 ## App-selected package output
 
 An app may set `"outputDirectory": "ai"` in its schema-1
@@ -324,19 +364,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 +392,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 +412,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 +434,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 +473,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 +517,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 +534,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

@@ -58,6 +58,27 @@ previous source identity while its start URL and scope move to the root. An
 authored `manifest.id` remains authoritative. Packaged default identity remains
 `./`. App identity and saved application data remain unchanged.
 
+### Application pages and preserved HTML resources
+
+Optional `package.documents` in `arcane-app.json` selects the app-root-relative
+`.html`/`.htm` pages that receive managed import maps and PWA links/bootstrap.
+Its schema-1 projection is `arcane-package.json`'s top-level `documents`.
+For example, `"documents": ["index.html"]` selects the entry while other
+included HTML documents retain their exact content. The entry is always selected;
+`[]` also selects only the entry. Omitting the property preserves automatic
+discovery of the entry and included secondary pages with an active `<base>`.
+Selected pages retain the existing path-correct base requirement.
+
+This declaration does not add or remove resources from `package.include`,
+`package.exclude`, serving, packaging or the offline inventory. Included
+originals remain available and can be cached under the normal offline selection,
+including when a selected page displays them in an iframe. With an explicit
+list, those unselected documents are not scanned as application pages or given
+managed import maps, base handling or PWA injection. HTML-import components and
+shared runtime-resource traversal keep their existing processing. See
+[application document selection](protocols.md#application-document-selection)
+for ordering and the complete declaration contract.
+
 ### Root generated output
 
 For a standalone application, `appsRoot: "."` places the app at its repository
@@ -86,9 +107,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 +143,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.
@@ -133,19 +157,22 @@ their app and SDK versions match. It is not a content measurement.
 
 The package owns its selected inventory once, after any app adapter finishes.
 It follows actual resource references to include meaningful query variants.
-Generated application pages receive a manifest link and an `async` module
+Selected application pages receive a manifest link and an `async` module
 marked `data-arcane-pwa`. Existing application scripts retain their order.
 PWA registration does not wait for models, storage, preferences or page rendering.
 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
-from actual local resource references, including the managed import map. Authored
-fields such as `v`, encoded and repeated fields, empty query segments, fragments,
+SDK processing of selected application pages, components and runtime resources
+removes only SDK-owned `arcaneVersion` fields from actual local resource references,
+including the managed import map. Explicitly unselected HTML documents keep their
+exact content. 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 +184,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.
@@ -173,13 +202,14 @@ If `package.pwa.offline.include` is nonempty, the resource must also
 match that offline selection and must not match `offline.exclude`. Adding a
 path only to the offline selection does not add it to the app's resources.
 The running source server reads changed app descriptors before the next app,
-root-navigation or generated-PWA request. Include/exclude rules, the entry and
-PWA settings share the current selection; no restart or package projection
-write is needed. Edits to selected source files are picked up by the next due
+root-navigation or generated-PWA request. Include/exclude rules, the entry,
+document selection and PWA settings share the current selection; no restart or
+package projection 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.