arcane-os 0.66.0 → 0.68.0

package/docs/reference/local-ai.md

@@ -174,6 +174,34 @@ This factory accepts chat/ONNX requirements; the separate
 owns image requirements. The development and generated native composition
 split the shared application record accordingly.
 
+### Native service owners
+
+A native application service uses its Core lifecycle or request context to
+obtain the existing selected owner:
+
+```js
+const localAI = await context.getService('local-ai');
+const onnx = localAI.getONNXRuntime();
+const modelAssets = await context.getService('model-assets');
+```
+
+`getService()` awaits only that service's existing startup. The synchronous
+`getONNXRuntime()` returns its actual `load/run/unload/current/subscribe/close`
+owner; it neither prepares another runtime nor loads a model. An unselected
+engine reports `LOCAL_AI_RUNTIME_NOT_SELECTED`; an unavailable or recovering
+owner reports `LOCAL_AI_RUNTIME_UNAVAILABLE`, and an aborted service lifetime
+retains its abort reason. Development and generated native compositions register
+one shared model-assets service when ONNX or image generation is selected.
+
+Reacquire `getONNXRuntime()` on each explicit model load because runtime recovery
+replaces that owner. Retain the acquired handle for that session's cleanup and
+await its `unload({id})` without an already-aborted request signal before releasing
+the corresponding model-assets retain handle. The native ONNX owner joins actual
+worker exit; a cancelled request's rejection alone does not establish that exit.
+Core closes services concurrently, and the host can cancel in-flight native work
+at shutdown. These native members require no renderer readiness and introduce no
+second inference engine. See [native Core composition](core-runtime.md#native-service-composition).
+
 `localai.status` returns `{runtimes}` and, when Ollama is selected, the existing
 `ollama` and `models.ollama` catalog fields. Runtime records distinguish
 `installed`, `available`, `state`, `models`, ownership and errors. A listening
@@ -198,6 +226,14 @@ background health polling.
 | `llama.unload` | `{model}` | Current state after release |
 | `llama.chat` | `{model,payload,stream?,streamId?}` | Complete OpenAI-shaped completion |
 
+`llama.status` and `llama.models` observe the selected service without loading,
+restarting or waiting for it. Starting, loading, stopped and failed services
+return their retained state/catalog; an available service supplies a fresh
+catalog observation. The llama.cpp runtime record includes `released: true`
+only after Core successfully closes its owned single-model server. Explicit
+load, inference or recovery can resume that engine; observation cannot.
+Status observation adds no background polling.
+
 The `payload` is the complete request. SDK option names are translated only at
 the upstream protocol boundary; messages, tool definitions and documents remain
 unchanged. An explicit `payload.model` selects that request's model. Core waits
@@ -213,7 +249,8 @@ observe load, sleep and unload changes. Direct servers expose readiness at
 request boundaries; they do not offer the router's passive model event stream.
 
 Unloading a model from an owned single-model server closes that owned process;
-a subsequent load can start it again. Releasing an externally owned direct
+a subsequent load can start it again. Repeating that unload returns the released
+state without restarting the process. Releasing an externally owned direct
 server returns `released: true, unloaded: false`, retaining the real catalog
 and leaving that server running.
 
@@ -289,6 +326,38 @@ does not install software or select a model. A missing Core connection reports
 unavailability, leaving browser Wllama/ONNX routes available for the application
 to select.
 
+Omit `client` to follow the installed Core client through
+[`subscribeCoreClient`](core-client.md): construction may precede installation.
+Each installation reads `llama.status` without selecting, downloading or loading
+a model. Retirement or replacement synchronously revokes this provider's
+`status().loaded`, cancels its owned operations and detaches the old lifecycle
+listener. Late results cannot restore the retired selection. Explicitly load
+the selection against the replacement client before inference. Passing a
+`client`, including `null`, keeps that caller-supplied connection fixed.
+
+`status()` is this provider's current state. The `arcane-ai-provider/2` contract
+does not provide a provider-state subscription, so this installation handling
+alone does not update an idle AI runtime's retained role state. The provider
+runtime still reconciles the provider at its existing operation boundaries.
+`inspect()` reports whether an explicit load can proceed, separately from
+`status().loaded`. A genuine `starting` or `loading` service without an error
+permits that load preflight even before its catalog arrives; Core's `llama.load`
+waits for startup and verifies the exact requested model. An owned, successfully
+released service permits loading only a model retained in its actual catalog.
+An available service still requires that catalog membership. These observations
+do not fabricate model records or readiness, and unavailable external services,
+closed services and actual errors remain unavailable.
+
+`dispose()` removes installation and service subscriptions and cancels owned
+operations synchronously, then attempts its actually retained model's release
+through its captured client. A configured selection alone does not own a native
+model: disposing before load or after successful unload sends no native release,
+including when the caller explicitly supplied `client: null`. A failed release
+rejects with the actual error even though the provider is disposed; disposal
+does not establish successful native unload.
+It never unloads a retired selection through a replacement client or closes the
+shared Core client.
+
 If a router evicts the primary model while serving a request-specific model,
 reload the primary selection before its next request. The provider does not
 silently change the application's saved model choice. Release registration
@@ -316,13 +385,45 @@ try {
 ```
 
 The factory accepts `{modulePath,signal?,onEvent?}` and starts no worker until
-`load({id,model,sessionOptions?,signal?})`. The model path is absolute for this
+`load({id,model,sessionOptions?,executionPreference?,signal?})`. The model path is absolute for this
 direct Node API. Session creation defaults to the CPU execution provider;
 explicit native session options remain caller-owned. The returned session
 record contains `id`, `model`, `state`, `loaded`, `error`, input/output names and
 metadata. A live ID requires explicit unload before replacement. An ID may be
 loaded again once its previous worker exits after a failed load or unload.
 A run error retains the loaded session so a corrected request can use it.
+`current().sessions[].stopping` becomes `true` when terminal shutdown begins,
+including worker failure or explicit cancellation/unload. The session is then
+unavailable for new runs even while `loaded` remains `true` until actual exit.
+A recoverable run error keeps `stopping:false` and the loaded session usable.
+`current().sessions[].exited` reports actual worker exit, independently of a
+rejected load or inference. Unload joins worker exit and output delivery even
+when requesting termination fails; complete cleanup errors remain observable.
+
+Select `executionPreference: 'gpu'` to try the installed runtime's advertised
+CUDA, TensorRT, DirectML, CoreML and WebGPU providers in that order, followed by
+CPU when no accelerator session can be created. Discovery runs once per load;
+each advertised candidate receives one actual session-creation attempt with CPU
+available for graph nodes that the accelerator cannot handle. No provider is
+downloaded by selection. The upstream `bundled` flag describes packaging and
+does not exclude separately installed CUDA or TensorRT libraries. An explicit
+`sessionOptions.executionProviders`, including an empty array, takes precedence
+and is passed unchanged without automatic discovery or retries. Automatic
+DirectML attempts default `enableMemPattern` to `false` and `executionMode` to
+`'sequential'` as required by that provider; explicit caller values remain
+unchanged, including on the final CPU attempt.
+
+Automatic GPU selection adds an `execution` record to the loaded session and
+its ordinary state events: `preference`, complete `supportedBackends`,
+`selectedProviders`, ordered `attempts` with their full errors, `fallback`, and
+`discoveryError`. Each attempt records `executionProviders`, `status`
+(`configured` or `failed`), and `error`. `fallback: true` means the SDK created
+the final CPU session after GPU preference, including when no GPU candidate was
+advertised. Successful creation establishes an accepted provider configuration;
+it does not establish that a GPU executed any graph nodes. If every attempt
+fails, the load error retains the complete attempt errors and `execution`
+record. Inference failures retain their existing behavior and do not replay
+inference on another provider.
 
 `run({id,feeds,fetches?,runOptions?,signal?})` returns the complete output-name
 map of `{type,dims,data}` tensors. Input records use that same shape with native
@@ -383,6 +484,15 @@ Closing the accessor cancels its requests and subscriptions; model unloading
 is explicit because other accessors may share the Core session. It never
 closes the shared Core client.
 
+Omitting `client` follows Core installation events with current-client replay,
+including installation after construction. Each new connection reads
+`onnx.status`; it does not install a runtime or load a model. Retirement or
+replacement immediately clears retained session readiness and cancels this
+accessor's operations. Late old-client state and results are ignored. Passing
+an explicit `client`, including `null`, retains caller ownership and does not
+follow global installation changes. `close()` also removes the installation
+subscription.
+
 Construction neither opens a connection nor installs a runtime. A browser needs
 an already available native Core service or the explicit development bridge.
 Unavailable native ONNX leaves browser ONNX/Wllama under the application's

package/docs/reference/local-image-generation.md

@@ -199,14 +199,16 @@ ordered `Blob` or `File` members after its resumable download. Range support
 allows concurrent transfer within a member; those transfer parts remain the
 store's concern. Use `offline: true` to require an already complete stored model.
 The store does not select or run the image engine. In source development,
-load the development Core bootstrap described
-in [Local AI through Core](local-ai.md#development) before constructing the
-accessor. Native hosts install their Core client through the existing host path.
+use the development Core bootstrap described
+in [Local AI through Core](local-ai.md#development). The accessor can be
+constructed before that client is installed; perform model operations once
+the service is available. Native hosts install their Core client through the
+existing host path.
 An ordinary browser without Core reports local image generation as unavailable.
 
 | Member | Contract |
 |---|---|
-| `createCoreImageRuntime({client?, signal?, onEvent?})` | Uses the installed Core client by default, subscribes to lifecycle events and asynchronously reads one initial status snapshot. It returns immediately. |
+| `createCoreImageRuntime({client?, signal?, onEvent?})` | Follows Core installation and lifecycle events by default, asynchronously reading status for each client. An explicit `client`, including `null`, remains caller-owned. It returns immediately. |
 | `load({model, context?, assetProjectionId?, resourcePaths?, signal?})` | Loads the selected model and returns authoritative service state after native completion. `context` supplies native context options. |
 | `generate({model, prompt, parameters?, assetProjectionId?, resourcePaths?, signal?, onProgress?})` | Returns the complete result with `images: [{blob, mediaType, width, height}]`. Additional runtime result metadata remains present. |
 | `unload({signal?})` | Explicitly unloads the shared selected native context and returns its resulting state. |
@@ -229,6 +231,15 @@ model definitions, including their resource metadata before engine preparation
 finishes. Installed files do not imply a loaded model. A late status
 response never overwrites a newer lifecycle event.
 
+With `client` omitted, the accessor consumes the shared
+[`subscribeCoreClient`](core-client.md) installation stream. A late installation
+attaches the service listener and reads current status; it never installs an
+engine or loads a model. Retirement or replacement synchronously clears
+readiness and transient `Thinking`, cancels owned requests and detaches the
+retired service listener. Old state, progress and results cannot update the
+replacement connection. `close()` also removes the installation subscription;
+it does not claim that the shared native model was unloaded.
+
 Prompts and parameters pass unchanged to the native runtime. Native option
 names, supported model operations and defaults belong to that runtime and the
 selected model definition. A prompt containing U+0000 or an unpaired UTF-16

package/docs/reference/model-assets.md

@@ -1,6 +1,6 @@
-# Native working files from stored model assets
+# Native working files from model assets
 
-These public APIs were first published in `arcane-os@0.61.0`. Browser
+Browser preparation and native retain/release ownership were first published in `arcane-os@0.61.0`. Browser
 preparation is exported by `arcane-os/ai/core-model-assets`, and the native
 service by `arcane-os/core/model-assets`. The image example below uses
 `arcane-os/ai/core-image`, published in the same release.
@@ -87,6 +87,53 @@ cleanup failures remain observable.
 
 ## Native ownership
 
+Native services can prepare explicitly selected upstream members without a
+renderer or browser store. Obtain the registered shared service through
+`await context.getService('model-assets')`, then use its native preparation API:
+
+```javascript
+const modelAssets = await context.getService('model-assets');
+const projection = await modelAssets.prepare({
+    id: selectedOperationId,
+    workingDirectory: selectedWorkingDirectory,
+    members: selectedMembers, // [{path: 'onnx/model.onnx', url: selectedURL}, ...]
+    signal,
+    onProgress: renderPreparationProgress
+});
+const use = modelAssets.retain(projection.id);
+await modelAssets.release(projection.id);
+try {
+    await ownNativeModelLifetime(use.members);
+} finally {
+    // Join actual native unload/worker exit before releasing these files.
+    await use.release();
+}
+```
+
+`prepare({id,workingDirectory,members,signal,onProgress})` performs standard
+fetches only when explicitly called. Every member has its original relative
+`path` and selected `url`; the caller supplies the complete companion-file set.
+Independent members download concurrently. Each complete response stream is
+written directly through the existing ordered native file owner, without a
+whole-model buffer or base64 conversion. No model or runtime is selected or
+downloaded by service startup. The result is the ready projection snapshot with
+ordered `members: [{path,nativePath}]`.
+
+Progress uses `open`, `download`, `complete` and `ready` phases, with
+`completed`, `total` and `unit:'files'`; member progress additionally includes
+`memberIndex` and `path`. Progress callbacks may return a promise, which the
+preparation observes. They must not await cleanup of the preparation currently
+calling them. Callback failures remain preparation failures. HTTP failures
+retain `url`, `status` and the complete response text in `response`.
+
+`release(id)` relinquishes preparation ownership without a request signal.
+For active native downloads, release or disposal aborts their fetches and joins
+the transfer tasks and native writes before deleting only their owned child
+directory. Preparation cancellation and failure follow that same cleanup path;
+the original failures and cleanup failures remain observable. A native retain
+handle continues to protect completed files through actual engine release.
+Native preparation leaves browser DBOPFS originals and unrelated files alone.
+
 ```javascript
 import {createModelAssetService} from 'arcane-os/core/model-assets';
 
@@ -103,7 +150,7 @@ try {
 ```
 
 `createModelAssetService({appRoot})` returns a Core service with `current()`,
-`retain(id)` and `dispose()`. `retain()` accepts only a completed projection
+`prepare(options)`, `retain(id)`, `release(id)` and `dispose()`. `retain()` accepts only a completed projection
 and returns `{id,directory,members,release}`. A native engine takes this handle
 before loading and releases it after actual unload, failed-load cleanup or
 worker exit. A rejected inference/load promise alone does not establish native

package/docs/reference/native-decisions.md

@@ -0,0 +1,181 @@
+# Native Laya typed decisions
+
+`arcane-os/local-ai/decisions` and `arcane-os/core/decisions` run the selected
+Laya FP32 graph through the SDK's existing native ONNX owner. Tokenization runs
+in its own Node Worker. A Core service can load and evaluate decisions without
+a renderer, browser session, WebGPU browser context or chat provider.
+
+The application owns the model selection, original state text, questions,
+options and interpretation. The SDK owns model preparation, token framing,
+inference and cleanup. This is option scoring, not a conversational LLM, a
+replacement for a configured chat model or the cloud System One API.
+
+## Compose with existing Core services
+
+Register a decision service alongside the selected local-AI and model-assets
+services in the application's existing Core runtime:
+
+```js
+import {createNativeDecisionService} from 'arcane-os/core/decisions';
+
+const decisions = createNativeDecisionService({
+    model: 'onnx-community/laya-typed-decisions-ONNX',
+    dtype: 'fp32',
+    workingDirectory: '.models/laya'
+}, {appRoot});
+
+// Include decisions in the existing createCoreRuntime({services}) selection.
+// That runtime already owns local-ai with ONNX selected and model-assets.
+await runtime.getService('decisions');
+await decisions.load(); // Explicit activation; no model download at registration.
+try {
+    const result = await decisions.evaluate([{
+        state: 'The moon chef has one kettle and seventeen impatient dragons.',
+        question: 'What should the chef prepare?',
+        options: ['Tea', 'An inflatable castle']
+    }]);
+    console.log(result.decisions[0].value);
+} finally {
+    await decisions.unload();
+}
+```
+
+Here `runtime` and `appRoot` are the application's existing Core runtime and
+root. Add the service before starting that runtime; the example does not create
+a second Core host or engine. Development and packaged native compositions
+already register one model-assets service when ONNX is selected. The decision
+service obtains those exact owners with `context.getService('local-ai')`,
+`localAI.getONNXRuntime()` and `context.getService('model-assets')` on explicit
+load. It reacquires the current ONNX owner after a later runtime recovery.
+See [Core composition](core-runtime.md#native-service-composition) and
+[native service owners](local-ai.md#native-service-owners).
+
+`createNativeDecisionService(configuration, {appRoot})` defaults its service
+name to `decisions`. It exposes `load`, `evaluate`, `classify` (an alias for
+`evaluate`), `current`, `subscribe`, `unload` and `dispose`, plus Core lifecycle
+`start(context)`. Its RPC methods are:
+
+| Method | Parameters and result |
+| --- | --- |
+| `decisions.status` | Current lifecycle snapshot; does not load anything. |
+| `decisions.load` | Explicit activation; returns the ready lifecycle snapshot. The request signal cancels activation. |
+| `decisions.evaluate` | `{rows, runOptions?}`; returns `{decisions, outputs}`. The request signal cancels the active model operation. |
+| `decisions.unload` | Releases the activation. Service-lifetime cleanup continues after the caller disconnects. |
+
+RPC evaluation uses the SDK's existing complete JSON tensor encoding for
+`outputs` at the transport boundary. Direct native evaluation returns native
+typed tensor records. Service notifications use `decisions.state`; direct
+`subscribe(listener, {emitCurrent:true, signal})` replays current state by
+default and returns an unsubscribe function. Startup stores the service
+context only: importing or registering this service starts no tokenizer,
+model download or inference.
+
+## Direct native model
+
+`createNativeDecisionModel(options)` from `arcane-os/local-ai/decisions` returns
+`{load, evaluate, classify, current, status, subscribe, unload, dispose}`.
+`status` aliases `current`; `classify` aliases `evaluate`. Supply the existing
+native `onnx` owner, plus either the existing `modelAssets` owner and selected
+`workingDirectory`, or caller-owned native files:
+
+```js
+import {createNativeDecisionModel} from 'arcane-os/local-ai/decisions';
+
+const decisions = createNativeDecisionModel({
+    onnx: localAI.getONNXRuntime(),
+    paths: {
+        model: selectedGraphPath,
+        tokenizer: selectedTokenizerPath,
+        tokenizerConfig: selectedTokenizerConfigPath
+    }
+});
+```
+
+These direct paths are native filesystem paths. Keep the graph's external data
+beside it under the exact filename required by the graph. The Core service
+resolves configured `paths` relative to `appRoot`; it does not copy or remove
+caller-owned files. For SDK-prepared files, the default selected upstream is
+`onnx-community/laya-typed-decisions-ONNX`, revision `main`, with exactly:
+
+- `onnx/model.onnx` and `onnx/model.onnx_data`;
+- `tokenizer.json` and `tokenizer_config.json`.
+
+`model` selects the upstream Hugging Face repository and `revision` its
+revision. Native preparation performs normal upstream fetches only during
+explicit `load()`. It streams complete members through the existing working
+file owner; it neither vendors the weights nor creates a second persistent
+model store. The approved `@huggingface/tokenizers@0.2.0` dependency reads the
+selected tokenizer files in its Worker. No Transformers or second ONNX runtime
+is loaded by this API.
+
+This graph selection requires `dtype:'fp32'`, which is also the default; another
+dtype reports the incompatible selection rather than substituting a graph.
+`sessionOptions` and `runOptions` pass to the existing native ONNX API unchanged.
+`executionPreference` defaults to `gpu` here: actual advertised native GPU
+provider creation is attempted, followed by an honest CPU fallback. Explicit
+`sessionOptions.executionProviders` takes precedence. The underlying generic
+ONNX factory continues to default to CPU. Accepted provider configuration is
+not evidence that GPU nodes executed. Full provider-attempt diagnostics remain
+in `execution`; see [native ONNX sessions](local-ai.md#native-onnx-sessions).
+
+## Complete inputs and outputs
+
+`evaluate(rows, {signal, runOptions})` requires an explicitly loaded or loading
+activation; it does not silently load an inactive model. Rows retain their
+caller order, complete `state`, `question` and string-array `options`, plus
+optional `type` (`choice`, `score` or `noul`). Additional row fields remain in
+the returned row. Strings are not trimmed, rewritten or clipped. The shared
+browser/native encoding owner constructs only the model's necessary token
+framing; repeated identical state is tokenized once per batch. Tokenization
+and ONNX execution run outside Core's foreground thread.
+
+The result is `{decisions, outputs}`. Each decision contains its original
+`row`, complete option `logits`, unrounded raw-softmax `probabilities`,
+`answerIndex` and `value`. `choice` returns the selected complete option;
+`score` returns the probability-weighted zero-based option index; `noul`
+requires `[falseOption, trueOption]` and returns the probability of option 1.
+When the graph actually supplies `act_logits`, action logits, probabilities
+and `actProbability` are also returned. Every named graph output is retained
+as `{type, dims, data}`, including extra tensors and padding. Raw model scores
+are not claimed calibrated confidence. Results do not enter chat history,
+memory extraction or DBOPFS automatically.
+
+The model's real graph/context limits still apply. There is no SDK token cap,
+silent chunking or fabricated result aggregation. Native/browser token-ID or
+numerical parity requires execution evidence for the selected tokenizer and
+runtime; sharing the encoding implementation alone does not establish it.
+
+## Lifetime and cancellation
+
+`current()` returns `{family, model, revision, dtype, state, loaded, busy,
+activeRequests, progress, error, execution}`. States include `unloaded`,
+`loading`, `ready`, `unloading`, `disposing`, `disposed` and `error`. Semantic
+progress includes model preparation, tokenization and evaluation; downloaded
+members report files, not byte progress. Complete technical errors belong in
+developer diagnostics, while the application owns its user-facing status.
+
+Concurrent callers share one explicit activation. Cancelling a load or
+evaluation cancels that activation and its outstanding operations, because the
+native session and tokenizer have one owner. Use separately owned models when
+independent cancellation is required. The construction `signal` governs the
+whole model lifetime. `unload()` permits another explicit load after successful
+cleanup; `dispose()` is terminal. Readiness is revoked as disposal begins.
+
+Retained model files remain owned until the ONNX and tokenizer Workers really
+exit. A rejected load, inference or termination request alone does not permit
+file deletion. Cleanup joins active operations and native output delivery,
+preserves cleanup errors, then releases only its working projection. It never
+deletes supplied `paths`. A failed ordinary row does not destroy a healthy
+loaded session or cancel sibling evaluations. The ONNX owner's `stopping:true`
+retires decision readiness immediately on terminal Worker failure or shutdown,
+even while its physical `loaded` state remains true pending actual exit. Cancelled or
+retired operations cannot return a successful late result.
+
+Shared Node/Worker/filesystem code is portable across Windows, Linux and macOS;
+the selected ONNX Runtime build and provider determine actual platform/device
+availability. Android requires the host's supported native adaptation. Static
+source review and synthetic authored fixtures are not model execution or a
+claim of tested platform, precision or accelerator behavior.
+
+Upstream selection: [Laya FP32 model files](https://huggingface.co/onnx-community/laya-typed-decisions-ONNX/tree/main),
+[Tokenizer package](https://www.npmjs.com/package/@huggingface/tokenizers).

package/docs/reference/runtime-components.md

@@ -112,7 +112,7 @@ snapshot remains owned until the browser's `afterprint` event.
 | [`task-progress.html`](#task-progresshtml) | Runs and displays a task list with started/change/complete/error state. | `configure()`<br>`setTasks()`<br>`updateTask()`<br>`runTasks()`<br>`clear()`<br>`destroy()` | `task-progress-ready`<br>`task-progress-started`<br>`task-progress-change`<br>`task-progress-complete`<br>`task-progress-error` | Task state normalized; injected task results mixed |
 | [`terminal-workspace.html`](#terminal-workspacehtml) | Presents multiple terminal sessions, output, active selection, theme, and terminal actions. | `configure()`<br>`addSession()`<br>`removeSession()`<br>`activateSession()`<br>`append()`<br>`clear()`<br>`setState()`<br>`setTheme()`<br>`focus()`<br>`destroy()` | `terminal-workspace-ready`<br>`terminal-submit`<br>`terminal-interrupt`<br>`terminal-clear`<br>`terminal-session-new`<br>`terminal-session-close`<br>`terminal-session-select`<br>`terminal-settings` | UI/session state normalized; native command results supplied externally |
 | [`theme-editor.html`](#theme-editorhtml) | Edits, previews, saves, and resets semantic custom theme tokens. | `configure()`<br>`getTheme()`<br>`setTheme()`<br>`setBusy()`<br>`setStatus()`<br>`destroy()` | `theme-editor-ready`<br>`theme-preview`<br>`theme-save`<br>`theme-reset` | Fully normalized Theme values |
-| [`theme-switcher.html`](#theme-switcherhtml) | Selects and refreshes system, light, dark, or custom theme mode. | `setMode()`<br>`refresh()` | No component-specific event | Preference/native appearance behavior mixed; no component-ready contract |
+| [`theme-switcher.html`](#theme-switcherhtml) | Selects and refreshes system, light, dark, or custom theme mode with per-instance choices and labels. | `configure()`<br>`setMode()`<br>`refresh()` | No component-specific event | Preference/native appearance behavior mixed; no component-ready contract |
 | [`unified-inbox.html`](#unified-inboxhtml) | Displays provider-neutral communication threads with active/loading state. | `configure()`<br>`setThreads()`<br>`setActive()`<br>`setLoading()`<br>`destroy()` | `unified-inbox-ready`<br>`inbox-refresh`<br>`thread-select` | DOM-normalized |
 | [`voice-transcription.html`](#voice-transcriptionhtml) | Records manual clips or optional continuous microphone audio with pause/periodic segments, ordered transcription and saves, retained failures, and complete transcript delivery. | `configure()`<br>`requestSTTActivation()`<br>`startRecording()`<br>`stopRecording()`<br>`retryTranscription()`<br>`cancelRecording()`<br>`save()`<br>`completeTranscription()/complete()`<br>`clear()`<br>`reset()`<br>`destroy()` | `voice-transcription-ready`<br>`voice-transcription-state`<br>`voice-transcription-segment`<br>`voice-transcription-empty`<br>`voice-transcription-error`<br>`voice-transcription-change`<br>`voice-transcription-complete`<br>`speech-transcription-complete`<br>`speech-transcription-cancelled`<br>`speech-stt-activation-request`<br>`speech-stt-activation-error` | Sticky STT readiness, capture/queue lifecycle, retry, cancellation, and complete state/text are normalized; media/provider behavior remains external |
 | [`weather-widget.html`](#weather-widgethtml) | Displays normalized current and daily weather with refresh intent. | `setWeather()`<br>`clear()`<br>`destroy()` | `weather-widget-ready`<br>`weather-refresh` | Display normalized; provider supplied externally |
@@ -2015,11 +2015,61 @@ Shared dependencies: [`Theme.js`](runtime-entities.md#themejs).
 
 ### Overview
 
-Selects and refreshes system, light, dark, or custom theme mode.
+Selects and refreshes system, light, dark, or custom theme mode. Native buttons
+retain complete readable labels and wrap when their component runs out of room,
+independently of viewport width. Each button has a `2.75rem` minimum target in
+both dimensions. Selected buttons retain `aria-pressed` and an inset outline;
+disabled choices and keyboard focus have distinct presentation.
 
 ### Public surface
 
-Methods/properties: `setMode()`, `refresh()`.
+Methods/properties: `configure(options)`, `setMode(mode='system')`, `refresh()`.
+
+`configure({modes,labels})` changes only this component's presentation:
+
+- `modes` is an ordered array of the available identifiers `system`, `light`,
+  `dark`, and `custom`. It selects both visible choices and DOM/keyboard order.
+  Omitted `modes` retains the current presentation; an empty array displays no
+  choices. Unknown or repeated identifiers throw `TypeError` before changing
+  the presentation.
+- `labels` is a partial record of complete string labels keyed by those mode
+  identifiers. Omitted labels keep their current text. Text is assigned through
+  `textContent`, never interpreted as markup or reduced to initials. A label for
+  a built-in mode that is not a string throws `TypeError`.
+- The return value is `{modes,labels}` containing independent mutable copies of
+  the current presentation. Later changes to supplied/returned records do not
+  reconfigure the component.
+
+Label-only and unchanged-order configuration retain the existing buttons in
+place. An actual reorder restores keyboard focus to the previously focused
+button when that choice remains visible and enabled, without scrolling.
+
+The default remains Auto / Light / Dark / Skin, using identifiers
+`system`, `light`, `dark`, and `custom`. A caller may omit Skin or change Auto's
+label to System without removing custom-theme support from other instances.
+Configuration never changes preferences, activates a theme, or replaces the
+current selected mode. If the active mode is omitted, no visible button claims
+to be selected. Restoring that choice restores its existing pressed and disabled
+state. Skin remains disabled until the manager has a saved custom theme.
+
+For the initial presentation, `data-modes` accepts whitespace-separated mode
+identifiers and `data-system-label` supplies the complete system-mode label.
+These attributes are read once before the asynchronous ThemeManager import and
+preference refresh, so initial choices do not wait for `html-import-ready`.
+Use `configure()` after that event for subsequent presentation changes;
+changing these attributes later does not reconfigure an existing instance.
+
+`setMode()` updates pressed state and the host's `data-mode` only. `refresh()`
+loads the existing ThemeManager state, updates selection and Skin availability,
+and resolves with the complete manager state. Clicking a choice uses the same
+manager persistence/activation operation; buttons remain disabled while that
+operation is pending. Presentation configuration preserves that pending state.
+
+The host inherits text color. Existing `--app-bar-border` (falling back to
+`--border-color`), `--app-bar-accent` (then `--secondary-color`),
+`--app-bar-active-text` (then `--primary-color`), and `--focus-color` overrides
+remain supported. Applications own their palette and surrounding placement;
+the component adds no application-specific palette or settings section.
 
 This fragment declares no component-specific readiness or action event; use the loader's `html-import-ready` only to know that import execution completed.
 
@@ -2033,11 +2083,18 @@ Shared dependencies: [`ThemeManager.js`](runtime-modules.md#thememanagerjs).
 
 ```html
 <html-import
-  id="theme-switcher.html"
-  href="/arcane/components/theme-switcher.html">
+  id="theme-switcher"
+  href="/node_modules/arcane-os/runtime/arcane/components/theme-switcher.html"
+  data-modes="light dark system"
+  data-system-label="System">
 </html-import>
 ```
 
+This instance displays Light / Dark / System in that order. An instance without
+the two configuration attributes retains all four default choices. Both use
+the existing shared preference owner; presentation does not create a new store
+or migrate saved themes.
+
 ## unified-inbox.html
 
 ### Overview

package/docs/reference/runtime-modules.md

@@ -120,7 +120,7 @@ own asynchronous work, cancellation, and backpressure.
 | [`OllamaSettings.js`](#ollamasettingsjs) | esm | Defines complete runtime/service preference schemas and deterministic Arcane brain alias names. | Cross-host | Fully normalized settings/name contract. |
 | [`OpenMeteoWeatherProvider.js`](#openmeteoweatherproviderjs) | esm | Searches and loads Open-Meteo data into complete mutable Arcane weather entities. | Browser / native WebView / server with fetch + cloud | Provider data normalized to mutable entities; transport errors mixed. |
 | [`PersistentAIChatSession.js`](#persistentaichatsessionjs) | esm | Adds explicit retained-history/memory policy to complete configured chat without changing DBOPFS or ChatEntity semantics. | Browser / native WebView with DBOPFS and configured chat | Retained context commits atomically; `persist:false` turns are one-operation-only. |
-| [`PreferenceStore.js`](#preferencestorejs) | esm | Loads and updates schema-defined app preferences through native storage with a narrow browser fallback. | Browser/native hybrid | Complete ordinary values remain mutable; setAll uses one optional atomic adapter batch for every selected value when advertised, otherwise performs complete ordered serial writes, and only exact unsupported native capability changes future operations to the browser fallback. |
+| [`PreferenceStore.js`](#preferencestorejs) | esm | Loads and updates schema-defined app preferences through native storage with a narrow browser fallback. | Browser/native hybrid | Complete values and operation context retained; exact optional namespace absence or existing Android unsupported capability selects the existing local adapter; partial-service and genuine failures remain errors; an advertised rejected batch is never retried serially. |
 | [`PreparedSpeech.js`](#preparedspeechjs) | esm | Owns detached ordered preparation, semantic audio reuse, and per-caller cancellation behind AI.prepareTTS. | Browser / native WebView with injected synthesis and optional DBOPFS | Complete original inputs, ordered audio metadata, durable reuse, and observable preparation results. |
 | [`PrintView.js`](#printviewjs) | esm | Prints current rendered content and title through one document-owned print lifecycle. | Browser / supported native WebView print implementation | Complete rendered snapshot, preparation cancellation, resource lifetime, and honest request result. |
 | [`QRCode.min.js`](#qrcodeminjs) | classic-script | Vendored QRCode generator for DOM, canvas, SVG, and image output. | Browser vendor script | Vendor-native. |
@@ -134,7 +134,7 @@ own asynchronous work, cancellation, and backpressure.
 | [`ScreenCapture.js`](#screencapturejs) | esm | Captures a display surface as image, video, or GIF with explicit lifecycle events. | Browser / native WebView | State/events normalized; permission and codec errors mixed. |
 | [`SpeechPlayback.js`](#speechplaybackjs) | esm | Admits complete speech segments to a capacity-advertising provider immediately, retains serialized native/custom lookahead, and plays every result in exact indexed order. | Browser + native bridge | Stored part text stays exact; the outbound speech-input copy receives automatic formatting-mark cleanup; provider/media failures remain mixed. |
 | [`StaticDocumentCatalog.js`](#staticdocumentcatalogjs) | esm | Loads a positive static document inventory with cache, search, and complete context. | Browser / native WebView / server with fetch | Mutable complete catalog/content normalization; malformed data and transport failures remain visible. |
-| [`SystemAppearance.js`](#systemappearancejs) | esm | Reads or applies native appearance, returning an explicit unsupported browser state when no bridge exists. | Browser/native hybrid | Absent bridge normalized; native result/error preserved. |
+| [`SystemAppearance.js`](#systemappearancejs) | esm | Reads or applies native appearance, returning an explicit unsupported result when the bridge or optional namespace is absent. | Browser/native hybrid | Exact absent optional namespace normalized with its complete error; partial-method and genuine native errors preserved. |
 | [`SystemPlatformPresentation.js`](#systemplatformpresentationjs) | classic-script | Maps kernel names to presentation labels/classes without granting platform authority. | Browser / native WebView classic script | Fully normalized presentation only. |
 | [`SystemToolRegistry.js`](#systemtoolregistryjs) | esm | Registers validated command builders and constructs command strings without executing them. | Cross-host | Fully normalized definitions/quoting. |
 | [`TerminalClient.js`](#terminalclientjs) | esm | Maps native terminal sessions and Arcane events into an EventTarget client. | Native bridge | Client events/state normalized; native result/error mixed. |
@@ -3475,9 +3475,31 @@ Exact exports: `PREFERENCE_STORE_ERROR_CODES`,
 
 **Browser/native hybrid.** Complete ordinary values and returned snapshots remain
 mutable after schema normalization. Non-Android
-`Arcane.preferences.setMany()` supplies the optional atomic batch. Only exact
-unsupported native capability changes future operations to app-scoped
-localStorage; an in-flight advertised batch is never downgraded after rejection.
+`Arcane.preferences.setMany()` supplies the optional atomic batch. The default
+adapter uses the existing app-scoped localStorage owner when there is no native
+preferences facade, on the existing Android route, or after either the existing
+`ANDROID_CAPABILITY_UNSUPPORTED` error or an exact Core lookup error:
+`code:'METHOD_NOT_ALLOWED'`, `reason:'core-namespace-unavailable'`,
+`namespace:'preferences'`, and `method:'preferences.<current operation>'`.
+This marker proves the entire optional namespace was absent before dispatch.
+A missing method in a partial/read-only service, an older unmarked error,
+permission denial, persistence failure, transport error, or cancellation never
+selects local storage. Explicit caller adapters retain their own behavior.
+
+For `get`, `set`, and `delete`, that positively absent namespace retries the
+same operation once through the existing local adapter, then keeps that adapter
+for the store's later operations. Complete arguments and the existing
+`{operationId,signal}` context are retained. Disposal and caller cancellation
+are checked before selecting or invoking the local adapter, so a late native
+absence result cannot start a cancelled local write. No data location, schema,
+saved value, or migration is introduced.
+
+An in-flight advertised `setMany` batch is never downgraded to serial writes
+after rejection. Exact namespace absence selects the local adapter for later
+operations and preserves that batch's original rejection with no local write.
+ThemeManager's first Light/Dark/System choice uses two ordinary `set` calls,
+not a batch: both may complete through the existing local owner before the
+selected theme is applied. Its persistence-first ordering is unchanged.
 If cancellation settles after a native batch was dispatched, reload the store to
 reconcile any atomic host commit that completed before cancellation. Transport:
 Arcane.preferences or app-scoped localStorage. [Deep protocol details](protocols.md).
@@ -4064,7 +4086,8 @@ console.log(Object.keys(module));
 
 ### Overview
 
-Reads or applies native appearance, returning an explicit unsupported browser state when no bridge exists.
+Reads or applies native appearance, returning an explicit unsupported result
+when the bridge or its optional namespace is absent.
 
 ### Public surface
 
@@ -4074,7 +4097,21 @@ Exact exports: `default`.
 
 ### Availability and normalization
 
-**Browser/native hybrid.** Absent bridge normalized; native result/error preserved. Transport: Arcane.appearance. [Deep protocol details](protocols.md).
+**Browser/native hybrid.** No bridge or callable method retains the existing
+`{supported:false,platform:'browser'}` result. A callable facade is not proof of
+an installed service: `available()` reports callable `apply` presence only.
+`current()` and `apply()` recognize only a matching Core
+`METHOD_NOT_ALLOWED` error with `reason:'core-namespace-unavailable'`,
+`namespace:'appearance'`, and the exact requested method. They return
+`{supported:false,reason:'core-namespace-unavailable',error}`, retaining the
+complete original error for diagnostics and making no platform or native
+application claim. Absence is not cached, so later service registration can
+serve the next operation. Partial-method absence, unmarked permission errors,
+transport/cancellation failures and all other native errors reject unchanged.
+Native success values and existing appearance input normalization remain
+unchanged. ThemeManager may therefore complete a browser color-scheme change
+when native appearance is explicitly unsupported, while genuine failures stay
+observable. Transport: Arcane.appearance. [Deep protocol details](protocols.md).
 
 ### Example