arcane-os 0.88.1 → 0.90.0

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

@@ -981,7 +981,7 @@
       ],
       "availability": "Browser and supported native WebViews",
       "transport": "HTMLImport + DOM; injected Arcane/provider modules where listed",
-      "normalization": "Preference/native appearance behavior mixed; selected button background, text and outline remain visible during hover while the hover fill applies only to unselected enabled buttons; no component-ready contract"
+      "normalization": "Preference/native appearance behavior mixed; selected button background, text and outline remain visible during hover while the hover fill applies only to unselected enabled buttons; no component-ready contract; pending choices expose aria-disabled and ignore repeated activation while staying in the keyboard focus flow; completion and failure do not move focus, and an unavailable Skin choice retains native disabling"
     },
     {
       "file": "runtime/arcane/components/unified-inbox.html",

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

@@ -30,8 +30,8 @@
       "summary": "Owns provider-selectable chat and the one-time caller-authority browser STT/TTS configuration, lifecycle, synthesis, transcription, and playback boundary.",
       "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, default repeated-formatting-mark removal from cloned outbound TTS input, explicit textFormat:'plain' preservation for complete synthesis/preparation while streaming cleanup remains automatic and caller/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; each preparation owns its pending activation interest, final-interest cancellation aborts that activation while other interests preserve it, complete cache hits start no model, and cancellation after readiness leaves the ready model loaded; 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": "Native fetchTTS(payload,signal) and fetchSTT(audio,signal) forward caller cancellation separately from their complete Core speech payloads, normalize aborts to AbortError and suppress late results; actual engine interruption remains service-owned. 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; default speech-input cleanup with SDK-internal preparation metadata and explicit complete-call textFormat:'plain' consumed before engine dispatch; `prepareTTS({parts,storage,identity,textFormat,signal,onState})` returning ordered segments, state, ready, getAudio(index), and cancel(); async `readPreparedTTS({parts,textFormat,storage,identity,signal,onState})` returning a complete ready handle or null through the same semantic matcher, with no activation, unmute, synthesis, playback, storage writes, or partial repair; manifest, audio availability, and returned-handle reads use DBOPFS createTable:false so absent tables remain absent; supplied adapters own that read-existing behavior; missing matches/audio return null, malformed metadata and storage failures reject, and omitted storage sees only completed matching same-AI in-memory audio; hits replay ready state, misses emit nothing, and the lookup signal detaches on settlement while returned-handle cancellation stays independent; `prepareAudioOutput()` returning the persistent WebAudio handle {kind,state,contextState,error,subscribe,resume,dispose} without resume, unmute, model load, sources, sound, or gesture listeners; current-state replay and output-specific canonical `AI_AUDIO_OUTPUT_STATE_EVENT` (`ai-audio-output-state`), with ready only for an actually running context; explicit owner disposal observes context-bound cleanup and close; `playPreparedTTS(prepared,{signal,onState,audioOutput})` returning state, error, finished, pause(), resume(), and stop() with one playback lane per AI and observational state/error callbacks; explicit live same-AI audioOutput borrows its context until owner disposal, while omission or null preserves per-playback terminal close; 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`."
+      "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, default repeated-formatting-mark removal from cloned outbound TTS input, explicit textFormat:'plain' preservation for complete synthesis/preparation while streaming cleanup remains automatic and caller/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; each preparation owns its pending activation interest, final-interest cancellation aborts that activation while other interests preserve it, complete cache hits start no model, and cancellation after readiness leaves the ready model loaded; 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. High-level LLM selection defaults to eager activation; startLanguageModel:false preserves the selected tuple and registered adapters without preloading through later readiness callbacks. Caller cancellation waits for accepted old-role cleanup and prevents later configuration/preload, or reaches the first owned load after selection commits. Newer accepted selections supersede older continuations; deferred or cancelled activation stays inactive until explicit load/startup, and a caller abort after successful settlement never unloads the ready model. Separate callers joining an existing runtime load retain their current cancellation ownership.",
+      "surface": "Native fetchTTS(payload,signal) and fetchSTT(audio,signal) forward caller cancellation separately from their complete Core speech payloads, normalize aborts to AbortError and suppress late results; actual engine interruption remains service-owned. 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; default speech-input cleanup with SDK-internal preparation metadata and explicit complete-call textFormat:'plain' consumed before engine dispatch; `prepareTTS({parts,storage,identity,textFormat,signal,onState})` returning ordered segments, state, ready, getAudio(index), and cancel(); async `readPreparedTTS({parts,textFormat,storage,identity,signal,onState})` returning a complete ready handle or null through the same semantic matcher, with no activation, unmute, synthesis, playback, storage writes, or partial repair; manifest, audio availability, and returned-handle reads use DBOPFS createTable:false so absent tables remain absent; supplied adapters own that read-existing behavior; missing matches/audio return null, malformed metadata and storage failures reject, and omitted storage sees only completed matching same-AI in-memory audio; hits replay ready state, misses emit nothing, and the lookup signal detaches on settlement while returned-handle cancellation stays independent; `prepareAudioOutput()` returning the persistent WebAudio handle {kind,state,contextState,error,subscribe,resume,dispose} without resume, unmute, model load, sources, sound, or gesture listeners; current-state replay and output-specific canonical `AI_AUDIO_OUTPUT_STATE_EVENT` (`ai-audio-output-state`), with ready only for an actually running context; explicit owner disposal observes context-bound cleanup and close; `playPreparedTTS(prepared,{signal,onState,audioOutput})` returning state, error, finished, pause(), resume(), and stop() with one playback lane per AI and observational state/error callbacks; explicit live same-AI audioOutput borrows its context until owner disposal, while omission or null preserves per-playback terminal close; 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`. `setAI(llmService,sttService,ttsService,model,modelTTS,modelSTT,options)` and `transitionAI(llmService,sttService,ttsService,model,modelTTS,modelSTT,options)` preserve six positional preferences; `configureProviders(selections,options)` and `transitionProviders(selections,options)` accept the same optional {signal:null,startLanguageModel:true} defaults. setAI retains its synchronous boolean and configureProviders its synchronous route result. Explicit `providerRuntime.load('llm',{signal})` or `startProviders({startLanguageModel:true,signal})` activates a deferred selected route."
     },
     {
       "file": "runtime/arcane/modules/AIModelSelectionController.js",
@@ -133,7 +133,7 @@
       "summary": "Sticky mutable LLM, speech-to-text, and text-to-speech lifecycle snapshots, intents, subscriptions, and startup-settlement barriers.",
       "availability": "Cross-host in-process state contract; actual role readiness remains provider specific",
       "protocol": "arcane-ai-runtime-state/1 over the per-realm globalThis.arcaneEvents authority",
-      "normalization": "Closed monotonic sticky role snapshots, transient lifecycle intents, synchronous current-state replay, AbortSignal cleanup, and startup settlement are normalized; unloaded recovery/error may retain the exact busy operation until settlement, without readiness for new inference.",
+      "normalization": "Closed monotonic sticky role snapshots, transient lifecycle intents, synchronous current-state replay, AbortSignal cleanup, and startup settlement are normalized; unloaded recovery/error may retain the exact busy operation until settlement, without readiness for new inference. During unloading, an already loaded role may retain busy:true with its actual operationId while captured requests settle; this grants no readiness or new-request permission and is not a continuesAIRuntimeOperation recovery state.",
       "surface": "Protocol/event/role/state constants; snapshot, state subscribe/publish, intent request/subscribe, continuesAIRuntimeOperation(previous,current,operationId) for the real continuing runtime operation, and `startAIRuntime({startMuted,startTranscription,signal})` returning `{barrier,settled,cancel}`."
     },
     {
@@ -1201,7 +1201,7 @@
       "summary": "Matches configured risk signals and levels against complete text.",
       "availability": "Cross-host",
       "protocol": "In-process only",
-      "normalization": "Fully normalized.",
+      "normalization": "Complete literal text; existing non-string conversion only.",
       "surface": "`DEFAULT_LEVELS`, `analyzeRiskSignals()`."
     },
     {

package/docs/reference/local-ai.md

@@ -86,7 +86,8 @@ transport loss retain their owning cancellation behavior. A terminal engine
 failure reaches the original request as its actual error rather than a
 fabricated readiness success. See [native speech reconciliation](native-speech.md).
 
-`llamaCpp` accepts `url`, `model`, `modelsDirectory`, and an `args` string array.
+`llamaCpp` accepts `url`, `model`, `alias`, `modelsDirectory`, `executionTarget`,
+and an `args` string array.
 `model` selects a single GGUF file; `modelsDirectory` selects llama.cpp router
 mode. Paths resolve from the application root. Ollama accepts `url`,
 `modelsDirectory`, and `args`. The default endpoints are
@@ -94,6 +95,24 @@ mode. Paths resolve from the application root. Ollama accepts `url`,
 directories are `.arcane/models/llama.cpp` and `.arcane/models/ollama` inside the
 application. Applications choose and provision their models explicitly.
 
+A llama runtime requirement accepts `backend: 'auto' | 'cpu' | 'cuda'`, with
+`auto` preserving the ordinary platform distribution. Explicit `cpu` also
+configures CPU execution, including on a Metal-capable macOS distribution.
+`cuda` currently selects the official Windows x64 CUDA 13.4 engine and its
+matching same-release CUDA companion archive. For example:
+
+```json
+{"runtimes": [{"id": "llama.cpp", "backend": "cuda"}]}
+```
+
+Development prepares this explicit distribution instead of treating an unknown
+PATH executable or external listener as proof of its backend. Native packaging
+bundles the selected runtime tree and companion libraries through the existing
+runtime workflow. A custom CUDA `url` also needs its explicit `companionUrl`;
+the SDK does not guess a companion location. Installation records distinguish
+the distribution's `backend` from its `requestedBackend` execution mode.
+Selecting an unavailable distribution reports its actual error.
+
 ## Development
 
 ```sh
@@ -119,10 +138,23 @@ Zstandard archives use the supported Node runtime's decompressor.
 
 Selected ONNX preparation installs `onnxruntime-node@1.30.0` by default into a
 managed npm prefix, retaining its complete published runtime dependency tree.
-It uses the upstream CPU installation option to skip supplementary GPU downloads.
+The npm installation skips supplementary upstream GPU downloads. On Windows
+x64, an omitted version or explicit `1.30.0`, with no explicit `url`, also
+selects the SDK's corrected native distribution, revision
+`1.30.0-directml-reshape-1`. The installer downloads
+`arcane-onnx-runtime-windows-x64.tar.gz` from the installed `arcane-os` package's
+numeric GitHub release and extracts its native libraries into the new
+installation. Its URL is
+`https://github.com/TheWizardNexus/arcane-os-sdk/releases/download/<sdk-version>/arcane-onnx-runtime-windows-x64.tar.gz`.
+The same-version npm JavaScript and binding remain in place. Explicit URLs,
+other ONNX versions and other platform/architecture selections retain their
+upstream package path. For the corrected selection, an existing installation
+without the matching `nativeDistributionRevision` is left intact and a fresh
+installation is prepared; running installations keep their original trees.
 Node/npm must be available while preparing that runtime; a native app consumes
 the bundled tree without installing it again. Applications that omit ONNX do
-not install its package.
+not install its package. Runtime preparation alone establishes no model or
+device execution result.
 
 For the optional development browser connection, load the bootstrap after the
 managed import map and before creating a Core-backed provider:
@@ -226,7 +258,7 @@ background health polling.
 | --- | --- | --- |
 | `llama.status` | `{}` | Runtime state and model catalog |
 | `llama.models` | `{}` | `{models}` |
-| `llama.load` | `{model}` | State after the exact model reports loaded |
+| `llama.load` | `{model,assetProjectionId?,resourcePaths?,executionTarget?}` | State after the exact model reports loaded |
 | `llama.unload` | `{model}` | Current state after release |
 | `llama.chat` | `{model,payload,stream?,streamId?}` | Complete OpenAI-shaped completion |
 
@@ -238,6 +270,36 @@ only after Core successfully closes its owned single-model server. Explicit
 load, inference or recovery can resume that engine; observation cannot.
 Status observation adds no background polling.
 
+For a saved browser GGUF, prepare its complete file through the existing
+[`model-assets` owner](model-assets.md), then call `llama.load` with its
+`assetProjectionId` and `resourcePaths: {model: 'selected.gguf'}`. Core retains
+that member before replacing its owned server, uses the exact `model` value as
+the server alias, and releases the retained use only after actual process exit.
+The preparation owner can release its use when loading settles. Replacement,
+cancelled loading, unload and shutdown all preserve this lifetime. A cancelled
+projected load joins process shutdown before returning. Ordinary router loads
+retain their existing shared-load behavior.
+
+`executionTarget: {deviceId}` uses the identifier from this computer's execution
+device catalog. Windows CPU selection disables GPU offload; Windows NVIDIA GPU
+selection requires the CUDA distribution and resolves the current adapter LUID
+to its CUDA UUID. The new server sees that one physical GPU as `CUDA0`.
+No machine-specific device ID is embedded in configuration examples. Each host
+resolves its own saved selection; an absent or unsupported device reports an
+error. Other host adapters remain subject to their declared catalog support.
+`executionTarget: null` uses the configured runtime default. Omission preserves
+an active selection's target. Runtime `execution` separates `requestedTarget`,
+`resolvedDevice` and `configuredTarget`; `observedTarget: null` means actual
+inference placement has not been observed. Configuration is not placement proof.
+
+An external server keeps ownership of its model and device. Projected loading
+or explicit target changes report `LOCAL_AI_EXTERNAL_SELECTION_UNSUPPORTED`
+without stopping it or changing a working Core observation. `managed` describes
+whether an installed executable can be managed at this listener; `owned` reports
+an actual SDK-owned process. Recovery retains a live projection across process
+replacement. If the projection was already released after exit, prepare it again;
+resuming never substitutes another model or target.
+
 The `payload` is the complete request. SDK option names are translated only at
 the upstream protocol boundary; messages, tool definitions and documents remain
 unchanged. An explicit `payload.model` selects that request's model. Core waits
@@ -365,10 +427,44 @@ runtime still reconciles the provider at its existing operation boundaries.
 permits that load preflight even before its catalog arrives; Core's `llama.load`
 waits for startup and verifies the exact requested model. An owned, successfully
 released service permits loading only a model retained in its actual catalog.
-An available service still requires that catalog membership. These observations
+With `prepareModel`, an installed `managed` service also admits an explicit
+load before the requested model exists in its catalog. An available external
+service still requires catalog membership. These observations
 do not fabricate model records or readiness, and unavailable external services,
 closed services and actual errors remain unavailable.
 
+The optional `prepareModel({selection,signal,progress})` callback runs only at
+an actual provider load. Return `{assetProjectionId,resourcePaths,executionTarget,release?}`;
+direct `provider.load` fields override the corresponding callback
+fields, including an explicit null target. The provider awaits `release()`
+after Core loading settles and before reporting readiness. Preparation must
+observe cancellation and settle so even a late returned projection is released.
+Only a dispatched Core selection owns a native unload; cancelled preparation
+alone does not unload another model.
+
+```js
+import {prepareCoreModelAssets} from 'arcane-os/ai/core-model-assets';
+
+// modelFile is the complete GGUF Blob/File read from the application's store.
+// selectedDeviceId came from this host's execution-device catalog.
+const provider = createCoreLocalAIProvider({
+  client,
+  async prepareModel({signal, progress}) {
+    const projection = await prepareCoreModelAssets({
+      client, workingDirectory: '.arcane/model-work', signal,
+      members: [{path: 'moon-raccoon.gguf', file: modelFile}],
+      onProgress: progress
+    });
+    return {
+      assetProjectionId: projection.id,
+      resourcePaths: {model: 'moon-raccoon.gguf'},
+      executionTarget: {deviceId: selectedDeviceId},
+      release: projection.release
+    };
+  }
+});
+```
+
 `dispose()` removes installation and service subscriptions and cancels owned
 operations synchronously, then attempts its actually retained model's release
 through its captured client. A configured selection alone does not own a native
@@ -639,7 +735,7 @@ not execution evidence on each platform.
 
 ## Native bundling
 
-The SDK portable native build includes selected official runtime trees under
+The SDK portable native build includes complete selected runtime trees under
 `runtime/local-ai/<runtime-id>`. Runtime records in the artifact are relative
 to the artifact root and resolve on the destination machine. The generated
 Core entry composes the local AI service only when the application selects it.
@@ -649,13 +745,16 @@ Model files remain application-selected native resources.
 `arcane-os/local-ai`. Both accept `{runtimes,directory,platform,architecture,
 signal,onEvent}`; bundling also requires `outputRoot`. Platform names follow
 Node: `win32`, `linux`, `darwin`, and supported Android distributions.
-Architectures are `x64` or `arm64`. Availability depends on the upstream
-runtime's published platform assets; Ollama has no official Android runtime
+Architectures are `x64` or `arm64`. Availability depends on the selected
+distribution's published platform assets; Ollama has no official Android runtime
 archive in this installer.
 
 Ensure returns absolute `{id,version,platform,architecture,root}` records.
 Server runtimes also include `executable`; ONNX includes `modulePath` pointing
-to its public package entry. Image records include `libraryPath`,
+to its public package entry. The corrected Windows x64 ONNX selection also
+includes `nativeDistributionRevision: '1.30.0-directml-reshape-1'`; bundling
+retains that metadata with the complete native libraries. Image records include
+`libraryPath`,
 `bindingModulePath`, requested `backend`, installed `variants` and selected
 `models` metadata. Variant records carry backend, runtime root and library path.
 Bundle returns `{runtimes,files}`,

package/docs/reference/mcp-stdio.md

@@ -75,7 +75,8 @@ Save this in the consuming application and configure the MCP client's subprocess
 command as `node` with that application's script path. Client configuration
 file formats and process launch policy remain client-owned. Change `menu` to
 change the complete result; no model, repository, or native host is needed for
-this example.
+this example. A native package can instead use its
+[existing bundled runtime](#launch-from-a-native-package).
 
 The application explicitly converts its domain record into an MCP result.
 The SDK does not guess from `content`, `message`, or other domain field names.
@@ -255,6 +256,80 @@ The adapter uses `-32700` for malformed JSON, `-32600` for invalid requests,
 `-32603` for internal failures, and `-32002` for a missing resource. Its
 `-32000` lifecycle error requests initialization before ordinary operations.
 
+## Launch from a native package
+
+The generated `runtime/arcane-core.mjs` accepts
+`--arcane-app-entry <app-relative-module>` to import an application-owned entry
+instead of starting ordinary Core. Include the entry and its complete local
+source closure in the application's `package.nativeResources`, for example:
+
+```json
+{
+  "package": {
+    "nativeResources": {
+      "include": ["native", "src", "package.json"]
+    }
+  }
+}
+```
+
+Save the complete example above as `native/moon-mcp.mjs`. Native packaging copies
+the selected files beneath the artifact's `app/` directory. It does not discover
+entry dependencies from this runtime argument or execute the entry during
+packaging. Public imports such as `arcane-os/mcp/stdio` use the artifact's
+existing SDK package and Node's ordinary package resolution.
+
+Configure the MCP client's command and argument array for the selected artifact:
+
+| Artifact | Command | Arguments |
+| --- | --- | --- |
+| Windows | `<artifact-root>/runtime/ArcaneCore.exe` | `["--arcane-app-entry", "native/moon-mcp.mjs"]` |
+| macOS | `<artifact-root>/runtime/node` | `["<artifact-root>/runtime/arcane-core.mjs", "--arcane-app-entry", "native/moon-mcp.mjs"]` |
+| Portable | The host's supported Node executable | `["<artifact-root>/runtime/arcane-core.mjs", "--arcane-app-entry", "native/moon-mcp.mjs"]` |
+
+These are placeholders for the actual native paths. For macOS, `artifact-root`
+is `<app-id>.app/Contents/Resources`. The portable provider supplies no Node
+executable. Windows uses its existing SEA executable and filesystem loader;
+do not pass `arcane-core.mjs` as a script argument to that executable. These
+commands select the runtime directly, not the GUI launcher, and create no
+window or second Core host.
+
+The module path resolves from the artifact's `app/`, independently of the
+client's working directory. Native path separators, spaces, Unicode, `#` and
+`%` retain their filesystem meaning through file-URL conversion. The original
+`process.argv` remains complete and unchanged, including this flag, its path,
+and every app argument. The flag is read from user arguments starting at index
+2 for both normal Node and SEA. A missing or empty value throws `TypeError`;
+module-loading failures remain actual errors and never start ordinary Core.
+
+This is a dynamic import: the entry runs its top-level code and observes its
+own session lifetime, as the example's `server.start()` and `await server.closed`
+do. Do not put its only startup behind `if (import.meta.main)`; the imported
+module is not Node's main entry. The SDK calls no default export or factory.
+
+App-entry mode skips ordinary Core launch-context loading, manifest service
+composition, state-directory creation, local-AI startup, shared-host startup,
+and Core signal handlers. If the application wants the existing explicit launch
+JSON or host state-root arguments, append them to the same argument array and
+read them deliberately in its entry:
+
+```javascript
+import {readCoreLaunchContext} from 'arcane-os/core/host';
+
+const context = await readCoreLaunchContext();
+```
+
+For example, append `"--arcane-launch-config", "<selected-launch.json>"`.
+Relative launch JSON paths retain their caller-working-directory meaning. The
+application chooses defaults, services and any connection to an existing Core;
+the entry selector neither reads nor applies the manifest's launch defaults.
+
+The application owns process signals, graceful MCP drain, and its underlying
+service shutdown. Keep stdout exclusively for MCP JSON-RPC and diagnostics on
+stderr; the ordinary Core `arcane/1` transport must not share those MCP pipes.
+When the flag is absent, ordinary Core startup and service lifecycle are
+unchanged. See [native entry composition](core-native-packaging.md#app-owned-runtime-entry).
+
 ## Evidence boundary
 
 `test/mcp-stdio-server.test.mjs` contains focused in-memory stream fixtures for

package/docs/reference/native-app-control.md

@@ -73,11 +73,11 @@ connection or other business result.
 | Member | Contract |
 | --- | --- |
 | `connectAppControl({endpoint, signal?, onError?})` | Connect once to the explicit running host. It never launches an app, creates Core, changes a profile or reconnects automatically. |
-| `status(options?)` | Returns app identity, platform/host, current URL, document generation, readiness, window title/state/client dimensions and available operations. Readiness describes the document, not models or application services. |
+| `status(options?)` | Returns app identity, platform/host, current URL, document generation, readiness, window title/state/client dimensions and available operations. Window state is `Normal`, `Maximized`, `Minimized`, or `Fullscreen`. Readiness describes the document, not models or application services. |
 | `inspect(parameters={}, options?)` | Optional `shadowPath` selects an open shadow root. Optional CSS `selector` selects zero or more elements within the selected root; omission selects the whole root. Optional `documentGeneration` selects the expected document. Returns complete HTML/text, live control state and DOM-derived role/name hints. |
 | `capture(parameters={}, options?)` | Returns `{mimeType:'image/png', data, documentGeneration, url}`. `data` contains the complete base64 PNG. Optional `documentGeneration` selects the expected document. |
 | `act(parameters, options?)` | Requires `documentGeneration`, one unambiguous CSS `selector` within the root selected by optional `shadowPath`, and the action fields below. |
-| `key(parameters, options?)` | Requires `documentGeneration` and `key:'Tab'`, `'Enter'`, or `'Space'`. Optional `shiftKey:true` is supported only for Tab. Sends one ordered press/release pair to the selected WebView's current focus. |
+| `key(parameters, options?)` | Requires `documentGeneration` and `key:'Tab'`, `'Enter'`, `'Space'`, or `'Escape'`. Optional `shiftKey:true` is supported only for Tab. Sends one ordered press/release pair to the selected WebView's current focus. |
 | `resize(parameters, options?)` | Requires positive integral native client `width` and `height` supported by WinForms. Optional `documentGeneration` selects the expected document. Resizes only a Normal window and returns immediate previous/actual client dimensions plus the subsequently observed CSS viewport. |
 | `close()` | Closes this caller's connection and cancels its pending requests. It never closes the app or Core. Returns the connection's completion promise. |
 | `closed` | Connection lifetime promise; actual transport failures remain observable. |
@@ -207,6 +207,8 @@ const moved = await app.key({documentGeneration: page.documentGeneration, key: '
 console.log(moved.previous.focusPath, moved.actual.focusPath);
 await app.key({documentGeneration: moved.documentGeneration, key: 'Tab', shiftKey: true});
 await app.key({documentGeneration: moved.documentGeneration, key: 'Enter'});
+const current = await app.inspect();
+await app.key({documentGeneration: current.documentGeneration, key: 'Escape'});
 ```
 
 Keys use the selected WebView's current focus. No selector, shadow path, frame
@@ -214,7 +216,10 @@ selection, focus assignment or desktop activation is performed. Tab and
 Shift+Tab use a fixed Tab `rawKeyDown`/`keyUp` pair, with the Shift modifier on
 both events for Shift+Tab. Enter and Space use `keyDown` with their corresponding
 text, followed by `keyUp`, preserving browser default actions and application
-`preventDefault` handling. Shift+Tab does not send a separate Shift key pair.
+`preventDefault` handling. Escape uses `key:'Escape'`, `code:'Escape'` and native
+virtual key 27 in a `rawKeyDown`/`keyUp` pair, without text fields. It follows the
+selected WebView's normal Escape handling; it does not promise that a particular
+dialog closes. Shift+Tab does not send a separate Shift key pair.
 The API exposes these fixed keys, not an arbitrary protocol method or script.
 
 The result contains `key`, `shiftKey`, `previous` and `actual` document views,
@@ -264,7 +269,7 @@ origin. Read `viewport` for the resulting CSS dimensions instead of assuming a
 particular DPI or zoom conversion.
 
 Immediately before the UI-thread mutation, the host checks the actual
-`WindowState` and records `previous:{title,state,width,height}`. It records
+window state and records `previous:{title,state,width,height}`. It records
 `actual` in the same shape immediately after the native setter, then observes
 the CSS `viewport` asynchronously. The result also contains `requested`,
 `resizeAttempted`, `resizeCompleted`, `documentGeneration` and `url`.
@@ -274,13 +279,20 @@ native snapshot and the document observation; these records are not an atomic
 native/CSS snapshot. Completion does not establish that asynchronous application
 resize handlers have settled.
 
-Maximized or minimized windows return `ARCANE_APP_CONTROL_FAILED` before any
+Maximized, minimized or fullscreen windows return `ARCANE_APP_CONTROL_FAILED` before any
 size mutation, with `reason:'unsupported-window-state'`,
 `supportedWindowState:'Normal'` and the complete current `window` in the error's
 `data` entries. The host never automatically restores, maximizes or minimizes a
 window to satisfy this request. Invalid dimensions return `INVALID_ARGUMENT`.
 The same state rule applies to explicit restoration.
 
+Native fullscreen reports `Fullscreen`, including while its underlying WinForms
+state is Normal. A minimized fullscreen window reports `Minimized`. The
+requesting document can select its state through
+[`Arcane.window.setState({state})`](core-client.md#current-window-state); app-control
+does not add a separate state-setting operation. That facade uses lowercase
+state values, while app-control preserves its existing capitalized values.
+
 Restore using the actual `previous.width` and `previous.height` from the
 operation being reversed, never a historical status snapshot or CSS viewport
 dimensions. Restoration is an explicit second request; cancellation does not

package/docs/reference/protocols.md

@@ -475,6 +475,20 @@ the selected runtime content. The lock document describes the selected
 installation and projected roots; it is not a content-identity or admission
 record.
 
+Both runtime materializers accept explicit `browserDecisions: true` to acquire
+the upstream bundled Transformers.js 4.3.0 entry, matching ONNX Runtime
+1.31.0-dev.20260914-8d85527a0 asyncify module/WASM, and license files into
+`arcane/sdk/ai/decisions-runtime/` before replacement. Default `false` performs
+no optional acquisition. The complete selected files remain unchanged;
+`workspace.decisions.started`/`workspace.decisions.progress` count completed
+files. Cancellation, HTTP failures and observer failures join acquisition
+cleanup and preserve the previous projection. Retain the option on each refresh
+that needs the closure. The optional `browserDecisions` result describes its
+directory, versions and filenames; installed materialization nests it under
+`workspaceRuntime`. Model/tokenizer data remain upstream and cache-owned.
+See [extension-local decisions](ai/browser-decisions.md#extension-local-executables-manifest-v3)
+for the separate `runtime.local: true` browser selection.
+
 `upgradeApplication()` and `arcane upgrade` run the application's ordinary
 `npm upgrade` command. They do not independently reconcile the installed SDK
 projection, semantic Arcane lock, or managed import map.

package/docs/reference/runtime-modules.md

@@ -128,7 +128,7 @@ own asynchronous work, cancellation, and backpressure.
 | [`RecordLinkIndex.js`](#recordlinkindexjs) | esm | Parses record links and builds their normalized index. | Cross-host | Fully normalized. |
 | [`RecordPassageIndex.js`](#recordpassageindexjs) | esm | Indexes text lines, page markers, dates, rules, and excerpts for record review. | Cross-host | Fully normalized. |
 | [`RecordReviewStore.js`](#recordreviewstorejs) | esm | Stores normalized record-review decisions through native storage or app-scoped local fallback. | Browser/native hybrid | Complete records preserved; unreadable stored content fails observably. |
-| [`RiskSignalAnalyzer.js`](#risksignalanalyzerjs) | esm | Matches configured risk signals and levels against complete text. | Cross-host | Fully normalized. |
+| [`RiskSignalAnalyzer.js`](#risksignalanalyzerjs) | esm | Matches configured risk signals and levels against complete text. | Cross-host | Complete literal text; existing non-string conversion only. |
 | [`ScamRiskPolicy.js`](#scamriskpolicyjs) | esm | Combines deterministic scam signals with optional Arcane blocked-domain evidence and safety guidance. | Cross-host | Complete mutable results; blocked-domain policy requires `secure:true`. |
 | [`ScopedOPFSCache.js`](#scopedopfscachejs) | esm | Provides a narrow exact-key JSON cache inside one app-owned OPFS namespace. | Browser / native WebView | Filename-safe keys, complete JSON values, and malformed-cache cleanup normalized; storage errors mixed. |
 | [`ScreenCapture.js`](#screencapturejs) | esm | Captures a display surface as image, video, or GIF with explicit lifecycle events. | Browser / native WebView | State/events normalized; permission and codec errors mixed. |
@@ -1386,7 +1386,11 @@ transcription-model load.
 **Cross-host state contract.** States are `unavailable`, `unloaded`, `loading`,
 `recovering`, `ready`, `unloading`, `error`, and `disposed`. Recovery remains
 `loaded: false`; `recovering` and `error` may retain `busy: true` with an actual
-`operationId` until the pending request settles. Revisions increase monotonically.
+`operationId` until the pending request settles. During `unloading`, an already
+loaded role may retain `busy: true` with its actual `operationId` while captured
+requests settle. That observation grants no readiness or permission for a new
+request and is not a `continuesAIRuntimeOperation` recovery state.
+Revisions increase monotonically.
 The events `arcane-ai-runtime-state`, `arcane-ai-runtime-intent`, and
 `arcane-ai-runtime-startup-settled` normalize observation only: receiving one
 does not grant a native capability, prove browser support, or load a provider.
@@ -4010,9 +4014,11 @@ Matches configured risk signals and levels against complete text.
 
 Exact exports: `DEFAULT_LEVELS`, `analyzeRiskSignals`.
 
+`analyzeRiskSignals(input, {signals, levels})` scans the complete `String(input ?? '')` without Unicode normalization or whitespace changes. Fullwidth characters and decomposed characters remain as supplied. Each signal's `RegExp.lastIndex` resets before testing; signal order, weights and selected levels determine the mutable `{level, matches, score, textLength}` result. `textLength` is the JavaScript string length after the existing non-string conversion; `null` and `undefined` become an empty string. Ordinary `ScamRiskPolicy.assessScamRisk()` uses this same literal-text path.
+
 ### Availability and normalization
 
-**Cross-host.** Fully normalized. Transport: In-process only. [Deep protocol details](protocols.md).
+**Cross-host.** Complete literal text; existing non-string conversion only. Transport: In-process only. [Deep protocol details](protocols.md).
 
 ### Example