arcane-os 0.5.17 → 0.5.18

package/docs/reference/runtime-modules.md

@@ -4,6 +4,13 @@ Every file shipped under `runtime/arcane/modules/` appears here. Start with the
 
 Apps import renderer ESM from `/arcane/modules/<file>`. Classic scripts, the OPFS worker, uPlot stylesheet, and vendor license are called out explicitly. Importing a module does not grant a native capability.
 
+Applications own response-detail preferences, their saved values, and any
+verbosity instruction appended to the system prompt. The former
+`AIResponseLength.js` module and its exports have been removed. Before adopting
+this source change, consumers must normalize preferences in their application
+and pass their complete system prompt directly instead of calling the former
+no-op `applyAIResponseLength()` helper. Existing saved preferences are unchanged.
+
 ## Availability shorthand
 
 - **Cross-host** means in-process logic built from standard JavaScript/Web APIs.
@@ -44,8 +51,7 @@ own asynchronous work, cancellation, and backpressure.
 | [`AIPreferenceRuntime.js`](#aipreferenceruntimejs) | esm | Applies and reads non-persistent per-user AI preference overrides. | Cross-host | Normalized six-slot preference state. |
 | [`AIPreferenceTuple.js`](#aipreferencetuplejs) | esm | Normalizes and compares the six provider/model preference slots. | Cross-host | Fully normalized frozen tuple. |
 | [`AIProviderRuntime.js`](#aiproviderruntimejs) | esm | Owns provider-neutral selection, lifecycle, routing, startup, requests, streaming, cancellation, and independent LLM/STT/TTS state. | Cross-host runtime; provider-specific availability | Normalized required provider members plus route/status contracts, with explicit local-only selection and no implicit fallback. |
-| [`AIResponseLength.js`](#airesponselengthjs) | esm | Normalizes current low/medium/high response-preference selectors while preserving complete prompts. | Cross-host | Current selector normalization; prompt content remains unchanged. |
-| [`AIResponseURLPolicy.js`](#airesponseurlpolicyjs) | esm | Extracts and audits links from AI Markdown, rendered HTML, CSS, srcset, bare URLs, and email text. | Cross-host | Normalized frozen allowlist audit. |
+| [`AIResponseURLPolicy.js`](#airesponseurlpolicyjs) | esm | Extracts and audits links from AI Markdown, rendered HTML, CSS, srcset, bare URLs, and email text. | Cross-host | Mutable audit with exact link comparison after renderer-level decoding. |
 | [`AIRuntimeState.js`](#airuntimestatejs) | esm | Publishes sticky mutable role snapshots, lifecycle intents, and startup-settlement barriers. | Cross-host state contract | Closed monotonic state records; events report state but grant no authority. |
 | [`AnsiText.js`](#ansitextjs) | esm | Parses terminal ANSI sequences into display spans or strips them to plain text. | Cross-host | Normalized text/span output. |
 | [`ApiModelDatabase.js`](#apimodeldatabasejs) | esm | Fetches an injectable HTTP JSON model with parser, cache, redacted public endpoint records, and request lifecycle events. | Browser / native WebView / server with fetch | Request records are normalized; fetch/provider failures remain mixed. |
@@ -100,6 +106,7 @@ own asynchronous work, cancellation, and backpressure.
 | [`OpenMeteoWeatherProvider.js`](#openmeteoweatherproviderjs) | esm | Searches and loads Open-Meteo data into complete mutable Arcane weather entities. | Browser / native WebView / server with fetch + cloud | Provider data normalized to mutable entities; transport errors mixed. |
 | [`PersistentAIChatSession.js`](#persistentaichatsessionjs) | esm | Adds explicit retained-history/memory policy to complete configured chat without changing DBOPFS or ChatEntity semantics. | Browser / native WebView with DBOPFS and configured chat | Retained context commits atomically; `persist:false` turns are one-operation-only. |
 | [`PreferenceStore.js`](#preferencestorejs) | esm | Loads and updates schema-defined app preferences through native storage with a narrow browser fallback. | Browser/native hybrid | Complete ordinary values remain mutable; setAll uses one optional atomic adapter batch for every selected value when advertised, otherwise performs complete ordered serial writes, and only exact unsupported native capability changes future operations to the browser fallback. |
+| [`PreparedSpeech.js`](#preparedspeechjs) | esm | Owns detached ordered preparation, semantic audio reuse, and per-caller cancellation behind AI.prepareTTS. | Browser / native WebView with injected synthesis and optional DBOPFS | Complete original inputs, ordered audio metadata, durable reuse, and observable preparation results. |
 | [`QRCode.min.js`](#qrcodeminjs) | classic-script | Vendored QRCode generator for DOM, canvas, SVG, and image output. | Browser vendor script | Vendor-native. |
 | [`Questionnaire.js`](#questionnairejs) | esm | Evaluates whether a one-time questionnaire prompt is due without performing the prompt. | Cross-host | Normalized conservative boolean. |
 | [`RecordLinkIndex.js`](#recordlinkindexjs) | esm | Parses record links and builds their normalized index. | Cross-host | Fully normalized. |
@@ -144,6 +151,8 @@ default `AI`; read-only `providerRuntime`, `browserSpeechConfiguration`, and
 `streamRequest()`, `streamMessage()`, `fetchRequest()`, `fetch()`,
 read-only `ttsSegmentation`, `configureTTSSegmentation()`,
 `streamTTS(text='',end=false,options={})`,
+`prepareTTS({parts,storage,identity,signal,onState})`,
+`playPreparedTTS(prepared,{signal,onState})`,
 `finishTTS()`, `fetchTTS()`, `fetchSTT()`, `stopAudio()`, `resumeAudio()`,
 `playAudio()`; consumes `user-entity-loaded` and `arcane-ollama-ready`,
 installs `window.ai`, and emits `ai-ready` and `ai-tts-failure`.
@@ -312,13 +321,63 @@ flush, not a queue-wide playback barrier. A muted call resolves `false`.
 Playback completion stays pending while the browser waits for an audio-unlock
 gesture or a recoverable resume attempt. If resuming a closed `AudioContext`
 fails, the affected jobs terminate and their playback results settle `false`.
-`stopAudio()` cancels all speech owned
-by this AI instance and settles pending playback promises `false`. A trailing
+`stopAudio()` cancels streamed speech and prepared playback owned
+by this AI instance and settles pending playback promises `false`; detached
+preparation retains its own cancellation lifetime. A trailing
 pause delays the next queued audio; the preceding promise resolves when its
 last audio buffer ends, without waiting out that pause. Completion describes
 the playback lifecycle, not proof that a listener heard the sound. See the
 [complete-passage example](ai/browser-speech.md#queue-complete-passages-and-wait-for-playback).
 
+`prepareTTS({parts,storage,identity,signal,onState})` returns an immediate
+`{segments,state,ready,getAudio(index),cancel()}` handle for detached complete
+speech preparation. Parts are strings or `{input,voice?,speed?,pauseAfterMs?}`
+records. It retains the full source for semantic matching, snapshots the
+selected speech configuration and segmentation, and applies automatic
+formatting cleanup once to the speech copy. Generation uses the existing
+bounded provider queue without adding playback. Optional
+`storage:{db,table,key}` saves complete audio files and their MIME metadata in
+the caller's ready DBOPFS instance; the separate JSON-compatible `identity`
+adds application-owned semantic context. Reuse compares complete inputs rather
+than an SDK version alone.
+
+`state` is `queued`, `preparing`, `ready`, `error`, or `cancelled`.
+`onState({state,completed,total,segments,error})` synchronously observes
+preparation progress. `ready` resolves the complete record after every segment
+is ready and, when storage is selected, durably saved. `getAudio(index)` waits
+for the corresponding ordered segment and returns its complete `Blob` with
+the retained MIME type. Preparation failure rejects; cancellation rejects as
+`AbortError` and preserves successfully stored segments. Matching pending
+requests share synthesis only on the same AI instance and storage group;
+cancelling one handle does not cancel another active matching caller.
+Preparation cancellation prevents later synthesis, but an already-started
+shared provider load/unmute has no per-preparation signal and may finish.
+
+`playPreparedTTS(prepared,{signal,onState})` can attach immediately. Its returned
+`{state,error,finished,pause(),resume(),stop()}` handle schedules segments in
+their original order using the existing AI audio clock. `finished` resolves `true` after
+natural completion and `false` after stop, cancellation, or failure; genuine
+failures also use the existing complete diagnostics and `ai-tts-failure` event.
+Part pauses separate adjacent audio; the final trailing pause does not delay
+`finished` after the final audio buffer ends. State/error getters and the
+optional synchronous `onState({state,error})` callback expose `waiting`,
+`waiting-for-gesture`, `scheduled`, `paused`, `complete`, `stopped`, or `error`.
+Use `waiting-for-gesture` for audio-unlock UI; a `false` result from `resume()`
+alone is not a first-segment-ready signal.
+Pause and resume are asynchronous boolean controls scoped to that handle's
+audio context; stop is synchronous. Playback completion and these controls do
+not cancel independent preparation. One AI has one playback lane: attaching
+prepared playback replaces its preceding streamed or prepared audio, and
+`streamTTS()` interrupts active prepared playback. `stopAudio()` stops all
+this AI's playback but keeps detached preparation running; `setSpeechMuted(true)` also cancels
+provider TTS work and unloads it. Replacing the selected speech configuration
+cancels missing generation for that earlier selection. Completed stored audio
+remains in application storage.
+Fully stored replay enables playback without loading the selected speech
+model even when the AI starts muted. Missing audio alone requests the shared
+TTS readiness path. See [prepared narration](ai/browser-speech.md#prepare-narration-once-and-replay-stored-audio)
+for full record shapes, storage ownership, and a complete example.
+
 Streaming speech retains sentence
 segmentation by default. `configureTTSSegmentation({punctuation,wordCadence})`
 accepts `punctuation:'sentence'|'any'|'none'` and a `wordCadence` that is either
@@ -809,35 +868,6 @@ const runtime = getAIProviderRuntime();
 console.log(runtime.protocol, runtime.status());
 ```
 
-## AIResponseLength.js
-
-### Overview
-
-Normalizes current low/medium/high response-preference selectors while
-preserving complete prompts unchanged.
-
-### Public surface
-
-Response-preference constants plus `normalizeAIResponseLength()`,
-`aiResponseLengthInstruction()`, and `applyAIResponseLength()`. Every option is
-labeled `Complete`, the instruction helper returns an empty string, and the
-application helper returns its complete `systemPrompt` unchanged.
-
-Exact exports: `AI_RESPONSE_LENGTH_DEFAULT`, `AI_RESPONSE_LENGTH_OPTIONS`, `aiResponseLengthInstruction`, `applyAIResponseLength`, `normalizeAIResponseLength`.
-
-### Availability and normalization
-
-**Cross-host.** Current selector normalization with no prompt transformation.
-Transport: In-process only. [Deep protocol details](protocols.md).
-
-### Example
-
-```javascript
-import * as module from '/arcane/modules/AIResponseLength.js';
-
-console.log(Object.keys(module));
-```
-
 ## AIResponseURLPolicy.js
 
 ### Overview
@@ -852,7 +882,19 @@ Exact exports: `auditAIResponseLinks`, `decodeHTMLCharacterReferences`, `extract
 
 ### Availability and normalization
 
-**Cross-host.** Normalized frozen allowlist audit. Transport: In-process; bundled Marked parser. [Deep protocol details](protocols.md).
+**Cross-host.** Returns a mutable `{ok, links, unsupportedLinks, allowedLinks}`
+audit. Browsers use detached native HTML elements to parse rendered markup and
+decode character references. Hosts without a document retain lexical extraction
+and the existing limited entity decoder. Rendered values are decoded only once.
+Markdown destinations, CSS URLs, srcset candidates, and authored source positions
+remain part of the audit; DOM-only attribute links use document order after
+authored links because the DOM does not expose source offsets.
+
+Comparison uses exact values after entity and Markdown escape decoding. URI
+encoding, decoding, or URL canonicalization would change those values and is
+not applied. The audit neither changes the response content nor fetches or
+navigates to links. Transport: In-process; bundled Marked parser.
+[Deep protocol details](protocols.md).
 
 ### Example
 
@@ -2292,7 +2334,7 @@ Exact exports: `MarkdownSpeech`.
 ### Availability and normalization
 
 **Cross-host.** The runtime projection and public package entrypoint share the
-same dependency-free implementation. `append()` returns only
+same implementation. `append()` returns only
 the newly available narration. Only a trailing candidate marker and whether
 it repeats are retained; ordinary text is emitted immediately. Terminal
 `append(text,true)` flushes a single pending mark and resets state. `reset()`
@@ -2690,6 +2732,54 @@ import * as module from '/arcane/modules/PreferenceStore.js';
 console.log(Object.keys(module));
 ```
 
+## PreparedSpeech.js
+
+### Overview
+
+Shared preparation mechanism used by `AI.prepareTTS()`. It owns ordered
+generation admission, same-owner request sharing, complete audio storage and
+semantic reuse, and each caller's preparation lifetime. It does not construct
+an audio context, play speech, or select application content.
+
+### Public surface
+
+Named `prepareSpeech({owner,parts,originalParts=parts,selection=null,
+segmentation=null,storage=null,identity=null,signal=null,onState,synthesize})`.
+The owning AI supplies already segmented speech parts, complete original parts,
+its selection snapshot, and its synthesis callback. The returned handle is
+`{segments,state,ready,getAudio(index),cancel()}`. Applications use
+`AI.prepareTTS()` and `AI.playPreparedTTS()` so the existing AI owner retains
+automatic formatting cleanup, segmentation, provider readiness/capacity, and
+ordered playback. See the [complete preparation contract](ai/browser-speech.md#prepare-narration-once-and-replay-stored-audio).
+
+`storage:{db,table,key}` is optional; the ready DBOPFS instance supplies
+`get`, `set`, `readFile`, and `writeFile`. JSON-compatible semantic inputs stay
+complete in the version-1 manifest. Raw audio is persisted separately and its
+MIME type is retained in metadata. Storage mutation serializes by database,
+table, and key within the realm. Synthesis sharing is scoped to the same owner
+and matching semantic inputs/storage; playback remains outside this module.
+
+Exact exports: `prepareSpeech`.
+
+### Availability and normalization
+
+**Browser or native WebView with Blob, AbortController, an injected synthesis
+callback, and optional ready DBOPFS.** Import creates no provider or
+playback. Calling the preparation function starts owned asynchronous work.
+`ready` rejects complete synthesis/storage failures or `AbortError` after
+cancellation; successful audio remains available for reuse. Malformed part,
+storage, or semantic metadata inputs throw `TypeError`; an invalid segment
+index rejects with `RangeError`. No Core capability is selected here.
+
+### Example
+
+```javascript
+import {prepareSpeech} from '/arcane/modules/PreparedSpeech.js';
+
+// Applications use AI.prepareTTS; this import only exposes the SDK mechanism.
+console.log(typeof prepareSpeech); // function
+```
+
 ## QRCode.min.js
 
 ### Overview

package/docs/reference/sdk-api.md

@@ -19,7 +19,7 @@ This table is the Node `package.json#exports` map: it defines package
 entrypoints for SDK/tooling code. It is distinct from the generated browser
 import map that resolves application-facing `arcane/*` modules and the focused
 EventManager entry. See [browser runtime delivery](protocols.md#browser-runtime-delivery)
-for the installed-inventory-derived physical-runtime contract in SDK `0.5.17`.
+for the installed-inventory-derived physical-runtime contract in SDK `0.5.18`.
 
 | Specifier | Purpose |
 | --- | --- |
@@ -37,13 +37,29 @@ for the installed-inventory-derived physical-runtime contract in SDK `0.5.17`.
 | `arcane-os/logging` | Shared console diagnostics controlled by the existing `user.developer` preference. |
 | `arcane-os/preference-store` | Portable preference records and injected storage adapters. |
 | `arcane-os/speech-playback` | Portable speech preparation, playback state, and injected media adapters. |
-| `arcane-os/speech-text` | Dependency-free speech-input formatting cleanup for complete text and streamed chunks. |
+| `arcane-os/speech-text` | Speech-input formatting cleanup for complete text and streamed chunks. |
 | `arcane-os/ai/browser-wasm` | Caller-selected browser-local Wllama inference, complete DBOPFS model storage, streaming, cancellation, and structural tool-call results. |
 | `arcane-os/ai/browser-speech` | Caller-selected browser-local Whisper STT and Kokoro TTS provider mechanisms, ordinary upstream assets, materialized/native routing, Workers, and cancellation. |
 | `arcane-os/mail` | Portable Mail runtime, durable outbox, complete transport responses, and provider-neutral acceptance contracts. |
 
 Eight JSON schemas and `package.json` are data-only export subpaths. In Node ESM, import JSON with `with {type: 'json'}`, or resolve and read it explicitly.
 
+### Managed AI narration
+
+Applications import `AI` through `arcane/AI` in the managed browser map.
+`ai.prepareTTS({parts,storage,identity,signal,onState})` prepares complete
+punctuation segments without playing them and optionally saves/reuses their
+audio through application-owned DBOPFS. Its immediate handle exposes ordered
+segments, preparation state, `ready`, `getAudio(index)`, and `cancel()`.
+`ai.playPreparedTTS(prepared,{signal,onState})` attaches ordered playback and
+returns `state`, `error`, `finished`, `pause()`, `resume()`, and `stop()`.
+Each AI has one playback lane; replacing playback preserves independent
+preparation. Fully cached replay does not load the speech
+model. See [prepared narration](ai/browser-speech.md#prepare-narration-once-and-replay-stored-audio)
+for complete inputs, storage ownership, progress, errors, and cancellation,
+and [AI.js](runtime-modules.md#aijs) for the managed runtime contract.
+These are AI instance methods, not new npm export names.
+
 ## Shared operation contract
 
 High-level operations accept one options object. Common fields are `workspaceRoot`, `appId`, `target`, `signal`, and `onEvent`; only fields meaningful to that operation are consumed. Long work acknowledges first, owns its child tasks, keeps event delivery ordered and backpressured, emits progress or heartbeats, observes cancellation where safe, and rejects with `ArcaneError` on failure.
@@ -757,7 +773,7 @@ deterministic map. The package root also contains the public
 {
   schemaVersion: 1,
   kind: 'arcane-app-runtime-projection',
-  sdkVersion: '0.5.17',
+  sdkVersion: '0.5.18',
   pathPrefix: 'arcane/',
   files: [{path}]
 }
@@ -1719,7 +1735,7 @@ console.log(splitSpeechText('Hello world.'));
 
 ### Overview
 
-Streams the SDK's dependency-free speech formatting cleanup across input chunk
+Streams the SDK's speech formatting cleanup across input chunk
 boundaries. `append()` removes runs of two or more identical `*`, `#`, `_`,
 backtick, or `~` marks while retaining single marks and every other character.
 It is a narrow speech filter, not a Markdown parser. Normal SDK TTS calls use
@@ -3633,7 +3649,7 @@ workspace it additionally returns the exact installed package authority:
     packageSource,
     canonicalPackageRoot,
     packageName: 'arcane-os',
-    packageVersion: '0.5.17',
+    packageVersion: '0.5.18',
     runtimeRoot,
     browserRuntimeRoot
   }
@@ -3641,9 +3657,9 @@ workspace it additionally returns the exact installed package authority:
 ```
 
 The dependency can be named `arcane-os` or be one exact npm alias for
-`npm:arcane-os@0.5.17`. The selected installation must still be one direct,
+`npm:arcane-os@0.5.18`. The selected installation must still be one direct,
 physical, non-link package directory whose manifest identifies exactly as
-`arcane-os@0.5.17`; duplicate canonical/alias declarations reject.
+`arcane-os@0.5.18`; duplicate canonical/alias declarations reject.
 `allowMissingManagedImportMap` is an internal packaging/development seam. An
 ordinary caller should leave it `false`.
 

package/examples/wasm-ai-demo/index.html

@@ -319,6 +319,7 @@
           "arcane-os/event-manager": "/src/event-manager.mjs",
           "arcane-os/dom-event-instrumentation": "/src/dom-event-instrumentation.mjs",
           "event-pubsub": "/browser-runtime/dependencies/event-pubsub/index.js",
+          "strong-type": "/runtime/strong-type/index.js",
           "arcane-os/ai/browser-wasm": "/browser-runtime/ai/browser-wasm.mjs",
           "arcane-os/ai/browser-speech": "/browser-runtime/ai/browser-speech.mjs",
           "arcane-os/preference-store": "/runtime/arcane/modules/PreferenceStore.js",