arcane-os 0.92.0 → 0.94.0

package/docs/reference/core/arcane-api.md

@@ -49,6 +49,7 @@ This inventory covers every enumerable, non-method member exposed directly or th
 | `Arcane.storage` | Namespace | App-scoped native key/value storage. |
 | `Arcane.preferences` | Namespace | App-scoped preference reads and atomic writes. |
 | `Arcane.window` | Namespace | SDK host window presentation for the calling document; adapter availability is independent of the OS-user appearance service. |
+| `Arcane.notifications` | Namespace | Native app-scoped desktop notifications and retained host-lifetime outcomes; see the [notification contract](../core-client.md#native-desktop-notifications). |
 | `Arcane.appearance` | Namespace | Native appearance state and application. |
 | `Arcane.session` | Namespace | Current Arcane session lifecycle. |
 | `Arcane.provisioning` | Namespace | Provisioning-plan operations. |
@@ -394,6 +395,37 @@ product-neutral reference.
 
 Terminal output and lifecycle changes are event-driven. The canonical [Arcane event inventory](arcane-events.md#event-inventory) defines `terminal.output`, `terminal.exit`, and the Android `terminal.error` payload. The shared `TerminalClient` adapter correlates those deliveries with owned sessions and re-emits DOM events for reusable UI code.
 
+## Native desktop notifications
+
+These methods use the actual application's native window bridge. Windows source
+support is pending selected native build and OS delivery verification. Direct
+shared-Core listeners and other unimplemented host adapters are unavailable;
+there is no browser or audio substitute. The [complete contract](../core-client.md#native-desktop-notifications)
+defines records, cancellation, duplicate IDs, permission reporting and recovery.
+
+| Method | Parameters | Return | Description |
+| --- | --- | --- | --- |
+| `Arcane.notifications.status(options?)` | `options`: standard `signal`, `timeoutMs`, `onRequest` request options | `Promise<{supported,available,permissionDisabled,reason?,error?}>` | Reports actual host support and permission state without changing preferences. Only an exact unavailable Core namespace is normalized, retaining its original complete error. |
+| `Arcane.notifications.show(request, options?)` | `request`: `{id,title,body,data}`; `options`: standard request options | `Promise<NotificationRecord>` | Submits exact title/body and opaque JSON-compatible data for the application's stable ID. Native submission is distinct from visual display or human receipt; a reused ID rejects with the existing record. |
+| `Arcane.notifications.state(selection?, options?)` | `selection`: `{id?}`, defaults to `{}`; `options`: standard request options | `Promise<{revision,notifications:NotificationRecord[]}>` | Returns complete retained records for the current host lifetime. Subscribe to `notifications.state` first and merge by revision. |
+| `Arcane.notifications.close(selection, options?)` | `selection`: `{id}`; `options`: standard request options | `Promise<NotificationRecord>` | Removes the exact owned notice and retains its record; no implicit resend or replacement. |
+
+`NotificationRecord` contains `{id,title,body,data,state,revision}` plus actual
+timestamps, reasons and complete errors. `event` identifies the latest observed
+event and `events` retains its ordered history; activation can race removal
+without changing an already `closed` state. Accepted notices survive renderer
+navigation. Terminal callbacks remain retained; timeout dismissal does not mean
+Notification Center removal. Recipients, triggers, text, deduplication and
+navigation belong to the application. Cross-process persistence and cold-start
+activation are outside this contract.
+
+Windows keeps a stable native identity per WebView profile so the OS retains
+that profile's notification preferences. The SDK persists registration metadata
+only; its notification text/data records remain in host memory. A second
+simultaneous notifier for the same profile reports
+`notification-owner-already-running`; distinct profiles remain independent.
+Live COM ownership and notices drain at host shutdown.
+
 ## Platform, installation, users, and system
 
 | Method | Parameters | Return | Description |

package/docs/reference/core/arcane-events.md

@@ -26,6 +26,31 @@ Every subscription method returns an unsubscribe function. Call it when the owni
 | `terminal.exit` | Live, future-only terminal session notification. | Core-backed Arcane Terminal and Android Arcane Terminal hosts. | A terminal process exits and the host removes its session. | `sessionId` identifies the terminal session; `exitCode` is the process exit code when available; `signal` is the terminating signal name or `null`. |
 | `terminal.error` | Live, future-only terminal session notification. | Android Arcane Terminal hosts. | Android stops a session at its output limit or cannot read one of its output streams. | `sessionId` identifies the terminal session; `message` explains the output-limit or stream-reading failure. |
 | `appearance.changed` | Live, future-only host notification. | Microsoft NT WebView2 hosts. | The host observes an operating-system appearance change. | `scheme` is the configured host scheme; `effectiveScheme` is the resolved `dark` or `light` scheme; `source` is `windows`. |
+| `notifications.state` | Live, future-only complete notification record; retained state is read separately. | SDK Windows application-window adapter; native build and OS delivery verification pending. Other unimplemented hosts and direct shared-Core listeners are unavailable. | An owned native notification changes submission, activation, dismissal, closure or failure state. | Complete `{id,title,body,data,state,revision}` record plus actual timestamps, reasons and errors. Caller `id` correlates the record; `revision` orders updates. Native submission is not a display or human-receipt acknowledgement. |
+
+### Recover native notification state
+
+Subscribe to `notifications.state` before calling `Arcane.notifications.state()`
+and merge each record by revision. The event is not a durable completion event
+for `when()`. A later renderer reads the host's retained records, including
+actual terminal outcomes; accepted notices survive navigation. Retire old-client
+subscriptions and pending snapshots when the installed client changes.
+The record's `event` names its latest observation and `events` retains complete
+ordered history. A raced `event:'activated'` can accompany `state:'closed'`;
+the application decides how to route that actual activation.
+
+Windows profile identity/shortcut registration persists across launches to
+preserve OS preferences; the SDK's notification text, data and event records
+remain in host memory for the current lifetime. A second simultaneous notifier
+for that profile is unavailable with `notification-owner-already-running`;
+other profiles are independent. Shutdown drains owned notices and live COM
+ownership.
+
+`submitted` means native `Show` returned. Later failure remains possible, and a
+timeout dismissal does not establish removal from Notification Center. Explicit
+`Arcane.notifications.close({id})` removes the owned notice while retaining its
+record. See the [complete notification contract](../core-client.md#native-desktop-notifications)
+for cancellation, permissions, exact content and host-lifetime limits.
 
 ### Subscribe and clean up
 

package/docs/reference/core-client.md

@@ -284,6 +284,105 @@ forwards the app's computed `--background` and `--text-color` in native hosts.
 Applications using that owner need no duplicate theme listener. Ordinary
 browsers keep their CSS presentation without making a native request.
 
+## Native desktop notifications
+
+`Arcane.notifications` uses the existing Core request transport to the actual
+application window's native host. The Windows adapter is source implementation;
+selected native build and actual OS delivery verification remain pending. A
+matching published host is required for delivery. The portable facade is the
+same on Windows, Linux and macOS, with Android requiring a host adapter; other
+unimplemented hosts and direct shared-Core listener connections are unavailable.
+Those listener connections bypass the window bridge. There is no browser
+`Notification`, audio or simulated delivery substitute.
+
+| Method | Parameters | Result |
+| --- | --- | --- |
+| `status(options?)` | Request options only | Actual native `supported`, `available` and `permissionDisabled`, with the host's reason/error when present |
+| `show(request, options?)` | `{id,title,body,data}` | Complete notification record for the actual submission outcome |
+| `state(selection = {}, options?)` | Optional `{id}` selects one owned ID; omission selects all retained records | `{revision,notifications:[complete records]}` |
+| `close(selection, options?)` | `{id}` | Complete record after the exact owned notice's removal operation |
+
+Every method accepts the standard `invoke` options `signal`, `timeoutMs` and
+`onRequest({requestId})`. Requests, title/body strings and opaque JSON-compatible
+`data` pass through unchanged. The application owns recipients, triggers, text,
+deduplication and navigation. The OS controls presentation; preserving the
+complete request does not establish that every character was visibly displayed.
+
+`status()` changes no OS permissions or preferences. Only the exact Core error
+`METHOD_NOT_ALLOWED` with `reason:'core-namespace-unavailable'` becomes
+`{supported:false,available:false,permissionDisabled:null,
+reason:'host-notifications-unavailable',error}`; `error` is the original complete
+error and no platform is invented. All other invocation rejections propagate
+unchanged. The native adapter can return an unavailable result with the complete
+OS initialization or settings error. `permissionDisabled:null` means the permission state is
+unknown. Use this status operation to discover the window adapter; Core's
+service capability list does not describe host-intercepted notification methods.
+Native `supported:null` means initialization could not establish OS support;
+`available:false` retains its actual reason and complete error when supplied.
+
+A retained record contains `{id,title,body,data,state,revision}` and the actual
+timestamps, reasons and complete errors supplied by its owner. `submitted` means
+the native `Show` call returned. It does not establish visible display or human
+receipt. Later activation, dismissal and failure remain observable and retained.
+A dismissal due to timeout does not establish removal from Notification Center.
+Use `close({id})` for explicit OS removal. Closing retains the record; showing
+the same caller ID again during this host lifetime rejects with its existing
+record instead of resending or replacing it.
+The top-level `event` names the latest observation, while `events` retains the
+complete ordered history. An activation racing successful removal can report
+`event:'activated'` with `state:'closed'`; the application owns action routing.
+
+The live `notifications.state` event carries one complete updated record. It is
+future-only. Subscribe before requesting the snapshot, then merge records by
+their revisions so a delayed snapshot cannot overwrite a newer event:
+
+```js
+const records = new Map();
+function receiveNotification(record) {
+    const previous = records.get(record.id);
+    if (!previous || record.revision >= previous.revision) records.set(record.id, record);
+}
+const stop = Arcane.events.on('notifications.state', receiveNotification);
+try {
+    const snapshot = await Arcane.notifications.state();
+    for (const record of snapshot.notifications) receiveNotification(record);
+} catch (error) {
+    stop();
+    throw error;
+}
+// Call stop() when this observation ends; it does not remove native notices.
+```
+
+When the installed Core client changes, detach the old event listener and ignore
+its outstanding snapshot response. Recreate the records map for the new
+client/host lifetime so an earlier host's revisions cannot suppress its records.
+Subscribe and read the new client's snapshot
+through [installation observation](#observe-installation-and-retirement).
+Accepted notices and their records survive renderer navigation within the same
+native host. There is no persisted cross-process recovery or cold-process
+activation contract.
+
+Windows reuses an SDK-created native identity and shortcut for the existing
+WebView profile across launches, preserving that profile's OS notification
+preferences. Its owned `AppUserModelId` registration stores the application's
+display name, icon and live activator identity without changing notification
+preferences or registering a cold-start launch command.
+The SDK persists registration metadata only; its notification text
+and data records remain in host memory. OS notification retention remains
+platform-owned.
+Distinct profiles have independent notification settings. One live notifier
+owns a profile's COM activation registration; a second simultaneous host using
+that profile reports `available:false` with
+`reason:'notification-owner-already-running'` and may retry explicitly later.
+Shutdown releases live COM ownership and owned notices while preserving the
+identity registration for a later launch.
+
+Cancellation observed before submission prevents that pending show from
+submitting. After submission, request cancellation or renderer retirement cannot
+reverse human interaction and does not remove the accepted notice; `close` is
+explicit. Host shutdown drains owned operations, removes owned notices and
+detaches callbacks, surfacing complete cleanup errors.
+
 ## Events and request lifetime
 
 `events.on(name, listener)`, `once(name, listener)` and

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

@@ -1,12 +1,12 @@
 {
   "schemaVersion": 1,
-  "sdkVersion": "0.91.0",
+  "sdkVersion": "0.92.0",
   "environment": {
     "runtime": "Node.js for Node entrypoints; browser for browser-only entrypoints",
     "minimumVersion": "22.23.2 for Node entrypoints",
     "moduleSystem": "ESM"
   },
-  "memberCount": 308,
+  "memberCount": 314,
   "runtimeSubpathPatterns": {
     "arcane-os/modules/*": "./runtime/arcane/modules/*",
     "arcane-os/entities/*": "./runtime/arcane/entities/*"
@@ -166,6 +166,90 @@
       "protocol": "arcane/1 service definition",
       "normalization": "Binding identity equals the named createNativeDecisionService export"
     },
+    {
+      "id": "local-ai-kokoro:createNativeKokoroRuntime",
+      "name": "createNativeKokoroRuntime",
+      "displayName": "createNativeKokoroRuntime()",
+      "kind": "function",
+      "signature": "createNativeKokoroRuntime({onnx,modelAssets,runtime,prepare,modelId='kokoro',model=KOKORO_MODEL,revision=KOKORO_REVISION,dtype='fp32',paths,assetProjectionId,resourcePaths,sessionOptions,executionPreference='gpu',executionTarget,signal,onEvent}={})",
+      "entrypoints": ["arcane-os/local-ai/kokoro"],
+      "primaryImport": "arcane-os/local-ai/kokoro",
+      "group": "Core native speech",
+      "summary": "Composes the selected Kokoro FP32 graph with the host's existing ONNX/model-resource owners and a persistent native phonemization/Opus helper.",
+      "availability": "Node with matching prepared helper/data and ONNX resources; SDK helper archive for Windows x64, other hosts require a matching custom helper distribution",
+      "protocol": "Replaying kokoro.state, retained ONNX activation and complete ordered native speech requests",
+      "normalization": "Returns current/subscribe/load/synthesize/unload/close; construction performs no preparation or inference. Explicit load selects a DBOPFS projection or complete native resource paths; synthesis retains complete ordered input, selected US/GB voice and 24kHz mono WAV or Ogg Opus output. Active cancellation joins owned helper/session retirement and preserves surviving queued work on the same configured provider; ONNX native interruption may wait for the current call. No alternate model, voice or provider retry is introduced. See native-speech.md for exact activation, selection and result contracts."
+    },
+    {
+      "id": "local-ai-kokoro:default",
+      "name": "default",
+      "displayName": "createNativeKokoroRuntime default export",
+      "kind": "function",
+      "signature": "default as createNativeKokoroRuntime",
+      "entrypoints": ["arcane-os/local-ai/kokoro"],
+      "primaryImport": "arcane-os/local-ai/kokoro",
+      "group": "Core native speech",
+      "summary": "Default binding for the same native Kokoro engine factory.",
+      "availability": "Node with matching prepared native resources",
+      "protocol": "Native Kokoro engine lifecycle",
+      "normalization": "Binding identity equals the named createNativeKokoroRuntime export"
+    },
+    {
+      "id": "local-ai-kokoro:KOKORO_MODEL",
+      "name": "KOKORO_MODEL",
+      "displayName": "KOKORO_MODEL",
+      "kind": "constant",
+      "signature": "const KOKORO_MODEL",
+      "entrypoints": ["arcane-os/local-ai/kokoro"],
+      "primaryImport": "arcane-os/local-ai/kokoro",
+      "group": "Core native speech",
+      "summary": "Identifies the Kokoro model implemented by the native frontend.",
+      "availability": "Node",
+      "protocol": "Native model selection",
+      "normalization": "Value is onnx-community/Kokoro-82M-v1.0-ONNX; constructor selection preserves this model's FP32 graph and resource contract"
+    },
+    {
+      "id": "local-ai-kokoro:KOKORO_REVISION",
+      "name": "KOKORO_REVISION",
+      "displayName": "KOKORO_REVISION",
+      "kind": "constant",
+      "signature": "const KOKORO_REVISION",
+      "entrypoints": ["arcane-os/local-ai/kokoro"],
+      "primaryImport": "arcane-os/local-ai/kokoro",
+      "group": "Core native speech",
+      "summary": "Identifies the selected upstream Kokoro model revision.",
+      "availability": "Node",
+      "protocol": "Native model resource selection",
+      "normalization": "Value is 1939ad2a8e416c0acfeecc08a694d14ef25f2231; graph, tokenizer and voice resources use this same revision"
+    },
+    {
+      "id": "local-ai-kokoro:KOKORO_SAMPLE_RATE",
+      "name": "KOKORO_SAMPLE_RATE",
+      "displayName": "KOKORO_SAMPLE_RATE",
+      "kind": "constant",
+      "signature": "const KOKORO_SAMPLE_RATE",
+      "entrypoints": ["arcane-os/local-ai/kokoro"],
+      "primaryImport": "arcane-os/local-ai/kokoro",
+      "group": "Core native speech",
+      "summary": "Native Kokoro PCM synthesis rate in samples per second.",
+      "availability": "Node",
+      "protocol": "Audio format",
+      "normalization": "Value is 24000; the selected output is mono WAV or Ogg Opus with the complete synthesized sample sequence"
+    },
+    {
+      "id": "local-ai-kokoro:KOKORO_VOICES",
+      "name": "KOKORO_VOICES",
+      "displayName": "KOKORO_VOICES",
+      "kind": "constant",
+      "signature": "const KOKORO_VOICES",
+      "entrypoints": ["arcane-os/local-ai/kokoro"],
+      "primaryImport": "arcane-os/local-ai/kokoro",
+      "group": "Core native speech",
+      "summary": "The 28 supported US and British English voice identifiers for the selected native Kokoro resources.",
+      "availability": "Node",
+      "protocol": "Native speech voice selection",
+      "normalization": "Complete ordered voice array exported by the frontend; af_heart is the omitted voice default. An unsupported explicit voice reports its actual incompatibility without substitution."
+    },
     {
       "id": "local-ai-whisper:createWhisperRuntime",
       "name": "createWhisperRuntime",
@@ -345,8 +429,8 @@
       "group": "Core native speech",
       "summary": "Composes host-supplied transcription and synthesis engines with independent loading and role readiness.",
       "availability": "Node Core with explicitly supplied engines; engine platform, model and format support remain engine-owned",
-      "protocol": "arcane/1 speech.status/transcribe/synthesize with speech.state/progress",
-      "normalization": "Returns current/subscribe/close/start/methods/drain/dispose; forwards complete requests and results unchanged; replaying service state, synchronous accepted Thinking, combined request/lifetime cancellation and concurrent joined engine shutdown; no engine installation or automatic provider selection"
+      "protocol": "arcane/1 speech.status/load/unload/transcribe/synthesize with speech.state/progress",
+      "normalization": "Returns current/subscribe/close/start/methods/drain/dispose; forwards complete requests and results unchanged; replaying service state, synchronous accepted Thinking, combined request/lifetime cancellation and concurrent joined engine shutdown. Explicit load/unload require role stt or tts and forward the remaining activation fields and complete result through that role's configured engine; supported preparation remains with that engine. Startup waiting is independently owned from caller cancellation; no automatic provider selection is introduced."
     },
     {
       "id": "core-speech:default",
@@ -609,10 +693,10 @@
       "entrypoints": ["arcane-os/local-ai"],
       "primaryImport": "arcane-os/local-ai",
       "group": "Core local AI",
-      "summary": "Reuses selected managed native runtimes or installs complete llama.cpp/Ollama/image distributions, ONNX npm runtime trees with selected SDK native libraries, or NeMo libraries.",
+      "summary": "Reuses selected managed native runtimes or installs complete llama.cpp/Ollama/image distributions, ONNX npm runtime trees with selected SDK native libraries, NeMo libraries, or Kokoro native helper/data trees.",
       "availability": "Node; selected distribution platform and architecture assets determine runtime availability",
       "protocol": "Upstream release archives and selected ONNX/Koffi npm installations; corrected Windows x64 ONNX native libraries from the installed SDK numeric release",
-      "normalization": "Returns absolute runtime records, including image library/binding/variant/model metadata; Windows x64 ONNX with no explicit URL and omitted version or 1.30.0 adds nativeDistributionRevision 1.30.0-directml-reshape-1, reuses that revision or prepares a fresh installation while preserving older trees; explicit URLs and other ONNX versions/platforms retain their upstream package path; shares matching installs, preserves libraries, reports failures without changing global PATH or services and prepares no model files"
+      "normalization": "Returns absolute runtime records, including image library/binding/variant/model metadata; Windows x64 ONNX with no explicit URL and omitted version or 1.30.0 adds nativeDistributionRevision 1.30.0-directml-reshape-1, reuses that revision or prepares a fresh installation while preserving older trees; explicit URLs and other ONNX versions/platforms retain their upstream package path; shares matching installs, preserves libraries, reports failures without changing global PATH or services and prepares no model files. Kokoro returns helperExecutable, espeakDataDirectory and libraryDirectory for the complete selected helper tree; Windows x64 defaults to the installed SDK numeric release, while explicit url/helperRoot supplies another prepared distribution and preserves model/ONNX ownership."
     },
     {
       "id": "local-ai:bundleLocalAIRuntimes",
@@ -626,7 +710,7 @@
       "summary": "Copies selected complete runtime distributions into a fresh native artifact staging root.",
       "availability": "Node; supports bundling selected published platform assets independently of the build host",
       "protocol": "Artifact-relative runtime/local-ai layout",
-      "normalization": "Returns {runtimes,files} with artifact-relative runtime/variant paths and complete inventory; corrected Windows x64 ONNX retains nativeDistributionRevision and complete native libraries while modulePath becomes artifact-relative; image URL descriptors remain for post-launch preparation and external model working paths report portability incompatibility"
+      "normalization": "Returns {runtimes,files} with artifact-relative runtime/variant paths and complete inventory; corrected Windows x64 ONNX retains nativeDistributionRevision and complete native libraries while modulePath becomes artifact-relative; image URL descriptors remain for post-launch preparation and external model working paths report portability incompatibility. Kokoro retains the complete helper/data tree and relocates helperExecutable, espeakDataDirectory and libraryDirectory; ONNX and model resources retain their separate owners."
     },
     {
       "id": "root:WS",
@@ -4122,7 +4206,7 @@
       "summary": "Sends one complete TWiN Cloud request with an explicit caller-owned key and model.",
       "availability": "Node and Browser; remote HTTPS provider",
       "protocol": "TWiN Cloud complete-response chat",
-      "normalization": "Preserves complete messages and parsed provider JSON; maps explicit structured-output, tool, and reasoning options; shares overload-only HTTP 429 retry after 3000 ms and cancellation; retains no browser profile, storage, or request history"
+      "normalization": "Preserves complete messages and provider JSON; Fetch rejection and all HTTP 429/529 share three retries; quota recovery honors Retry-After or exponential delay with transient same-endpoint/credential pacing, complete terminal errors and cancellation; retains no browser profile, storage, or history"
     },
     {
       "id": "twin-cloud:fetchSystemOneRequest",
@@ -4171,21 +4255,21 @@
       "name": "fetchHTTPResponse",
       "displayName": "fetchHTTPResponse()",
       "kind": "function",
-      "signature": "async fetchHTTPResponse(url,options)",
+      "signature": "async fetchHTTPResponse(url,options,{onRetry=null}={})",
       "entrypoints": ["arcane-os/ai/twin-cloud"],
       "primaryImport": "arcane-os/ai/twin-cloud",
       "group": "Shared AI transport integration",
       "summary": "Returns a successful unconsumed Fetch Response through the shared AI HTTP owner.",
       "availability": "Node and Browser",
       "protocol": "Shared AI HTTP transport",
-      "normalization": "Preserves caller Fetch options and complete error bodies; repeats only overload HTTP 429 after 3000 ms; signal cancellation uses ARCANE_AI_REQUEST_ABORTED"
+      "normalization": "Preserves caller Fetch options and complete errors; Fetch rejection and all HTTP 429/529 share three retries; Retry-After or exponential quota delay and transient same-endpoint/credential pacing remain abortable; onRetry observes waiting/requesting; cancellation uses ARCANE_AI_REQUEST_ABORTED"
     },
     {
       "id": "twin-cloud:fetchJSONResponse",
       "name": "fetchJSONResponse",
       "displayName": "fetchJSONResponse()",
       "kind": "function",
-      "signature": "async fetchJSONResponse(url,options)",
+      "signature": "async fetchJSONResponse(url,options,{onRetry=null}={})",
       "entrypoints": ["arcane-os/ai/twin-cloud"],
       "primaryImport": "arcane-os/ai/twin-cloud",
       "group": "Shared AI transport integration",
@@ -4304,7 +4388,7 @@
       "summary": "Describes existing Core method input, output and semantic shapes.",
       "availability": "Node and browser/bundler",
       "protocol": "arcane/1 method descriptions",
-      "normalization": "Descriptive data only, including independent localai.devices inventory and localai.resolveTarget physical-selection records; presence does not establish engine support or observed execution. The active host and its registered services remain the authority for method availability"
+      "normalization": "Descriptive data only, including independent localai.devices inventory and localai.resolveTarget physical-selection records; presence does not establish engine support or observed execution. Native notifications.status/show/state/close describe actual host support, exact caller content, retained host-lifetime outcomes and explicit owned removal; native submission does not establish display or human receipt. The active host and its registered services remain the authority for method availability"
     },
     {
       "id": "core-contracts:CoreError",
@@ -4360,7 +4444,7 @@
       "summary": "Projects a Core client into the established application-facing Arcane namespace.",
       "availability": "Browser and native WebView JavaScript hosts with a Core client",
       "protocol": "arcane/1 compatibility facade",
-      "normalization": "Routes namespace methods through client.invoke while retaining operation-specific parameters, correlation, streaming callbacks, timeouts and cancellation; window.state({signal}?) reads the requesting window and window.setState({state},{signal}?) selects normal, maximized or fullscreen. The matching Windows host returns {platform:'windows',supported:true,state}, including observed minimized state, restores normal bounds/frame controls on leaving fullscreen and prevents activation/focus assignment during visible state transitions without changing TopMost, Core, origin or profile. Saved Settings remain application-owned; cancellation does not undo an applied change and unavailable hosts retain their actual errors without fallback. window.setTheme(presentation,{signal}?) forwards the complete per-window backgroundColor/textColor record, with omitted fields unchanged and null reset, and returns the host's actual applied/unsupported result without changing system appearance"
+      "normalization": "Routes namespace methods through client.invoke while retaining operation-specific parameters, correlation, streaming callbacks, timeouts and cancellation; window.state({signal}?) reads the requesting window and window.setState({state},{signal}?) selects normal, maximized or fullscreen. The matching Windows host returns {platform:'windows',supported:true,state}, including observed minimized state, restores normal bounds/frame controls on leaving fullscreen and prevents activation/focus assignment during visible state transitions without changing TopMost, Core, origin or profile. Saved Settings remain application-owned; cancellation does not undo an applied change and unavailable hosts retain their actual errors without fallback. window.setTheme(presentation,{signal}?) forwards the complete per-window backgroundColor/textColor record, with omitted fields unchanged and null reset, and returns the host's actual applied/unsupported result without changing system appearance. notifications.status/show/state/close forward complete caller requests and standard invoke options; status normalizes only METHOD_NOT_ALLOWED with core-namespace-unavailable while retaining the complete original error. Matching native window hosts retain complete notification records and ordered revisions across renderer navigation, with notifications.state events and subscribe-before-snapshot recovery. Submitted means native Show returned, not displayed or read; cancellation after submission does not remove an accepted notice, and explicit close retains its record. Recipient, text, trigger, deduplication and navigation policy remains application-owned. speech.load(request,options) and speech.unload(request,options) forward complete activation requests, cancellation and request observers with no elapsed-time cutoff; selected engines own preparation and native retirement."
     },
     {
       "id": "core-client:installCoreClient",

package/docs/reference/local-ai.md

@@ -1,13 +1,16 @@
 # Local AI through Core
 
 Core owns native llama.cpp and Ollama processes, ONNX worker sessions,
-selected local image generation and retained Whisper transcription. The browser retains its own
+selected local image generation, retained Whisper transcription and native
+Kokoro synthesis. The browser retains its own
 Wllama and ONNX implementations, and can also use an explicitly connected Core
 when that system service is available. Runtime installation, model loading and
 inference are separate operations.
 
 Native ONNX runs caller-selected graphs with complete named input/output tensors.
-Applications own preprocessing, tokenization and model-specific pipelines.
+Applications own preprocessing, tokenization and model-specific pipelines unless
+they explicitly select an SDK engine such as native Kokoro, which owns its
+versioned speech frontend.
 Browser ONNX continues through its existing browser implementation.
 
 ## Application requirements
@@ -113,6 +116,71 @@ the SDK does not guess a companion location. Installation records distinguish
 the distribution's `backend` from its `requestedBackend` execution mode.
 Selecting an unavailable distribution reports its actual error.
 
+### Native Kokoro selection
+
+Select both the existing ONNX runtime and the native speech helper:
+
+```json
+{
+  "runtimes": [
+    {"id": "onnx"},
+    {"id": "kokoro-native", "modelId": "kokoro"}
+  ]
+}
+```
+
+`kokoro-native` is the installable helper ID, `kokoro-onnx` is the speech
+provider ID, and `kokoro` is the default model alias. The requirement also
+preserves `model`, `revision`, `dtype`, prepared `paths`, `assetProjectionId`,
+`resourcePaths`, `sessionOptions`, `executionPreference` and `executionTarget`
+for the engine. The implemented model/revision, complete resource mapping,
+voices, synthesis formats and cancellation contract are in
+[native speech](native-speech.md#native-kokoro-engine).
+
+With no `helperRoot` or `url`, Windows x64 preparation selects
+`arcane-kokoro-windows-x64.tar.gz` from the installed SDK's numeric release:
+`https://github.com/TheWizardNexus/arcane-os-sdk/releases/download/<sdk-version>/arcane-kokoro-windows-x64.tar.gz`.
+That SDK version selects the default helper release; an authored runtime
+`version` alone does not select another SDK release's helper.
+An explicit `url` selects a complete platform-matching archive, with optional
+`version` metadata. Alternatively, `helperRoot` supplies an already prepared
+complete tree copied into the new installation. Select one of these sources.
+Linux and macOS currently require that explicit archive or prepared tree;
+the native CMake source is available, with no claim of an exercised helper
+build on those platforms.
+
+The helper record accepts `helperExecutable`, `espeakDataDirectory` and
+`libraryDirectory` overrides within the selected tree. Defaults are
+`bin/arcane-kokoro.exe` on Windows (`bin/arcane-kokoro` elsewhere), `share`, and
+`bin`. The data field identifies the parent containing `espeak-ng-data`.
+Overrides are relative to the selected tree or absolute locations inside
+`helperRoot`; all three paths relocate with that complete tree. Installation
+prepares the helper and its matching data, independently of ONNX and without
+downloading model weights, tokenizer files or voices.
+
+Development and generated native composition register this engine as the TTS
+role of `createSpeechService`, sharing the existing model-assets service and
+the selected local-ai ONNX owner. Whisper, when selected, retains the separate
+STT role and device choice. Construction and no-assets startup leave Kokoro
+unloaded without helper preparation. An explicit activation with prepared
+resources acquires the helper in development and waits only for that existing
+ONNX owner. Native packaging has already bundled the helper. These waits stay
+inside speech activation; page rendering and independent services continue.
+Omitting the explicit `onnx` requirement reports unavailability on activation.
+After an explicit `localai.services.recover({runtimes: ['onnx']})` completes,
+the next explicit `speech.load({role: 'tts', ...selection})` reacquires the
+current ONNX owner through existing preparation, after prior activation cleanup.
+
+For saved browser assets, prepare the complete projection through the existing
+[`model-assets` owner](model-assets.md), then call
+`Arcane.speech.load({role: 'tts', modelId: 'kokoro', assetProjectionId,
+resourcePaths, executionTarget}, {signal})`. Core retains the incoming
+projection before replacing its activation and releases it only after native
+exit. Preparing/loading a model remains separate from installing the helper.
+Raw constructor `paths` are caller-prepared native paths; portable assembly
+does not turn external model paths or a prior process's projection ID into
+packaged resources. Prepare the intended model resources at their actual host.
+
 ## Development
 
 ```sh
@@ -125,6 +193,8 @@ configuration. Subsequent `arcane dev` runs reuse the saved requirements.
 application selects its `models` in the runtime record before requesting a
 load or generation. The development owner composes separate image and
 model-assets services alongside the existing chat/ONNX service.
+`--local-ai onnx,kokoro-native` records the native TTS requirements above;
+its model activation remains explicit when no assets are configured.
 Development checks selected endpoints and existing executable paths, then
 installs missing runtimes under the application's `.arcane/local-ai/runtimes`.
 Runtime preparation runs alongside HTTP serving. Browser rendering continues
@@ -174,8 +244,8 @@ processes. An already running external service remains running.
 handle with `ready`, `current()`, `handler()` and `close()`. Its `ready` promise
 means Core composition has started, not that installation or a selected model
 is ready. Runtime preparation continues at each owning service. `current()`
-includes separate `core`, `localAI` and optional `image` state; image status
-remains callable during preparation. Composition failures reject `ready`;
+includes separate `core`, `localAI` and optional `image` and `speech` state;
+image status remains callable during preparation. Composition failures reject `ready`;
 later service preparation failures remain on Core lifecycle and diagnostic
 events. Page rendering waits for neither.
 
@@ -227,7 +297,8 @@ 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.
+one shared model-assets service when ONNX, llama.cpp, image generation or
+native Kokoro 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
@@ -757,6 +828,11 @@ retains that metadata with the complete native libraries. Image records include
 `libraryPath`,
 `bindingModulePath`, requested `backend`, installed `variants` and selected
 `models` metadata. Variant records carry backend, runtime root and library path.
+Kokoro records include `helperExecutable`, `espeakDataDirectory` and
+`libraryDirectory`; bundling preserves the complete helper tree under
+`runtime/local-ai/kokoro-native` and makes all three paths artifact-relative.
+The generated entry resolves them on the destination host and obtains the
+existing ONNX owner when the selected TTS activation needs it.
 Bundle returns `{runtimes,files}`,
 with artifact-relative runtime paths and a complete emitted file inventory.
 Bundling requires a fresh native staging destination, preserving existing