arcane-os 0.6.0 → 0.6.2

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## 0.6.2
+
+- Replace browser NPU setup buttons with direct browser-specific flags links
+  and retain copy-address controls and the public `open()` method.
+- Add the missing GPU performance flags link, setup instructions, and GPU
+  detection control. Chrome uses its own `chrome://` flags address.
+- Show adapter availability and its reported name after one shared detection
+  request. Keep fallback and failed detection visible without claiming that
+  the browser performance flag is enabled or a model is running on that GPU.
+  Detection creates no device, loads no model, and changes no browser settings.
+
+## 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

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.6.0` SDK contract. Applications pin one exact npm
+This checkout defines the `0.6.2` 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.6.0 new hello-speech --path ./hello-speech --target browser
+npx arcane-os@0.6.2 new hello-speech --path ./hello-speech --target browser
 cd hello-speech
 npm install
 npm run dev
@@ -363,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.6.0 new my-app --path ./my-app --target portable --git
+npx arcane-os@0.6.2 new my-app --path ./my-app --target portable --git
 cd my-app
 npm install
 npm run dev
@@ -373,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.6.0
+npm install --save-dev --save-exact arcane-os@0.6.2
 npm exec -- arcane init my-app --target portable
 ```
 
@@ -389,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.6.0` for the initial bootstrap because it names this npm
+Use `npx arcane-os@0.6.2` 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`,
@@ -409,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.6.0.tgz
+npm install --save-dev --save-exact ../arcane-os-sdk/arcane-os-0.6.2.tgz
 npm ci
 ```
 
@@ -418,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.6.0` registry package and
+the local declaration with the exact `arcane-os@0.6.2` registry package and
 commit the regenerated lock.
 
 Generated repositories use `npm ci --ignore-scripts` in CI. Run dependency
@@ -557,7 +557,7 @@ package installation, or assertions.
 
 ## Current target support
 
-Version `0.6.0` exposes one browser target and five explicitly paired
+Version `0.6.2` 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,104 @@
+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";
+      highPerformanceGpu = { name, url: "chrome://flags/#force-high-performance-gpu" };
+    } 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),
+  };
+}
+
+// Adapter selection is availability evidence, not the browser flag's state or
+// proof that a model is executing on this GPU. The power preference is a hint.
+export async function detectBrowserGpu(navigatorObject = globalThis.navigator) {
+  if (!is.function(navigatorObject?.gpu?.requestAdapter)) {
+    return { available: false, reason: "api-unavailable" };
+  }
+  const adapter = await navigatorObject.gpu.requestAdapter({ powerPreference: "high-performance" });
+  if (!adapter) return { available: false, reason: "adapter-unavailable" };
+  const info = adapter.info;
+  return {
+    available: true,
+    name: info?.description
+      || [info?.vendor, info?.architecture, info?.device].filter(Boolean).join(" ")
+      || "WebGPU adapter",
+    isFallbackAdapter: is.boolean(info?.isFallbackAdapter)
+      ? info.isFallbackAdapter
+      : is.boolean(adapter.isFallbackAdapter) ? adapter.isFallbackAdapter : null,
+  };
+}

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/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.6.0` runtime requires Arcane `0.8.12` or newer. Compatibility
+The SDK `0.6.2` 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

package/docs/reference/README.md

@@ -143,7 +143,7 @@ The synchronized browser payload exposes:
   ESM modules, classic vendor globals, one worker protocol, and one Node-oriented
   mail transport;
 - 14 shared entity modules under `runtime/arcane/entities/`;
-- 39 reusable HTML-import components under `runtime/arcane/components/`;
+- 40 reusable HTML-import components under `runtime/arcane/components/`;
 - seven shared CSS artifacts, images, optional physical-workspace security
   files where present, and the vendored `strong-type` dependency.
 

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

@@ -130,6 +130,53 @@ window.addEventListener('ai-tts-failure', function reportSpeechFailure(event) {
 
 Call `speechEvents.abort()` when disposing that interface to remove the listener.
 
+## Browser NPU and GPU 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, then requests one WebGPU adapter to display its availability and reported
+name. It does not load a model or create a GPU device or WebNN context:
+
+```html
+<html-import
+  id="browserAISetup"
+  href="/arcane/components/browser-ai-setup.html">
+</html-import>
+```
+
+The **NPU setup** section provides real browser-specific flags links. 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. Full addresses and copy controls
+remain available if the browser blocks internal-page links.
+The [ONNX Runtime WebNN guide](https://onnxruntime.ai/docs/tutorials/web/ep-webnn.html)
+documents the **Enables WebNN API** flag and model/operator requirements.
+
+The **GPU performance** section shows adapter detection and, on desktop Windows
+Chromium browsers, the matching Force High Performance GPU flags link. Identified
+Chrome uses `chrome://flags/#force-high-performance-gpu`; other recognized
+Chromium browsers use their corresponding internal scheme. **Detect GPU** or
+**Refresh browser availability** requests a new availability result; concurrent
+requests share the pending operation. The public `checkGpu()` method provides
+the same promise, while `refresh()` remains a synchronous API-presence and
+settings update. Component readiness does not wait for adapter detection.
+
+Adapter selection uses `powerPreference: "high-performance"` as a hint, not proof
+of the selected GPU's performance or the flag's current state. A returned
+adapter establishes availability only; its fallback classification is reported
+when exposed. The component cannot read the browser flag or prove that a model
+is executing on the adapter. See the
+[component contract](../runtime-components.md#browser-ai-setuphtml) for result
+fields, failure handling, and disposal behavior.
+
+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`.

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

@@ -5,9 +5,9 @@
     "repository": "https://github.com/TheWizardNexus/arcane-os-sdk.git",
     "branch": "main",
     "path": "runtime/arcane/components",
-    "sdkVersion": "0.5.18"
+    "sdkVersion": "0.6.2"
   },
-  "componentCount": 39,
+  "componentCount": 40,
   "loader": "/arcane/modules/HTMLImport.js",
   "artifacts": [
     {
@@ -76,6 +76,30 @@
       "transport": "HTMLImport + DOM; injected Arcane/provider modules where listed",
       "normalization": "DOM-normalized; caller/provider results remain external"
     },
+    {
+      "file": "runtime/arcane/components/browser-ai-setup.html",
+      "name": "browser-ai-setup.html",
+      "purpose": "Displays browser API and WebGPU adapter availability with browser-specific NPU and GPU flags links.",
+      "methods": [
+        "refresh()",
+        "checkGpu()",
+        "open()",
+        "destroy()",
+        "ready"
+      ],
+      "events": [
+        "browser-ai-setup-ready"
+      ],
+      "slots": [],
+      "dependencies": [
+        "browser-device-settings.mjs",
+        "arcane-os/logging",
+        "arcane-os/event-manager"
+      ],
+      "availability": "Browser and supported native WebViews",
+      "transport": "HTMLImport + DOM; browser flags links, Clipboard API, WebGPU adapter request, and preserved open() navigation attempt with alert",
+      "normalization": "API presence, adapter availability, and setup instructions normalized. Mounting starts one adapter request; checkGpu() coalesces concurrent calls, while refresh() remains synchronous. No GPU device, model, or WebNN context is created. Adapter availability does not establish browser flag state, high-performance selection, or model execution."
+    },
     {
       "file": "runtime/arcane/components/calculator.html",
       "name": "calculator.html",

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 and WebGPU adapter availability, with browser-specific NPU and GPU flags links. | `refresh()`<br>`checkGpu()`<br>`open()`<br>`destroy()`<br>`ready` | `browser-ai-setup-ready` | API and adapter availability; browser flag state and model 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,81 @@ 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, detects an
+available WebGPU adapter, and provides browser-specific NPU and GPU flags links.
+The WebNN addresses are real links: Chrome and Edge receive their own addresses;
+other or unidentified browsers show both explicit choices. Desktop Windows
+Chromium browsers also receive the matching Force High Performance GPU link,
+including `chrome://flags/#force-high-performance-gpu` for identified Chrome.
+Copy controls and complete addresses remain available when the browser blocks
+navigation to an internal page.
+
+### Public surface
+
+Methods/properties: `refresh()`, `checkGpu()`, `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.
+
+`checkGpu()` returns a promise for one adapter-availability record. Concurrent
+calls share the pending promise. The component requests an adapter with the
+`"high-performance"` power-preference hint; it does not create a GPU device or
+load a model. An unavailable result contains `available: false` and a `reason`
+of `"api-unavailable"` or `"adapter-unavailable"`. An available result contains
+`available: true`, the reported adapter `name`, and `isFallbackAdapter` as a
+boolean or `null` when the browser exposes no classification. Adapter selection
+does not prove that a browser flag is enabled, that the fastest GPU was selected,
+or that a model is using it. Failure is displayed and logged, and the promise
+resolves to `false`; destruction also yields `false` and suppresses late UI
+updates.
+
+Mounting starts one `checkGpu()` operation. **Detect GPU** repeats it explicitly;
+**Refresh browser availability** calls both `refresh()` and `checkGpu()`. Calling
+`refresh()` directly remains synchronous and does not request an adapter.
+`ready` and `browser-ai-setup-ready` describe component setup, which can complete
+while adapter detection is still pending.
+
+`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 pending clipboard and adapter operations.
+It does not cancel the browser-owned adapter request. 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, adapter availability,
+and setup instructions are normalized; browser flag state, clipboard support,
+and model execution remain platform-owned. Mounting requests one WebGPU adapter
+when that API is available. No GPU device, model, or WebNN context is created.
+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

@@ -3566,5 +3566,5 @@ console.log(Object.keys(module));
 ## Entity and component continuations
 
 - [Runtime entity modules](runtime-entities.md) explains all 14 modules, and [shared entity contracts](core/arcane-entities.md) owns all 29 exports.
-- [Runtime components](runtime-components.md) owns all 39 HTML-import fragments, methods, slots, and events.
+- [Runtime components](runtime-components.md) owns all 40 HTML-import fragments, methods, slots, and events.
 - [Arcane Ollama](arcane-ollama.md) expands the raw-versus-normalized behavior of `Ollama.js`.

package/package.json

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

package/runtime/arcane/components/browser-ai-setup.html

@@ -0,0 +1,288 @@
+<link rel="stylesheet" href="./arcane/css/primitives.css?v=1">
+<style>
+    :host{display:block;min-width:0}
+    .availability{display:grid;gap:var(--arcane-space-2);margin:0}
+    .availability div{display:grid;gap:var(--arcane-space-1)}
+    .availability dt{font-weight:700}
+    .availability dd{margin:0}
+    .flag-choice{margin-block:var(--arcane-space-4)}
+    .flag-choice h3{margin-block:var(--arcane-space-2)}
+    .actions{display:flex;flex-wrap:wrap;gap:var(--arcane-space-2)}
+    p,dt,dd,li,button,a{overflow-wrap:anywhere}
+    button{white-space:normal}
+    .flag-address{display:block;white-space:pre-wrap;overflow-wrap:anywhere;user-select:text;margin-block:var(--arcane-space-2)}
+    #gpuAvailability{white-space:normal;overflow-wrap:anywhere;line-height:1.4;max-width:100%;box-sizing:border-box}
+    li{margin-block:var(--arcane-space-2)}
+</style>
+
+<section class="arcane-card" aria-labelledby="setupTitle">
+    <header class="arcane-card__header">
+        <h2 id="setupTitle" class="arcane-section-heading">Browser AI acceleration</h2>
+    </header>
+    <div class="arcane-card__body">
+        <p id="browserName"></p>
+        <dl class="availability" aria-live="polite">
+            <div><dt>WebNN API</dt><dd id="webnnAvailability"></dd></div>
+            <div><dt>WebGPU API</dt><dd id="webgpuAvailability"></dd></div>
+        </dl>
+        <p class="arcane-help">These checks show browser APIs only. They do not report whether a model is running on an NPU or GPU.</p>
+        <h3>NPU setup</h3>
+        <p id="browserInstructions"></p>
+        <div id="flagAddresses"></div>
+        <ol id="setupSteps"></ol>
+        <p>Browser API availability does not confirm that an NPU or a particular model is supported. You choose whether to change the browser setting.</p>
+        <p><a href="https://onnxruntime.ai/docs/tutorials/web/ep-webnn.html">ONNX Runtime WebNN setup documentation</a></p>
+        <h3>GPU performance</h3>
+        <p><span id="gpuAvailability" class="arcane-badge" role="status" aria-live="polite"></span></p>
+        <p id="gpuAdapterName" class="arcane-help"></p>
+        <button id="detectGpu" class="arcane-button arcane-button--secondary" type="button">Detect GPU</button>
+        <p id="gpuInstructions"></p>
+        <div id="gpuFlagAddress">
+            <a id="gpuFlagsLink" class="flag-address"></a>
+            <button id="copyGpuAddress" class="arcane-button arcane-button--secondary" type="button">Copy GPU flags address</button>
+            <ol>
+                <li>Open the address above. If the browser blocks the link, copy the address and paste it into the address bar.</li>
+                <li>Find “Force High Performance GPU” and choose Enabled.</li>
+                <li>Save your work, then completely close and reopen the browser before loading the model again.</li>
+            </ol>
+        </div>
+        <p class="arcane-help">GPU detection reports adapter availability. This page cannot read the flag's current setting or confirm that a model is using that adapter.</p>
+        <p id="copyStatus" class="arcane-help" role="status" aria-live="polite"></p>
+    </div>
+    <footer class="arcane-card__footer">
+        <button id="refreshAvailability" class="arcane-button arcane-button--secondary" type="button">Refresh browser availability</button>
+        <p id="setupStatus" class="arcane-help" role="status" aria-live="polite"></p>
+    </footer>
+</section>
+
+<script type="module">
+    const host=this;
+    const root=host.shadowRoot;
+    host.ready=false;
+
+    const {
+        getBrowserDeviceSettings,
+        detectBrowserGpu,
+        openBrowserDeviceSettings,
+        WEBNN_BROWSER_SETTINGS
+    }=await import('../sdk/ai/browser-device-settings.mjs');
+    const {arcaneLogging}=await import('arcane-os/logging');
+    const {createArcaneEventSource,projectArcaneDOMEvent}=await import('arcane-os/event-manager');
+    const events=createArcaneEventSource(host,{
+        source:'arcane.component.browser-ai-setup',
+        eventTypes:['browser-ai-setup-ready']
+    });
+    const lifecycleController=new AbortController();
+    const status=root.querySelector('#setupStatus');
+    const copyStatus=root.querySelector('#copyStatus');
+    const gpuAvailability=root.querySelector('#gpuAvailability');
+    const gpuAdapterName=root.querySelector('#gpuAdapterName');
+    const detectGpuButton=root.querySelector('#detectGpu');
+    const gpuFlagsLink=root.querySelector('#gpuFlagsLink');
+    const copyGpuButton=root.querySelector('#copyGpuAddress');
+    const copyButtons=[copyGpuButton];
+    const choices=[];
+    const setupSteps=[
+        'If the flags page does not open, copy the matching address into your browser\'s address bar and open it.',
+        'Find “Enables WebNN API” and choose Enabled.',
+        'Save your work, then use the browser\'s Relaunch control.',
+        'Return to this page and select Refresh browser availability.'
+    ];
+    let copyTask=null;
+    let gpuTask=null;
+    let destroyed=false;
+
+    host.refresh=refresh;
+    host.checkGpu=checkGpu;
+    host.open=open;
+    host.destroy=destroy;
+
+    function refresh(){
+        if(destroyed)return false;
+        const settings=getBrowserDeviceSettings();
+        root.querySelector('#browserName').textContent=settings.browserId==='unknown'
+            ?'Browser not identified.'
+            :`Browser: ${settings.name}.`;
+        root.querySelector('#webnnAvailability').textContent=settings.webnnAvailable
+            ?'Exposed to this page.'
+            :'Unavailable to this page.';
+        root.querySelector('#webgpuAvailability').textContent=settings.webgpuAvailable
+            ?'Exposed to this page.'
+            :'Unavailable to this page.';
+        root.querySelector('#browserInstructions').textContent=settings.webnnFlagsURL
+            ?`Open the ${settings.name} WebNN flags link below to set up NPU access.`
+            :'A matching WebNN flags address is not known for this browser. Choose Google Chrome or Microsoft Edge below if that is the browser you are using.';
+        for(const choice of choices){
+            choice.row.hidden=Boolean(settings.webnnFlagsURL)
+                &&choice.target.url!==settings.webnnFlagsURL;
+        }
+        const gpuTarget=settings.highPerformanceGpu;
+        root.querySelector('#gpuFlagAddress').hidden=!gpuTarget;
+        root.querySelector('#gpuInstructions').textContent=gpuTarget
+            ?`If this computer has multiple GPUs, use the ${gpuTarget.name} flags link to request the high-performance GPU when available.`
+            :'The Force High Performance GPU flag is documented here for desktop Windows Chromium browsers. No matching flags link is known for this browser and platform.';
+        if(gpuTarget){
+            gpuFlagsLink.href=gpuTarget.url;
+            gpuFlagsLink.textContent=gpuTarget.url;
+            gpuFlagsLink.setAttribute('aria-label',`${gpuTarget.name} Force High Performance GPU flags address: ${gpuTarget.url}`);
+        }else{
+            gpuFlagsLink.removeAttribute('href');
+            gpuFlagsLink.textContent='';
+        }
+        return settings;
+    }
+
+    function checkGpu(){
+        if(destroyed)return Promise.resolve(false);
+        if(gpuTask)return gpuTask;
+        gpuAvailability.textContent='Detecting GPU...';
+        gpuAvailability.dataset.status='pending';
+        gpuAdapterName.textContent='';
+        detectGpuButton.disabled=true;
+        gpuTask=detect().finally(function finishGpuDetection(){
+            gpuTask=null;
+            if(!destroyed)detectGpuButton.disabled=false;
+        });
+        return gpuTask;
+
+        async function detect(){
+            try{
+                const result=await detectBrowserGpu();
+                if(destroyed)return false;
+                gpuAvailability.textContent=result.available
+                    ?result.isFallbackAdapter===true
+                        ?'Fallback WebGPU adapter detected.'
+                        :'GPU detected — WebGPU adapter available.'
+                    :'No WebGPU adapter available to this page.';
+                gpuAvailability.dataset.status=result.available&&result.isFallbackAdapter!==true
+                    ?'success':'warning';
+                gpuAdapterName.textContent=result.available?result.name:'';
+                return result;
+            }catch(error){
+                if(!destroyed){
+                    gpuAvailability.textContent='GPU detection failed. Select Detect GPU to try again.';
+                    gpuAvailability.dataset.status='error';
+                    arcaneLogging.error('Unable to detect the browser GPU adapter.',error);
+                }
+                return false;
+            }
+        }
+    }
+
+    function open(browserId){
+        if(destroyed)return false;
+        const current=refresh();
+        const selectedId=browserId??current.browserId;
+        const target=WEBNN_BROWSER_SETTINGS.find(function matchSetupBrowser(browser){
+            return browser.browserId===selectedId;
+        });
+        if(!target){
+            status.textContent='Choose the Google Chrome or Microsoft Edge flags link that matches your browser.';
+            return false;
+        }
+        const instructions=setupSteps.map(function numberSetupStep(step,index){
+            return `${index+1}. ${step}`;
+        }).join('\n');
+        openBrowserDeviceSettings(
+            target,
+            `NPU setup for ${target.name}\n\n${instructions}\n\n${target.url}`
+        );
+        status.textContent='If the flags page did not open, copy its address above and paste it into your browser\'s address bar.';
+    }
+
+    function copyAddress(address){
+        if(destroyed)return Promise.resolve(false);
+        if(copyTask)return copyTask;
+        copyStatus.textContent='Copying address...';
+        for(const button of copyButtons)button.disabled=true;
+        copyTask=writeAddress().finally(function finishAddressCopy(){
+            copyTask=null;
+            if(!destroyed){
+                for(const button of copyButtons)button.disabled=false;
+            }
+        });
+        return copyTask;
+
+        async function writeAddress(){
+            try{
+                await globalThis.navigator.clipboard.writeText(address);
+                if(destroyed)return false;
+                copyStatus.textContent='Address copied. Paste it into your browser\'s address bar.';
+                return true;
+            }catch(error){
+                if(!destroyed){
+                    copyStatus.textContent='The address could not be copied automatically. Select the complete address above, copy it manually, and paste it into your browser\'s address bar.';
+                    arcaneLogging.error('Unable to copy the browser flags address.',error);
+                }
+                return false;
+            }
+        }
+    }
+
+    const addressList=root.querySelector('#flagAddresses');
+    for(const target of WEBNN_BROWSER_SETTINGS){
+        const row=document.createElement('section');
+        const heading=document.createElement('h3');
+        const address=document.createElement('a');
+        const actions=document.createElement('div');
+        const copyButton=document.createElement('button');
+        row.className='flag-choice';
+        heading.textContent=target.name;
+        address.className='flag-address';
+        address.href=target.url;
+        address.textContent=target.url;
+        address.setAttribute('aria-label',`${target.name} WebNN flags address: ${target.url}`);
+        actions.className='actions';
+        copyButton.type='button';
+        copyButton.className='arcane-button arcane-button--secondary';
+        copyButton.textContent=`Copy ${target.name} address`;
+        copyButton.addEventListener('click',function copySelectedBrowserAddress(){
+            return copyAddress(target.url);
+        },{signal:lifecycleController.signal});
+        actions.append(copyButton);
+        row.append(heading,address,actions);
+        addressList.append(row);
+        choices.push({row,target});
+        copyButtons.push(copyButton);
+    }
+
+    copyGpuButton.addEventListener('click',function copyGpuFlagsAddress(){
+        const target=getBrowserDeviceSettings().highPerformanceGpu;
+        if(target)return copyAddress(target.url);
+    },{signal:lifecycleController.signal});
+    detectGpuButton.addEventListener('click',checkGpu,{signal:lifecycleController.signal});
+    const stepList=root.querySelector('#setupSteps');
+    for(const step of setupSteps){
+        const item=document.createElement('li');
+        item.textContent=step;
+        stepList.append(item);
+    }
+
+    root.querySelector('#refreshAvailability').addEventListener('click',function refreshBrowserAvailability(){
+        refresh();
+        status.textContent='Browser API availability refreshed.';
+        return checkGpu();
+    },{signal:lifecycleController.signal});
+    host.ownerDocument.defaultView.addEventListener('pagehide',function disposeBeforePageUnload(event){
+        if(!event.persisted)destroy();
+    },{
+        signal:lifecycleController.signal
+    });
+
+    function destroy(){
+        if(destroyed)return false;
+        destroyed=true;
+        host.ready=false;
+        lifecycleController.abort('browser-ai-setup-destroyed');
+        events.dispose();
+        return true;
+    }
+
+    refresh();
+    checkGpu();
+    host.ready=true;
+    const publication=events.dispatch('browser-ai-setup-ready',{}, {
+        publicDetail:{ready:true}
+    });
+    projectArcaneDOMEvent(host,publication.occurrence);
+</script>