arcane-os 0.68.0 → 0.70.0

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

@@ -805,14 +805,17 @@ does not select another page or speak background work.
 
 ### Preparation inputs and reuse
 
-`ai.prepareTTS({parts,storage,identity,signal,onState})` accepts an ordered array
+`ai.prepareTTS({parts,textFormat,storage,identity,signal,onState})` accepts an ordered array
 of strings or `{input,voice?,speed?,pauseAfterMs?}` records. An omitted voice
 uses the selected model default; omitted speed uses `ai.voiceSpeed`; omitted
 pause is zero. The SDK snapshots the selected speech configuration and current
 punctuation/word-cadence options for that preparation. A part's pause applies
 after its final extracted segment. Complete original input remains available
-for semantic comparison; automatic Markdown cleanup affects only the speech
-copy and occurs once before segmentation.
+for semantic comparison; default Markdown cleanup affects only the speech
+copy and occurs once before segmentation. Set `textFormat:'plain'` to preserve
+each supplied input exactly through that segmentation. The prepared segment
+text participates in semantic reuse, so a changed synthesis input does not
+reuse audio produced from the cleaned version.
 
 `storage` is optional. When supplied, `{db,table,key}` names the caller's ready
 DBOPFS instance and its application-owned table/key. The SDK stores complete
@@ -839,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.
@@ -871,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
 
@@ -977,7 +989,7 @@ speech method retain their existing behavior.
 ## Automatic speech-input formatting cleanup
 
 The shared streaming, audio-file, and `SpeechPlayback` paths remove repeated
-same formatting marks from the outbound speech-input copy automatically:
+same formatting marks from the outbound speech-input copy by default:
 
 ```javascript
 ai.streamTTS('## Heading\n**Hello');
@@ -994,10 +1006,13 @@ waits for its next character or the final flush.
 
 `end:true`, `finishTTS()`, or cancellation clears pending streaming formatting
 state. `fetchTTS()`, provider-runtime TTS requests, direct Kokoro provider
-requests, and `SpeechPlayback` apply the same cleanup to complete input. An
-existing `textFormat` extra is ignored and cannot disable or select cleanup.
+requests, and `SpeechPlayback` apply the same default cleanup to complete input.
+Complete-input APIs can explicitly select `textFormat:'plain'` as described
+below. The streaming `streamTTS()` options still ignore `textFormat`;
+streaming narration and `SpeechPlayback` keep their existing cleanup.
 SDK-internal delegation carries `{speechInputPrepared:true}` outside the speech
-payload only after one cleanup pass, preventing a second non-idempotent pass.
+payload after its owner selects text treatment, preventing a second
+non-idempotent cleanup pass or cleanup of explicitly plain input.
 Applications omit that internal metadata. Displayed messages, saved history,
 model input, caller payload objects, language, voice, synthesis capacity, and
 playback timing are not changed by the filter.
@@ -1023,6 +1038,39 @@ console.log(speechText.append('## Head', false)); // ' Head'
 console.log(speechText.append('ing', true)); // ing
 ```
 
+### Exact complete synthesis input
+
+Use the public `textFormat:'plain'` selection for already-authored speech or an
+exact generated preview. It belongs in `prepareTTS` options, or alongside the
+`input`/`text` field of a complete synthesis payload:
+
+```javascript
+function preparePreview(ai, preview, signal) {
+  return ai.prepareTTS({parts: [preview], textFormat: 'plain', signal});
+}
+
+function fetchPreview(ai, preview, signal) {
+  return ai.fetchTTS({input: preview, textFormat: 'plain'}, signal);
+}
+```
+
+The same payload field is supported by `AI.prepareTTSPlayback()` for audio-file
+providers, `AIProviderRuntime.request('tts', {operation:'synthesize', payload,
+localOnly, signal})`, its `synthesize(payload, options)` alias, and direct
+Kokoro `request()` calls using either `{text,...}` or `{model,input,...}`.
+The SDK consumes `textFormat` before engine/host dispatch. The original nonblank input,
+including whitespace and repeated formatting marks, remains unchanged; voice,
+speed, selected model, cancellation and audio ordering retain their existing
+owners. Only `'plain'` selects exact input; omission and other values retain
+the existing narration cleanup. Applications never supply the internal
+`speechInputPrepared` argument.
+
+This selection governs SDK text treatment, not the selected engine's input
+capacity or pronunciation. [Kokoro.js 1.2.1](https://github.com/hexgrad/kokoro/blob/664c76a704021239ba59c84dcbaa4d3dece01fe9/kokoro.js/src/kokoro.js)
+still tokenizes with truncation in both `generate()` and `stream()`; plain input
+does not establish complete audio for an oversized engine input. The SDK's existing complete-text forwarding
+fixture does not prove upstream synthesis completeness.
+
 ## Choose a device or reduce memory use
 
 Local Whisper and Kokoro roles accept
@@ -1458,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
@@ -1496,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
 
@@ -1610,10 +1677,11 @@ const result = await kokoro.request({
 The voice belongs to the caller-selected inventory; omission uses that model's
 default voice. The provider-native result is
 `{audio:Float32Array,sampleRate,voice}`. The provider/2 shared request form accepts
-`{model,input,responseFormat:'wav',voice?,speed?}` and returns
+`{model,input,textFormat?,responseFormat:'wav',voice?,speed?}` and returns
 `{audio:Uint8Array,contentType:'audio/wav'}`. High-level `AI.fetchTTS()` wraps
 that provider result in a WAV `Blob`. Returned provider records remain ordinary
-mutable values.
+mutable values. Both payload forms accept `textFormat:'plain'` to retain exact
+input; omission keeps the default speech-formatting cleanup.
 
 ## Lifecycle and cancellation
 

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
@@ -372,6 +385,47 @@ observes complete diagnostics and exit. Cancelling that operation closes its
 input, allowing the window and accepted Core service work to drain without a
 forced process termination.
 
+### Initial native window size
+
+An application can select its initial client area and resizing behavior in
+`arcane-app.json`, independently of its page layout:
+
+```json
+{
+  "native": {
+    "type": "app",
+    "icon": "img/icon.png",
+    "order": 100,
+    "bundledApps": [],
+    "window": {"width": 1280, "height": 800, "resizable": true}
+  }
+}
+```
+
+This is the `native` portion of the existing app descriptor. Each `window`
+member is optional. `width` and `height` are positive integral client dimensions
+in logical pixels at 96 DPI; `resizable` is a boolean. Omitting a member retains
+the host's existing choice, and omitting `window` preserves existing startup.
+The native registry projection preserves the record; the browser package
+projection gains no window controls. Portable and Windows assembly copy the
+record to `arcane-native.json` as `window`, without changing page or service
+content.
+
+The matching Windows host applies the dimensions once on initial load, using
+the display DPI and fitting the outer window within the selected monitor's
+usable work area. This fit does not impose a persistent maximum size. Explicit
+`resizable:false` uses a fixed frame and disables the maximize control; `true`
+permits ordinary resizing and maximizing. Later app/user resizing remains
+untouched. A composing launcher's `Load` handler runs after this initial sizing
+and can restore its own saved window state. The SDK adds no saved-bounds store.
+
+Direct Windows host composition uses nullable `ArcaneHostOptions` members
+`InitialClientWidth`, `InitialClientHeight`, and `Resizable` with the same
+semantics. Older precompiled Windows hosts do not read these options; use the
+matching SDK host archive when rebuilding an application. The portable record
+is available to platform adapters; this addition implements its Windows host
+behavior and leaves window sizing on other platforms unchanged.
+
 ### Application icon and window colors
 
 `appDescriptor.native.icon` selects the application's existing app-relative

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.67.0",
+  "sdkVersion": "0.68.0",
   "environment": {
     "runtime": "Node.js for Node entrypoints; browser for browser-only entrypoints",
     "minimumVersion": "22.23.2 for Node entrypoints",
@@ -1891,7 +1891,7 @@
       "summary": "Default binding for the canonical PreferenceStore runtime class in Node and managed browsers.",
       "availability": "Node with injected adapters, or browser/native WebView storage",
       "protocol": "Node ESM / authenticated managed browser import map",
-      "normalization": "Binding identity and namespace come directly from the canonical runtime module"
+      "normalization": "Canonical runtime binding. Default adapter recognizes only exact absent preferences namespace/matching method or existing Android unsupported capability; single operations retry once through existing app-scoped local storage after disposal/cancellation checks, preserving complete values and context. An advertised rejected batch is never retried serially; its original rejection remains before later local operations. Explicit adapters and partial-service/genuine failures retain their behavior."
     },
     {
       "id": "preference-store:PREFERENCE_STORE_ERROR_CODES",
@@ -4318,7 +4318,7 @@
       "summary": "Creates an app-neutral Core dispatcher with explicit services, request lifetimes, events and graceful drain.",
       "availability": "Node on Windows, Linux and macOS native hosts; Android requires its host adaptation",
       "protocol": "arcane/1 dispatcher and service lifecycle",
-      "normalization": "Starts services independently; runtime.getService(name) and context.getService(name) return the same registered object after only its shared startup, without a renderer or global barrier. Lookup is readiness, not a lifetime lease; new lookups reject during shutdown. Preserves complete results/errors, cancels request-lifetime work and drains accepted service work; runtime.replay publishes current dispatcher/service state without restart and preserves reentrant lifecycle publication order"
+      "normalization": "Starts services independently; runtime.getService(name) and context.getService(name) return the same registered object after only its shared startup, without a renderer or global barrier. Lookup is readiness, not a lifetime lease; new lookups reject during shutdown. Preserves complete results/errors, cancels request-lifetime work and drains accepted service work; runtime.replay publishes current dispatcher/service state without restart and preserves reentrant lifecycle publication order. Missing dispatch retains METHOD_NOT_ALLOWED with exact method/namespace and core-namespace-unavailable or core-method-unavailable; named services, registered methods and built-in namespaces establish presence. Handler/startup/permission errors remain unchanged."
     },
     {
       "id": "core-stdio:encodeCoreFrame",

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

@@ -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

@@ -2018,8 +2018,10 @@ Shared dependencies: [`Theme.js`](runtime-entities.md#themejs).
 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.
+both dimensions. Selected buttons retain `aria-pressed`, their selected colors
+and an inset outline while hovered; ordinary hover fill applies only to
+unselected, enabled choices. Disabled choices and keyboard focus have distinct
+presentation.
 
 ### Public surface