arcane-os 0.5.19 → 0.6.1

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## 0.6.1
+
+- Add a reusable profile component for browser NPU setup and WebNN/WebGPU API
+  availability. Its setup button uses the existing GPU guidance approach:
+  attempt the appropriate Chrome or Edge flags page, then show an alert with
+  instructions and the address to paste if the browser blocks navigation.
+- Share browser identification and the flags-opening helper with the existing
+  high-performance GPU notice. Preserve that notice's targets and wording.
+  Setup does not change saved preferences, browser flags, selected models, or
+  inference; API availability is not reported as physical NPU execution.
+
+## 0.6.0
+
+- Prefer WebNN NPU, then WebGPU, then CPU through WASM for browser Whisper
+  transcription and Kokoro synthesis. Skip absent accelerator APIs and replace
+  failed model-load Workers before trying the next backend with the same
+  application-selected model and precision.
+- Add Whisper execution configuration and NPU selection for both speech roles.
+  Explicit `webnn-npu`, `webgpu`, and `wasm` choices report failure without
+  falling back. Whisper retains one slot; Kokoro retains four by default and
+  accepts capacities from one through four.
+- Report requested and successfully selected backends for both roles through
+  provider execution status. Selection reports upstream session loading;
+  actual accelerator use and speech quality depend on the selected runtime,
+  model, browser, drivers, and hardware. Wllama remains on its WebGPU backend.
+
 ## 0.5.19
 
 - Report observed Wllama initialization stages and runtime activity through

package/README.md

@@ -19,7 +19,7 @@ version-locked SDK runtime, while an integrated Arcane checkout uses its live
 `arcane/` runtime. Both profiles preserve the same app URLs, theme, packaging,
 event, cancellation, and browser run contracts.
 
-This checkout defines the `0.5.19` SDK contract. Applications pin one exact npm
+This checkout defines the `0.6.1` SDK contract. Applications pin one exact npm
 version and lockfile; registry state is deliberately not baked into application
 artifacts.
 
@@ -35,7 +35,7 @@ Create one browser application, install its pinned SDK, and start its source
 server:
 
 ```bash
-npx arcane-os@0.5.19 new hello-speech --path ./hello-speech --target browser
+npx arcane-os@0.6.1 new hello-speech --path ./hello-speech --target browser
 cd hello-speech
 npm install
 npm run dev
@@ -299,10 +299,16 @@ provider factories. The package contains the plain-JavaScript provider and
 Worker machinery, not speech runtimes, models, voices, or a CDN default. An app
 must supply each runtime/model selection explicitly. Speech roles
 load, cancel, unload, fail, and recover independently, so speech failure never
-silently falls back or prevents text chat. Kokoro defaults to a four-slot Worker
-and model-session pool: it selects WebGPU when the browser can load the complete
-pool and otherwise recreates that pool on WASM. Apps may select `webgpu` or
-`wasm` explicitly and may set the bounded TTS capacity from one through four.
+switches to a cloud provider or prevents text chat. Both roles default to
+NPU, GPU, then CPU automatic selection: WebNN NPU when its browser API is
+exposed, then WebGPU, then WASM. Failed model loads release their Workers before
+the next backend uses the same model and precision. Apps may select
+`webnn-npu`, `webgpu`, or `wasm` explicitly without automatic fallback.
+Whisper keeps one transcription slot; Kokoro defaults to four Worker/model
+sessions and accepts capacities from one through four. Both roles expose
+requested and selected devices through execution status. A selected backend
+reports successful upstream loading, not physical accelerator use for every
+operation; model and hardware compatibility remain upstream.
 
 Applications that need faster spoken-response onset can configure the shared
 TTS stream without taking over synthesis or playback:
@@ -357,7 +363,7 @@ uses the same controller for automatic memory extraction.
 Create a new repository-shaped Arcane application with the exact stable SDK:
 
 ```bash
-npx arcane-os@0.5.19 new my-app --path ./my-app --target portable --git
+npx arcane-os@0.6.1 new my-app --path ./my-app --target portable --git
 cd my-app
 npm install
 npm run dev
@@ -367,7 +373,7 @@ To enroll an existing repository, install the exact SDK and initialize only
 missing Arcane files:
 
 ```bash
-npm install --save-dev --save-exact arcane-os@0.5.19
+npm install --save-dev --save-exact arcane-os@0.6.1
 npm exec -- arcane init my-app --target portable
 ```
 
@@ -383,7 +389,7 @@ npm exec -- arcane-os targets
 No global SDK install or standalone Arcane CLI is required. The application
 repository's exact npm dependency and lockfile own the CLI and toolchain version.
 
-Use `npx arcane-os@0.5.19` for the initial bootstrap because it names this npm
+Use `npx arcane-os@0.6.1` for the initial bootstrap because it names this npm
 package explicitly; bare `npx arcane` outside an installed project could resolve
 a different package. Both installed commands invoke the same headless toolchain.
 Project-local npm scripts use the SDK pinned by that app's `package-lock.json`,
@@ -403,7 +409,7 @@ node ./bin/arcane.mjs new local-app --path ../local-app --target portable --git
 
 # From the generated app repository
 cd ../local-app
-npm install --save-dev --save-exact ../arcane-os-sdk/arcane-os-0.5.19.tgz
+npm install --save-dev --save-exact ../arcane-os-sdk/arcane-os-0.6.1.tgz
 npm ci
 ```
 
@@ -412,7 +418,7 @@ same location. The lockfile retains the selected package dependency while
 Arcane uses the installed package name and version. Local directory `file:` dependencies are not
 accepted because npm may install them as links; use a packed `.tgz`. A GitHub
 runner also needs that tarball at the locked path. After publication, replace
-the local declaration with the exact `arcane-os@0.5.19` registry package and
+the local declaration with the exact `arcane-os@0.6.1` registry package and
 commit the regenerated lock.
 
 Generated repositories use `npm ci --ignore-scripts` in CI. Run dependency
@@ -551,7 +557,7 @@ package installation, or assertions.
 
 ## Current target support
 
-Version `0.5.19` exposes one browser target and five explicitly paired
+Version `0.6.1` exposes one browser target and five explicitly paired
 native development targets: a non-runnable portable directory, a
 Windows x64 unsigned-local-test EXE bundle, Linux x64 and Linux ARM64
 unsigned-local-test DEBs, and an Android development-signed APK. The

package/browser-runtime/ai/browser-device-settings.mjs

@@ -0,0 +1,83 @@
+import Is from "../dependencies/strong-type/index.js";
+
+const is = new Is(false);
+
+export const WEBNN_BROWSER_SETTINGS = [
+  { browserId: "chrome", name: "Google Chrome", url: "chrome://flags/#web-machine-learning-neural-network" },
+  { browserId: "edge", name: "Microsoft Edge", url: "edge://flags/#web-machine-learning-neural-network" },
+];
+
+// Internal-page navigation may be blocked. The instructions remain available
+// regardless; returning from this function is not evidence that settings opened.
+export function openBrowserDeviceSettings(target, message) {
+  try {
+    globalThis.open?.(target.url, "_blank", "noopener,noreferrer");
+  } catch {
+    // Continue to the address-bar instructions when the browser rejects the URL.
+  }
+  globalThis.alert?.(message);
+}
+
+// Browser identity selects setup instructions, never hardware or model readiness.
+export function getBrowserDeviceSettings(navigatorObject = globalThis.navigator) {
+  const userAgent = String(navigatorObject?.userAgent ?? "");
+  const clientHints = navigatorObject?.userAgentData;
+  const platform = String(clientHints?.platform || navigatorObject?.platform || userAgent);
+  const brands = new Set();
+  for (const entry of clientHints?.brands ?? []) brands.add(entry.brand);
+  const desktopWindows = /\b(?:Windows|Win32|Win64)\b/iu.test(platform)
+    && clientHints?.mobile !== true
+    && !/\b(?:Android|iPhone|iPad|iPod|Mobile)\b/iu.test(userAgent);
+  let browserId = "unknown";
+  let name = "this browser";
+  let highPerformanceGpu = null;
+
+  // Preserve the existing GPU guidance for browsers that also identify as Chrome.
+  if (brands.has("Vivaldi") || /\bVivaldi\//u.test(userAgent)) {
+    browserId = "vivaldi";
+    name = "Vivaldi";
+    highPerformanceGpu = { name, url: "vivaldi://flags/#force-high-performance-gpu" };
+  } else if (brands.has("Brave") || is.function(navigatorObject?.brave?.isBrave)) {
+    browserId = "brave";
+    name = "Brave";
+    highPerformanceGpu = { name, url: "brave://flags/#force-high-performance-gpu" };
+  } else if (brands.has("Opera") || /\bOPR\//u.test(userAgent)) {
+    browserId = "opera";
+    name = "Opera";
+    highPerformanceGpu = { name, url: "opera://flags/#force-high-performance-gpu" };
+  } else if (brands.has("Microsoft Edge") || /\bEdg\//u.test(userAgent)) {
+    browserId = "edge";
+    name = "Microsoft Edge";
+    highPerformanceGpu = { name, url: "edge://flags/#force-high-performance-gpu" };
+  } else if (
+    brands.has("Chromium")
+    || brands.has("Google Chrome")
+    || /\b(?:Chrome|Chromium)\//u.test(userAgent)
+  ) {
+    // Keep the established generic GPU address for Chromium browsers that mask their brand.
+    highPerformanceGpu = { name: "your browser", url: "about://flags/#force-high-performance-gpu" };
+    if (
+      brands.has("Google Chrome")
+      || (!clientHints?.brands && /\bChrome\//u.test(userAgent)
+        && !/\b(?:SamsungBrowser|UCBrowser|YaBrowser)\//u.test(userAgent))
+    ) {
+      browserId = "chrome";
+      name = "Google Chrome";
+    } else {
+      browserId = "chromium";
+      name = "your Chromium browser";
+    }
+  }
+
+  const webnnFlagsURL = WEBNN_BROWSER_SETTINGS.find(function matchesBrowser(entry) {
+    return entry.browserId === browserId;
+  })?.url ?? null;
+  return {
+    browserId,
+    name,
+    webnnFlagsURL,
+    highPerformanceGpu: desktopWindows ? highPerformanceGpu : null,
+    webnnAvailable: is.function(navigatorObject?.ml?.createContext),
+    webgpuAvailable: Boolean(navigatorObject?.gpu),
+  };
+}

package/browser-runtime/ai/browser-speech-providers.mjs

@@ -23,8 +23,8 @@ const ROLE_OPERATION = completeValue({ stt: "transcribe", tts: "synthesize" });
 const STT_SAMPLE_RATE = 16_000;
 const TTS_SAMPLE_RATE = 24_000;
 const TTS_RESPONSE_FORMAT = "wav";
-const TTS_EXECUTION_DEVICES = new Set(["auto", "webgpu", "wasm"]);
-const DEFAULT_TTS_EXECUTION_DEVICE = "auto";
+const SPEECH_EXECUTION_DEVICES = new Set(["auto", "webnn-npu", "webgpu", "wasm"]);
+const DEFAULT_SPEECH_EXECUTION_DEVICE = "auto";
 const DEFAULT_TTS_MAX_CONCURRENT_REQUESTS = 4;
 const MAX_TTS_CONCURRENT_REQUESTS = 4;
 const ROLE_REQUEST_REASON = completeValue({
@@ -150,24 +150,21 @@ function requiredIdentifier(value, label) {
 }
 
 function normalizeSpeechExecution(role, execution) {
-  if (role === "stt") {
-    if (execution !== undefined) {
-      throw new TypeError("Browser Whisper does not accept an execution option.");
-    }
-    return completeValue({ device: "wasm", maxConcurrentRequests: 1 });
-  }
+  const label = role === "stt" ? "Browser Whisper" : "Browser Kokoro";
+  const defaultConcurrency = role === "stt" ? 1 : DEFAULT_TTS_MAX_CONCURRENT_REQUESTS;
+  const maximumConcurrency = role === "stt" ? 1 : MAX_TTS_CONCURRENT_REQUESTS;
   if (execution === undefined) {
     return completeValue({
-      device: DEFAULT_TTS_EXECUTION_DEVICE,
-      maxConcurrentRequests: DEFAULT_TTS_MAX_CONCURRENT_REQUESTS,
+      device: DEFAULT_SPEECH_EXECUTION_DEVICE,
+      maxConcurrentRequests: defaultConcurrency,
     });
   }
   if (!execution || !is.object(execution) || is.array(execution)) {
-    throw new TypeError("Browser Kokoro execution must be a plain data record.");
+    throw new TypeError(`${label} execution must be a plain data record.`);
   }
   const prototype = Object.getPrototypeOf(execution);
   if (prototype !== Object.prototype && prototype !== null) {
-    throw new TypeError("Browser Kokoro execution must be a plain data record.");
+    throw new TypeError(`${label} execution must be a plain data record.`);
   }
   const descriptors = Object.getOwnPropertyDescriptors(execution);
   for (const key of Reflect.ownKeys(descriptors)) {
@@ -175,34 +172,35 @@ function normalizeSpeechExecution(role, execution) {
       (key !== "device" && key !== "maxConcurrentRequests")
       || !Object.hasOwn(descriptors[key], "value")
     ) {
-      throw new TypeError("Browser Kokoro execution contains an unsupported or accessor field.");
+      throw new TypeError(`${label} execution contains an unsupported or accessor field.`);
     }
   }
   const device = Object.hasOwn(descriptors, "device")
     ? descriptors.device.value
-    : DEFAULT_TTS_EXECUTION_DEVICE;
+    : DEFAULT_SPEECH_EXECUTION_DEVICE;
   const maxConcurrentRequests = Object.hasOwn(descriptors, "maxConcurrentRequests")
     ? descriptors.maxConcurrentRequests.value
-    : DEFAULT_TTS_MAX_CONCURRENT_REQUESTS;
-  if (!TTS_EXECUTION_DEVICES.has(device)) {
-    throw new TypeError('Browser Kokoro execution.device must be "auto", "webgpu", or "wasm".');
+    : defaultConcurrency;
+  if (!SPEECH_EXECUTION_DEVICES.has(device)) {
+    throw new TypeError(`${label} execution.device must be "auto", "webnn-npu", "webgpu", or "wasm".`);
   }
   if (
     !is.safeInteger(maxConcurrentRequests)
     || maxConcurrentRequests < 1
-    || maxConcurrentRequests > MAX_TTS_CONCURRENT_REQUESTS
+    || maxConcurrentRequests > maximumConcurrency
   ) {
-    throw new TypeError("Browser Kokoro execution.maxConcurrentRequests must be a safe integer from 1 through 4.");
+    throw new TypeError(`${label} execution.maxConcurrentRequests must be a safe integer from 1 through ${maximumConcurrency}.`);
   }
   return completeValue({ device, maxConcurrentRequests });
 }
 
-function navigatorHasWebGpu() {
-  try {
-    return Boolean(globalThis.navigator?.gpu);
-  } catch {
-    return false;
-  }
+function speechExecutionDevices(requestedDevice) {
+  if (requestedDevice !== "auto") return [requestedDevice];
+  const devices = [];
+  if (is.function(globalThis.navigator?.ml?.createContext)) devices.push("webnn-npu");
+  if (globalThis.navigator?.gpu) devices.push("webgpu");
+  devices.push("wasm");
+  return devices;
 }
 
 function createProviderAuthority({
@@ -1187,14 +1185,12 @@ function createBrowserSpeechProvider({
       cache,
       lifecycleReason,
       activeOperation,
-      execution: role === "tts"
-        ? completeValue({
-          requestedDevice: speechExecution.device,
-          selectedDevice,
-          maxConcurrentRequests: speechExecution.maxConcurrentRequests,
-          activeRequestCount: requestOperations.size,
-        })
-        : null,
+      execution: completeValue({
+        requestedDevice: speechExecution.device,
+        selectedDevice,
+        maxConcurrentRequests: speechExecution.maxConcurrentRequests,
+        activeRequestCount: requestOperations.size,
+      }),
       secureIntent,
       warnings: providerWarnings(runtimeWarnings),
     });
@@ -1535,34 +1531,42 @@ function createBrowserSpeechProvider({
               `${role}-load-superseded-by-unload`,
             );
           }
-          const primaryDevice = role === "stt"
-            ? "wasm"
-            : speechExecution.device === "auto"
-              ? navigatorHasWebGpu() ? "webgpu" : "wasm"
-              : speechExecution.device;
-          try {
-            pool = await loadWorkerPool(
-              preparation,
-              primaryDevice,
-              record.warnings,
-              linked.controller.signal,
-            );
-          } catch (error) {
-            if (
-              role !== "tts"
-              || speechExecution.device !== "auto"
-              || primaryDevice !== "webgpu"
-              || linked.controller.signal.aborted
-              || operationGeneration !== generation
-            ) {
-              throw error;
+          const devices = speechExecutionDevices(speechExecution.device);
+          for (const [index, device] of devices.entries()) {
+            throwIfAborted(linked.controller.signal, `${role}-load-cancelled`);
+            if (operationGeneration !== generation) {
+              throw providerError(
+                "ARCANE_AI_OPERATION_SUPERSEDED",
+                "Browser speech loading was superseded.",
+                undefined,
+                `${role}-load-superseded-by-unload`,
+              );
+            }
+            try {
+              pool = await loadWorkerPool(
+                preparation,
+                device,
+                record.warnings,
+                linked.controller.signal,
+              );
+              break;
+            } catch (error) {
+              if (
+                index === devices.length - 1
+                || linked.controller.signal.aborted
+                || operationGeneration !== generation
+                || error?.code === "ARCANE_AI_REQUEST_ABORTED"
+                || error?.code === "ARCANE_AI_OPERATION_SUPERSEDED"
+              ) {
+                throw error;
+              }
+              // A fresh Worker releases a failed upstream initialization before
+              // the next backend reuses the same prepared model and precision.
+              const warning = `Browser ${role} ${device} loading failed; trying ${devices[index + 1]}.`;
+              record.warnings = [...record.warnings, warning];
+              lastWarnings = record.warnings;
+              console.warn(warning, error);
             }
-            pool = await loadWorkerPool(
-              preparation,
-              "wasm",
-              record.warnings,
-              linked.controller.signal,
-            );
           }
           throwIfAborted(
             linked.controller.signal,

package/browser-runtime/ai/browser-wasm-llm-provider.mjs

@@ -8,6 +8,7 @@ import {
   resolveModelSecurity,
 } from "./model-controller.mjs";
 import { createPackagedWllamaRuntime } from "./browser-wllama-runtime.mjs";
+import { getBrowserDeviceSettings, openBrowserDeviceSettings } from "./browser-device-settings.mjs";
 import { arcaneEvents } from "../event-manager.mjs";
 
 const is = new Is(false);
@@ -264,65 +265,20 @@ function publicDescriptor(source) {
   return modelDescriptor(source);
 }
 
-function highPerformanceGpuBrowser() {
-    const navigatorObject = globalThis.navigator;
-    const userAgent = String(navigatorObject?.userAgent ?? "");
-    const clientHints = navigatorObject?.userAgentData;
-    const platform = String(clientHints?.platform || navigatorObject?.platform || userAgent);
-    if (
-        !/\b(?:Windows|Win32|Win64)\b/iu.test(platform)
-        || clientHints?.mobile === true
-        || /\b(?:Android|iPhone|iPad|iPod|Mobile)\b/iu.test(userAgent)
-    ) {
-        return null;
-    }
-
-    const brands = new Set();
-    for (const entry of clientHints?.brands ?? []) {
-        brands.add(entry.brand);
-    }
-    // Vivaldi can append its identity while also identifying as Edge or Chrome.
-    if (brands.has("Vivaldi") || /\bVivaldi\//u.test(userAgent)) {
-        return { name: "Vivaldi", url: "vivaldi://flags/#force-high-performance-gpu" };
-    }
-    if (brands.has("Brave") || is.function(navigatorObject?.brave?.isBrave)) {
-        return { name: "Brave", url: "brave://flags/#force-high-performance-gpu" };
-    }
-    if (brands.has("Opera") || /\bOPR\//u.test(userAgent)) {
-        return { name: "Opera", url: "opera://flags/#force-high-performance-gpu" };
-    }
-    if (brands.has("Microsoft Edge") || /\bEdg\//u.test(userAgent)) {
-        return { name: "Microsoft Edge", url: "edge://flags/#force-high-performance-gpu" };
-    }
-    if (
-        brands.has("Chromium")
-        || brands.has("Google Chrome")
-        || /\b(?:Chrome|Chromium)\//u.test(userAgent)
-    ) {
-        // Some Chromium browsers mask their brand. about:// uses their own flags page.
-        return { name: "your browser", url: "about://flags/#force-high-performance-gpu" };
-    }
-    return null;
-}
-
 function notifyHighPerformanceGpu(adapter) {
     if (highPerformanceGpuNoticeShown) {
         return;
     }
-    const browser = highPerformanceGpuBrowser();
+    const browser = getBrowserDeviceSettings().highPerformanceGpu;
     if (!browser) {
         return;
     }
     highPerformanceGpuNoticeShown = true;
-    try {
-        globalThis.open?.(browser.url, "_blank", "noopener,noreferrer");
-    } catch {
-        // Browsers may reject internal-page navigation from web content.
-    }
     const adapterName = adapter.description || adapter.name
         || [adapter.vendor, adapter.architecture].filter(Boolean).join(" ")
         || "the available WebGPU adapter";
-    globalThis.alert?.(
+    openBrowserDeviceSettings(
+        browser,
         `Selected WebGPU adapter: ${adapterName}.\n\n`
         + `If this computer has multiple GPUs, enable “Force High Performance GPU” in ${browser.name} `
         + "to request the high-performance GPU when available. "

package/browser-runtime/ai/speech-worker-runtime.mjs

@@ -738,10 +738,9 @@ function validateConfiguration(configuration, role) {
     if (
       descriptorMismatch
       || !Object.hasOwn(descriptors, "device")
-      || (role === "stt" && descriptors.device.value !== "wasm")
-      || (role === "tts"
-        && descriptors.device.value !== "wasm"
-        && descriptors.device.value !== "webgpu")
+      || (descriptors.device.value !== "wasm"
+        && descriptors.device.value !== "webgpu"
+        && descriptors.device.value !== "webnn-npu")
     ) {
       throw workerError(
         "ARCANE_AI_INVALID_REQUEST",
@@ -1367,7 +1366,7 @@ async function createWhisperEngine(namespace, configuration, signal, report) {
     "automatic-speech-recognition",
     configuration.model.repository,
     {
-      device: "wasm",
+      device: configuration.execution?.device ?? "wasm",
       dtype: configuration.model.dtype ?? "fp32",
       revision: configuration.model.revision,
       progress_callback: report,

package/docs/architecture.md

@@ -279,7 +279,7 @@ paths are withheld from the native provider. The provider copies the complete
 selected release rather than accepting an unrelated source path. Verification
 is a separate explicit operation for a selected release artifact.
 
-The SDK `0.5.19` runtime requires Arcane `0.8.12` or newer. Compatibility
+The SDK `0.6.1` runtime requires Arcane `0.8.12` or newer. Compatibility
 is contractual rather than exact-version pinning: the prepared Core must meet
 the highest minimum declared by the runtime, selected app, and bundled app
 dependencies; keep each app's Arcane protocol generation; and provide every