arcane-os 0.69.0 → 0.71.0

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

@@ -842,6 +842,14 @@ cancellation signal. Cancelling one handle detaches that caller; the shared
 preparation is aborted only when its last pending caller cancels. Different AI
 instances do not share an in-flight synthesis operation. Complete stored
 results remain reusable through the same application storage.
+
+Missing audio participates in the provider runtime's shared TTS activation with
+the preparation's cancellation signal. Cancelling the final pending interest
+aborts that activation; another preparation, explicit playback activation, or
+direct TTS load joining it keeps the load alive. Cancellation does not unload a
+model whose activation has already completed. A complete audio-cache hit never
+requests model activation. Provider cancellation and cleanup remain cooperative;
+an aborted caller wait alone is not evidence that native work has stopped.
 After a durable preparation completes, a later preparation call rereads its
 manifest and saved-file presence, regenerating only missing segments. A
 completed preparation without storage reuses its retained Blobs.
@@ -874,9 +882,10 @@ The supplied signal observes preparation until `ready` settles. Manual
 handle. If a raw audio write has already begun when cancellation arrives,
 its metadata transaction finishes so that successful audio can be reused;
 no later queued write starts for that cancelled preparation.
-Cancelling preparation prevents later synthesis, but the existing shared
-provider load/unmute operation has no per-preparation signal and may finish.
-Cancellation does not claim to stop an already-started shared model load.
+Cancelling preparation prevents later synthesis and releases its pending
+activation interest. Other pending interests retain the shared load; cancelling
+the final interest forwards abort to its provider-owned activation. Actual
+provider cleanup remains observable through that operation's settlement.
 
 ### Playback controls and independent lifetimes
 
@@ -1497,23 +1506,39 @@ The Worker installs one private module router before importing the entrypoint:
 - a dynamic import whose target is known imports the materialized URL;
 - a fetch whose target is known reads the materialized URL;
 - a Worker whose target is known starts the SDK role Worker and imports the
-  materialized target there; and
-- a Cache match whose target is known returns the materialized file.
+  materialized target there.
 
-Every unmapped operation keeps ordinary browser behavior:
+Resource ownership extends to ordinary self-contained speech runtimes as well
+as graph runtimes:
 
 - an unmapped relative or URL-like import resolves against the calling module's
   original source URL, while a bare specifier remains unchanged for native
   import-map resolution;
-- an unmapped fetch calls native `fetch` and preserves the caller's options;
-- an unmapped Worker calls the native `Worker` constructor and preserves the
-  caller's options; and
-- an unmapped Cache operation delegates to native Cache Storage.
-
-Cache `put`, `add`, `addAll`, `delete`, and `keys` are normal mutable browser
-operations. The SDK does not replace them with a read-only cache. Relative
-requests are resolved from the calling module's original source URL before the
-native Cache operation.
+- an unmapped HTTP fetch preserves the caller's request options and reaches
+  the parent DBOPFS resource store; Blob/data resources remain local;
+- an unmapped module Worker starts through the SDK role Worker and forwards
+  its resource fetches to that same store; and
+- an unmapped classic Worker retains native execution. Its internal fetches
+  are outside this module-Worker routing contract.
+
+Inside the dedicated speech Worker, native CacheStorage is temporarily
+unavailable before runtime import, so the selected runtime takes its existing
+fetch path. Transformers' public browser/custom/filesystem cache switches are
+disabled there. The SDK does not fabricate Cache matches or mutation results,
+and it neither clears nor changes saved native caches. The original Worker
+environment is restored on unload or failed import. Existing explicit
+`removeBrowserSpeechModelCache()` remains a separate caller-selected operation.
+
+The existing speech store exposes `fetchResource(input, options)` for its
+Worker loaders, returning `{file,status,statusText,headers,url,redirected}`.
+New declared files and fetched model, voice, configuration, and WASM resources
+stream into ordered DBOPFS parts even without a response length. Closed-part
+progress uses `unit:'shards'`; declared-file progress retains `unit:'files'`
+with the current shard record in `resource`. Complete declared peer files and
+closed resource parts survive cancellation. Existing whole-file caches remain
+readable without migration. HTTP resume is used only when the server returns
+the requested range; otherwise the complete resource is downloaded anew.
+Worker termination aborts and joins its parent-owned resource operations.
 
 Routing discovery is best effort and is not an admission gate. If the scanner
 cannot interpret a module, that module is left unchanged and follows its native
@@ -1535,11 +1560,14 @@ provider:
   `namespace.env.backends.onnx.wasm.wasmPaths = {mjs,wasm}`, keeps remote model
   loading enabled, and applies caller-selected `numThreads` when present.
 
-Transformers and Kokoro keep their normal provider downloads and Cache behavior
-for routes not materialized by the SDK. Kokoro voice aliases and Transformers
+Transformers and Kokoro use their normal provider request semantics through
+the selected DBOPFS resource owner. Kokoro voice aliases and Transformers
 model aliases may be listed in `runtimeRequestUrls` so an upstream request for a
 known file resolves to the already materialized local file. Model, voice, and
 runtime selection remains with the application and upstream publisher.
+Native ESM imports remain platform-owned; only declared runtime modules are
+materialized by artifact preparation. Custom classic Worker internals are not
+claimed as stored by this contract.
 
 ## Providers
 

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

@@ -117,21 +117,15 @@ current mutable status snapshot. Provider states are `unloaded`, `loading`, `rea
 
 Browser-WASM model loads report `cache-check`, `download`, and `initialize`
 phases. Download records preserve the ordered model-file fields `completed`,
-`total`, and `unit:'files'`. They add `loadedBytes`, `totalBytes`,
-`remainingBytes`, `bytesPerSecond`, `etaSeconds`, `activeTransfers`,
-`transferLimit`, and `transferMode`. `loadedBytes` is aggregate downloaded or
-restored progress for the current install. Active partial writes count while
-they are staged, then are removed from that total if their transfer fails;
-completed shards or Range parts reused from an interrupted attempt remain
-counted. Unknown totals, remaining counts, rates, and ETAs are `null`;
-once known, byte values and seconds are nonnegative numbers. `activeTransfers`
-is the current transfer-worker count, `transferLimit` is the selected concurrency
-bound, and `transferMode` identifies `probing`, `files`, `ranges`, or `single`.
-The store coalesces chunk-driven changes on a 250 ms cadence and publishes
-immediately when download starts, the transfer plan or total becomes known,
-active-worker count changes, and the download completes. At known completion, remaining bytes and ETA are zero
-and active transfers are zero. Applications format the raw measures into B,
-KB, MB, GB, transfer-rate, and duration labels.
+`total`, and `unit:'files'`. Their ordered `members` records contain each file's
+`name`, committed-part `completed`, `total`, and `unit:'shards'`. A streaming
+response has `total:null` until its end is observed; completion then supplies
+the actual committed-part count. Previously complete members identify
+`state:'cached'`. `activeTransfers` is the current transfer-worker count,
+`transferLimit` is the selected concurrency, and `transferMode` identifies
+`probing`, `files`, `ranges`, or `single`. No byte progress, rate, or estimated
+completion time is produced. Closed-part and lifecycle changes publish promptly;
+the existing 250 ms heartbeat retains the current semantic state.
 
 Initialization keeps `phase:'initialize'` and reports a `stage` and a readable
 `message` from the packaged runtime's existing log signals: runtime startup,
@@ -172,8 +166,11 @@ optional descriptor `bytes` divides that member into deterministic contiguous
 parts of roughly 4 MB each, up to 4,096 parts. Each exact completed part is
 committed separately in OPFS, so retry or refresh fetches only the small
 in-flight parts plus any other missing parts; the ordered parts are exposed to
-Wllama as one logical model Blob. Range offsets remain transport-local; only
-aggregate transfer telemetry is public.
+Wllama as one logical model Blob. Ordinary full responses, including unknown
+content lengths and single-file models, also stream directly into ordered OPFS
+parts. Model data is not accumulated in one JavaScript buffer. Range offsets
+and physical part framing remain storage/transport-local; progress describes
+completed files and parts.
 
 ## Model selection, optional hardening, and cache
 
@@ -181,7 +178,7 @@ The canonical model descriptor is
 `{id, files:[{name?,url,bytes?},...]}`. The ordered `files` array is nonempty;
 names and URLs are unique. Each URL must be absolute HTTPS without credentials
 or a fragment. An optional positive safe-integer `bytes` value is used only for
-progress and HTTP Range planning. Missing or unusable metadata never blocks a
+HTTP Range planning. Missing or unusable metadata never blocks a
 download, and a declared value is not a content-length check.
 
 Fetch follows HTTPS redirects and records the requested and final HTTPS URL. A
@@ -205,11 +202,22 @@ admission work. Observational byte counting and exact HTTP Range framing remain
 transport-local. A load succeeds only after Wllama reports that the model is
 loaded.
 
-The DBOPFS adapter commits each complete member or Range part independently and
-exposes only a complete ordered model set as a cache hit.
+The DBOPFS adapter commits ordered parts independently and exposes only a
+complete ordered model set as a cache hit. Existing whole-file and Range-part
+caches remain readable without migration. Closed parts survive interrupted
+writes; a source without supported resume starts that member's next transfer
+from its beginning. Complete peer members remain cached.
 `load({offline:true})` never performs a model request; it uses a compatible
 cached entry or rejects with `ARCANE_AI_MODEL_OFFLINE_MISS`.
 
+The same store exposes `fetchResource(input, options)` for SDK-owned browser
+model loaders. It returns `{file,status,statusText,headers,url,redirected}`
+after storing the complete response through the shared part owner. Ordinary
+Fetch request options, `signal`, and semantic `onProgress` are supported.
+The browser decision model accepts this store through its additive `store`
+option; resource acquisition stays with the SDK while model selection stays
+with the application. See [browser decisions](browser-decisions.md).
+
 ```javascript
 const {security, cache} = ai.status().llm;
 console.log(security?.secure === true); // false when the optional field is absent

package/docs/reference/core-native-packaging.md

@@ -210,6 +210,19 @@ details and [the client contract](core-client.md) for native bridge integration.
 
 ## Launch-time locations
 
+For one app-owned Core shared by the native window and a separate MCP process,
+the launch context may explicitly select `sharedHost:{endpoint,logFile}`. The
+generated native child then connects through a stdio bridge, starting an
+independent headless Core only when the selected endpoint is absent. Its
+endpoint claim precedes application service imports/factories. Closing a native
+window disconnects its bridge; explicit shared-host shutdown drains services.
+Omitting `sharedHost` preserves the existing stdio-owned Core lifetime.
+See [shared Core host ownership](core-shared-host.md) for exact startup,
+connection, cancellation, diagnostics, endpoint, and platform contracts.
+The packaged-web service exposes `current()` as its active `{origin,url,port}`
+or `null`; the shared host replays that current listener to a newly attached
+macOS bridge, without restarting the server or retaining historical events.
+
 The generated Core entry accepts `--arcane-launch-config <path>`. The public
 `readCoreLaunchContext({argv=process.argv.slice(2)}={})` function in
 `arcane-os/core/host` reads that explicitly selected JSON object. A native host

package/docs/reference/core-runtime.md

@@ -71,6 +71,15 @@ receives `(parameters, {application, service, emit, getService, requestId, signa
 `this` bound to its service definition. A hook or handler may publish a complete
 service-owned event through `emit(event, data)`.
 
+A request handler's `emit` places its owning request ID in the event frame's
+optional top-level `requestId`, leaving `data` unchanged. Multi-connection hosts
+can route those frames to the requesting connection even when different clients
+choose the same application `streamId`. Lifecycle-hook `emit` and public
+`runtime.emit` remain uncorrelated service-wide events. Retain that service
+context when an application intentionally publishes a change to every client;
+request-context events belong to the originating request. The ordinary Core
+client still delivers the complete original event data to its listeners.
+
 ### Native service composition
 
 `await runtime.getService(name)` and `await context.getService(name)` return the

package/docs/reference/core-shared-host.md

@@ -0,0 +1,190 @@
+# One application, one shared Core host
+
+`arcane-os/core/host` provides a Node local-IPC owner for applications whose
+native UI and separate MCP process use the same catalog, drafts, review queue,
+and Git service. The application chooses one endpoint and one set of services.
+The endpoint is a nonempty local pipe/socket path. The SDK connects to it,
+optionally starts an explicit headless entry,
+and keeps client disconnection separate from service shutdown.
+
+This is an explicit same-application connection. It does not scan applications
+or processes, share preference files, copy a catalog, retry requests, or retain
+event history. Application methods and policy stay in the application services.
+Use the [MCP server](mcp-stdio.md) for external MCP framing; local Core continues
+to use the existing `arcane/1` protocol and Content-Length stream framing.
+
+## Host entry
+
+```js
+import {runSharedCoreHost} from 'arcane-os/core/host';
+
+const host = await runSharedCoreHost({
+    endpoint: process.env.MOON_CORE_ENDPOINT,
+    application: {id: 'moon-cheese-ledger'},
+    version: '1.0.0',
+    async configure(runtime, {signal}) {
+        // Only the successful endpoint owner imports and constructs services.
+        const {default: createLedger} = await import('./ledger.mjs');
+        signal.throwIfAborted();
+        runtime.registerService(createLedger());
+    }
+});
+await host?.closed;
+```
+
+`startSharedCoreHost({endpoint,application,version,configure,getReplayEvents,
+signal,onError})` binds the selected endpoint **before** calling `configure`.
+The callback receives the existing runtime and the host's lifetime signal.
+Register each service as it is constructed so its drain/disposal belongs to the
+runtime even if a later factory fails. Put asynchronous service initialization
+in `start`, as with ordinary Core composition. Factory imports can run
+concurrently; requests wait for composition, then only their own service's
+startup. Dispatcher readiness does not claim model or service readiness.
+
+It resolves to `{runtime,endpoint,closed,close}`. `close()` rejects new work,
+joins composition, closes the runtime, drains complete queued frames, and
+closes its connections. It retains the endpoint claim through service cleanup
+before stopping the listener, so a new launcher cannot start a second service
+owner during an accepted save. Accepted service-lifetime requests finish
+before service drain/disposal. A supplied signal begins this same shutdown;
+the lazy factory receives cancellation and is joined before cleanup. Register
+resources before rejecting after creation. Startup and shutdown errors remain
+observable; `closed` rejects on host shutdown failure. `onError` observes
+transport/background errors, with console diagnostics by default.
+
+An endpoint already in use rejects with the native `EADDRINUSE` error and
+`coreHostPhase:'listen'`, without invoking the factory.
+`runSharedCoreHost(options)` adds the explicit headless startup handshake: a
+losing launcher connects to the existing owner and confirms dispatcher response
+without importing its own application service modules. It returns `null` in
+that case. The winning launcher returns the same host object. It reports startup
+success or the complete failure to a parent Node IPC channel when present and
+never calls `process.exit()`.
+
+## Connect, reuse, or start headlessly
+
+```js
+import {connectSharedCoreHost} from 'arcane-os/core/host';
+
+const connection = await connectSharedCoreHost({
+    endpoint: selectedEndpoint,
+    start: {
+        command: process.execPath,
+        args: [selectedHostEntry],
+        logFile: selectedDiagnosticLog
+    }
+});
+const catalog = await connection.client.invoke('catalog.read', {});
+// The UI or MCP process is finished. Shared services remain alive.
+await connection.close();
+```
+
+`connectSharedCoreHost({endpoint,start,signal,onError})` first connects to the
+selected endpoint. Only connection absence (`ENOENT` or `ECONNREFUSED`) selects
+`start`; other errors propagate unchanged. Omit `start` for connect-only use.
+The optional record is `{command,args=[],cwd,env,logFile}`. Its arguments and
+environment are captured at acceptance. The selected entry must call
+`runSharedCoreHost`. Parent directories for the endpoint and diagnostic file
+must already exist. No shell, runtime installer, service manager, or automatic
+request retry is involved.
+
+Headless startup uses an independent child with ignored stdin and complete
+stdout/stderr appended to the explicit diagnostic file. The child reports its
+endpoint claim/composition result through its startup IPC channel; the launcher
+then disconnects that channel and releases the child process reference. An
+aborted connection/start wait rejects or closes the connecting client; it does
+not kill a host that another connection may already use. The host may therefore
+continue running after a launch wait is cancelled. Startup diagnostics and the
+endpoint remain the actual outcome owners. No startup timeout is imposed by
+this layer; supply a signal when the caller needs a bounded wait.
+
+The result is `{client,endpoint,closed,close,shutdown}`. `client` is the existing
+[Core client](core-client.md), with full invoke/cancellation/event behavior and
+current-runtime replay enabled. A connected transport is not a ready model.
+`close()` and `client.close()` cancel this connection's request-lifetime work
+and disconnect it. They leave accepted service-lifetime work and the host
+running. `closed` observes connection termination and rejects on a transport
+error. A subsequent connection uses the still-running owner. Reconnection is
+explicit; failed or uncertain requests are never resubmitted.
+
+`await connection.shutdown(invokeOptions)` explicitly invokes the host-owned
+`core.host.shutdown` operation. It drains the shared runtime, returns
+`{state:'closed'}` after successful service cleanup, then closes the connection.
+A drain failure returns the full Core error. Shutdown affects **all** clients
+of that app endpoint and belongs to the application owner's explicit lifecycle,
+not ordinary UI/MCP cleanup. The host reserves this one method; application
+services should use their own namespaces. Cancelling the caller's invoke wait
+after shutdown acceptance does not undo the shared shutdown.
+
+## Correlation, events, and state
+
+Each connection has its own request-ID space. The transport substitutes an
+internal Core request ID and restores the originating ID on responses and
+the optional top-level event `requestId`. Existing `data.requestId` values that
+carry that same Core correlation ID are restored too. `parameters`, returned results, schemas,
+documents, and content remain complete and unchanged. A handler's
+`context.requestId` is the Core-side correlation ID; put it in the event's
+separate `requestId` field, not inside application content.
+
+Responses and request-context events go to the originating connection in
+order. Core supplies the top-level request correlation outside `data`, so two
+clients may choose the same `streamId` without receiving each other's chunks.
+Retired request frames are never routed to another connection. Ordinary
+application/service events from the lifecycle context or `runtime.emit` are broadcast to
+connected clients. Runtime state includes all active work and translates this
+connection's IDs; other connections' active requests retain Core-side IDs.
+`request.cancel` and `requests.cancelAll` affect only the sending connection's
+requests. A disconnect performs the same scoped cancellation. The underlying
+runtime continues to preserve service-lifetime acceptance.
+
+`runtime.replay` sends only that connection the current `core.ready`,
+`core.state`, and `core.service.state` snapshot. Optional synchronous
+`getReplayEvents()` returns current `{event,data}` records from their actual
+service owners. It is for current domain state, not historical chunks or
+retired requests. Subscribe before requesting a domain snapshot when its live
+events may change; applications own those domain methods and state.
+
+## Native launch and platforms
+
+The generated portable Core entry keeps ordinary stdio behavior unless the
+explicit launch context contains:
+
+```json
+{
+  "sharedHost": {
+    "endpoint": "APPLICATION-SELECTED-LOCAL-ENDPOINT",
+    "logFile": "APPLICATION-SELECTED-DIAGNOSTIC-FILE"
+  }
+}
+```
+
+Both native UI and external MCP clients select the same endpoint. With this
+option, the native Core child is a stdio-to-shared-Core bridge. It connects or
+launches the same entry with `--arcane-core-headless`; the headless entry claims
+the endpoint before importing services. Closing the native window ends its
+bridge, while the independent Core host remains available. Service options and
+the complete launch context retain their existing values. There is no implicit
+shared mode or new application descriptor field.
+
+`startSharedCoreBridge({endpoint,start,input=process.stdin,
+output=process.stdout,signal,onError})` is also public. It returns
+`{endpoint,closed,close}` and forwards full framed requests, events, and
+responses. EOF or bridge cancellation disconnects that client only. Terminal
+stream errors settle pending writes and reject `closed`; output is neither
+truncated nor replaced with a fabricated response.
+
+On Windows use an app-selected named pipe such as
+`\\.\pipe\moon-cheese-core`; on Linux/macOS use an app-selected Unix-domain
+socket path in an existing writable directory. Select the same absolute Unix
+path across UI and MCP launch contexts so differing working directories do not
+select different endpoints. Node and the operating system
+own their native endpoint requirements. A Unix socket left after an abnormal
+host exit is reported as a connection/bind failure; the SDK does not delete an
+existing endpoint to take ownership. The app owner can resolve that actual
+stale endpoint after establishing its stopped lifecycle. Android requires its
+host adaptation for local IPC and independent process ownership; application
+services and `arcane/1` client semantics remain the shared boundary.
+
+This source contract is distinct from a selected package/native artifact or
+execution on a particular platform. Applications adopt it through the published
+SDK and their corresponding native package build, not by copying this source.

package/docs/reference/inventory/package-api.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "sdkVersion": "0.68.0",
+  "sdkVersion": "0.69.0",
   "environment": {
     "runtime": "Node.js for Node entrypoints; browser for browser-only entrypoints",
     "minimumVersion": "22.23.2 for Node entrypoints",
@@ -4374,7 +4374,7 @@
       "summary": "Creates the SDK-owned provider that assembles one selected app and explicit services into a portable Core payload.",
       "availability": "Node; produces a portable payload rather than an executable host",
       "protocol": "arcane-native-builder/1 portable provider",
-      "normalization": "Preserves complete selected app and dependency releases; an explicit services selection overrides appDescriptor.native.services, otherwise the descriptor selection is used; reports executable:false and never substitutes for an unavailable platform host"
+      "normalization": "Preserves complete selected app and dependency releases; an explicit services selection overrides appDescriptor.native.services, otherwise the descriptor selection is used; optional appDescriptor.native.window carries positive integral logical client width/height and optional resizable into manifest.window with omitted fields preserved; reports executable:false and never substitutes for an unavailable platform host"
     },
     {
       "id": "native-portable-provider:arcaneNativeBuilderProvider",
@@ -4416,7 +4416,7 @@
       "summary": "Assembles selected application services and browser content with the SDK-owned Windows x64 WebView2 and SEA host.",
       "availability": "Node for assembly; Windows x64 with WebView2 Runtime for execution",
       "protocol": "arcane-native-builder/1 windows-x64 provider",
-      "normalization": "Uses a selected hostDirectory or the exact installed SDK version's numeric release asset; preserves complete payloads; app displayName plus .exe (app ID fallback) and matching .exe.config use Windows filename substitutions only; manifest.host.executable owns inventory, icon, verify and run while generic cache/Core names remain unchanged; native.icon PNG/ICO derives the copied executable and host.icon without an app compiler, while other formats retain assembly with native.icon.unsupported and executableIcon:false; the matching host loads the selected window/taskbar icon and handles window.setTheme with per-field applied/unsupported results; run cancellation closes stdin and waits for host-owned graceful shutdown"
+      "normalization": "Uses a selected hostDirectory or the exact installed SDK version's numeric release asset; preserves complete payloads; app displayName plus .exe (app ID fallback) and matching .exe.config use Windows filename substitutions only; manifest.host.executable owns inventory, icon, verify and run while generic cache/Core names remain unchanged; native.icon PNG/ICO derives the copied executable and host.icon without an app compiler, while other formats retain assembly with native.icon.unsupported and executableIcon:false; the matching host loads the selected window/taskbar icon and handles window.setTheme with per-field applied/unsupported results; native.window selects initial 96-DPI logical client width/height and optional resizable through manifest.window, the matching host scales to actual DPI and fits initial placement to the usable screen while omitted fields and existing restored non-normal state remain unchanged; no saved-bounds subsystem is added and initial-fit logic is not reapplied during later resizing; run cancellation closes stdin and waits for host-owned graceful shutdown"
     },
     {
       "id": "native-windows-provider:arcaneNativeBuilderProvider",

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

@@ -967,7 +967,7 @@
     {
       "file": "runtime/arcane/components/theme-switcher.html",
       "name": "theme-switcher.html",
-      "purpose": "Selects and refreshes system, light, dark, or custom theme mode with per-instance choices and labels.",
+      "purpose": "Selects and refreshes system, light, dark, or custom theme mode with per-instance choices, labels, and CSS-configurable group/option radii, option font and group background.",
       "methods": [
         "configure()",
         "setMode()",
@@ -980,7 +980,7 @@
       ],
       "availability": "Browser and supported native WebViews",
       "transport": "HTMLImport + DOM; injected Arcane/provider modules where listed",
-      "normalization": "Preference/native appearance behavior mixed; no component-ready contract"
+      "normalization": "Preference/native appearance behavior mixed; selected button background, text and outline remain visible during hover while the hover fill applies only to unselected enabled buttons; no component-ready contract"
     },
     {
       "file": "runtime/arcane/components/unified-inbox.html",

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

@@ -29,8 +29,8 @@
       "summary": "Owns provider-selectable chat and the one-time caller-authority browser STT/TTS configuration, lifecycle, synthesis, transcription, and playback boundary.",
       "availability": "Browser + native bridge + TWiN Cloud",
       "protocol": "arcane-ai-browser-speech-configuration/1, AIProviderRuntime arcane-ai-provider/2 routes, globalThis.arcaneEvents, TWiN Cloud HTTPS, Arcane.ollama, Arcane.speech, Android WebView bridge",
-      "normalization": "Complete mutable caller-owned browser speech authority, SDK-owned provider registration/replacement/disposal, explicit STT/TTS activation, normalized 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": "Native fetchTTS(payload,signal) and fetchSTT(audio,signal) forward caller cancellation separately from their complete Core speech payloads, normalize aborts to AbortError and suppress late results; actual engine interruption remains service-owned. prepareTTSPlayback(payload,signal) silently returns a real Blob or native-speech descriptor; native controls expose finished/released/state/error/pause/resume/stop, and actual release owns the playback lane. fetchTTS and durable prepareTTS report ARCANE_AI_TTS_AUDIO_EXPORT_UNAVAILABLE for native voices. Request-local model overrides remain exact and never mutate the configured model. 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`."
+      "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, default repeated-formatting-mark removal from cloned outbound TTS input, explicit textFormat:'plain' preservation for complete synthesis/preparation while streaming cleanup remains automatic and caller/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": "Native fetchTTS(payload,signal) and fetchSTT(audio,signal) forward caller cancellation separately from their complete Core speech payloads, normalize aborts to AbortError and suppress late results; actual engine interruption remains service-owned. prepareTTSPlayback(payload,signal) silently returns a real Blob or native-speech descriptor; native controls expose finished/released/state/error/pause/resume/stop, and actual release owns the playback lane. fetchTTS and durable prepareTTS report ARCANE_AI_TTS_AUDIO_EXPORT_UNAVAILABLE for native voices. Request-local model overrides remain exact and never mutate the configured model. 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; default speech-input cleanup with SDK-internal preparation metadata and explicit complete-call textFormat:'plain' consumed before engine dispatch; `prepareTTS({parts,storage,identity,textFormat,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",
@@ -90,7 +90,7 @@
       "summary": "Provider-neutral selection, lifecycle, routing, startup, request, streaming, cancellation, and independent LLM/STT/TTS state.",
       "availability": "Cross-host in-process runtime; registered providers remain browser, native, or cloud specific",
       "protocol": "arcane-ai-runtime/2, arcane-ai-provider/2, arcane-ai-model-authority/1",
-      "normalization": "Normalizes mutable complete per-role routes, lifecycle/status, cancellation, streaming cleanup, capacity-1 FIFO LLM/STT lanes, bounded provider-declared parallel TTS requests with FIFO overflow, automatic repeated-formatting-mark removal from cloned direct TTS payloads, local-only selection, direct LLM history/declaration/terminal structural contracts, complete all-choice content/reasoning FIFO iteration, private automatic provider draining with result-first buffering, terminal-only structural calls, exact per-choice observed/terminal correlation, and a separate complete validated terminal result without creating a fallback.",
+      "normalization": "Normalizes mutable complete per-role routes, lifecycle/status, cancellation, streaming cleanup, capacity-1 FIFO LLM/STT lanes, bounded provider-declared parallel TTS requests with FIFO overflow, default repeated-formatting-mark removal from cloned direct TTS payloads or explicit textFormat:'plain' preservation with the control consumed before engine dispatch, local-only selection, direct LLM history/declaration/terminal structural contracts, complete all-choice content/reasoning FIFO iteration, private automatic provider draining with result-first buffering, terminal-only structural calls, exact per-choice observed/terminal correlation, and a separate complete validated terminal result without creating a fallback.",
       "surface": "Protocol constants; singleton-only `AIProviderRuntime`; `aiProviderRuntime`; `getAIProviderRuntime()`; provider registration/identity/selection, closed three-role and STT/TTS-only validation/configuration/replacement, status/catalog/inspection, startup, per-role load/unload/dispose/cancel, dispose-all, request/stream/speech aliases, SDK-internal speech-input preparation metadata, and mute controls."
     },
     {
@@ -578,11 +578,11 @@
         "DBOPFS_REASONS",
         "default"
       ],
-      "summary": "Provides app-scoped OPFS tables, explicit non-recursive empty-table removal, worker I/O, backup/restore, compression, and CRUD/batch APIs.",
+      "summary": "Provides app-scoped OPFS tables, committed-change subscriptions with targeted cache freshness, explicit non-recursive empty-table removal, worker I/O, backup/restore, compression, and CRUD/batch APIs.",
       "availability": "Browser / native WebView",
-      "protocol": "OPFS, DBOPFSWorker, Compression Streams, and per-realm globalThis.arcaneEvents authority",
+      "protocol": "OPFS, DBOPFSWorker, Compression Streams, per-realm globalThis.arcaneEvents authority, and native BroadcastChannel for live same-app/storage-partition committed changes",
       "normalization": "App scope and recognized file parsing are normalized; nonblank unreadable JSONL rows remain complete raw strings, empty-table removal reports removed, absent, or not-empty after a create:false directory lookup and without scanning or recursively clearing a directory, same-named files are preserved, aliases and cached handles are invalidated only when the directory is gone, and unexpected DOM/storage errors are preserved.",
-      "surface": "default `DBOPFS`; installs `window.dbopfs`, emits `dbopfs-ready`; table/file/backup APIs including removeEmptyTable(tableName). createCompressedPNG({tableNames,additionalTables,signal}) returns a PNG Blob without download or record writes; omitted names select all, [] none, and supplied tables replace matching saved tables in the export. downloadCompressedPNG(name,options) reuses the same preparation and initiates one download; cancellation prevents it. restoreFromPNG(file,{selectTables}) closes the decoded image after pixel extraction, awaits the optional caller selection/projection before any writes, and rejects DBOPFS_RESTORE_WRITE_FAILED AggregateError after all selected table batches settle when records fail, preserving original errors and failures {tableName,fileName,reason}; successful writes remain. No-options restore and setMany retain their contracts."
+      "surface": "default `DBOPFS`; installs `window.dbopfs`, emits `dbopfs-ready`; subscribeChanges(listener,{signal,once}) observes DBOPFS_EVENT_TYPES.change (dbopfs-change), returns idempotent unsubscribe/.dispose, and publishes metadata {applicationId,storagePath,tableName,directoryName,fileName,action,originId,sequence,changeId,remote} after successful storage commits only. Actions are write/append/delete/table-delete; batches preserve partial success, remote receipts invalidate targeted aliases before local publication and never rebroadcast, and pagehide/pageshow closes/reopens the native channel and clears memory caches without replay or fabricated changes. Local subscription/storage continue when BroadcastChannel is unavailable. Table/file/backup APIs include removeEmptyTable(tableName). createCompressedPNG({tableNames,additionalTables,signal}) returns a PNG Blob without download or record writes; omitted names select all, [] none, and supplied tables replace matching saved tables in the export. downloadCompressedPNG(name,options) reuses the same preparation and initiates one download; cancellation prevents it. restoreFromPNG(file,{selectTables}) closes the decoded image after pixel extraction, awaits the optional caller selection/projection before any writes, and rejects DBOPFS_RESTORE_WRITE_FAILED AggregateError after all selected table batches settle when records fail, preserving original errors and failures {tableName,fileName,reason}; successful writes remain. No-options restore and setMany retain their contracts."
     },
     {
       "file": "runtime/arcane/modules/DBOPFSDocumentLibrary.js",

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 with per-instance choices and labels. | `configure()`<br>`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, labels, and CSS-configurable group/option radii, option font and group background. | `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 |
@@ -2073,6 +2073,24 @@ The host inherits text color. Existing `--app-bar-border` (falling back to
 remain supported. Applications own their palette and surrounding placement;
 the component adds no application-specific palette or settings section.
 
+Set these public CSS custom properties on the `html-import` host or an ancestor
+to style one instance through the ordinary cascade. Omitting them preserves the
+existing presentation:
+
+| Property | Controls | Default |
+| --- | --- | --- |
+| `--theme-switcher-radius` | Outer group border radius | `1.6rem` |
+| `--theme-switcher-option-radius` | Each option's border radius | `1.4rem` |
+| `--theme-switcher-font` | Complete option `font` shorthand | `700 .875rem/1.25 system-ui,sans-serif` |
+| `--theme-switcher-background` | Group background, independent of option state | `color-mix(in srgb,currentColor 8%,transparent)` |
+
+The font value includes its size and family, plus any weight and line height.
+Use an application-owned complete font token or value, rather than the
+CSS-wide keyword `inherit` as the custom-property value. The host still inherits
+text color. These properties do not alter the `2.75rem` minimum targets,
+full-label wrapping, selected/hover/focus/disabled states, or theme persistence.
+Applications retain responsibility for readable font and color choices.
+
 This fragment declares no component-specific readiness or action event; use the loader's `html-import-ready` only to know that import execution completed.
 
 Shared dependencies: [`ThemeManager.js`](runtime-modules.md#thememanagerjs).
@@ -2097,6 +2115,22 @@ 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.
 
+An application can give that instance modest rounded corners and its own
+ordinary label font without accessing the shadow root:
+
+```css
+#theme-switcher {
+  --theme-switcher-radius: .65rem;
+  --theme-switcher-option-radius: .5rem;
+  --theme-switcher-font: 400 1rem/1.25 var(--app-font-family, system-ui, sans-serif);
+  --theme-switcher-background: transparent;
+  --app-bar-border: var(--border-color);
+}
+```
+
+These are example application values, not new component defaults. Other
+instances retain the defaults unless the application cascades overrides to them.
+
 ## unified-inbox.html
 
 ### Overview