arcane-os 0.32.0 → 0.33.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 0.33.0
+
+- Add the default and named `AIModelSelectionController` export at
+  `arcane-os/modules/AIModelSelectionController.js`. It coordinates existing
+  LLM, STT and TTS provider/model select elements with app-owned defaults,
+  catalogs and optional explicit asynchronous inventory discovery.
+- Preserve unknown saved values and newer drafts during asynchronous
+  hydration and discovery, including paired LLM provider/model choices and
+  per-provider model memory. Expose current selection, operation state,
+  original errors and deterministic disposal without late control mutations.
+- Keep the existing six-slot preference tuple order and spelling unchanged.
+  The controller neither saves User preferences nor activates or downloads
+  providers, models or voices; application policy and persistence stay local.
+
 ## 0.32.0
 
 - Export `profileUpdateFromSearchParams(searchParams)` from

package/README.md

@@ -19,7 +19,7 @@ version-locked SDK runtime, while an integrated Arcane checkout uses its live
 `arcane/` runtime. Both profiles share the theme, packaging, event, cancellation,
 and browser run contracts while retaining their selected application layout.
 
-This checkout defines the `0.32.0` SDK contract. Applications pin one exact npm
+This checkout defines the `0.33.0` SDK contract. Applications pin one exact npm
 version and lockfile; registry state is deliberately not baked into application
 artifacts.
 
@@ -85,7 +85,7 @@ Create one browser application, install its pinned SDK, and start its source
 server:
 
 ```bash
-npx arcane-os@0.32.0 new hello-speech --path ./hello-speech --target browser
+npx arcane-os@0.33.0 new hello-speech --path ./hello-speech --target browser
 cd hello-speech
 npm install
 ```

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

@@ -8,9 +8,9 @@
     "sdkVersion": "0.6.0",
     "protocol": "arcane/1"
   },
-  "artifactCount": 85,
-  "javascriptArtifactCount": 83,
-  "esmExportCount": 353,
+  "artifactCount": 86,
+  "javascriptArtifactCount": 84,
+  "esmExportCount": 355,
   "artifacts": [
     {
       "file": "runtime/arcane/modules/AI.js",
@@ -32,6 +32,20 @@
       "normalization": "Complete mutable caller-owned browser speech authority, SDK-owned provider registration/replacement/disposal, explicit STT/TTS activation, normalized Whisper STT and Kokoro TTS execution with default capacities 1 and 4 respectively, explicit provider-neutral execution snapshots through status(role,{execution:true}), sticky readiness, canonical window.user readiness without compatibility-event object-identity admission or polling, exact ordered structural calls with required arguments.message, atomic nonblank all-ID tool-result sequencing, complete all-choice streaming/data validation, native Ollama structural adaptation, complete-response then all validated tool callbacks then completion ordering, observed async callbacks, Blob/File transcription, automatic repeated-formatting-mark removal from cloned outbound TTS input while caller and visible content stays exact, immediate exact-segment synthesis, per-call voice/speed capture, optional final-segment pause on the existing audio clock, optional per-call terminal playback completion, detached preparation with complete semantic DBOPFS audio reuse and same-owner pending request sharing, independent prepared playback without a model load for cached audio, ordered audio-clock scheduling, playable audio, active-generation TTS operation-failure routing, mute, and cancellation are normalized; provider/model/runtime/voice policy remains caller-owned. Both speech roles default execution.device to auto: webnn-npu when navigator.ml.createContext is exposed, then webgpu when navigator.gpu is exposed, then wasm for CPU execution. Failed backend loads clean up the pool before trying fresh Workers with the same prepared model and dtype; explicit devices never fall back. STT capacity only accepts 1; TTS accepts 1 through 4. Execution snapshots expose requestedDevice, selectedDevice, maxConcurrentRequests, and activeRequestCount for both roles; selectedDevice is null while unloaded and names the successful upstream session backend request when loaded. It does not prove every operation used the physical NPU: WebNN unsupported operations may use WASM, and compatibility depends on the browser, driver, hardware, and graph.",
       "surface": "Browser-speech protocol/event/error/reason constants; default `AI`; read-only `providerRuntime`, `browserSpeechConfiguration`, and `browserSpeechDescriptor`; explicit `providerRuntime.status(role,{execution:true})` snapshots; `streamTTS(text,end,options={})` with optional voice, speed, pauseAfterMs, and waitForPlayback; automatic speech-input cleanup with SDK-internal preparation metadata; `prepareTTS({parts,storage,identity,signal,onState})` returning ordered segments, state, ready, getAudio(index), and cancel(); `playPreparedTTS(prepared,{signal,onState})` returning state, error, finished, pause(), resume(), and stop() with one playback lane per AI and observational state/error callbacks; configure/dispose speech, route lifecycle, declaration-validated chat/stream requests with exact ordered calls; optional streamRequest toolText:{name,field} and onToolText(text,call,displayId) for decoded selected argument text with actual call identity, distinct from ordinary prose and terminal tool execution; synthesis/transcription and playback controls; initializes from current canonical user readiness, installs `window.ai`, and projects `ai-ready` plus active-generation `ai-tts-failure`."
     },
+    {
+      "file": "runtime/arcane/modules/AIModelSelectionController.js",
+      "name": "AIModelSelectionController.js",
+      "kind": "esm",
+      "exports": [
+        "AIModelSelectionController",
+        "default"
+      ],
+      "summary": "Binds six caller-owned provider/model selects with draft-safe hydration, explicit inventory discovery, and paired LLM selection.",
+      "availability": "Browser / native WebView with supplied select elements",
+      "protocol": "In-process selection state and native input/change events",
+      "normalization": "Mutable six-slot selection copies preserve complete exact saved values, unknown options, labels, and newer drafts. Caller-owned catalogs merge with existing options; unscoped initial LLM options belong to the initial provider while unscoped explicit catalog entries are shared. LLM provider/model pairing preserves each provider's remembered model, with default-pair, first-enabled-match, or empty selection for a new provider. Explicit hydration and discovery track independent latest operations and retain complete errors. No User writes, storage, model activation, download, polling, or Core call occurs.",
+      "surface": "Named/default AIModelSelectionController; constructor({selects,defaults,catalogs,inventory}); getSelection(), hydrate(tupleOrPromise), discover(), state, and dispose(). Slot order: llmProvider, sttProvider, ttsProvider, llmModel, ttsModel, sttModel."
+    },
     {
       "file": "runtime/arcane/modules/AIPreferenceRuntime.js",
       "name": "AIPreferenceRuntime.js",
@@ -58,7 +72,7 @@
       "summary": "Normalizes and compares the six provider/model preference slots.",
       "availability": "Cross-host",
       "protocol": "In-process only",
-      "normalization": "Fully normalized frozen tuple.",
+      "normalization": "Mutable slot-order array and normalized tuple. Existing token trimming, aliases, caller-selected allowed values, and defaults remain unchanged; selection controllers can reuse the order independently of token normalization.",
       "surface": "`AI_PREFERENCE_SLOT_KEYS`, `normalizeAIPreferenceTuple()`, `aiPreferenceTuplesEqual()`."
     },
     {

package/docs/reference/runtime-modules.md

@@ -48,8 +48,9 @@ own asynchronous work, cancellation, and backpressure.
 | Module | Kind | Capability | Availability | Normalization |
 | --- | --- | --- | --- | --- |
 | [`AI.js`](#aijs) | esm | Provider-selectable chat, speech-to-text, text-to-speech, tool calling, structured output, streaming, bounded synthesis, and ordered audio-clock playback. | Browser + native bridge + cloud | High-level chat/speech behavior and active TTS operation failures are normalized; provider diagnostics remain mixed. |
+| [`AIModelSelectionController.js`](#aimodelselectioncontrollerjs) | esm | Binds six supplied provider/model selects with draft-safe hydration, explicit catalog discovery, and paired LLM selection. | Browser / native WebView | Mutable exact values and complete errors; storage and activation remain app-owned. |
 | [`AIPreferenceRuntime.js`](#aipreferenceruntimejs) | esm | Applies and reads non-persistent per-user AI preference overrides. | Cross-host | Normalized six-slot preference state. |
-| [`AIPreferenceTuple.js`](#aipreferencetuplejs) | esm | Normalizes and compares the six provider/model preference slots. | Cross-host | Fully normalized frozen tuple. |
+| [`AIPreferenceTuple.js`](#aipreferencetuplejs) | esm | Normalizes and compares the six provider/model preference slots. | Cross-host | Mutable slot order and normalized tuple. |
 | [`AIProviderRuntime.js`](#aiproviderruntimejs) | esm | Owns provider-neutral selection, lifecycle, routing, startup, requests, streaming, cancellation, and independent LLM/STT/TTS state. | Cross-host runtime; provider-specific availability | Normalized required provider members plus route/status contracts, with explicit local-only selection and no implicit fallback. |
 | [`AIResponseURLPolicy.js`](#airesponseurlpolicyjs) | esm | Extracts and audits links from AI Markdown, rendered HTML, CSS, srcset, bare URLs, and email text. | Cross-host | Mutable audit with exact link comparison after renderer-level decoding. |
 | [`AIRuntimeState.js`](#airuntimestatejs) | esm | Publishes sticky mutable role snapshots, lifecycle intents, and startup-settlement barriers. | Cross-host state contract | Closed monotonic state records; events report state but grant no authority. |
@@ -683,6 +684,123 @@ async function sayHello(applicationRuntime) {
 
 For on-device TTS, use the [browser speech quick start](ai/browser-speech.md).
 
+## AIModelSelectionController.js
+
+### Overview
+
+Use existing native selects to edit provider/model preferences while saved
+preferences or an optional model inventory arrive asynchronously. The controller
+owns only selection and option rendering. Applications retain their labels,
+catalogs, defaults, saved preferences, model readiness, and explicit activation.
+Importing or constructing it never loads a model, starts discovery, or writes
+User preferences or storage.
+
+### Public surface
+
+Exact exports: `AIModelSelectionController`, `default` (the same class).
+
+`new AIModelSelectionController({selects, defaults, catalogs, inventory})` accepts
+six existing selects by the following names. Tuples use this exact order:
+
+| Index | Select key | Selection |
+| --- | --- | --- |
+| 0 | `llmProvider` | LLM provider |
+| 1 | `sttProvider` | Speech-to-text provider |
+| 2 | `ttsProvider` | Text-to-speech provider |
+| 3 | `llmModel` | LLM model |
+| 4 | `ttsModel` | Text-to-speech model |
+| 5 | `sttModel` | Speech-to-text model |
+
+`defaults` is an optional tuple; omitted slots use the selects' initial values.
+Optional `catalogs` uses those same six keys, with arrays of strings or
+`{value, label, provider?, disabled?}` records. The LLM model catalog also accepts
+`CoreLocalModelCatalog` records shaped `{preferenceValue, providerValue, label}`.
+Only the LLM model list uses provider filtering; existing options may supply
+their provider in `data-provider`. An initial LLM option without that attribute
+belongs to the initial default LLM provider. An explicitly supplied catalog entry
+without a provider is shared across providers. Rendered options retain their
+provider metadata. Caller catalog entries merge with the selects'
+existing options, retaining supplied disabled states. Entries with the same value
+use the later catalog definition, and discovered entries take precedence over
+authored entries. Unknown saved selections receive an option
+containing their exact value; values and labels are never trimmed or shortened.
+
+- `getSelection()` returns a mutable copy of the current six-slot tuple.
+- `hydrate(tupleOrPromise)` explicitly applies saved selections. Missing tuple
+  entries use application defaults. Native `input` or `change` edits made after
+  hydration starts survive its completion, and the LLM provider/model pair is
+  preserved together when either is edited. The newest hydration owns updates.
+- `discover()` explicitly invokes optional `inventory({selection, signal})`.
+  The caller returns per-slot catalog arrays; they merge with authored options
+  without replacing selected values or drafts. A newer discovery aborts the
+  preceding signal and owns subsequent catalog updates. There is no polling.
+- `state` returns `{hydrating, discovering, disposed, hydrationError,
+  discoveryError}`. Async failures retain their complete rejection objects.
+- `dispose()` removes the owned native listeners, aborts pending inventory work,
+  and prevents late hydration or discovery from changing the controls. New work
+  after disposal rejects; existing asynchronous callers still own their promises.
+
+Successful `hydrate()` and `discover()` calls resolve a current six-slot tuple
+copy. Superseded successful operations also return the current selection without
+reapplying their older data. `discover()` with no inventory callback returns the
+current selection without starting work. `dispose()` returns `true` on its first
+call and `false` on subsequent calls; the last selection remains readable.
+When constructing a new controller over the same controls, supply the complete
+app catalogs again: provider-filtered choices are retained by the current
+controller, while only the current provider's choices appear in the DOM.
+
+When the user changes the LLM provider, the controller remembers the preceding
+provider's model. Returning to a provider restores its remembered model.
+Otherwise, it selects the application's default provider/model pair when
+applicable, the first enabled matching catalog model, or an empty value.
+An explicitly saved or remembered disabled selection is retained.
+It never carries a different provider's model forward as the new selection.
+The other four slots remain independent.
+
+### Availability and normalization
+
+**Browser / native WebView.** This controller requires supplied select elements,
+uses native `input` and `change` events, and creates no custom event bus. It does
+not query Core or infer readiness from inventory presence. An application may
+provide an inventory callback that obtains `localAI.status` and passes its
+`CoreLocalModelCatalog` projection; platform access remains with that caller.
+
+Missing controls, non-string selection values or labels, a non-array hydration
+result, and a supplied non-function inventory raise `TypeError`. Hydration and
+discovery preserve complete caller failures through their promises; the latest
+operation also records its error in the corresponding state field. Disposal
+errors describe that lifecycle boundary. Selection itself has no persistence,
+network, provider-transition, or activation side effect.
+
+### Example
+
+This example uses an app-owned form containing the six named selects above and
+a `<pre id="selected-models">` result. Their existing options and initial values
+are the catalog and defaults, so changing one control visibly shows the tuple
+the application can choose to save. No model policy or storage is added.
+
+```javascript
+import AIModelSelectionController from 'arcane-os/modules/AIModelSelectionController.js';
+
+const form = document.querySelector('#model-preferences');
+const controller = new AIModelSelectionController(
+    {
+        selects: form.elements
+    }
+);
+
+form.addEventListener(
+    'change',
+    function showModelSelection() {
+        document.querySelector('#selected-models').textContent = JSON.stringify(
+            controller.getSelection()
+        );
+    }
+);
+
+// Call controller.dispose() when the owning settings view is removed.
+```
+
 ## AIPreferenceRuntime.js
 
 ### Overview
@@ -721,7 +839,11 @@ Exact exports: `AI_PREFERENCE_SLOT_KEYS`, `aiPreferenceTuplesEqual`, `normalizeA
 
 ### Availability and normalization
 
-**Cross-host.** Fully normalized frozen tuple. Transport: In-process only. [Deep protocol details](protocols.md).
+**Cross-host.** The slot-order array and returned tuples are mutable. Existing
+token trimming, aliases, caller-selected allowed values, and default selection
+are unchanged. `AIModelSelectionController` reuses the canonical slot order
+without applying token normalization to saved selections. Transport: In-process
+only. [Deep protocol details](protocols.md).
 
 ### Example
 

package/package.json

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

package/runtime/arcane/modules/AIModelSelectionController.js

@@ -0,0 +1,279 @@
+import Is from 'strong-type';
+import {AI_PREFERENCE_SLOT_KEYS} from './AIPreferenceTuple.js';
+
+const is = new Is(false);
+
+function selectionText(value) {
+    if (!is.string(value)) {
+        throw new TypeError('Model selections and option values must be strings.');
+    }
+    return value;
+}
+
+function catalogOptions(entries = []) {
+    return Array.from(entries, function catalogOption(entry) {
+        if (is.string(entry)) {
+            return {value: entry, label: entry};
+        }
+        const value = selectionText(entry.value ?? entry.preferenceValue);
+        return {
+            value,
+            label: selectionText(entry.label ?? value),
+            provider: entry.provider ?? entry.providerValue,
+            disabled: entry.disabled === true
+        };
+    });
+}
+
+/**
+ * Owns selection UI only. Applications own catalogs, saved preferences,
+ * discovery requests and all provider/model activation.
+ */
+export class AIModelSelectionController {
+    #keys = [...AI_PREFERENCE_SLOT_KEYS];
+    #selects;
+    #defaults;
+    #authored = {};
+    #discovered = {};
+    #selection;
+    #revisions = [0, 0, 0, 0, 0, 0];
+    #models = new Map();
+    #inventory;
+    #listener;
+    #hydration = 0;
+    #hydrating = false;
+    #hydrationError = null;
+    #discovery = null;
+    #discoveryError = null;
+    #disposed = false;
+
+    constructor({selects, defaults, catalogs = {}, inventory} = {}) {
+        this.#selects = selects;
+        this.#inventory = inventory;
+        this.#defaults = [];
+        for (const [index, key] of this.#keys.entries()) {
+            const control = selects?.[key];
+            if (!control || !is.function(control.addEventListener)
+                || !is.function(control.removeEventListener)) {
+                throw new TypeError(`An existing select element is required for ${key}.`);
+            }
+            this.#defaults.push(selectionText(defaults?.[index] ?? control.value));
+            const initialProvider = key === 'llmModel' ? this.#defaults[0] : undefined;
+            const existing = Array.from(control.options, function existingOption(option) {
+                return {
+                    value: option.value,
+                    label: option.label ?? option.textContent,
+                    provider: option.dataset?.provider ?? initialProvider,
+                    disabled: option.disabled
+                };
+            });
+            this.#authored[key] = [...catalogOptions(existing), ...catalogOptions(catalogs[key])];
+        }
+        if (inventory !== undefined && !is.function(inventory)) {
+            throw new TypeError('Model inventory must be a function when supplied.');
+        }
+        this.#selection = [...this.#defaults];
+        this.#rememberModel();
+        this.#render();
+        this.#listener = this.#handleChange.bind(this);
+        for (const key of this.#keys) {
+            selects[key].addEventListener('input', this.#listener);
+            selects[key].addEventListener('change', this.#listener);
+        }
+    }
+
+    get state() {
+        return {
+            hydrating: this.#hydrating,
+            discovering: this.#discovery !== null,
+            disposed: this.#disposed,
+            hydrationError: this.#hydrationError,
+            discoveryError: this.#discoveryError
+        };
+    }
+
+    getSelection() {
+        return [...this.#selection];
+    }
+
+    async hydrate(preferences) {
+        this.#requireActive();
+        const hydration = ++this.#hydration;
+        const revisions = [...this.#revisions];
+        this.#hydrating = true;
+        this.#hydrationError = null;
+        try {
+            const saved = await preferences;
+            if (!is.array(saved)) {
+                throw new TypeError('Hydrated AI preferences must be an array in six-slot order.');
+            }
+            if (this.#disposed || hydration !== this.#hydration) {
+                return this.getSelection();
+            }
+            const selection = this.getSelection();
+            const llmEdited = revisions[0] !== this.#revisions[0]
+                || revisions[3] !== this.#revisions[3];
+            for (const [index] of this.#keys.entries()) {
+                if (revisions[index] !== this.#revisions[index]
+                    || ((index === 0 || index === 3) && llmEdited)) {
+                    continue;
+                }
+                selection[index] = selectionText(saved[index] ?? this.#defaults[index]);
+            }
+            this.#selection = selection;
+            this.#rememberModel();
+            this.#render();
+            return this.getSelection();
+        } catch (error) {
+            if (!this.#disposed && hydration === this.#hydration) {
+                this.#hydrationError = error;
+            }
+            throw error;
+        } finally {
+            if (hydration === this.#hydration) {
+                this.#hydrating = false;
+            }
+        }
+    }
+
+    async discover() {
+        this.#requireActive();
+        if (!this.#inventory) {
+            return this.getSelection();
+        }
+        const previous = this.#discovery;
+        const discovery = new AbortController();
+        this.#discovery = discovery;
+        this.#discoveryError = null;
+        previous?.abort();
+        try {
+            const catalogs = await this.#inventory(
+                {
+                    selection: this.getSelection(),
+                    signal: discovery.signal
+                }
+            );
+            if (this.#disposed || this.#discovery !== discovery) {
+                return this.getSelection();
+            }
+            const discovered = {};
+            for (const key of this.#keys) {
+                discovered[key] = catalogOptions(catalogs?.[key]);
+            }
+            this.#discovered = discovered;
+            this.#render();
+            return this.getSelection();
+        } catch (error) {
+            if (!this.#disposed && this.#discovery === discovery) {
+                this.#discoveryError = error;
+            }
+            throw error;
+        } finally {
+            if (this.#discovery === discovery) {
+                this.#discovery = null;
+            }
+        }
+    }
+
+    dispose() {
+        if (this.#disposed) {
+            return false;
+        }
+        this.#disposed = true;
+        this.#hydrating = false;
+        for (const key of this.#keys) {
+            this.#selects[key].removeEventListener('input', this.#listener);
+            this.#selects[key].removeEventListener('change', this.#listener);
+        }
+        const discovery = this.#discovery;
+        this.#discovery = null;
+        discovery?.abort();
+        return true;
+    }
+
+    #requireActive() {
+        if (this.#disposed) {
+            throw new Error('The model selection controller is disposed.');
+        }
+    }
+
+    #rememberModel() {
+        this.#models.set(this.#selection[0], this.#selection[3]);
+    }
+
+    #optionsFor(key) {
+        const options = new Map();
+        const entries = [...this.#authored[key], ...(this.#discovered[key] ?? [])];
+        for (const option of entries) {
+            if (key === 'llmModel' && option.provider !== undefined
+                && option.provider !== this.#selection[0]) {
+                continue;
+            }
+            options.set(option.value, option);
+        }
+        return options;
+    }
+
+    #handleChange(event) {
+        const index = this.#keys.findIndex(function changedControl(key) {
+            return this.#selects[key] === event.currentTarget;
+        }, this);
+        if (this.#disposed || index < 0) {
+            return;
+        }
+        const value = event.currentTarget.value;
+        this.#revisions[index] += 1;
+        if (index === 0 && value !== this.#selection[0]) {
+            this.#rememberModel();
+            this.#selection[0] = value;
+            this.#selection[3] = this.#modelForProvider(value);
+            this.#revisions[3] += 1;
+        } else {
+            this.#selection[index] = value;
+        }
+        this.#rememberModel();
+        if (index === 0) {
+            this.#render();
+        }
+    }
+
+    #modelForProvider(provider) {
+        if (this.#models.has(provider)) {
+            return this.#models.get(provider);
+        }
+        if (provider === this.#defaults[0]) {
+            return this.#defaults[3];
+        }
+        for (const option of this.#optionsFor('llmModel').values()) {
+            if (!option.disabled) {
+                return option.value;
+            }
+        }
+        return '';
+    }
+
+    #render() {
+        for (const [index, key] of this.#keys.entries()) {
+            const control = this.#selects[key];
+            const selected = this.#selection[index];
+            const options = this.#optionsFor(key);
+            if (!options.has(selected)) {
+                options.set(selected, {value: selected, label: selected});
+            }
+            control.replaceChildren();
+            for (const option of options.values()) {
+                const element = control.ownerDocument.createElement('option');
+                element.value = option.value;
+                element.textContent = option.label;
+                element.disabled = option.disabled === true;
+                if (option.provider !== undefined) {
+                    element.dataset.provider = option.provider;
+                }
+                control.append(element);
+            }
+            control.value = selected;
+        }
+    }
+}
+
+export default AIModelSelectionController;

package/runtime/arcane/modules/AIPreferenceTuple.js

@@ -1,14 +1,14 @@
 import Is from 'strong-type';
 const is=new Is(false);
 
-export const AI_PREFERENCE_SLOT_KEYS=Object.freeze([
+export const AI_PREFERENCE_SLOT_KEYS=[
     'llmProvider',
     'sttProvider',
     'ttsProvider',
     'llmModel',
     'ttsModel',
     'sttModel'
-]);
+];
 
 function preferenceToken(value){
     return is.string(value)