arcane-os 0.5.17 → 0.5.18

package/browser-runtime/speech-text.mjs

@@ -1,3 +1,7 @@
+import Is from './dependencies/strong-type/index.js';
+
+const is=new Is(false);
+
 function stripSpeechFormatting(text=''){
     return text.replace(/([*#_`~])\1+/g,'');
 }
@@ -7,7 +11,7 @@ class MarkdownSpeech {
     #pending='';
 
     append(text='',end=false){
-        if(typeof text!=='string'){
+        if(!is.string(text)){
             throw new TypeError('Markdown speech input must be text.');
         }
 

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

@@ -13,7 +13,7 @@ import map resolves `arcane/AI` and `arcane/DBOPFS`. These browser modules are
 not Node inference APIs. To create an application:
 
 ```bash
-npx arcane-os@0.5.17 new hello-speech --path ./hello-speech --target browser
+npx arcane-os@0.5.18 new hello-speech --path ./hello-speech --target browser
 cd hello-speech
 npm install
 npm run dev
@@ -280,8 +280,9 @@ passage synchronously before `Promise.all` waits, so synthesis can use the
 provider's available capacity. The returned array has one boolean per passage
 in input order: `true` after all its extracted audio buffers naturally end,
 or `false` after terminal cancellation or failure. `ai.stopAudio()` cancels
-all speech owned by that AI instance and settles pending playback results
-`false`.
+streamed speech and prepared playback owned by that AI instance and settles
+pending playback results `false`. Detached preparation described below keeps
+its independent lifetime.
 
 The selected voice and speed are captured for segments extracted by that call.
 That includes any text left in the same AI instance's partial-stream buffer;
@@ -301,6 +302,198 @@ pause delays the next queued audio on the existing `AudioContext` clock; it
 does not delay the preceding promise after that passage's last buffer ends.
 The promise is a playback result, not a listener acknowledgement.
 
+## Prepare narration once and replay stored audio
+
+Use `ai.prepareTTS()` when preparation must continue independently of playback,
+or when a later visit should reuse generated audio. It returns a handle
+synchronously and starts preparing the supplied complete parts without speaking
+them. Attach `ai.playPreparedTTS()` immediately to play those parts as their
+audio becomes available, or omit playback to prepare them silently.
+
+Use the configured `ai` and ready, application-owned `dbopfs` from the quick
+start. Configuration itself does not load Kokoro. This path reads stored audio
+first: a complete match can replay while the AI starts muted, with no model
+load. Only missing audio requests the selected provider's shared load/unmute
+path. Do not eagerly call `setSpeechMuted(false)` before this path if fully
+cached playback should avoid loading the model.
+
+```javascript
+ai.configureTTSSegmentation(
+    {
+        punctuation: 'any',
+        wordCadence: null
+    }
+);
+
+function prepareNarration(text, key) {
+    return ai.prepareTTS(
+        {
+            parts: [
+                {
+                    input: text,
+                    voice: speechSelection.model.defaultVoice,
+                    speed: 1,
+                    pauseAfterMs: 0
+                }
+            ],
+            storage: {
+                db: dbopfs,
+                table: 'saved_narration',
+                key
+            },
+            identity: {
+                model: speechSelection.model,
+                runtime: speechSelection.runtime
+            },
+            onState: reportNarrationPreparation
+        }
+    );
+}
+
+function reportNarrationPreparation(state) {
+    console.log('Narration preparation:', state);
+}
+
+function reportNarrationPlayback(state) {
+    console.log('Narration playback:', state);
+}
+
+async function readNarration(text, key) {
+    const prepared = prepareNarration(text, key);
+    const playback = ai.playPreparedTTS(
+        prepared,
+        {onState: reportNarrationPlayback}
+    );
+    const [record, ended] = await Promise.all(
+        [prepared.ready, playback.finished]
+    );
+    return {record, ended};
+}
+```
+
+Call `readNarration('**Hello**. Welcome back.', 'welcome')` from an owned user
+action and handle its rejection. Calling only `prepareNarration(...)` prepares
+silently; observe that handle's `ready` promise to receive its complete record
+or error. A storage key groups application content. The application owns its
+keys, preparation priority, semantic identity, and retention policy; the SDK
+does not select another page or speak background work.
+
+### Preparation inputs and reuse
+
+`ai.prepareTTS({parts,storage,identity,signal,onState})` accepts an ordered array
+of strings or `{input,voice?,speed?,pauseAfterMs?}` records. An omitted voice
+uses the selected model default; omitted speed uses `ai.voiceSpeed`; omitted
+pause is zero. The SDK snapshots the selected speech configuration and current
+punctuation/word-cadence options for that preparation. A part's pause applies
+after its final extracted segment. Complete original input remains available
+for semantic comparison; automatic Markdown cleanup affects only the speech
+copy and occurs once before segmentation.
+
+`storage` is optional. When supplied, `{db,table,key}` names the caller's ready
+DBOPFS instance and its application-owned table/key. The SDK stores complete
+generated audio as raw files and retains MIME metadata separately so subsequent
+`Blob` playback preserves its content type. Reuse compares complete semantic
+inputs, including parts, selection, segmentation, and separate application
+`identity`. A changed voice, speed, source text, or other semantic selection
+prepares the changed request. An SDK patch version alone does not invalidate
+stored speech.
+
+The storage key is encoded as `encodeURIComponent(key) + '.json'` for its
+manifest. That version-1 manifest keeps an `entries` array of semantic variants
+under the key. Each entry records
+`{id,parts,originalParts,selection,segmentation,identity,segments}`; the ordered
+stored segment entries name `{audioFile,contentType}`. `originalParts` retains
+the complete source text, including whitespace. These persistent semantic
+inputs and `identity` must be JSON-compatible. Raw audio filenames contain the
+generated record ID and segment index. Storage writes preserve existing
+variants; the application chooses when its records should be removed.
+
+Matching pending requests on the same AI instance and the same storage
+`db`/`table`/`key` share synthesis. Each caller receives its own handle and
+cancellation signal. Cancelling one handle detaches that caller; the shared
+preparation is aborted only when its last pending caller cancels. Different AI
+instances do not share an in-flight synthesis operation. Complete stored
+results remain reusable through the same application storage.
+After a durable preparation completes, a later preparation call rereads its
+manifest and saved-file presence, regenerating only missing segments. A
+completed preparation without storage reuses its retained Blobs.
+
+Preparation requests retain call order for synthesis admission. Within each
+request, punctuation segments use the existing bounded provider queue: the
+default Kokoro capacity admits up to four at once, with later segments waiting
+in FIFO order. Completion may be out of order; segment metadata and playback
+remain in input order. Preparing another request does not attach it to playback.
+
+### Preparation handle and progress
+
+| Member | Contract |
+| --- | --- |
+| `state` | Current string: `queued`, `preparing`, `ready`, `error`, or `cancelled`. |
+| `segments` | Ordered segment metadata with `input`, `voice`, `speed`, `pauseAfterMs`, `index`, `state`, `audioFile`, `contentType`, and `error`. |
+| `ready` | Promise resolving the complete ordered record when every segment is generated or reused and, when storage is supplied, durably saved. Rejects with the complete error or `AbortError` if cancelled while pending. |
+| `getAudio(index)` | Promise waiting for that ordered segment and returning its complete `Blob` with the recorded MIME type. |
+| `cancel()` | Cancels this preparation handle without erasing successful stored segments. |
+
+The optional synchronous `onState` callback receives
+`{state,completed,total,segments,error}`. It observes preparation only; it is
+not a playback-state callback. `completed` counts settled segments, including
+failed segments; inspect `state`, segment errors, and `ready` for the outcome.
+`total` is the number of ordered segments.
+Without `storage`, the handle retains generated Blobs for its lifetime; the
+same result shape has `audioFile:null` and the actual `contentType`.
+The supplied signal observes preparation until `ready` settles. Manual
+`cancel()` remains available afterward to stop further reads through that
+handle. If a raw audio write has already begun when cancellation arrives,
+its metadata transaction finishes so that successful audio can be reused;
+no later queued write starts for that cancelled preparation.
+Cancelling preparation prevents later synthesis, but the existing shared
+provider load/unmute operation has no per-preparation signal and may finish.
+Cancellation does not claim to stop an already-started shared model load.
+
+### Playback controls and independent lifetimes
+
+`ai.playPreparedTTS(prepared,{signal,onState})` returns
+`{state,error,finished,pause(),resume(),stop()}` immediately. It uses the
+existing AI audio-clock scheduler and waits for each earlier segment before scheduling
+later audio. Ready adjacent buffers retain contiguous scheduling. Requested
+pauses separate adjacent parts; a final trailing pause does not delay
+`finished`, which resolves after the final audio buffer ends.
+
+`state` and `error` are current-state getters. The optional synchronous
+`onState` callback receives `{state,error}` and is observational. Playback
+states are `waiting`, `waiting-for-gesture`, `scheduled`, `paused`, `complete`,
+`stopped`, and `error`. Use `waiting-for-gesture` to present an audio-unlock
+control. A `false` result from `resume()` is not a first-segment-ready signal;
+inspect `state` and `error` to distinguish a stopped or unavailable context
+from browser gesture waiting. The ordinary playback path creates its audio
+context immediately, before the first audio segment is ready.
+
+`finished` resolves `true` after natural playback completion and `false` after
+stop, playback cancellation, or failure. Real failures also reach the existing
+`ai-tts-failure` event and complete SDK diagnostics. `pause()`
+and `resume()` control only this handle's audio context, and `stop()` stops
+that playback handle. The controls return booleans; pause and resume are
+asynchronous. Each AI has one playback lane: a new `playPreparedTTS()` call
+stops its preceding streamed or prepared playback, and `streamTTS()` interrupts
+active prepared playback. This replacement preserves detached preparation.
+None of these playback controls cancels preparation or deletes saved audio.
+Use the preparation handle's `cancel()` or its separate `signal` when the
+application also wants to stop preparation. Successful saved segments survive
+cancellation or failure for later reuse.
+
+`ai.stopAudio()` stops streamed speech and all prepared playback on that AI,
+while detached preparation continues. `ai.setSpeechMuted(true)` additionally
+cancels provider TTS work and unloads the provider. Replacing the speech
+configuration cancels missing generation tied to the earlier selection.
+Neither action deletes completed stored audio. Apply those broader lifecycle
+controls deliberately when the application intends to stop provider work.
+
+Preparation `ready` and playback `finished` are separate promises. Natural
+playback completion must not be used as a signal to cancel other background
+preparations. A page that starts several preparations owns and observes every
+`ready` promise, even when it plays only one handle. Browser autoplay permission
+still applies; neither promise proves that a person heard the audio.
+
 ## Stream chunks as they arrive
 
 Use the configured `ai` created above. Run this snippet from an owned user
@@ -378,7 +571,7 @@ Applications omit that internal metadata. Displayed messages, saved history,
 model input, caller payload objects, language, voice, synthesis capacity, and
 playback timing are not changed by the filter.
 
-The dependency-free helper is public for code that needs the speech-only
+The shared helper is public for code that needs the speech-only
 transformation directly:
 
 ```javascript
@@ -466,7 +659,7 @@ These are actions for your own controls, using the same `ai` instance:
 
 ```javascript
 function stopSpeech() {
-  ai.stopAudio(); // Cancels queued speech and stops scheduled/playing audio.
+  ai.stopAudio(); // Stops streamed speech and all prepared playback.
 }
 
 async function muteSpeech() {

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

@@ -3,6 +3,46 @@
 Use this page to choose an API by capability. The compact labels tell you where
 it runs; the [protocol guide](protocols.md) contains the implementation detail.
 
+## Shared type predicates
+
+SDK-owned JavaScript uses the declared `strong-type` dependency for type
+predicates. Node and managed renderer modules import `Is` from `strong-type`;
+browser providers and workers use their shipped relative dependency path.
+Component scripts import it within their own asynchronous component scope.
+Publication bootstrap tools import the shipped runtime dependency by relative
+path so they remain available before npm dependency installation.
+The dependency pin and both shipped projections use 2.0.1. Update them together
+through the published dependency workflow when another version is needed.
+
+Reuse one non-throwing instance per module or component:
+
+```javascript
+import Is from 'strong-type';
+
+const is=new Is(false);
+
+function requireText(value){
+    if(!is.string(value))throw new TypeError('Text is required.');
+    return value;
+}
+```
+
+The predicates classify values without coercing them. Existing API owners keep
+their defaults, domain constraints, complete payloads, and public error behavior.
+Use `number` for primitive numbers, `finite` for finite numbers, and `integer`
+or `safeInteger` for the corresponding integer contract. `object` includes null;
+retain a contract's separate null and array handling. `plainObject` is narrower
+than a general non-array object check and must not silently reject previously
+accepted class instances.
+
+Constructor identity checks, diagnostic type labels, foreign-language source,
+and isolated generated script bodies retain native operators where a replacement
+would change their contract or execution scope. `DBOPFSWorker.js` and
+`SystemPlatformPresentation.js` retain their few native predicates to preserve
+classic-script loading and synchronous availability. Upstream dependency source is
+consumed unchanged. Non-throwing strong-type array and constructor probes return
+false when a probe throws; SDK branching continues through its owning error path.
+
 ## Availability labels
 
 | Label | Meaning |

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

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "sdkVersion": "0.5.17",
+  "sdkVersion": "0.5.18",
   "environment": {
     "runtime": "Node.js for Node entrypoints; browser for browser-only entrypoints",
     "minimumVersion": "22.23.2 for Node entrypoints",

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.5.17"
+    "sdkVersion": "0.5.18"
   },
   "componentCount": 39,
   "loader": "/arcane/modules/HTMLImport.js",

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

@@ -5,12 +5,12 @@
     "repository": "https://github.com/TheWizardNexus/arcane-os-sdk.git",
     "branch": "main",
     "path": "runtime/arcane",
-    "sdkVersion": "0.5.17",
+    "sdkVersion": "0.5.18",
     "protocol": "arcane/1"
   },
   "artifactCount": 85,
   "javascriptArtifactCount": 83,
-  "esmExportCount": 356,
+  "esmExportCount": 352,
   "artifacts": [
     {
       "file": "runtime/arcane/modules/AI.js",
@@ -29,8 +29,8 @@
       "summary": "Owns provider-selectable chat and the one-time caller-authority browser STT/TTS configuration, lifecycle, synthesis, transcription, and playback boundary.",
       "availability": "Browser + native bridge + TWiN Cloud",
       "protocol": "arcane-ai-browser-speech-configuration/1, AIProviderRuntime arcane-ai-provider/2 routes, globalThis.arcaneEvents, TWiN Cloud HTTPS, Arcane.ollama, Arcane.speech, Android WebView bridge",
-      "normalization": "Complete mutable caller-owned browser speech authority, SDK-owned provider registration/replacement/disposal, explicit STT/TTS activation, normalized Kokoro TTS execution with default capacity 4, explicit provider-neutral execution snapshots through status(role,{execution:true}), sticky readiness, canonical window.user readiness without compatibility-event object-identity admission or polling, exact ordered structural calls with required arguments.message, atomic nonblank all-ID tool-result sequencing, complete all-choice streaming/data validation, native Ollama structural adaptation, complete-response then all validated tool callbacks then completion ordering, observed async callbacks, Blob/File transcription, automatic repeated-formatting-mark removal from cloned outbound TTS input while caller and visible content stays exact, immediate exact-segment synthesis, per-call voice/speed capture, optional final-segment pause on the existing audio clock, optional per-call terminal playback completion, ordered audio-clock scheduling, playable audio, active-generation TTS operation-failure routing, mute, and cancellation are normalized; provider/model/runtime/voice policy remains caller-owned.",
-      "surface": "Browser-speech protocol/event/error/reason constants; default `AI`; read-only `providerRuntime`, `browserSpeechConfiguration`, and `browserSpeechDescriptor`; explicit `providerRuntime.status(role,{execution:true})` snapshots; `streamTTS(text,end,options={})` with optional voice, speed, pauseAfterMs, and waitForPlayback; automatic speech-input cleanup with SDK-internal preparation metadata; configure/dispose speech, route lifecycle, declaration-validated chat/stream requests with exact ordered calls, synthesis/transcription, and playback controls; initializes from current canonical user readiness, installs `window.ai`, and projects `ai-ready` plus active-generation `ai-tts-failure`."
+      "normalization": "Complete mutable caller-owned browser speech authority, SDK-owned provider registration/replacement/disposal, explicit STT/TTS activation, normalized Kokoro TTS execution with default capacity 4, explicit provider-neutral execution snapshots through status(role,{execution:true}), sticky readiness, canonical window.user readiness without compatibility-event object-identity admission or polling, exact ordered structural calls with required arguments.message, atomic nonblank all-ID tool-result sequencing, complete all-choice streaming/data validation, native Ollama structural adaptation, complete-response then all validated tool callbacks then completion ordering, observed async callbacks, Blob/File transcription, automatic repeated-formatting-mark removal from cloned outbound TTS input while caller and visible content stays exact, immediate exact-segment synthesis, per-call voice/speed capture, optional final-segment pause on the existing audio clock, optional per-call terminal playback completion, detached preparation with complete semantic DBOPFS audio reuse and same-owner pending request sharing, independent prepared playback without a model load for cached audio, ordered audio-clock scheduling, playable audio, active-generation TTS operation-failure routing, mute, and cancellation are normalized; provider/model/runtime/voice policy remains caller-owned.",
+      "surface": "Browser-speech protocol/event/error/reason constants; default `AI`; read-only `providerRuntime`, `browserSpeechConfiguration`, and `browserSpeechDescriptor`; explicit `providerRuntime.status(role,{execution:true})` snapshots; `streamTTS(text,end,options={})` with optional voice, speed, pauseAfterMs, and waitForPlayback; automatic speech-input cleanup with SDK-internal preparation metadata; `prepareTTS({parts,storage,identity,signal,onState})` returning ordered segments, state, ready, getAudio(index), and cancel(); `playPreparedTTS(prepared,{signal,onState})` returning state, error, finished, pause(), resume(), and stop() with one playback lane per AI and observational state/error callbacks; configure/dispose speech, route lifecycle, declaration-validated chat/stream requests with exact ordered calls, synthesis/transcription, and playback controls; initializes from current canonical user readiness, installs `window.ai`, and projects `ai-ready` plus active-generation `ai-tts-failure`."
     },
     {
       "file": "runtime/arcane/modules/AIPreferenceRuntime.js",
@@ -79,23 +79,6 @@
       "normalization": "Normalizes mutable complete per-role routes, lifecycle/status, cancellation, streaming cleanup, capacity-1 FIFO LLM/STT lanes, bounded provider-declared parallel TTS requests with FIFO overflow, automatic repeated-formatting-mark removal from cloned direct TTS payloads, local-only selection, direct LLM history/declaration/terminal structural contracts, complete all-choice content/reasoning FIFO iteration, private automatic provider draining with result-first buffering, terminal-only structural calls, exact per-choice observed/terminal correlation, and a separate complete validated terminal result without creating a fallback.",
       "surface": "Protocol constants; singleton-only `AIProviderRuntime`; `aiProviderRuntime`; `getAIProviderRuntime()`; provider registration/identity/selection, closed three-role and STT/TTS-only validation/configuration/replacement, status/catalog/inspection, startup, per-role load/unload/dispose/cancel, dispose-all, request/stream/speech aliases, SDK-internal speech-input preparation metadata, and mute controls."
     },
-    {
-      "file": "runtime/arcane/modules/AIResponseLength.js",
-      "name": "AIResponseLength.js",
-      "kind": "esm",
-      "exports": [
-        "AI_RESPONSE_LENGTH_DEFAULT",
-        "AI_RESPONSE_LENGTH_OPTIONS",
-        "aiResponseLengthInstruction",
-        "applyAIResponseLength",
-        "normalizeAIResponseLength"
-      ],
-      "summary": "Normalizes low/medium/high response-preference selectors while leaving complete prompts unchanged.",
-      "availability": "Cross-host",
-      "protocol": "In-process only",
-      "normalization": "Selectors normalize to low, medium, or high; every label is Complete, the instruction is empty, and prompt content remains unchanged.",
-      "surface": "Response-preference constants plus `normalizeAIResponseLength()`, `aiResponseLengthInstruction()`, and `applyAIResponseLength()`."
-    },
     {
       "file": "runtime/arcane/modules/AIResponseURLPolicy.js",
       "name": "AIResponseURLPolicy.js",
@@ -108,8 +91,8 @@
       ],
       "summary": "Extracts and audits links from AI Markdown, rendered HTML, CSS, srcset, bare URLs, and email text.",
       "availability": "Cross-host",
-      "protocol": "In-process; bundled Marked parser",
-      "normalization": "Normalized frozen allowlist audit.",
+      "protocol": "In-process; bundled Marked parser and native HTML parsing when a document is available",
+      "normalization": "Mutable audit with exact link comparison after entity and Markdown escape decoding, without URI canonicalization or response mutation. Browsers use native HTML parsing; hosts without a document retain lexical extraction and the existing limited entity decoder. Already decoded rendered values are not decoded again. Authored links retain source offsets; DOM-only attribute links use document order after authored links.",
       "surface": "`auditAIResponseLinks()`, `extractAIResponseLinks()`, `normalizeAIResponseLink()`, `decodeHTMLCharacterReferences()`."
     },
     {
@@ -834,7 +817,7 @@
       "summary": "Re-exports the shared MarkdownSpeech class that removes repeated same formatting marks from streamed narration before speech segmentation.",
       "availability": "Cross-host",
       "protocol": "Shared arcane-os/speech-text package entrypoint",
-      "normalization": "The runtime projection and public package subpath share dependency-free speech-only filtering of repeated *, #, _, backtick, and ~ runs across chunks; single marks and all other characters remain literal; terminal flush and reset clear pending formatting state.",
+      "normalization": "The runtime projection and public package subpath share speech-only filtering of repeated *, #, _, backtick, and ~ runs across chunks; single marks and all other characters remain literal; terminal flush and reset clear pending formatting state.",
       "surface": "`MarkdownSpeech`; `append(text='',end=false)`, `reset()`."
     },
     {
@@ -1018,6 +1001,19 @@
       "normalization": "Complete ordinary values remain mutable; setAll uses one optional atomic adapter batch for every selected value when advertised, otherwise retains complete serial per-key compatibility, never retries a rejected dispatched batch serially, and only exact unsupported native capability changes future operations to the browser fallback.",
       "surface": "Event/error constants, default `PreferenceStore`, re-exported `Preference`/schema; load/set/setAll/reset APIs, required adapter get/set/delete plus optional setMany, state-free EventTarget/on compatibility, and `dispose()`."
     },
+    {
+      "file": "runtime/arcane/modules/PreparedSpeech.js",
+      "name": "PreparedSpeech.js",
+      "kind": "esm",
+      "exports": [
+        "prepareSpeech"
+      ],
+      "summary": "Owns detached ordered speech preparation, complete semantic audio reuse, and per-caller cancellation behind AI.prepareTTS.",
+      "availability": "Browser or native WebView with Blob, AbortController, an injected synthesis callback, and optional ready DBOPFS",
+      "protocol": "In-process preparation handle plus caller-owned DBOPFS raw audio and version-1 semantic manifest",
+      "normalization": "Preserves complete original parts and JSON-compatible semantic context, shares pending matching work on the same owner/storage group, admits segments in order, stores complete Blobs and MIME metadata, retains successful audio after failure or cancellation, and separates generation readiness from playback.",
+      "surface": "Named prepareSpeech({owner,parts,originalParts,selection,segmentation,storage,identity,signal,onState,synthesize}) returns {segments,state,ready,getAudio(index),cancel()}; applications use AI.prepareTTS and AI.playPreparedTTS so the shared AI owner retains segmentation, provider readiness, capacity, and playback."
+    },
     {
       "file": "runtime/arcane/modules/QRCode.min.js",
       "name": "QRCode.min.js",

package/docs/reference/protocols.md

@@ -66,7 +66,7 @@ portable subpaths that resolve directly to canonical runtime-module namespaces
 from both Node package exports and managed browser keys;
 `arcane/PreferenceStore` and `arcane/SpeechPlayback` remain their established
 browser import-map names. The additional portable `arcane-os/speech-text`
-subpath owns shared dependency-free speech-input cleanup and has the same
+subpath owns shared speech-input cleanup and has the same
 managed browser key. There is
 no exported `importMapApplication()` function, `generateImportMap()` function, or
 `arcane-os/import-map` package subpath.