arcane-os 0.76.0 → 0.78.0

package/docs/reference/runtime-modules.md

@@ -121,7 +121,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 values and operation context retained; exact optional namespace absence or existing Android unsupported capability selects the existing local adapter; partial-service and genuine failures remain errors; an advertised rejected batch is never retried serially. |
-| [`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. |
+| [`PreparedSpeech.js`](#preparedspeechjs) | esm | Owns detached ordered preparation, semantic audio reuse, cache-only lookup, and per-caller cancellation behind AI.prepareTTS and AI.readPreparedTTS. | Browser / native WebView with optional DBOPFS and injected synthesis for generation | Complete original inputs, ordered audio metadata, durable reuse, and observable preparation results. |
 | [`PrintView.js`](#printviewjs) | esm | Prints current rendered content and title through one document-owned print lifecycle. | Browser / supported native WebView print implementation | Complete rendered snapshot, preparation cancellation, resource lifetime, and honest request result. |
 | [`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. |
@@ -171,10 +171,12 @@ default `AI`; read-only `providerRuntime`, `speechActivationPending`, `browserSp
 read-only `ttsSegmentation`, `configureTTSSegmentation()`,
 `streamTTS(text='',end=false,options={})`,
 `prepareTTS({parts,textFormat,storage,identity,signal,onState})`,
-`playPreparedTTS(prepared,{signal,onState})`,
+`readPreparedTTS({parts,textFormat,storage,identity,signal,onState})`,
+`prepareAudioOutput()`, `playPreparedTTS(prepared,{signal,onState,audioOutput})`,
 `finishTTS()`, `prepareTTSPlayback()`, `fetchTTS()`, `fetchSTT()`, `stopAudio()`, `resumeAudio()`,
 `playAudio()`; consumes `user-entity-loaded` and `arcane-ollama-ready`,
-installs `window.ai`, and emits `ai-ready` and `ai-tts-failure`.
+installs `window.ai`, and emits `ai-ready`, `ai-tts-failure`, and
+`AI_AUDIO_OUTPUT_STATE_EVENT` (`'ai-audio-output-state'`).
 
 `fetch(...)` and `fetchRequest(options)` are asynchronous complete-response
 entry points. `streamMessage(...)` and `streamRequest(options)` deliver
@@ -496,7 +498,35 @@ cancelling one handle does not cancel another active matching caller.
 Preparation cancellation prevents later synthesis and releases its activation
 interest. The provider's operation remains responsible for actual cleanup.
 
-`playPreparedTTS(prepared,{signal,onState})` can attach immediately. Its returned
+`await readPreparedTTS({parts,textFormat,storage,identity,signal,onState})`
+returns a complete ready preparation handle or `null`. It uses the same original
+parts, selected speech configuration, voice/speed/pause values, text treatment,
+segmentation, and application identity as `prepareTTS()` for semantic matching.
+It never activates or unmutes a provider, synthesizes, starts playback, writes
+storage, or repairs a partial record. With storage, it reads the existing
+manifest and every ordered audio reference through the existing per-key storage
+queue. It passes `{createTable:false}` to DBOPFS manifest and audio reads,
+including later handle reads, so missing tables stay absent. Supplied database
+adapters are responsible for honoring that read-existing contract.
+No matching record or any missing audio returns `null`; unreadable
+metadata and other storage errors reject. Without storage, only a completed,
+matching, same-AI retained in-memory preparation can be returned; pending or
+failed work returns `null`.
+
+A hit returns `{segments,state,ready,getAudio(index),cancel()}` with `state`
+and every segment already `ready`; `onState` synchronously replays that state.
+A miss emits no state callback. The lookup signal rejects cancellation as
+`AbortError` and detaches when lookup settles; aborting it after success does
+not cancel the returned handle. An already-started non-abortable database read
+may finish after cancellation; observed cancellation prevents subsequent reads
+or a returned handle. The handle's explicit `cancel()` retains its
+own lifetime. Durable `getAudio(index)` reopens the stored file with its retained
+MIME type, so a later file removal remains an observable error. Native speech
+without audio export rejects with `ARCANE_AI_TTS_AUDIO_EXPORT_UNAVAILABLE`, as
+`prepareTTS()` does. Pass a returned handle to `playPreparedTTS()` only when
+playback is wanted.
+
+`playPreparedTTS(prepared,{signal,onState,audioOutput})` 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
@@ -521,6 +551,38 @@ 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.
 
+`prepareAudioOutput()` synchronously creates or reuses this AI's persistent
+WebAudio context and returns the same handle until disposed or closed. It is
+silent: no resume, unmute, model load, source creation, test sound, or gesture
+listener registration. The handle exposes `kind:'web-audio'`, current
+`state`, `contextState`, and complete `error` getters, plus
+`subscribe(listener)`, `resume()`, and `dispose()`.
+`subscribe` immediately replays `{kind,state,contextState,error}`, observes
+future changes for this output, and returns an idempotent unsubscribe function.
+The named `AI_AUDIO_OUTPUT_STATE_EVENT` export identifies canonical occurrences
+with that snapshot as `detail` and an output-specific `operationId`.
+
+Output `ready` means its context is actually `running`, independently of model
+readiness, HTML audio, native speech, future autoplay permission, or audible
+delivery. Other states are the platform's current state (including `suspended`
+or `interrupted`), `gesture-required` after an actual `NotAllowedError`,
+`unavailable` when context creation fails, `error`, `disposing`, `disposed`,
+or `closed`. Explicit `resume()` resolves a boolean for actual readiness;
+unavailable/disposed, superseded, or paused-playback cases resolve `false`.
+Platform rejection rejects with the actual error and retains observable state.
+
+Pass `{audioOutput}` to `playPreparedTTS` to borrow that same AI's live output;
+another owner's, closed, or disposing handle throws `TypeError`. Borrowed
+playback leaves the context open after completion or stop. Omission or `null`
+preserves the existing per-playback context and terminal context close.
+Owner `dispose()` stops context-bound playback and dependent clock work,
+observes cleanup, and awaits actual close without cancelling detached speech
+preparation or deleting saved audio. Concurrent disposal calls share their
+promise; failures remain observable and a failed close can be retried.
+Disposal/closure releases handle subscriptions after their final notification.
+See [silent reusable output](ai/browser-speech.md#prepare-a-silent-reusable-webaudio-output)
+for state details and usage.
+
 Streaming speech retains sentence
 segmentation by default. `configureTTSSegmentation({punctuation,wordCadence})`
 accepts `punctuation:'sentence'|'any'|'none'` and a `wordCadence` that is either
@@ -2221,6 +2283,23 @@ default `DBOPFS`; installs `window.dbopfs`, emits `dbopfs-ready`; table/file/bac
 
 Exact exports: `DBOPFS_EVENT_TYPES`, `DBOPFS_REASONS`, `default`.
 
+`getTableHandle(tableName='', {create=true}={})` lazily opens or creates the
+requested table by default. `{create:false}` looks up only an existing table
+without joining a pending create request; a missing table rejects with the
+platform's `NotFoundError`. The existing `memories` / `memory` alias is retained.
+`readFile(tableName='', fileName='', {createTable=true}={})` returns the complete
+raw file. `{createTable:false}` also prevents table creation, and missing tables
+or files reject with `NotFoundError`. Its synchronous-access worker fallback
+already opens existing app/table/file handles without creating them.
+
+`get(tableName='', fileName='', force=false, {createTable=true}={})` retains its
+existing parsed-value cache and `force` behavior, forwarding `createTable` when
+it reads a file. On a read, `NotFoundError` resolves `null`; other errors reject.
+Use `get(tableName,fileName,true,{createTable:false})` for an existing-storage
+lookup that does not return an earlier cached value. Omitted options preserve the previous
+lazy table-creation behavior. These options change neither write operations nor
+the owning app scope's initialization.
+
 `subscribeChanges(listener, {signal, once})` observes
 `DBOPFS_EVENT_TYPES.change` (`dbopfs-change`) through the existing canonical
 `arcane-os/event-manager` source. It returns an idempotent unsubscribe function
@@ -3616,10 +3695,11 @@ console.log(Object.keys(module));
 
 ### 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.
+Shared preparation mechanism used by `AI.prepareTTS()` and `AI.readPreparedTTS()`.
+It owns ordered generation admission, same-owner request sharing, complete audio
+storage and semantic reuse, cache-only lookup, and each caller's preparation
+lifetime. It does not construct an audio context, play speech, or select
+application content.
 
 ### Public surface
 
@@ -3628,10 +3708,29 @@ 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
+`AI.prepareTTS()`, `AI.readPreparedTTS()`, 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).
 
+Named async `readPreparedSpeech({owner,parts,originalParts=parts,selection=null,
+segmentation=null,storage=null,identity=null,signal=null,onState=null})` uses
+the same complete semantic matcher and resolves a ready preparation handle or
+`null`. It performs no synthesis, model activation, playback, storage writes,
+or repair. A durable lookup reads the existing manifest and every audio file;
+missing matching records or audio return `null`, while malformed metadata and
+other read failures reject. Manifest, audio availability, and returned-handle
+audio reads pass `{createTable:false}` to DBOPFS so a missing table is never
+created; supplied adapters own the same read-existing behavior. Without storage
+it reads only a completed matching same-owner in-memory preparation, never
+pending or failed work. A hit replays
+ready state through `onState`; a miss emits nothing. Lookup cancellation rejects
+with `AbortError` and is detached on settlement. After success the returned
+handle's explicit `cancel()` is independent of the lookup signal; its `ready`
+resolves the complete record and `getAudio(index)` preserves the existing MIME
+and later-read error behavior. Already-started non-abortable database reads may
+settle after cancellation; no further reads or handle are returned after the
+cancellation is observed.
+
 `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
@@ -3639,13 +3738,14 @@ 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`.
+Exact exports: `prepareSpeech`, `readPreparedSpeech`.
 
 ### 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.
+**Browser or native WebView with Blob, AbortController, optional ready DBOPFS,
+and an injected synthesis callback for generation.** Import creates no provider or
+playback. Calling `prepareSpeech` starts owned asynchronous generation/reuse;
+`readPreparedSpeech` only reads existing complete audio.
 `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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arcane-os",
-  "version": "0.76.0",
+  "version": "0.78.0",
   "description": "Arcane OS JavaScript SDK, project-local CLI, browser runtime, and repository-portable application packager.",
   "type": "module",
   "main": "./src/index.mjs",
@@ -125,7 +125,7 @@
     "test:unit": "node ./bin/arcane-test.mjs test/app-descriptor.test.mjs test/app-schema.test.mjs test/app-selection.test.mjs test/contracts.test.mjs test/conversation-closing-report.test.mjs test/doctor.test.mjs test/mail-credentials.test.mjs test/mail-outbox.test.mjs test/mail-public-api.test.mjs test/mail-send.test.mjs test/mail-transport.test.mjs test/native-windows-icon.test.mjs test/targets.test.mjs test/workspace-operation-lock.test.mjs",
     "test:functional": "node ./bin/arcane-test.mjs test/ai-ollama-readiness.test.mjs test/core-ollama-lifecycle.test.mjs test/ai-request-model.test.mjs test/ai-request-retry.test.mjs test/ai-stream-cancellation.test.mjs test/browser-decisions.test.mjs test/browser-kokoro-complete-input.test.mjs test/browser-speech-providers.test.mjs test/browser-speech-artifacts.test.mjs test/browser-speech-resource-bridge.test.mjs test/browser-wasm-gpu-notice.test.mjs test/browser-wasm-download-resume.test.mjs test/chat-input.test.mjs test/chat-stream-speech.test.mjs test/chat-transcript-scroll.test.mjs test/chat-transient-retention.test.mjs test/cli.test.mjs test/continuous-voice-capture.test.mjs test/codex-app-server.test.mjs test/mcp-stdio-server.test.mjs test/core-classic-source.test.mjs test/core-client.test.mjs test/core-client-installation.test.mjs test/core-ai-installation.test.mjs test/core-llama-lifecycle.test.mjs test/core-development.test.mjs test/core-host.test.mjs test/core-shared-host.test.mjs test/core-model-assets.test.mjs test/core-native-services.test.mjs test/core-packaged-web.test.mjs test/core-runtime.test.mjs test/core-stdio.test.mjs test/dbopfs-committed-events.test.mjs test/dbopfs-document-library.test.mjs test/dbopfs-model-resources.test.mjs test/dbopfs-png.test.mjs test/dbopfs.test.mjs test/dev-server.test.mjs test/dev-pwa.test.mjs test/dom-event-instrumentation.test.mjs test/event-manager.test.mjs test/events.test.mjs test/file-preview.test.mjs test/import-map.test.mjs test/local-image-editing.test.mjs test/mail-cli.test.mjs test/mail-runtime.test.mjs test/mail-server.test.mjs test/markdown-editor.test.mjs test/markdown-media.test.mjs test/markdown-source-map.test.mjs test/modal.test.mjs test/model-resource-bridge.test.mjs test/native-decisions.test.mjs test/native-onnx.test.mjs test/native-module-packaging.test.mjs test/native-module-resource-references.test.mjs test/packaging.test.mjs test/pwa-packaging.test.mjs test/pwa-client.test.mjs test/pwa-install.test.mjs test/pwa-worker.test.mjs test/persistent-ai-chat-session.test.mjs test/reference-completeness.test.mjs test/rendered-print.test.mjs test/runtime-api-behavior.test.mjs test/runtime.test.mjs test/scaffold.test.mjs test/speech-playback.test.mjs test/site.test.mjs test/theme-manager.test.mjs test/twin-cloud-images.test.mjs test/twin-cloud.test.mjs test/websocket-client-import-map.test.mjs test/websocket.test.mjs test/update-check.test.mjs test/user-explicit-updates.test.mjs",
     "test:integration": "node ./bin/arcane-test.mjs test/installed-package-runtime.test.mjs test/root-app-layout.test.mjs test/integrated-shared.test.mjs test/integrated-workspace.test.mjs test/mail-browser.test.mjs test/native-macos-provider.test.mjs test/native-plan.test.mjs test/native-portable-provider.test.mjs test/native-provider-loader.test.mjs test/npm-release.test.mjs test/release-bundle.test.mjs test/release-capability-smoke.test.mjs test/shared-payload-batch.test.mjs test/tarball.test.mjs test/browser-wasm-cpu.test.mjs test/wllama-webgpu-runtime.test.mjs",
-    "test:regression": "node ./bin/arcane-test.mjs test/channel-workflows.test.mjs test/html-import-registration.test.mjs test/html-import-packaged-script.test.mjs test/logging-regression.test.mjs test/markdown-speech.test.mjs test/prepared-speech.test.mjs test/native-provider-generation.test.mjs test/speech-queue-regression.test.mjs test/testing.test.mjs test/test-sets.test.mjs",
+    "test:regression": "node ./bin/arcane-test.mjs test/channel-workflows.test.mjs test/html-import-registration.test.mjs test/html-import-packaged-script.test.mjs test/logging-regression.test.mjs test/markdown-speech.test.mjs test/prepared-speech.test.mjs test/ai-audio-output.test.mjs test/native-provider-generation.test.mjs test/speech-queue-regression.test.mjs test/testing.test.mjs test/test-sets.test.mjs",
     "check": "node tools/check-source.mjs && npm test",
     "check:release": "node tools/check-source.mjs --package-only && npm run test:release",
     "pack:local": "npm pack --ignore-scripts",