arcane-os 0.51.0 → 0.51.2

package/docs/reference/availability-and-normalization.md

@@ -71,17 +71,22 @@ version; WebKitGTK availability must not be generalized to macOS.
 | Build browser UI and app-local behavior | `/arcane/modules/*.js`, shared entities, and components | **Browser**; many modules also run inside every native renderer | Pure modules own their result contracts. Modules that call `Arcane` inherit the bridge boundary described below. |
 | Select and observe independent LLM/STT/TTS roles | `/arcane/modules/AIProviderRuntime.js` and `AIRuntimeState.js` | **Cross-host** controller/state; registered providers retain their own host requirements | Required/projected provider members, route/configuration records, and status fields; per-role lifecycle, cancellation, stream cleanup, sticky state, and startup barriers are normalized. `localOnly` creates no fallback. |
 | Run a caller-selected local LLM entirely in a browser renderer | `arcane-os/ai/browser-wasm` through `createArcaneAI()` | **Browser** only; secure context, WebAssembly, and OPFS/DBOPFS; full WebGPU offload by default or explicit CPU with `gpuLayers:0` | The public AI API module normalizes multi-model lifecycle, status, complete all-choice streaming, cancellation, exact ordered structural tool-call visibility, and session persistence. Model sources are canonical ordered file descriptors; licenses and model choice remain application policy. |
-| Run caller-selected Whisper or Kokoro in a browser renderer | `arcane-os/ai/browser-speech` registered with `AIProviderRuntime` | **Browser** only; DBOPFS, Web Locks, Workers, Fetch/object URLs, and a caller-supplied self-contained runtime/model closure are required | STT/TTS use independent provider/2 lifecycle and status. Kokoro adds bounded Worker/session concurrency and explicit `auto`, `webgpu`, or `wasm` execution. Complete model/runtime selection, offline behavior, cancellation, Worker teardown, and request/result shapes are normalized. No runtime/model content or cloud fallback is supplied. |
+| Run caller-selected Whisper or Kokoro in a browser renderer | `arcane-os/ai/browser-speech` registered with `AIProviderRuntime` | **Browser** only; DBOPFS, Web Locks, Workers, Fetch/object URLs, and a caller-supplied self-contained runtime/model closure are required | Independent provider/2 lifecycle and status, with `auto`, `webnn-npu`, `webgpu`, or `wasm` execution. Whisper owns one Worker/session; Kokoro defaults to four and accepts one through four. Complete model/runtime selection, offline behavior, cancellation, Worker teardown, and request/result shapes are normalized. No runtime/model content or cloud fallback is supplied. |
 | Capture speech with the explicitly selected native browser service | `createBrowserSpeechRecognitionProvider` from `arcane-os/ai/browser-speech`, configured as STT | **Browser / native WebView**, conditional on `SpeechRecognition` or `webkitSpeechRecognition`; no SDK model, Worker, or storage required | `localOnly:false` because the browser may use a remote service. Factory/catalog remain usable without native support; inspect/load report availability. User-gesture start, exact final results, transient interim text, stop/drain and abort are owned by the provider/runtime and shared controls. No provider fallback. |
-| Prepare ordered speech playback or reuse the speech-input formatting filter | `arcane-os/speech-playback` and `arcane-os/speech-text` | **Node** with injected media adapters, or **Browser / Native WebView** media; the text filter itself is **Cross-host** | Stored and caller-owned text stays exact. Only the outbound synthesis copy automatically loses repeated same formatting marks. A capacity-advertising provider receives complete segments immediately while retaining indexed playback; native/custom synthesis stays serialized. |
-| Preserve complete chat history and memory | `/arcane/modules/PersistentAIChatSession.js` | **Browser / native WebView** with ChatEntity/DBOPFS and a configured chat function | Existing DBOPFS names and memory semantics are preserved. Live-context commit is atomic; durable persistence is explicit and coherent across user/assistant turns and atomic all-ID tool-result batches. |
+| Speak with the explicitly selected browser voice service | `createBrowserSpeechSynthesisProvider` from `arcane-os/ai/browser-speech`, configured as TTS | **Browser / native WebView**, conditional on `speechSynthesis` and `SpeechSynthesisUtterance` | `localOnly:false`; actual voice metadata and a replaying catalog subscription, synchronous `setDefaultVoice(voiceURI\|null)`, silent preparation, and explicit playback controls. Native completion and resource release are distinct. Native speech provides playback descriptors; exporting audio requires a provider that returns real audio. |
+| Prepare ordered speech playback or reuse the speech-input formatting filter | `arcane-os/speech-playback`, `AI.prepareTTSPlayback`, and `arcane-os/speech-text` | **Node** with injected media adapters, or **Browser / native WebView** media; the text filter itself is **Cross-host** | Stored and caller-owned text stays exact. Only the outbound synthesis copy loses repeated same formatting marks. Complete Blob segments or inert native descriptors keep their original order. Provider capacity owns synthesis admission; actual native release controls when the playback lane is free. |
+| Compose editable speech drafts and print a conversation | Shared [`chat.html`](runtime-components.md#chathtml) | **Browser / native WebView** with the selected AI/speech runtime | `transcriptionMode='draft'` places confirmed and interim recognition in the editable composer for manual Send. `appendDraft(text)` preserves existing text and selection. `print()` requests the complete rendered conversation with optional `printTitle`; a successful return confirms the dialog request only. |
+| Preserve complete chat history and memory | `/arcane/modules/PersistentAIChatSession.js` | **Browser / native WebView** with ChatEntity/DBOPFS and a configured chat function | Live-context commit is atomic; new durable records contain complete visible content and timestamps with optional application display metadata. Per-turn `persist:false` and entity-wide `persist=false` keep the operation's input and response outside retained context, transcript, memory, and DBOPFS. Existing saved records remain unchanged. |
+| Store and display images referenced by Markdown | `/arcane/modules/MarkdownMedia.js` and shared Markdown views | **Browser / native WebView** with application-owned DBOPFS storage | Complete image records stay in the selected table; raw Markdown holds stable `arcane-media:` references. Hydration owns temporary display URLs, cancellation, per-image errors, and print-resource retention. Pure record decoding performs no storage or network work. |
+| Print rendered editor content or file previews | `/arcane/modules/PrintView.js`, editor `print()`, and file/history `printPreview()` | **Browser / native WebView** with DOM and browser printing | Complete current rendered content, fonts, and resolved media are captured for print. Explicit requests await view preparation; native Print captures synchronously. Shared `print.css` supplies a light paper palette and one-inch margins; snapshots stay owned through `afterprint`. |
 | Search an app-owned document corpus for explicit chat context | `/arcane/modules/DBOPFSDocumentLibrary.js` | **Browser** or compatible injected DBOPFS adapter | Generation/manifest completion, complete lexical search, partial read failures, and untrusted context labels are normalized. Construction does not search; an explicitly wired context builder performs retrieval for each prepared chat send. |
 | Read host identity, capabilities, storage, preferences, appearance, or platform state | `globalThis.Arcane` | **Cross-host** where the method is implemented and admitted | Promise behavior and `Arcane.Error` are normalized. Result fields are normalized unless the method explicitly documents a platform-dependent snapshot. |
 | Use local AI without coupling app code to Ollama HTTP | `Arcane.localAI`, `Arcane.ai`, or `/arcane/modules/Ollama.js` | Primarily **Native**; Android exposes a narrower admitted inference projection | Admission, errors, and managed-operation events are normalized. Direct Ollama response envelopes remain **Provider-native**. |
 | Use TWiN Cloud from the renderer profile | `/arcane/modules/AI.js` | **Cloud** from an allowed browser/native renderer | High-level chat behavior is normalized by the module. The TWiN access key authenticates remote LLM chat; raw provider diagnostics remain provider-specific. No automatic cloud fallback is inferred from local failure. |
 | Send one TWiN Cloud request with an explicit key and model | `fetchRequest` from `arcane-os/ai/twin-cloud` | **Node** and **Browser**, using standard Fetch and a remote HTTPS provider | Keeps complete messages and returns the full parsed provider JSON. Rejected Fetch and HTTP 529 share three retries after 3000 ms; HTTP 429 overload retains unlimited three-second retries. Optional `onRetry` reports waiting/requesting phases without blocking recovery. Shared structured-output mapping and cancellation match browser TWiN transport. No browser profile, AI/user singleton, DBOPFS, or retained request history is created. |
 | Evaluate caller-owned state and questions with TWiN System One | `fetchSystemOneRequest` from `arcane-os/ai/twin-cloud` | **Node** and **Browser**, using standard Fetch and a remote HTTPS provider | Posts the explicit model and complete state/questions through the existing JSON transport. Returns the entire parsed provider result and shares its retry, diagnostic, and cancellation behavior. Model choice, question definitions, answer interpretation, and scoring policy stay with the caller; no conversation state is retained. |
-| Use speech through one application helper | `/arcane/modules/AI.js` and `Arcane.speech` | **Browser** or **Native** | Whisper and Kokoro keep their on-device paths; explicitly selected Web Speech STT and TWiN Cloud TTS declare their non-local behavior. The helper automatically cleans only the outbound synthesis-input copy and normalizes application-facing audio/text behavior while request/response plumbing differs below that boundary. |
+| Generate images from a complete caller-owned prompt | `generateImages` from `arcane-os/ai/twin-cloud` | **Node** and **Browser**, using standard Fetch, Blob, and a remote HTTPS provider | Caller selects `fal-ai/flux/schnell` or `stable-diffusion-3.5-large`, credentials, and provider parameters. Returns every image as a Blob with media metadata in provider order; owns progress, job polling, and cancellation. Submission is not automatically replayed after an ambiguous failure. Display and storage stay application-owned. |
+| Use speech through one application helper | `/arcane/modules/AI.js` and `Arcane.speech` | **Browser** or **Native** | Whisper and Kokoro keep their on-device paths; explicitly selected Web Speech STT/TTS and TWiN Cloud TTS declare their non-local behavior. `prepareTTSPlayback` supports real audio and silent native descriptors; `fetchTTS` and durable `prepareTTS` require real audio. Provider choice, model, voice, and credentials stay application-owned. |
 | Inspect or manage raw Ollama models | `Arcane.ollama` or `/arcane/modules/Ollama.js` | **Native** desktop Core for management; narrower Android inference only | Wrapper method names, errors, streaming correlation, and admission are Arcane-controlled. Direct Ollama success envelopes are intentionally provider-native. |
 | Use native terminal, installation, user, provisioning, or machine controls | matching `Arcane.*` namespace | **Native** and app/capability restricted | Calls and errors use the common bridge contract. Platform results can be host-specific and are marked in the method guide. |
 
@@ -189,18 +194,22 @@ status, and error state. The SDK supplies neither speech adapter runtime nor
 model/voice content; every selected file is application-owned and stored
 through the SDK-created DBOPFS adapter.
 
-Kokoro defaults to `{device:'auto',maxConcurrentRequests:4}`. Automatic
-selection attempts the complete Worker/session pool on WebGPU when exposed and
-recreates the complete pool on WASM if WebGPU loading rejects. Explicit
-`webgpu` or `wasm` disables that fallback. Each accepted synthesis owns one
-pool slot, and provider-neutral FIFO backpressure preserves later requests.
-Whisper remains one WASM Worker.
+Both speech roles default to `device:'auto'`: try `webnn-npu` when
+`navigator.ml.createContext` exists, then exposed WebGPU, then WASM. A failed
+backend load releases its Worker/session pool before a fresh pool tries the
+same prepared model and precision on the next backend. Explicit `webnn-npu`,
+`webgpu`, or `wasm` selects only that backend. Whisper accepts exactly one
+Worker/session. Kokoro defaults to `maxConcurrentRequests:4` and accepts one
+through four; its FIFO queue preserves later requests while those slots are
+occupied.
 
 For high-level speech, read
-`ai.providerRuntime.status('tts', {execution:true}).execution` after load.
-Kokoro reports `requestedDevice`, `selectedDevice`, `maxConcurrentRequests`,
-and `activeRequestCount`; requested `auto` with selected `wasm` identifies
-fallback. `selectedDevice` is `null` while unloaded. The default `status()`
+`ai.providerRuntime.status(role, {execution:true}).execution` for `stt` or `tts`
+after load. Both report `requestedDevice`, `selectedDevice`,
+`maxConcurrentRequests`, and `activeRequestCount`. `selectedDevice` is `null`
+while unloaded and identifies the successful session backend after load.
+WebNN may use WASM for unsupported operations, so that field does not establish
+that every operation ran on a physical NPU. The default `status()`
 remains the sticky lifecycle snapshot; execution is an explicit provider read,
 and inspection errors propagate. Neither state proves physical GPU kernel
 overlap. See the [copyable speech quick start](ai/browser-speech.md).
@@ -215,12 +224,14 @@ The projected [`AIProviderRuntime`](runtime-modules.md#aiproviderruntimejs)
 normalizes those browser providers and can admit an externally supplied native
 or cloud provider/2 adapter. `AI.js` also supplies built-in adapters for
 an already-selected TWiN Cloud LLM route, Ollama route, or admitted local Core
-speech route. Its built-in audio selections are on-device only: saved `OPENAI`
-speech selections migrate to `LOCAL_SPEACH` with `whisper-small` for STT and
-`kokoro` for TTS. The SDK publishes no privileged Core implementation,
-credential,
-model, or speech-runtime authority, and those adapters never probe, select,
-download, or fall back. The sticky
+speech route. Application-selected Web Speech recognition, Web Speech
+synthesis, and TWiN Cloud/FAL synthesis can be registered through
+`ai.configureSpeechProvider(role,provider,{modelId})`; configuration owns only
+the selected role and performs no network request. Saved selections remain
+application-owned, including selections waiting for provider registration.
+The SDK publishes no privileged Core implementation, credential, model, or
+speech-runtime authority. Capability-only built-in adapters report their
+existing routes without probing, downloading, or changing providers. The sticky
 [`AIRuntimeState`](runtime-modules.md#airuntimestatejs) surface keeps
 application UI independent of transport. A selected route remains explicit:
 browser failure is not permission to invoke Core or cloud.

package/docs/reference/cli.md

@@ -47,6 +47,8 @@ meaning and cardinality rules:
 | `--display-name` | string | `new`, `init` |
 | `--workspace` | directory | Commands that select an external or integrated workspace; defaults to `.`. |
 | `--app` | app id or label | Workspace/app operations except shared scope and `verify-bundle`; optional diagnostic label for `mail serve`. |
+| `--apps-root` | `.` or `apps` | `new`, `init`; standalone setup defaults to the repository root. |
+| `--sdk-runtime-source` | SDK checkout directory | `dev` only; maps live SDK source through the selected browser destinations for that server process. |
 | `--arcane-root` | directory | `doctor`, native `build`/`run`, `native-doctor`, `native-prepare` |
 | `--host` / `--port` | host / integer 0–65535 | Browser `dev`/`run` default to HTTPS at `127.0.0.1:8000`; `mail serve` defaults to HTTPS with HTTP/2 at `0.0.0.0:4433` and accepts an explicit bind host. |
 | `--http-port` | integer 0–65535 | Browser `dev`/`run` HTTP redirect listener; defaults to `0`, which selects an available port. |
@@ -198,8 +200,8 @@ npm exec -- arcane doctor --workspace . --arcane-root "../Arcane OS"
 Refreshes one selected application's browser runtime map, generates
 its standard browser import map, discovers every directly navigable
 `.html`/`.htm` document admitted by the selected descriptor's existing
-include/exclude rules, and commits the map artifact plus those managed documents
-as one transactional refresh. A directly navigable entry document declares exactly
+include/exclude rules, and prepares the map artifact plus those managed documents
+before writing them in order. A directly navigable entry document declares exactly
 one `<meta name="arcane-app-id" content="<selected-id>">`; an unmarked secondary
 document may instead carry an active `<base>`.
 Wrong or duplicate explicit app identity fails. The renderer then requires one
@@ -238,8 +240,8 @@ files remain unchanged. The same layout applies to `arcane dev` and
 `arcane package`. Generated and offline app files are committed; GitHub Actions
 consume those committed files. See [root generated output](pwa.md#root-generated-output).
 
-SDK `0.5.17` preserves the physical workspace route count and ordered include
-list. External and modern integrated routes require `components`, `css`,
+The supported physical layout preserves its route count and ordered include
+list. External and modern integrated physical routes require `components`, `css`,
 `dependencies`, `entities`, `img`, `modules`, and `sdk`; a physical workspace
 may omit only an optional trailing `security` include. The external license
 route remains separate and second.
@@ -248,10 +250,11 @@ External applications can instead select the four ordered
 [`installed-v1` routes](protocols.md#installed-package-browser-routes) in
 `arcane-packager.json`. This reads directly from the installed SDK package and
 requires neither a workspace `arcane/` directory nor `arcane.lock.json`.
-The generated browser destinations remain `arcane/`, `arcane/sdk/`, and
-`arcane/dependencies/strong-type/`; an npm alias changes package source paths,
-not those browser URLs. The SDK version comes from that installed package.
-Existing physical workspaces and scaffold output remain supported unchanged.
+Direct routes use the actual `node_modules/<dependency>/...` browser paths;
+an npm alias selects that alias's folder. Earlier virtual routes retain
+`arcane/`, `arcane/sdk/`, and `arcane/dependencies/strong-type/` destinations.
+The SDK version comes from the installed package. Existing physical workspaces
+and explicitly selected nested scaffolds remain supported.
 
 ### Result and safety
 
@@ -278,12 +281,16 @@ Success returns the normal selected-workspace wrapper:
 
 For the direct CLI command, `documentPaths` contains the configured entry first
 and every other descriptor-selected HTML/HTM document afterward in
-deterministic order. The generated artifact and selected documents are written
-together. A post-commit observer failure preserves delivery with
+deterministic order. The generated artifact is written first, followed by the
+selected documents. A write failure or cancellation can leave earlier writes
+in place; the operation does not restore them automatically. After successful
+writes, an observer failure preserves delivery with
 `eventDelivery.status === 'degraded'` and `ARCANE_EVENT_DELIVERY_FAILED`; it
 does not roll back complete application content.
 
-`new` and `init` generate the map during scaffolding. `dev` refreshes all
+Root `new` reports a pending map until the SDK is installed. Root `init` generates
+the map when the installation is available and otherwise reports the same pending
+state; explicit nested scaffolds generate it during setup. `dev` refreshes all
 selected documents once before binding. `package` consumes the saved source
 and maps; use `import-map` to refresh them explicitly before selecting output
 that needs updated maps. Packaging does not run tests or checks automatically.
@@ -293,10 +300,9 @@ Explicit `test` and `check` operations read the existing map without regeneratin
 watcher, polling, scheduled refresh, download, or self-update behavior.
 
 There is no supported `--dry-run` for `import-map`: do not pass that parser-wide
-flag because this command performs the real commit. Import-map-specific failures
+flag because this command writes the selected files. Import-map-specific failures
 use `ARCANE_IMPORT_MAP_INVALID`, `ARCANE_IMPORT_MAP_UNRESOLVED`, or
-`ARCANE_IMPORT_MAP_COLLISION`; packaging can additionally report
-`ARCANE_IMPORT_MAP_CLEANUP_FAILED`. Workspace, policy, usage, busy, and
+`ARCANE_IMPORT_MAP_COLLISION`. Workspace, policy, usage, busy, and
 cancellation failures retain their normal SDK codes.
 
 ### Example
@@ -348,7 +354,7 @@ An explicit live-source SDK mapping follows the selected browser destinations
 while reading canonical SDK source; it never replaces installed files.
 
 ```text
-arcane dev [--app <id>] [--public] [--http | --https] [--cert <file> --key <file>] [--host <address>] [--port 8000] [--http-port 0]
+arcane dev [--app <id>] [--public] [--http | --https] [--cert <file> --key <file>] [--host <address>] [--port 8000] [--http-port 0] [--sdk-runtime-source <sdk-root>]
 ```
 
 ### Lifecycle
@@ -374,6 +380,10 @@ HTTPS is the default for development and required for packaged browser previews.
 The published `node-http-server` 10.0.0 integration negotiates HTTP/2 or HTTP/1.1
 on the same HTTPS port using the configured PEM pair. Source routes, generated
 PWA resources, and conditional responses use the same serving pipeline.
+Static files retain the module's complete MIME map, including PDF, Markdown,
+audio and video. Generated representations use the same published map;
+unknown extensions retain `application/octet-stream`. No application MIME
+override is needed for these supported types.
 `--https` remains accepted but is no longer needed to select the transport.
 `--port` selects the HTTPS application port. A second HTTP listener returns
 `308` redirects to that HTTPS port, preserving the requested path and query.
@@ -565,8 +575,9 @@ arcane package [--app <id>] [--dry-run]
 
 The result includes the release root, manifest, and complete selected inventory.
 `ARCANE_APP_RELEASE.json` keeps the authored app-relative `app.entry` and records
-the package launch URL in `app.start`, such as `./apps/hello-world/index.html`.
-The file inventory includes that app tree and the root `index.html`.
+the package launch URL in `app.start`: `./index.html` for a root app with that
+entry, or `./apps/hello-world/index.html` for a nested app. The complete file
+inventory follows the selected layout and includes the root `index.html`.
 `--dry-run` plans the package without refreshing source, running tests, or
 replacing output.
 
@@ -738,6 +749,8 @@ The preview always uses HTTPS with the workspace certificate pair. Supply
 `--port` selects the HTTPS application port, and `--http-port` selects the
 paired HTTP `308` redirect port. The HTTP port defaults to an available port;
 the CLI prints its actual redirect URL and reports both listener endpoints.
+The preview uses the same complete `node-http-server` MIME map as source
+development, including PDF, Markdown and supported audio/video types.
 For a paired native target, it performs package, prepare, plan, build, launch,
 readiness, and owned cancellation in one process.
 

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

@@ -1,12 +1,12 @@
 {
   "schemaVersion": 1,
-  "sdkVersion": "0.5.18",
+  "sdkVersion": "0.51.1",
   "environment": {
     "runtime": "Node.js for Node entrypoints; browser for browser-only entrypoints",
     "minimumVersion": "22.23.2 for Node entrypoints",
     "moduleSystem": "ESM"
   },
-  "memberCount": 220,
+  "memberCount": 223,
   "runtimeSubpathPatterns": {
     "arcane-os/modules/*": "./runtime/arcane/modules/*",
     "arcane-os/entities/*": "./runtime/arcane/entities/*"
@@ -3118,7 +3118,7 @@
       "summary": "Compatibility export of createTwinCloudTTSProvider using the same function and implementation.",
       "availability": "Browser or Node with Fetch, Blob, AbortController, and an application-owned DigitalOcean inference key",
       "protocol": "arcane-ai-provider/2 tts/synthesize",
-      "normalization": "Same TWiN Cloud options, queued follow-ups, complete audio Blob results, and cancellation contract. Existing imports, stored provider IDs, and credentials remain valid without migration."
+      "normalization": "Same TWiN Cloud options, complete-job and submission queues, shared rate-limit cooldown, queued follow-ups, complete audio Blob results and cancellation contract. Existing imports, stored provider IDs and credentials remain valid without migration."
     },
     {
       "id": "browser-speech:createTwinCloudTTSProvider",
@@ -3129,10 +3129,10 @@
       "entrypoints": ["arcane-os/ai/browser-speech"],
       "primaryImport": "arcane-os/ai/browser-speech",
       "group": "Browser speech providers",
-      "summary": "Creates an explicitly selected TWiN Cloud remote TTS provider with immediate synthesis submission and configurable queued audio follow-ups.",
+      "summary": "Creates an explicitly selected TWiN Cloud remote TTS provider with complete-job queues and independently configurable follow-up HTTP scheduling.",
       "availability": "Browser or Node with Fetch, Blob, AbortController, and an application-owned inference key",
       "protocol": "arcane-ai-provider/2 tts/synthesize",
-      "normalization": "Construction and activation make no adapter network requests. SDK initial POSTs bypass the provider-local js-queue; follow-up status/result/audio GETs use followUpQueue capacity and cadence through complete body consumption. Retry-After affects only its job. Whole-job maxConcurrentRequests remains independent. Local Kokoro and Whisper paths are unchanged. Applications own model, voice, credentials, activation, and queue settings."
+      "normalization": "Construction and activation make no adapter network requests. Whole-job slots cover credentials, submission, remote completion and complete audio. Initial POST attempts and eligible retries are queued; HTTP 429 sets a shared cooldown. Follow-up status/result/audio reads use independent capacity and cadence through complete body consumption. Ambiguous paid POST failures are surfaced without replay. Applications own model, voice, credentials, activation and queue settings."
     },
     {
       "id": "browser-speech:createBrowserSpeechRecognitionProvider",
@@ -3162,7 +3162,7 @@
       "summary": "Creates a local-only Kokoro text-to-speech provider for the provider-neutral AI runtime.",
       "availability": "Browser with DBOPFS, Web Locks, Workers, object URLs, and caller-selected kokoro-js runtime/model content",
       "protocol": "arcane-ai-provider/2 tts/synthesize",
-      "normalization": "Independent load, status, request, unload, cancellation, and disposal; provider-native requests return 24000 Hz Float32Array PCM, while shared AI.js requests use wav and return complete Uint8Array audio/wav data; never selects a cloud fallback"
+      "normalization": "Independent load, status, request, unload, cancellation and disposal; optional ordinary model.voices records remain complete in the synchronous catalog without loading or constraining synthesis. Provider-native requests return 24000 Hz Float32Array PCM, while shared AI.js requests use wav and return complete Uint8Array audio/wav data; never selects a cloud fallback"
     },
     {
       "id": "browser-speech:createBrowserSpeechArtifactGraph",
@@ -3466,6 +3466,34 @@
       "protocol": "TWiN Cloud native System One request",
       "normalization": "Preserves complete state and questions within JSON transport and returns the full parsed provider result; shares existing JSON transport retry, diagnostics, and cancellation; leaves model choice, scales, and answer interpretation with the caller and retains no history"
     },
+    {
+      "id": "browser-speech:createBrowserSpeechSynthesisProvider",
+      "name": "createBrowserSpeechSynthesisProvider",
+      "displayName": "createBrowserSpeechSynthesisProvider()",
+      "kind": "function",
+      "signature": "createBrowserSpeechSynthesisProvider({id,model,language}={})",
+      "entrypoints": ["arcane-os/ai/browser-speech"],
+      "primaryImport": "arcane-os/ai/browser-speech",
+      "group": "Native browser speech",
+      "summary": "Creates a native browser TTS provider with silent voice discovery and preparation, live catalog subscriptions, and owned playback.",
+      "availability": "Browser with speechSynthesis and SpeechSynthesisUtterance; no SDK model, Worker or storage required",
+      "protocol": "arcane-ai-provider/2 tts/synthesize with native-speech playback descriptors",
+      "normalization": "Preserves complete input and native voiceURI/language metadata; setDefaultVoice changes future preparations without replacing the provider; explicit playback owns order, pause, resume, stop, completion and release; browser voices may use remote services and no audio file is fabricated"
+    },
+    {
+      "id": "twin-cloud:generateImages",
+      "name": "generateImages",
+      "displayName": "generateImages()",
+      "kind": "function",
+      "signature": "async generateImages({model,prompt,parameters={},twinKey,getApiKey,signal=null,id=Date.now(),onRequest,onResponse,onProgress}={})",
+      "entrypoints": ["arcane-os/ai/twin-cloud"],
+      "primaryImport": "arcane-os/ai/twin-cloud",
+      "group": "TWiN Cloud image generation",
+      "summary": "Generates caller-selected images and returns every image as a Blob in provider order.",
+      "availability": "Node and Browser with Fetch, Blob and AbortController; remote HTTPS provider",
+      "protocol": "TWiN Cloud async FAL Flux Schnell or Stable Diffusion image generation",
+      "normalization": "Returns {images:[{blob,mediaType,width?,height?}]}; preserves complete prompts and provider parameters, observes semantic progress and complete diagnostics, submits once, polls accepted jobs, propagates cancellation and retains no history or durable media"
+    },
     {
       "id": "twin-cloud:fetchHTTPResponse",
       "name": "fetchHTTPResponse",

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

@@ -5,7 +5,7 @@
     "repository": "https://github.com/TheWizardNexus/arcane-os-sdk.git",
     "branch": "main",
     "path": "runtime/arcane/components",
-    "sdkVersion": "0.7.2"
+    "sdkVersion": "0.51.1"
   },
   "componentCount": 41,
   "loader": "/arcane/modules/HTMLImport.js",
@@ -149,7 +149,7 @@
     {
       "file": "runtime/arcane/components/chat.html",
       "name": "chat.html",
-      "purpose": "Shared chat, visible selected-model activation/progress, masked auto-scrolling transcript, structural tool inspection/settlement, speech, language, and conversation-timebox surface.",
+      "purpose": "Shared chat, selected-model activation/progress, complete streamed transcript, structural tool settlement, editable speech drafts, rendered printing, language, and conversation timeboxes.",
       "methods": [
         "streamMessage()",
         "setMessageProgress()",
@@ -166,6 +166,11 @@
         "pendingToolCall",
         "pendingToolCalls",
         "sendMessage()",
+        "appendDraft()",
+        "transcriptionMode",
+        "recognitionLanguage",
+        "print()",
+        "printTitle",
         "languageChanged()",
         "requestAIActivation()",
         "destroy()"
@@ -195,7 +200,7 @@
       ],
       "availability": "Browser and supported native WebViews",
       "transport": "HTMLImport + DOM; injected Arcane/provider modules where listed",
-      "normalization": "UI/runtime state, honest model progress, complete timestamped transcript including ui_hidden stored records, exact saved nonblank assistant display names with AI fallback rather than current-name inference, live session name capture with host.aiName display fallback, user-facing structural arguments.message, nonblank all-ID tool-result restoration, collapsed complete raw inspection, ordered parallel-call replay validation, per-choice streamed/terminal complete-envelope correlation, complete nonstructural stream rendering, automatic repeated-formatting-mark removal from only the outbound speech-input copy while displayed and stored Markdown stays exact, generic visible failure outcomes with complete console diagnostics, atomic executed/declined/cancelled/not-executed result batches with one continuation, plural pending-call reload recovery, reentrant terminal-event ownership, and BFCache-preserving page lifecycle are normalized; destroy aborts observation and returns true once/false thereafter; AI/storage/media behavior remains mixed"
+      "normalization": "Default completed-transcription submit or opt-in transcriptionMode=draft, complete appendDraft text with preserved existing selection, native interim-range ownership, and rendered conversation print/printTitle are normalized. No-retention submissions stay outside transcript, recurring context, memory, and DBOPFS. UI/runtime state, honest model progress, complete timestamped transcript including ui_hidden stored records, exact saved nonblank assistant display names with AI fallback rather than current-name inference, live session name capture with host.aiName display fallback, user-facing structural arguments.message, nonblank all-ID tool-result restoration, collapsed complete raw inspection, ordered parallel-call replay validation, per-choice streamed/terminal complete-envelope correlation, complete nonstructural stream rendering, automatic repeated-formatting-mark removal from only the outbound speech-input copy while displayed and stored Markdown stays exact, generic visible failure outcomes with complete console diagnostics, atomic executed/declined/cancelled/not-executed result batches with one continuation, plural pending-call reload recovery, reentrant terminal-event ownership, and BFCache-preserving page lifecycle are normalized; destroy aborts observation and returns true once/false thereafter; AI/storage/media behavior remains mixed"
     },
     {
       "file": "runtime/arcane/components/conversation-view.html",
@@ -276,6 +281,8 @@
       "methods": [
         "beforeOpen()",
         "open()",
+        "close()",
+        "printPreview()",
         "destroy()"
       ],
       "events": [
@@ -287,7 +294,7 @@
       ],
       "availability": "Browser and supported native WebViews",
       "transport": "HTMLImport + DOM; injected Arcane/provider modules where listed",
-      "normalization": "DOM-native result. Forwards previewDescriptor, previewTransform, directoryFilter, data-hidden-prefixes, and data-show-hidden before the child file manager first loads; reopening refreshes them before loadAll. beforeOpen runs before those values are consumed. The child owns neutral preview rendering, cancellation, and media cleanup; destroy also destroys the child and modal."
+      "normalization": "DOM-native result. close() closes the child preview before the containing dialog and preserves the settled preview if closure is refused; printPreview() delegates to the active child print view. Forwards previewDescriptor, previewTransform, directoryFilter, data-hidden-prefixes, and data-show-hidden before the child file manager first loads; reopening refreshes them before loadAll. beforeOpen runs before those values are consumed. The child owns neutral preview rendering, cancellation, and media cleanup; destroy also destroys the child and modal."
     },
     {
       "file": "runtime/arcane/components/directory-picker.html",
@@ -404,6 +411,8 @@
         "setDirectoryFilter()",
         "select()",
         "clearSelection()",
+        "close()",
+        "printPreview()",
         "destroy()"
       ],
       "events": [
@@ -421,7 +430,7 @@
       ],
       "availability": "Browser and supported native WebViews",
       "transport": "HTMLImport + DOM; injected Arcane/provider modules where listed",
-      "normalization": "Selection/filter state and neutral previews normalized; storage/provider behavior mixed. Initial directoryFilter and setDirectoryFilter(fn|null) use false-only exclusion before built-in DBOPFS key/metadata reads; data-hidden-prefixes also applies to directories unless data-show-hidden is present. Existing file predicates preserve their first argument and receive optional directory/fileName/path/layout context. previewDescriptor(original File,{directory,fileName,extension,path,mimeType,signal}) may asynchronously return text/markdown/html/json content, conversation messages with role/content/real timestamp and optional name/status, collection items, or image/audio/pdf/download content as Blob/File or a lazy ({signal}) loader. Assistant conversation labels use the exact nonblank string name or AI without a role suffix; other role labels retain existing name/role presentation. User and assistant cards have distinct theme backgrounds and preserve data-role. Downloads require fileName; descriptors accept title and images accept alt. Lazy items load only on explicit request and retain item-local retry. Close, replacement, and destroy abort the preview signal, suppress late output, remove iframe srcdoc, stop audio, and revoke all owned object URLs. HTML preserves the exact string in iframe srcdoc; HTML/Markdown MIME fallback supports extensionless files. Nullish descriptors preserve previewTransform for JSON-family files and native previews; untransformed JSONL/NDJSON retains complete raw text, and other binary files download the original File."
+      "normalization": "Rendered printPreview() awaits selected-view readiness and preserves resources through afterprint. close() cancels pending opening and releases the settled preview only after successful closure. Declared image records in JSON-family files decode through MarkdownMedia while ordinary JSON and application preview hooks keep their presentation. Selection/filter state and neutral previews normalized; storage/provider behavior mixed. Initial directoryFilter and setDirectoryFilter(fn|null) use false-only exclusion before built-in DBOPFS key/metadata reads; data-hidden-prefixes also applies to directories unless data-show-hidden is present. Existing file predicates preserve their first argument and receive optional directory/fileName/path/layout context. previewDescriptor(original File,{directory,fileName,extension,path,mimeType,signal}) may asynchronously return text/markdown/html/json content, conversation messages with role/content/real timestamp and optional name/status, collection items, or image/audio/pdf/download content as Blob/File or a lazy ({signal}) loader. Assistant conversation labels use the exact nonblank string name or AI without a role suffix; other role labels retain existing name/role presentation. User and assistant cards have distinct theme backgrounds and preserve data-role. Downloads require fileName; descriptors accept title and images accept alt. Lazy items load only on explicit request and retain item-local retry. Close, replacement, and destroy abort the preview signal, suppress late output, remove iframe srcdoc, stop audio, and revoke all owned object URLs. HTML preserves the exact string in iframe srcdoc; HTML/Markdown MIME fallback supports extensionless files. Nullish descriptors preserve previewTransform for JSON-family files and native previews; untransformed JSONL/NDJSON retains complete raw text, and other binary files download the original File."
     },
     {
       "file": "runtime/arcane/components/header.html",
@@ -515,11 +524,13 @@
     {
       "file": "runtime/arcane/components/markdown-editor.html",
       "name": "markdown-editor.html",
-      "purpose": "Configurable Markdown authoring, toolbar, preview, plain-text title, and save surface with optional bounded input/preview panes and edit-position following.",
+      "purpose": "Markdown authoring, toolbar, live media preview, plain-text title, insertion, rendered printing, and saving, with optional input/preview panes and edit-position following.",
       "methods": [
         "configure()",
         "focus()",
         "clear()",
+        "insertMarkdown()",
+        "print()",
         "saveEntry()",
         "destroy()"
       ],
@@ -535,7 +546,7 @@
       ],
       "availability": "Browser and supported native WebViews",
       "transport": "HTMLImport + DOM; injected Arcane/provider modules where listed",
-      "normalization": "Editor values and optional presentation behavior normalized; injected save result mixed. fit and followPreview default false, preserve omitted prior configuration, and accept explicit false resets; data-fit and data-follow-preview select the initial options. Fit requires an application-bounded host and provides independent input/preview scrolling in roomy columns or narrow stacked panes without changing the application shell. Following responds to body typing/format edits, leaves manual preview scrolling independent until the next edit, and does not treat title edits or programmatic value replacement as follow requests. Preview rendering preserves the current source viewport and selection; configuration/value replacement retain source offsets and applicable selection positions, and layout changes never reattach the textarea. Formatting selects the formatted text without panning the source or its ancestors. Native typing, keyboard selection, and manual source scrolling remain independent without deferred scroll restoration. Public parts editor/title/toolbar/input/preview/actions/status/save-action allow application styling while the title stays native plain text. Existing controls, complete save payload, save cancellation, and destruction behavior remain."
+      "normalization": "insertMarkdown(text) replaces the current selection through the existing complete change lifecycle; print() captures the rendered preview without saving. Local MarkdownMedia images hydrate independently and remain owned through print. Editor values and optional presentation behavior normalized; injected save result mixed. fit and followPreview default false, preserve omitted prior configuration, and accept explicit false resets; data-fit and data-follow-preview select the initial options. Fit requires an application-bounded host and provides independent input/preview scrolling in roomy columns or narrow stacked panes without changing the application shell. Following responds to body typing/format edits, leaves manual preview scrolling independent until the next edit, and does not treat title edits or programmatic value replacement as follow requests. Preview rendering preserves the current source viewport and selection; configuration/value replacement retain source offsets and applicable selection positions, and layout changes never reattach the textarea. Formatting selects the formatted text without panning the source or its ancestors. Native typing, keyboard selection, and manual source scrolling remain independent without deferred scroll restoration. Public parts editor/title/toolbar/input/preview/actions/status/save-action allow application styling while the title stays native plain text. Existing controls, complete save payload, save cancellation, and destruction behavior remain."
     },
     {
       "file": "runtime/arcane/components/media-embed.html",
@@ -789,7 +800,7 @@
     {
       "file": "runtime/arcane/components/speech.html",
       "name": "speech.html",
-      "purpose": "Coordinates explicit speech-to-text activation, request cancellation, speech controls, transcription completion, mute state, and microphone availability.",
+      "purpose": "Coordinates selected speech providers, native recognition language and live progress, transcription completion, cancellation, TTS mute state, and microphone availability.",
       "methods": [
         "configure()",
         "setMuted()",
@@ -799,10 +810,13 @@
         "availability",
         "muted",
         "initialMuted",
+        "recognitionLanguage",
+        "displayTranscription",
         "componentReady"
       ],
       "events": [
         "speech-ready",
+        "speech-transcription-progress",
         "speech-transcription-complete",
         "speech-transcription-error",
         "speech-transcription-cancelled",
@@ -821,7 +835,7 @@
       ],
       "availability": "Browser and supported native WebViews",
       "transport": "HTMLImport + DOM; injected Arcane/provider modules where listed",
-      "normalization": "UI/runtime state, explicit STT activation intent, request-owned cancellation, capture generation/operation correlation, and BFCache-preserving page lifecycle are normalized; pending release retires only its generation and stale permission settlement cannot clear a newer retry; persisted pageshow resynchronizes mute state and rerenders retained controls/status, while nonpersisted pagehide destroys; provider/model authority and media behavior remain external"
+      "normalization": "Explicit native recognition emits cumulative final text and transient interim hypotheses with the original capture operationId. recognitionLanguage accepts exact BCP47 tags independently of conversation language; the desktop live-mode picker opens with all suggestions and filters only after editing. displayTranscription defaults true and may be disabled when Chat owns its editable draft. UI/runtime state, explicit STT activation intent, request-owned cancellation, capture generation/operation correlation, and BFCache-preserving page lifecycle are normalized; pending release retires only its generation and stale permission settlement cannot clear a newer retry; persisted pageshow resynchronizes mute state and rerenders retained controls/status, while nonpersisted pagehide destroys; provider/model authority and media behavior remain external"
     },
     {
       "file": "runtime/arcane/components/summary-strip.html",
@@ -992,7 +1006,7 @@
     {
       "file": "runtime/arcane/components/voice-transcription.html",
       "name": "voice-transcription.html",
-      "purpose": "Records manual clips or optional continuous microphone audio with rolling pre-roll, pause/periodic segments, ordered transcription and saves, retained failures, retry, cancellation, and complete transcript delivery.",
+      "purpose": "Records manual or continuous microphone input, including explicitly selected native recognition, with complete live output, ordered transcription and saves, retained failures, retry, and cancellation.",
       "methods": [
         "configure()",
         "requestSTTActivation()",
@@ -1029,7 +1043,7 @@
       ],
       "availability": "Browser and supported native WebViews",
       "transport": "HTMLImport + DOM; injected Arcane/provider modules where listed",
-      "normalization": "Sticky STT readiness and explicit activation; default manual capture; optional continuous amplitude-based capture with rolling pre-roll, ordered STT/save stages, retained failures, save-only retry, sequence-bearing segment events, and capture/processing/queued/errorPhase/error state. Complete text remains exact. Continuous stop flushes and drains; explicit cancel, transcript/configuration replacement, and destruction abort outstanding work and suppress late effects. Persisted pagehide stops and flushes continuous capture while retaining component state; persisted pageshow rerenders without restarting capture; nonpersisted pagehide destroys. Media/provider behavior remains external."
+      "normalization": "Selected native recognition puts canonical text, queued final segments, and transient interim text in the existing live output in order; only confirmed text enters value and the ordered save queue. Native stop drains final results; browser end does not restart capture. Sticky STT readiness and explicit activation; default manual capture; optional continuous amplitude-based capture with rolling pre-roll, ordered STT/save stages, retained failures, save-only retry, sequence-bearing segment events, and capture/processing/queued/errorPhase/error state. Complete text remains exact. Continuous stop flushes and drains; explicit cancel, transcript/configuration replacement, and destruction abort outstanding work and suppress late effects. Persisted pagehide stops and flushes continuous capture while retaining component state; persisted pageshow rerenders without restarting capture; nonpersisted pagehide destroys. Media/provider behavior remains external."
     },
     {
       "file": "runtime/arcane/components/weather-widget.html",

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

@@ -1,15 +1,18 @@
 {
   "schemaVersion": 1,
   "source": {
-    "commit": "567ad110bf57a1c2d4a3daa22ae93716cc5f4d7e",
-    "bundleVersion": "0.8.12"
+    "authority": "sdk-canonical",
+    "repository": "https://github.com/TheWizardNexus/arcane-os-sdk.git",
+    "branch": "main",
+    "path": "runtime/arcane/entities",
+    "sdkVersion": "0.51.1"
   },
   "moduleCount": 14,
   "exportCount": 30,
   "modules": [
     {"file":"runtime/arcane/entities/ApiModelRecord.js","exports":["default"],"availability":"cross-host","normalization":"normalized"},
     {"file":"runtime/arcane/entities/Calculation.js","exports":["default"],"availability":"cross-host","normalization":"normalized"},
-    {"file":"runtime/arcane/entities/Chat.js","exports":["default"],"availability":"browser/native-webview","normalization":"New default filenames combine the timestamp with an independent random identifier; explicit and saved filenames remain unchanged. Provider-facing recurring messages preserve raw structural protocol only for the one active matching continuation, then replace settled exchanges with complete ordinary visible content; transcript records remain sanitized and readable, including ui_hidden rows. aiName defaults to empty; addAIMessage and addTurn capture an optional exact nonblank application-owned name on new assistant records only. Provider names do not establish display attribution; assistant display names stay out of messages and memory extraction, and existing records are never renamed or rewritten. ordered parallel structural calls require one exact nonblank result for every pending ID in one atomic turn, with rollback-safe persistence."},
+    {"file":"runtime/arcane/entities/Chat.js","exports":["default"],"availability":"browser/native-webview","normalization":"Per-message persist:false and entity-wide persist=false skip new retained messages, transcript records, memory extraction, and DBOPFS writes; prior retained history and already accepted writes remain untouched. Requested tool records use the call message; settled tool records use the supplied public result message. New default filenames combine the timestamp with an independent random identifier; explicit and saved filenames remain unchanged. Provider-facing recurring messages preserve raw structural protocol only for the one active matching continuation, then replace settled exchanges with complete ordinary visible content; transcript records remain sanitized and readable, including ui_hidden rows. aiName defaults to empty; addAIMessage and addTurn capture an optional exact nonblank application-owned name on new assistant records only. Provider names do not establish display attribution; assistant display names stay out of messages and memory extraction, and existing records are never renamed or rewritten. ordered parallel structural calls require one exact nonblank result for every pending ID in one atomic turn, with rollback-safe persistence."},
     {"file":"runtime/arcane/entities/CommunicationMessage.js","exports":["communicationChannels","default"],"availability":"cross-host","normalization":"normalized"},
     {"file":"runtime/arcane/entities/CommunicationThread.js","exports":["default"],"availability":"cross-host","normalization":"normalized"},
     {"file":"runtime/arcane/entities/Document.js","exports":["default"],"availability":"browser/native-webview","normalization":"mixed"},