arcane-os 0.5.19 → 0.6.1

package/docs/reference/ai/browser-speech.md

@@ -55,11 +55,11 @@ export const speechSelection = {
 };
 ```
 
-The omitted execution record below uses the SDK's WebGPU-first automatic
-selection, so this basic configuration uses `fp32` because
+The omitted execution record below uses the SDK's NPU, GPU, then CPU automatic
+selection. This basic configuration uses `fp32` because
 [Kokoro.js recommends `fp32` when using WebGPU](https://github.com/hexgrad/kokoro/tree/main/kokoro.js#usage).
-Automatic fallback carries this same selected model and dtype to WASM; the SDK
-does not rewrite the application selection. If you intentionally choose
+Automatic fallback carries this same selected model and dtype between devices;
+the SDK does not rewrite the application selection. If you intentionally choose
 another dtype, evaluate that exact model, browser, and execution route.
 `selectedDevice` reports routing after load, not pronunciation, text fidelity,
 or audio quality.
@@ -130,6 +130,36 @@ window.addEventListener('ai-tts-failure', function reportSpeechFailure(event) {
 
 Call `speechEvents.abort()` when disposing that interface to remove the listener.
 
+## Browser NPU setup
+
+Applications can place the shared `browser-ai-setup.html` component in their
+profile or settings page. It reports whether this page exposes WebNN and
+WebGPU, without loading a model or creating an accelerator context:
+
+```html
+<html-import
+  id="browserAISetup"
+  href="/arcane/components/browser-ai-setup.html">
+</html-import>
+```
+
+**Set up NPU** uses the same browser-settings approach as the existing
+high-performance GPU notice: attempt to open the browser's flags page, then
+show instructions including the full address to paste if navigation was
+blocked. Chrome uses `chrome://flags/#web-machine-learning-neural-network`;
+Edge uses `edge://flags/#web-machine-learning-neural-network`. Unrecognized
+browsers receive explicit Chrome and Edge choices instead of an assumed target.
+The [ONNX Runtime WebNN guide](https://onnxruntime.ai/docs/tutorials/web/ep-webnn.html)
+documents the **Enables WebNN API** flag and model/operator requirements.
+
+This control does not save an execution preference, change browser settings,
+restart the browser, or report that the NPU is active. A WebNN API presence
+result is not proof of NPU hardware, a compatible model, or physical execution.
+The profile also cannot report a different chat page's loaded runtime. The
+existing automatic speech route remains NPU, then GPU, then CPU; upstream
+sessions can still place unsupported operators on CPU. Use the owning model
+runtime's evidence to determine actual accelerator execution.
+
 ## Developer diagnostics
 
 The shared logging API and speech traces are available in SDK `0.5.14`.
@@ -229,9 +259,10 @@ playback. `replay()` keeps completed and pending provider segments and retries
 only failed missing segments.
 
 The default `{device:'auto',maxConcurrentRequests:4}` attempts the full ONNX
-Worker/session pool on WebGPU, then recreates that pool on WASM only if WebGPU
-loading fails. The basic configuration above keeps `fp32` for this WebGPU-first
-path and any automatic WASM fallback. Use the status example below to read
+Worker/session pool on WebNN NPU, then WebGPU, then CPU through WASM. It skips
+an accelerator when its browser API is absent and replaces a failed candidate
+with a fresh pool before trying the next device. The basic configuration above
+keeps `fp32` throughout that sequence. Use the status example below to read
 `selectedDevice`; console node-assignment warnings alone do not identify the
 selected execution device or assess the generated audio.
 
@@ -588,8 +619,20 @@ console.log(speechText.append('ing', true)); // ing
 
 ## Choose a device or reduce memory use
 
-Omitting `tts.execution` selects `{device:'auto',maxConcurrentRequests:4}`.
-These are three alternative configurations, not a sequence of required loads:
+Both speech roles accept `execution:{device,maxConcurrentRequests}`. Omitting
+`stt.execution` selects `{device:'auto',maxConcurrentRequests:1}`; omitting
+`tts.execution` selects `{device:'auto',maxConcurrentRequests:4}`. Whisper keeps
+one transcription slot. Kokoro accepts capacities 1 through 4.
+
+Automatic selection tries `webnn-npu` when `navigator.ml.createContext` is
+exposed, then `webgpu` when `navigator.gpu` is exposed, then CPU through `wasm`.
+API exposure only determines which upstream backend to attempt; it
+does not establish compatible hardware, operators, or model shapes. A failed
+candidate is fully cleaned up before the next candidate uses fresh Workers
+with the same prepared model and dtype. An explicit `webnn-npu`, `webgpu`, or
+`wasm` selection attempts only that backend and reports its failure.
+
+These are four alternative TTS configurations:
 
 ```javascript
 async function selectSpeechExecution(execution) {
@@ -609,15 +652,22 @@ async function selectSpeechExecution(execution) {
 
 // Choose and call one from your application settings action:
 // await selectSpeechExecution({ device: 'auto' });
+// await selectSpeechExecution({ device: 'webnn-npu' });
 // await selectSpeechExecution({ device: 'webgpu' });
 // await selectSpeechExecution({ device: 'wasm', maxConcurrentRequests: 1 });
 ```
 
-The override accepts integers 1, 2, 3, or 4. `auto` tries a complete WebGPU pool
-when available, then recreates a complete WASM pool if that load cannot finish.
-Explicit `webgpu` reports a load error when unavailable; explicit `wasm` never
-attempts WebGPU. The same application-selected model and dtype apply on both
-devices. A configuration change leaves TTS muted; explicitly load/unmute again.
+The TTS capacity override accepts integers 1, 2, 3, or 4; an STT capacity
+override accepts only 1. Apply the same device choices to the configured
+`stt.execution` record. A configuration change leaves TTS muted; explicitly
+load/unmute again.
+
+The selected upstream versions expose WebNN NPU through
+[Transformers.js device selection](https://github.com/huggingface/transformers.js/blob/4.2.0/packages/transformers/src/backends/onnx.js)
+and [Kokoro.js device forwarding](https://github.com/hexgrad/kokoro/blob/664c76a704021239ba59c84dcbaa4d3dece01fe9/kokoro.js/src/kokoro.js).
+WebNN compatibility depends on the model's shapes and operations, browser,
+drivers, and hardware. Unsupported operations may run through WASM even after
+an NPU session loads; see the [ONNX Runtime WebNN contract](https://onnxruntime.ai/docs/tutorials/web/ep-webnn.html).
 
 ## Inspect the requested and selected device
 
@@ -627,15 +677,15 @@ loading. This explicitly reads the selected provider's current report; ordinary
 separate execution-state event subscription.
 
 ```javascript
-function printSpeechStatus() {
-  const status = ai.providerRuntime.status('tts', { execution: true });
+function printSpeechStatus(role = 'tts') {
+  const status = ai.providerRuntime.status(role, { execution: true });
   const execution = status.execution;
-  console.log('TTS state:', status.state);
+  console.log('Speech role and state:', role, status.state);
   if (execution) {
     console.log('Requested device:', execution.requestedDevice);
     console.log('Selected device:', execution.selectedDevice);
     console.log('Capacity:', execution.maxConcurrentRequests);
-    console.log('Active synthesis requests:', execution.activeRequestCount);
+    console.log('Active requests:', execution.activeRequestCount);
     console.log('Automatic WASM fallback:',
       execution.requestedDevice === 'auto' && execution.selectedDevice === 'wasm');
   }
@@ -645,13 +695,18 @@ function printSpeechStatus() {
 Call `printSpeechStatus()` after the load in `sayHello()` or from your status
 button. The same projection is at
 `ai.providerRuntime.status(null, {execution:true}).roles.tts.execution`.
+For configured Whisper, call `printSpeechStatus('stt')` or read the corresponding
+`roles.stt.execution` projection.
 `selectedDevice` is `null`
 until a pool is selected and returns to `null` on unload. Providers without an
 execution report omit `execution`; do not infer a device from `navigator.gpu`
 or a configured preference alone. An explicit inspection can throw a provider
 status error; handle it with the same `error.code` / `error.message` pattern.
-Treat `selectedDevice` as route status only; evaluate actual speech output for
-the model, dtype, browser, and device combinations your application supports.
+`selectedDevice` names the backend requested by the successful upstream session
+load. It does not prove that every operation ran on a physical NPU or GPU, or
+establish transcription correctness, pronunciation, or audio quality. Evaluate
+actual speech output for the model, dtype, browser, and device combinations your
+application supports.
 
 ## Stop, mute, cancel, and release
 
@@ -991,11 +1046,12 @@ they do not silently convert into a rejection policy.
 The Worker applies only the selected runtime settings needed to run the chosen
 provider:
 
-- Kokoro forwards the pool's selected `webgpu` or `wasm` device to
+- Kokoro forwards the pool's selected `webnn-npu`, `webgpu`, or `wasm` device to
   `KokoroTTS.from_pretrained()`. Its configured dtype remains exactly the
-  caller-selected dtype on both paths. The WASM path also uses
+  caller-selected dtype on every path. The WASM path also uses
   `namespace.env.wasmPaths = {mjs,wasm}`.
-- Transformers uses
+- Transformers forwards the selected device to its speech-recognition pipeline,
+  preserves the caller-selected dtype, and uses
   `namespace.env.backends.onnx.wasm.wasmPaths = {mjs,wasm}`, keeps remote model
   loading enabled, and applies caller-selected `numThreads` when present.
 
@@ -1029,15 +1085,15 @@ The constructors also accept ordinary `model` and `runtime` descriptors instead
 of `graph`; the two forms are mutually exclusive. Both forms require an
 SDK-created DBOPFS speech artifact store. `localOnly` remains `true`.
 
-Kokoro additionally accepts the exact `execution` record
-`{device,maxConcurrentRequests}`. `device` is `auto`, `webgpu`, or `wasm`;
-`maxConcurrentRequests` is an integer from 1 through 4. Omission defaults to
-`{device:'auto',maxConcurrentRequests:4}`. `auto` attempts a complete WebGPU
-Worker pool only when the browser exposes WebGPU. If that pool cannot load, the
-SDK tears it down and creates a complete WASM pool with the same caller-selected
-model and dtype. Explicit `webgpu` rejects when WebGPU cannot load; explicit
-`wasm` never attempts GPU. Whisper remains one WASM Worker and does not accept
-this option.
+Both constructors accept the exact `execution` record
+`{device,maxConcurrentRequests}`. `device` is `auto`, `webnn-npu`, `webgpu`, or
+`wasm`. Whisper permits capacity 1 and defaults to
+`{device:'auto',maxConcurrentRequests:1}`. Kokoro permits integer capacities 1
+through 4 and defaults to `{device:'auto',maxConcurrentRequests:4}`. `auto`
+tries WebNN NPU when `navigator.ml.createContext` is exposed, then WebGPU when
+`navigator.gpu` is exposed, then WASM. Before advancing after a failed load,
+the SDK tears down the candidate and creates fresh Workers using the same
+prepared model and dtype. Explicit device selections never fall back.
 
 Each constructor returns an `arcane-ai-provider/2` object with:
 
@@ -1123,12 +1179,13 @@ mutable values.
 Provider states are `unloaded`, `loading`, `ready`, `unloading`, `error`, and
 `disposed`. `status()` includes role, provider/model ids, state, lifecycle
 status and reason, active operation, loaded/busy flags, generation, error code,
-cache state, and warnings. Kokoro status also includes an `execution` record
+cache state, and warnings. Both speech roles include an `execution` record
 with requested and selected device, request limit, and active request count. A
-successful `selectedDevice:'webgpu'` reports the execution provider selected by
-the upstream model load; it does not claim that browser, driver, or GPU kernels
-overlap physically or that generated audio has been quality-validated. A
-security field is absent in ordinary mode.
+successful `selectedDevice` reports the backend requested by the upstream model
+load. It does not prove that every operation ran on a physical NPU or GPU,
+that accelerator kernels overlap, or that generated speech is correct. WebNN
+may execute unsupported operations through WASM. A security field is absent
+in ordinary mode.
 
 The provider/2 load context accepts an optional progress callback for interface
 compatibility, but the current browser-speech artifact and Worker transport
@@ -1203,7 +1260,7 @@ operation.
 ## Ownership
 
 - Applications own model, runtime, dtype, sample-rate, voice, profile, prompt,
-  catalog, activation, optional TTS execution override, and presentation
+  catalog, activation, optional STT/TTS execution override, and presentation
   policy.
 - Upstream publishers own their runtime, model, voice, and license delivery.
 - The SDK owns storage, materialization, routing, Worker lifecycle, normalized

package/docs/reference/behavioral-testing.md

@@ -41,7 +41,7 @@ development evidence; it is not native artifact or release acceptance.
 | Browser runtime modules | Every shipped ESM module parses and its export inventory matches the catalog; pure helpers run focused success/error cases. | DOM, OPFS, media, and Web Component journeys use a browser harness. |
 | Provider-neutral AI runtime and chat/speech activation | Provider/2 registration, three-role configuration, TWiN Cloud LLM readiness, on-device Whisper/Kokoro selection, opt-in STT startup, Core speech readiness, independent LLM/STT/TTS load/unload/status, capacity-1 FIFO settlement for LLM/STT, bounded parallel synthesis with FIFO admission for an explicitly capable TTS provider, owned STT signals, TTS mute lifecycle, route-owned voice defaults, immediate chunk synthesis admission, original-order audio-clock scheduling, sticky-state-only readiness for both speech components, selected-unloaded activation request/cancellation/error behavior, programmatic voice recording, transcript-replacement supersession of late settlement, direct `AI.fetchSTT` result delivery, rejection of non-local speech configuration, and absence of silent provider fallback are represented against complete providers and host callbacks. | Real model/runtime availability remains the selected provider's evidence boundary; provider-promise settlement, state, an abort signal, or an activation event does not by itself prove underlying provider work stopped or native, cloud, or browser-model availability. |
 | Browser-WASM local AI | The exported namespace, canonical ordered `{id, files:[{name?,url},...]}` descriptor, nonempty provider `sources` catalog, default `secure:false`, dormant `secure:true` intent, public AI API module lifecycle, lazy/manual policy, successful Wllama-load requirement, abort normalization, complete output and reasoning, all-choice validation, required structural-call `arguments.message`, exact call identity, and matching tool-result sequencing are represented in deterministic fixture sources. | A real Chrome exercise may load the selected Wllama runtime and model only after explicit user action. It is not an ordinary publication gate or an implicit model download. |
-| Browser speech | Caller-owned Whisper/Kokoro selection, independent STT/TTS routes, ordinary direct upstream runtime/model use, dormant `secure:true` intent, DBOPFS cache, materialized known-route/native-fallback behavior, GPU-first device selection with explicit WASM fallback, bounded Kokoro Worker/session pools, out-of-order synthesis settlement with FIFO admission, request-targeted TTS cancellation, destructive lifecycle cleanup, Blob/File STT conversion, WAV TTS conversion, complete text/audio, and no cloud fallback are represented with synthetic artifacts and adapters. | A real runtime/model/voice download, WebGPU model load, physical accelerator behavior, and actual transcription or synthesis use the application's selected upstream packages/providers, browser media support, and explicit user action. |
+| Browser speech | Caller-owned Whisper/Kokoro selection, independent STT/TTS routes, ordinary direct upstream runtime/model use, dormant `secure:true` intent, DBOPFS cache, materialized known-route/native-fallback behavior, NPU-to-GPU-to-CPU automatic selection for both roles, fresh Workers after a failed device load, explicit-device failure without fallback, bounded Kokoro Worker/session pools, out-of-order synthesis settlement with FIFO admission, request-targeted TTS cancellation, destructive lifecycle cleanup, Blob/File STT conversion, WAV TTS conversion, complete text/audio, and no cloud fallback are represented with synthetic artifacts and adapters. | A real runtime/model/voice download, WebNN or WebGPU model load, physical accelerator behavior, and actual transcription or synthesis use the application's selected upstream packages/providers, browser media support, and explicit user action. A selected backend is not proof that every operation ran on that physical accelerator; WebNN may execute unsupported operations through WASM. |
 | Persistent chat and document context | Atomic in-memory/history commit, explicit per-turn persistence, streamed/non-stream fallback, session-owned callback fields, complete data callbacks, per-turn request options, exact per-choice streamed/terminal call correlation before publication, terminal-only call acceptance, ordered parallel-call sequencing, atomic all-ID nonblank executed/declined/cancelled/not-executed result batches, readable unmodified malformed pre-existing rows, complete UI transcript metadata, generic visible failure outcomes with complete console diagnostics, BFCache-preserving component lifecycle, complete bootstrap/search/context, caller-source evaluation, cancellation, and partial-read handling are represented with app-scoped adapters. | Live Core/provider inference and durable browser storage remain separate authorities; tests never treat a fake chat function or in-memory adapter as host/storage proof. |
 | Core bridge docs | Canonical namespace/method/event/entity inventories match their one-per-member guides and required sections. | Live Core conformance belongs in Arcane OS because Core implementation is not shipped as SDK source. |
 | Arcane Ollama wrapper | Missing-host error, method forwarding, text/readiness normalization, unload request, and stream-option forwarding run against a deterministic fake `Arcane.ollama`. | Real managed-service, model download/create, GPU/resource admission, and service restart require an admitted Arcane host. |

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

@@ -5,7 +5,7 @@
     "repository": "https://github.com/TheWizardNexus/arcane-os-sdk.git",
     "branch": "main",
     "path": "runtime/arcane",
-    "sdkVersion": "0.5.18",
+    "sdkVersion": "0.6.0",
     "protocol": "arcane/1"
   },
   "artifactCount": 85,
@@ -29,7 +29,7 @@
       "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 Kokoro TTS execution with default capacity 4, 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.",
+      "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, synthesis/transcription, and playback controls; initializes from current canonical user readiness, installs `window.ai`, and projects `ai-ready` plus active-generation `ai-tts-failure`."
     },
     {

package/docs/reference/runtime-components.md

@@ -60,6 +60,7 @@ appropriate.
 | --- | --- | --- | --- | --- |
 | [`app-bar.html`](#app-barhtml) | Responsive application navigation, route state, status, and trailing actions. | `setNavigation()`<br>`setActiveRoute()`<br>`setStatus()`<br>`refresh()`<br>`destroy()` | `app-bar-ready` | DOM-normalized |
 | [`assistant-panel.html`](#assistant-panelhtml) | Reusable assistant drawer, message area, composer, pending/streaming/empty/error state, and actions. | `open()`<br>`close()`<br>`toggle()`<br>`send()`<br>`clear()`<br>`setState()`<br>`focusComposer()`<br>`scrollToEnd()`<br>`destroy()` | `assistant-ready`<br>`assistant-opened`<br>`assistant-closed`<br>`assistant-send`<br>`assistant-clear` | DOM-normalized; caller/provider results remain external |
+| [`browser-ai-setup.html`](#browser-ai-setuphtml) | Browser API availability and NPU setup instructions with browser-specific flags actions. | `refresh()`<br>`open()`<br>`destroy()`<br>`ready` | `browser-ai-setup-ready` | API presence only; settings navigation and hardware execution remain browser-owned |
 | [`calculator.html`](#calculatorhtml) | Calculator keypad and result/error event surface backed by CalculatorEngine. | `calculate()`<br>`destroy()` | `calculator-ready`<br>`calculation-complete`<br>`calculation-error` | Normalized Calculation/error events |
 | [`chart.html`](#charthtml) | Accessible uPlot line, area, or point chart with normalized options and rows. | `configure()`<br>`populate()`<br>`setData()`<br>`addData()`<br>`update()`<br>`destroy()` | `chart-ready`<br>`chart-remove` | Options/rows normalized; uPlot rendering is vendor-native |
 | [`chat.html`](#chathtml) | Shared chat, visible selected-model activation request, file upload, streaming, structural tool settlement, speech, language, availability, and conversation-timebox surface. | `streamMessage()`<br>`setMessageProgress()`<br>`setAIAvailability()`<br>`setInitialSpeechMuted()`<br>`setConversationComplete()`<br>`bindConversationTimebox()`<br>`bindSession()`<br>`submitMessage()`<br>`submitToolResult()`<br>`submitToolResults()`<br>`sendMessage()`<br>`languageChanged()`<br>`requestAIActivation()`<br>`destroy()` | `chat-ready`<br>`chat-session-bound`<br>`chat-session-message`<br>`chat-session-error`<br>`chat-send-message`<br>`chat-send-error`<br>`chat-file-uploaded`<br>`chat-file-upload-error`<br>`chat-language-changed`<br>`chat-language-change-error`<br>`chat-ai-activation-request`<br>`chat-ai-activation-error`<br>`chat-speech-synthesis-error`<br>`conversation-timebox-error` | UI/runtime state, explicit user activation intent, and honest structural-call settlement normalized; AI/storage/media behavior mixed |
@@ -153,6 +154,58 @@ Slots: `title`, `subtitle`, `identity`, `messages/message`, `composer`, `actions
 </html-import>
 ```
 
+## browser-ai-setup.html
+
+### Overview
+
+Displays WebNN and WebGPU API availability for the current page and explains how
+to enable WebNN for NPU use. Its setup action uses the same browser-flags opening
+attempt and alert fallback as the existing high-performance GPU notice. Chrome
+and Edge receive their own flags addresses; other or unidentified browsers show
+both explicit choices.
+
+### Public surface
+
+Methods/properties: `refresh()`, `open(browserId?)`, `destroy()`, `ready`.
+
+Events: `browser-ai-setup-ready`.
+
+`refresh()` synchronously updates API presence and browser guidance and returns
+the current settings record: `browserId`, `name`, `webnnFlagsURL`,
+`highPerformanceGpu`, `webnnAvailable`, and `webgpuAvailable`. It returns `false`
+after destruction. Availability means that the browser exposes the API to this
+page; it does not confirm a working adapter, loaded model, or hardware execution.
+
+`open()` refreshes the display, attempts to open the detected Chrome or Edge flags
+page, and presents an alert containing the full address and enable/relaunch
+instructions. Pass `"chrome"` or `"edge"` to choose explicitly. Invoke it from a
+user action. It returns `false` when destroyed or when no supported target is
+selected, and otherwise returns `undefined`; it never reports that navigation
+succeeded. Browsers may block internal-page navigation, so the full addresses
+also remain visible and copyable in the component.
+
+`destroy()` aborts owned listeners, disposes the event source, marks `ready`
+false, and suppresses UI updates from a pending clipboard operation. It returns
+`true` the first time and `false` thereafter. A BFCache-persisted `pagehide`
+preserves the component; nonpersisted `pagehide` destroys it.
+
+### Availability and normalization
+
+**Browser and supported native WebViews.** API presence and setup instructions
+are normalized; browser flags, clipboard support, and device execution remain
+platform-owned. Mounting or refreshing creates no model, GPU adapter, or WebNN
+context. The component saves no preferences, changes no browser settings, and
+does not restart the browser. It cannot report model state owned by another page.
+
+### Example
+
+```html
+<html-import
+  id="browser-ai-setup"
+  href="/arcane/components/browser-ai-setup.html">
+</html-import>
+```
+
 ## calculator.html
 
 ### Overview

package/docs/reference/runtime-modules.md

@@ -253,10 +253,15 @@ user activation intent exposed by the shared speech component.
 `setSpeechMuted(false)` records the public unmuted state only after the selected
 TTS route reaches ready; a failed load leaves the public state muted. In contrast,
 `setSpeechMuted(true)` cancels active TTS work and unloads that role.
-The optional browser-speech `tts.execution` record selects
-`device:'auto'|'webgpu'|'wasm'` and a `maxConcurrentRequests` integer from 1
-through 4. Omission uses GPU-first automatic selection with four bounded Kokoro
-Worker/session slots; STT remains one WASM Worker.
+The optional browser-speech `stt.execution` and `tts.execution` records select
+`device:'auto'|'webnn-npu'|'webgpu'|'wasm'` and `maxConcurrentRequests`.
+Omission uses NPU, GPU, then CPU automatic selection with one Whisper slot and
+four bounded Kokoro Worker/session slots. Whisper accepts only capacity 1;
+Kokoro accepts integers 1 through 4. Automatic loading attempts WebNN NPU when
+`navigator.ml.createContext` is exposed, then WebGPU when `navigator.gpu` is
+exposed, then WASM. A failed candidate is cleaned up before fresh Workers try
+the next device with the same prepared model and dtype. Explicit device
+selections report failure without falling back.
 Capacity 4 means up to four segments synthesize at once. Segment 5 and later
 wait in the SDK's FIFO queue; they are not dropped. Synthesis may finish out
 of order, but playback waits for earlier segments and plays exact input order.
@@ -265,11 +270,15 @@ latency. This capacity does not establish physical GPU kernel overlap.
 
 After configuration, explicitly inspect execution through
 `ai.providerRuntime.status('tts', {execution:true}).execution`. When supplied
-by the selected provider, this read returns its execution snapshot. Kokoro
-reports `requestedDevice`, `selectedDevice`, `maxConcurrentRequests`, and
+by the selected provider, this read returns its execution snapshot. Whisper and
+Kokoro report `requestedDevice`, `selectedDevice`, `maxConcurrentRequests`, and
 `activeRequestCount`. `selectedDevice` is `null` before load and after unload.
 `requestedDevice === 'auto' && selectedDevice === 'wasm'` identifies automatic
-WASM fallback after a successful load. Calling `status()` without options keeps
+WASM fallback after a successful load. Read the same fields for Whisper with
+`status('stt', {execution:true})`. The selected device is the backend requested
+by a successful upstream session load, not proof that every operation ran on a
+physical accelerator; WebNN may execute unsupported operations through WASM.
+Calling `status()` without options keeps
 the existing sticky lifecycle snapshot and does not inspect provider execution.
 Provider inspection failures are surfaced to the caller.
 `fetchTTS({model,voice,input,responseFormat,speed},signal,preparation={})` accepts the public
@@ -501,9 +510,11 @@ await ai.disposeBrowserSpeech({signal});
 
 The record is a mutable plain data record with exactly
 `{protocol,id,dbopfs,tableName?,stt?,tts?}` and at least one role. Each supplied
-mutable STT role is exactly `{providerId,graph,security?,offline}` or
-`{providerId,model,runtime,security?,offline}`. TTS accepts the corresponding
-shape plus optional `execution:{device,maxConcurrentRequests}`. The graph and
+mutable STT or TTS role is exactly
+`{providerId,graph,security?,offline,execution?}` or
+`{providerId,model,runtime,security?,offline,execution?}`. The optional
+`execution` record contains `{device,maxConcurrentRequests}` with the
+role-specific defaults and capacities described above. The graph and
 direct authority forms are mutually exclusive; `providerId` and `id` are nonblank exact strings,
 `graph` is the role-matching graph returned by the SDK browser
 speech artifact API, and `offline` is boolean. The direct form forwards its
@@ -526,8 +537,9 @@ or reproduce DBOPFS cache logic.
 
 The returned descriptor is exactly `{protocol,configurationId,stt,tts}`; an
 external, unmanaged role is `null`. A managed STT descriptor is
-`{role:'stt',providerId,modelId,artifactGraphId?,offline}`; TTS adds
-`defaultVoice` and the normalized `execution` record. `artifactGraphId` is present only for the graph form.
+`{role:'stt',providerId,modelId,artifactGraphId?,offline,execution}`; TTS adds
+`defaultVoice`. Both include the normalized `execution` record.
+`artifactGraphId` is present only for the graph form.
 `browserSpeechConfiguration` returns the exact caller-owned record when no
 managed role is carried. After a partial replacement that carries another
 managed role, it returns a mutable merged record with the replacement call's
@@ -764,16 +776,19 @@ never loads or downloads a model. `load()` forwards provider progress into the
 sticky role record; `unload()` and `dispose()` abort owned work, await exposed
 settlement, and verify provider status before publishing terminal state.
 
-`status('tts', {execution:true})` explicitly reads the selected provider and
-adds its optional `execution` snapshot to a copy of the role record.
+`status('stt', {execution:true})` or `status('tts', {execution:true})` explicitly
+reads the selected provider and adds its optional `execution` snapshot to a
+copy of the role record.
 `status(null, {execution:true})` provides the equivalent projection under
 `roles.llm`, `roles.stt`, and `roles.tts`. Providers that do not supply execution
 omit that field. No provider load or sticky-state event is triggered; default
 `status()` keeps its existing identity and behavior. A provider inspection
-error propagates. Kokoro's execution contains `requestedDevice`,
+error propagates. Each Whisper or Kokoro execution report contains `requestedDevice`,
 `selectedDevice` (`null` while unloaded), `maxConcurrentRequests`, and
-`activeRequestCount`; these describe provider execution, not physical GPU
-kernel overlap.
+`activeRequestCount`. The selected device names the backend requested by a
+successful upstream session load. It does not prove that every operation ran
+on a physical NPU or GPU, or that accelerator kernels overlap; WebNN may use
+WASM for unsupported operations.
 
 `validateSpeechConfiguration(value)` returns one mutable two-role selection
 record without committing it, where `value` is the closed `{stt,tts}` record.

package/docs/reference/sdk-api.md

@@ -6437,8 +6437,10 @@ createBrowserWhisperProvider(options={})
 
 The recognized options are
 `{id='arcane-browser-whisper',localOnly=true,graph,model,runtime,appSecurity,
-security,store,offline=false}`. `graph` is mutually exclusive with `model` and
-`runtime`. The mutable result is
+security,store,offline=false,execution={device:'auto',maxConcurrentRequests:1}}`.
+`execution.device` is `auto`, `webnn-npu`, `webgpu`, or `wasm`; its capacity is
+exactly 1. `graph` is mutually exclusive with `model` and `runtime`. The mutable
+result is
 `{protocol:'arcane-ai-provider/2',role:'stt',id,localOnly:true,
 maxConcurrentRequests:1,catalog,inspect,status,load,request,unload,dispose}`.
 The only request operation is
@@ -6448,8 +6450,22 @@ re-freeze the cloned record.
 
 `status()` returns
 `{role,providerId,modelId,state,lifecycleStatus,lifecycleReason,activeOperation,
-loaded,busy,generation,errorCode,cache,warnings}` and includes `security` only
-for an explicit secure intent.
+loaded,busy,generation,errorCode,cache,warnings,execution}` and includes
+`security` only for an explicit secure intent.
+`execution` reports `requestedDevice`, `selectedDevice`,
+`maxConcurrentRequests`, and `activeRequestCount`; `selectedDevice` is `null`
+before load and after unload. The high-level projection is
+`ai.providerRuntime.status('stt', {execution:true}).execution`.
+
+Automatic loading tries `webnn-npu` when `navigator.ml.createContext` is
+exposed, then `webgpu` when `navigator.gpu` is exposed, then CPU through `wasm`.
+A failed candidate is cleaned up before a fresh Worker tries the next backend
+with the same prepared model and dtype. Explicit selections do not fall back.
+`selectedDevice` names the backend requested by the successful upstream session
+load; it does not prove that every operation ran on a physical accelerator.
+WebNN may execute unsupported operations through WASM, and exact model,
+browser, driver, and hardware compatibility remains upstream.
+
 States are `unloaded`, `loading`, `ready`, `unloading`, `error`, and
 `disposed`. Compatible concurrent loads coalesce; concurrent requests fail as
 `ARCANE_AI_PROVIDER_BUSY`. Cancellation after the Worker request begins
@@ -6523,8 +6539,8 @@ createBrowserKokoroProvider(options={})
 The recognized options are
 `{id='arcane-browser-kokoro',localOnly=true,graph,model,runtime,appSecurity,
 security,store,offline=false,execution={device:'auto',maxConcurrentRequests:4}}`.
-`execution.device` is `auto`, `webgpu`, or `wasm`; its capacity is an integer
-from 1 through 4. `graph` is mutually exclusive with `model` and `runtime`. The
+`execution.device` is `auto`, `webnn-npu`, `webgpu`, or `wasm`; its capacity is
+an integer from 1 through 4. `graph` is mutually exclusive with `model` and `runtime`. The
 mutable result is
 `{protocol:'arcane-ai-provider/2',role:'tts',id,localOnly:true,
 maxConcurrentRequests,catalog,inspect,status,load,request,unload,dispose}`. The
@@ -6543,10 +6559,11 @@ mono 16-bit PCM. Unsupported formats fail
 `ARCANE_AI_UNSUPPORTED_RESPONSE_FORMAT`; malformed adapter audio fails
 `ARCANE_AI_INVALID_PROVIDER_RESULT`. Unknown fields and accessors reject as malformed.
 
-Automatic execution attempts a complete WebGPU pool when the browser exposes
-WebGPU and falls back by replacing the complete candidate pool with WASM when
-WebGPU model loading rejects. Explicit `webgpu` does not fall back. Every slot
-loads the same caller-selected model and dtype in a distinct Worker so the
+Automatic execution tries a complete WebNN NPU pool when
+`navigator.ml.createContext` is exposed, then WebGPU when `navigator.gpu` is
+exposed, then CPU through WASM. A failed candidate is cleaned up before a fresh
+pool tries the next backend. Explicit device selections do not fall back. Every
+slot loads the same caller-selected model and dtype in a distinct Worker so the
 selected adapter's per-isolate inference serialization does not serialize the
 pool. Direct provider `status().execution` reports `requestedDevice`,
 `selectedDevice`, `maxConcurrentRequests`, and `activeRequestCount`.
@@ -6555,7 +6572,11 @@ by `AI.configureBrowserSpeech()`, use
 `ai.providerRuntime.status('tts', {execution:true}).execution`. Requested
 `auto` with selected `wasm` means automatic fallback occurred. Inspection
 errors propagate; the default runtime `status()` remains a sticky lifecycle
-read. These fields do not prove physical GPU kernel overlap.
+read. `selectedDevice` names the backend requested by the successful upstream
+session load. These fields do not prove that every operation ran on a physical
+NPU or GPU, or that accelerator kernels overlap. WebNN may execute unsupported
+operations through WASM; exact model, browser, driver, and hardware
+compatibility remains upstream.
 
 Capacity 4 means up to four segments synthesize at once. Segment 5 and later
 wait in the SDK's provider-neutral FIFO queue; they are not dropped. Synthesis

package/examples/wasm-ai-demo/README.md

@@ -6,13 +6,15 @@ For the smallest first request, start with the [browser speech quick start](../.
 
 ## Speech defaults and inspection
 
-The demo deliberately omits `tts.execution` in `speechConfiguration(dbopfs)` so it consumes the SDK default `{device:'auto',maxConcurrentRequests:4}`. Change that application's TTS record to `execution:{device:'wasm',maxConcurrentRequests:1}` to use less memory, or choose `webgpu` explicitly. Allowed capacities are 1 through 4; Whisper and the LLM retain capacity one.
+The demo omits both speech execution records in `speechConfiguration(dbopfs)` so it consumes the SDK defaults: `{device:'auto',maxConcurrentRequests:1}` for Whisper STT and `{device:'auto',maxConcurrentRequests:4}` for Kokoro TTS. Auto tries WebNN NPU when `navigator.ml.createContext` is exposed, then WebGPU when `navigator.gpu` is exposed, then CPU through WASM. Failed loads are cleaned up before fresh Workers try the next device with the same prepared model and dtype. Explicit `webnn-npu`, `webgpu`, and `wasm` selections do not fall back.
 
-The maintained Kokoro selection uses `fp32` because [Kokoro.js recommends `fp32` when using WebGPU](https://github.com/hexgrad/kokoro/tree/main/kokoro.js#usage). Automatic fallback keeps the same dtype on WASM. `selectedDevice` identifies the loaded route; it does not validate speech correctness or audio quality, so evaluate actual output for each browser and device combination your application supports.
+Change the application's TTS record to `execution:{device:'wasm',maxConcurrentRequests:1}` to use fewer synthesis sessions. TTS accepts capacities 1 through 4; Whisper accepts only 1 and the LLM retains capacity one.
+
+The maintained Kokoro selection uses `fp32` because [Kokoro.js recommends `fp32` when using WebGPU](https://github.com/hexgrad/kokoro/tree/main/kokoro.js#usage). Automatic fallback keeps that dtype on every device. `selectedDevice` identifies the backend requested by the successful upstream session load. It does not prove every operation ran on a physical NPU or GPU; WebNN may use WASM for unsupported operations. Exact model, browser, driver, and hardware compatibility and actual speech quality require evaluation on that combination.
 
 Capacity 4 means up to four segments synthesize at once. Segment 5 and later wait in the SDK's FIFO queue; they are not dropped. Synthesis may finish out of order, but playback waits for earlier segments and plays exact input order. Each slot owns a Worker/model session, so raising capacity trades memory for latency.
 
-Use the shared Speech component to load/unmute speech, then select **Inspect speech execution** below Chat. The button reads `ai.providerRuntime.status('tts',{execution:true}).execution` and displays requested device, selected device, capacity, active requests, and automatic WASM fallback. It is a snapshot at the moment clicked. `selectedDevice:null` means no pool is selected; `webgpu` reports the upstream execution-provider selection and does not prove physical GPU kernel overlap or audio quality. Auto may fall back to WASM with the same selected model/dtype; explicit WebGPU reports an error when it cannot load.
+Use the shared Speech component to load/unmute speech, then select **Inspect speech execution** below Chat. The button reads `ai.providerRuntime.status('tts',{execution:true}).execution` and displays requested device, selected device, capacity, active requests, and automatic WASM fallback. It is a snapshot at the moment clicked. `selectedDevice:null` means no pool is selected. The corresponding Whisper report is available through `ai.providerRuntime.status('stt',{execution:true}).execution`; reading either report does not load a model.
 
 Shared Speech still owns mute, stop, and voice controls. The example's status button inspects the public report without loading a model or reaching into private providers.
 

package/examples/wasm-ai-demo/app.js

@@ -434,7 +434,7 @@ function speechConfiguration(dbopfs) {
       offline: false,
     },
     tts: {
-      // Omit execution to use the SDK's auto device and four synthesis slots.
+      // Omit execution for NPU, GPU, then CPU selection and four synthesis slots.
       // Kokoro.js recommends fp32 for the WebGPU route attempted by auto.
       providerId: "wasm-ai-demo-browser-kokoro",
       model: {

package/package.json

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