arcane-os 0.45.0 → 0.47.0

package/CHANGELOG.md

@@ -1,5 +1,44 @@
 # Changelog
 
+## 0.47.0
+
+- Add explicitly selected native browser speech recognition through
+  `createBrowserSpeechRecognitionProvider` in `arcane-os/ai/browser-speech`.
+  The provider uses the browser's SpeechRecognition capability without an SDK
+  model download or storage. It declares non-local behavior because the browser
+  may use its own remote recognition service. Applications own Profile selection
+  and language; Whisper, TTS, typing and existing defaults remain unchanged.
+- Own live capture through the existing independent STT runtime. Start stays in
+  the initiating user gesture; Stop drains final recognition, while cancellation,
+  provider replacement and cleanup suppress late results. Unsupported browsers
+  retain provider construction/catalog and report unavailability on activation.
+- Display native interim recognition immediately in transient shared controls.
+  Chat receives one complete combined final transcription at capture end;
+  continuous voice appends and saves confirmed segments in order through its
+  existing retryable save queue. Interim hypotheses are neither saved nor
+  submitted, and existing saved data is unchanged.
+
+## 0.46.0
+
+- Add public `decodeMarkdownMediaRecord` for complete stored image records or
+  JSON text without storage or network access. Preserve singleton record layers,
+  original content and explicit decoding errors; never select from multiple
+  records. File previews recognize declared image records in JSON-family files
+  while ordinary untyped/non-image JSON and application preview hooks keep their
+  existing presentation and precedence.
+- Preserve complete standalone IMG tags with multiline quoted descriptions
+  through the shared Markdown renderer and its original-source mapping. Native
+  HTML handling and literal Markdown examples keep their existing parsing;
+  stored Markdown is unchanged and requires no migration.
+- Use the existing light paper palette and 15mm page margins for rendered print
+  snapshots and direct shared-theme printing. Preserve full content, rendered
+  fonts, image pixels, SVG artwork, live screen preferences, cancellation and
+  resource ownership through afterprint. A dialog request is not proof of
+  physical printing or PDF completion.
+- Keep image destinations, export selection, model and credentials application
+  owned. No saved-data migration, model/provider/default change or app layout
+  change is introduced.
+
 ## 0.45.0
 
 - Add public MarkdownMedia save, read, reference parsing and hydration helpers.

package/README.md

@@ -19,7 +19,7 @@ version-locked SDK runtime, while an integrated Arcane checkout uses its live
 `arcane/` runtime. Both profiles share the theme, packaging, event, cancellation,
 and browser run contracts while retaining their selected application layout.
 
-This checkout defines the `0.45.0` SDK contract. Applications pin one exact npm
+This checkout defines the `0.47.0` SDK contract. Applications pin one exact npm
 version and lockfile; registry state is deliberately not baked into application
 artifacts.
 

package/browser-runtime/ai/browser-speech-recognition.mjs

@@ -0,0 +1,495 @@
+import Is from '../dependencies/strong-type/index.js';
+import {arcaneLogging} from '../logging.mjs';
+
+const is = new Is(false);
+
+function recognitionError(message, code, cause) {
+    const error = cause === undefined
+        ? new Error(message)
+        : new Error(
+            message,
+            {cause}
+        );
+    error.code = code;
+    return error;
+}
+
+function recognitionConstructor() {
+    if (is.function(globalThis.SpeechRecognition)) return globalThis.SpeechRecognition;
+    if (is.function(globalThis.webkitSpeechRecognition)) return globalThis.webkitSpeechRecognition;
+    return null;
+}
+
+function unavailableRecognition() {
+    return recognitionError(
+        'Native browser speech recognition is unavailable in this browser.',
+        'ARCANE_AI_SPEECH_RECOGNITION_UNAVAILABLE'
+    );
+}
+
+function assertIdentifier(value, label) {
+    if (!is.string(value) || !value || value.trim() !== value) {
+        throw new TypeError(`${label} must be a nonempty string without surrounding whitespace.`);
+    }
+}
+
+/**
+ * Browser-owned live recognition, which may use a remote recognition service.
+ * Loading selects the capability; only capture.start() opens a native session.
+ */
+export function createBrowserSpeechRecognitionProvider(
+    {id, model, language} = {}
+) {
+    assertIdentifier(id, 'Browser speech recognition provider id');
+    assertIdentifier(model?.id, 'Browser speech recognition model id');
+    if (language !== undefined && !is.string(language)) {
+        throw new TypeError('Browser speech recognition language must be a string.');
+    }
+
+    const modelId = model.id;
+    let state = 'unloaded';
+    let generation = 0;
+    let activeCapture = null;
+    let unloadOperation = null;
+    let disposeOperation = null;
+
+    function authority() {
+        return {
+            protocol: 'arcane-ai-model-authority/1',
+            providerId: id,
+            modelId,
+            role: 'stt',
+            localOnly: false
+        };
+    }
+
+    function assertSelection(selection) {
+        if (selection && (selection.providerId !== id
+            || selection.modelId !== modelId
+            || selection.localOnly === true
+            || (selection.role !== undefined && selection.role !== 'stt'))) {
+            throw recognitionError(
+                'The selected browser speech model does not match this provider.',
+                'ARCANE_AI_MODEL_AUTHORITY_REQUIRED'
+            );
+        }
+    }
+
+    function assertContext(context) {
+        if (context.role !== undefined && context.role !== 'stt') {
+            throw recognitionError('This provider supports only STT.', 'ARCANE_AI_INVALID_REQUEST');
+        }
+        assertSelection(context.selection);
+        if (context.signal?.aborted) {
+            const error = recognitionError(
+                'The browser speech operation was cancelled.',
+                'ARCANE_AI_REQUEST_ABORTED',
+                context.signal.reason
+            );
+            error.name = 'AbortError';
+            throw error;
+        }
+    }
+
+    function status() {
+        const loaded = state === 'ready';
+        return {
+            providerId: id,
+            role: 'stt',
+            modelId,
+            localOnly: false,
+            state,
+            loaded,
+            busy: activeCapture !== null,
+            execution: {
+                requestedDevice: 'browser-native',
+                selectedDevice: loaded ? 'browser-native' : null,
+                maxConcurrentRequests: 1,
+                activeRequestCount: activeCapture === null ? 0 : 1
+            }
+        };
+    }
+
+    function createCapture(
+        {
+            onSegment,
+            onInterim,
+            onState,
+            onError,
+            language: captureLanguage = language,
+            continuous = true
+        } = {}
+    ) {
+        const captureGeneration = generation;
+        let recognizer = null;
+        let signal = null;
+        let started = false;
+        let nativeStarted = false;
+        let receivedStart = false;
+        let stopping = false;
+        let cancelled = false;
+        let failed = false;
+        let settled = false;
+        let captureState = null;
+        let lastFinalIndex = -1;
+        let sequence = 0;
+        let resolveStarted = null;
+        let resolveDone;
+        const done = new Promise(
+            function waitForRecognitionEnd(resolve) {
+                resolveDone = resolve;
+            }
+        );
+
+        function reportError(error) {
+            if (!is.function(onError)) {
+                arcaneLogging.error('Browser speech recognition failed:', error);
+                return;
+            }
+            try {
+                const operation = onError(error);
+                Promise.resolve(operation).catch(reportErrorCallbackFailure);
+            } catch (callbackError) {
+                reportErrorCallbackFailure(callbackError);
+            }
+        }
+
+        function reportErrorCallbackFailure(error) {
+            arcaneLogging.error('Browser speech recognition error handler failed:', error);
+        }
+
+        function observeCallbackFailure(error) {
+            const callbackError = recognitionError(
+                'A browser speech recognition callback failed.',
+                'ARCANE_AI_SPEECH_CALLBACK_FAILED',
+                error
+            );
+            if (settled || cancelled || failed) {
+                reportError(callbackError);
+                return;
+            }
+            interrupt(callbackError);
+            abortNative();
+        }
+
+        function notify(callback, value) {
+            if (!is.function(callback)) return;
+            try {
+                const operation = callback(value);
+                Promise.resolve(operation).catch(observeCallbackFailure);
+            } catch (error) {
+                observeCallbackFailure(error);
+            }
+        }
+
+        function publishState(nextState) {
+            if (captureState === nextState) return;
+            captureState = nextState;
+            notify(onState, nextState);
+        }
+
+        function settleStarted(success) {
+            if (!resolveStarted) return;
+            const resolve = resolveStarted;
+            resolveStarted = null;
+            resolve(success);
+        }
+
+        function finish(success) {
+            if (settled) return;
+            settled = true;
+            nativeStarted = false;
+            signal?.removeEventListener('abort', cancel);
+            signal = null;
+            if (recognizer) {
+                recognizer.onstart = null;
+                recognizer.onresult = null;
+                recognizer.onerror = null;
+                recognizer.onend = null;
+                recognizer = null;
+            }
+            if (activeCapture === capture) activeCapture = null;
+            settleStarted(false);
+            publishState(failed ? 'interrupted' : 'stopped');
+            resolveDone(success);
+        }
+
+        function interrupt(error) {
+            if (failed || settled) return;
+            failed = true;
+            settleStarted(false);
+            reportError(error);
+            publishState('interrupted');
+        }
+
+        function abortNative() {
+            if (settled) return;
+            if (!nativeStarted) {
+                finish(false);
+                return;
+            }
+            try {
+                recognizer.abort();
+            } catch (error) {
+                const abortError = recognitionError(
+                    'Native browser speech recognition could not be cancelled.',
+                    'ARCANE_AI_SPEECH_RECOGNITION_ABORT_FAILED',
+                    error
+                );
+                if (failed) reportError(abortError);
+                else interrupt(abortError);
+                // An unsuccessful abort is not evidence of native end. Keep
+                // the session owned until the browser reports disconnection.
+            }
+        }
+
+        function cancel() {
+            if (settled || cancelled) return done;
+            cancelled = true;
+            settleStarted(false);
+            abortNative();
+            return done;
+        }
+
+        function recognitionStarted() {
+            if (settled || cancelled || failed) return;
+            receivedStart = true;
+            if (!stopping) publishState('listening');
+            settleStarted(!cancelled && !failed && !stopping);
+        }
+
+        function recognitionResults(event) {
+            if (settled || cancelled || failed) return;
+            try {
+                for (let index = event.resultIndex; index < event.results.length; index += 1) {
+                    if (settled || cancelled || failed) return;
+                    const result = event.results[index];
+                    if (!result.isFinal || index <= lastFinalIndex) continue;
+                    lastFinalIndex = index;
+                    sequence += 1;
+                    notify(
+                        onSegment,
+                        {text: result[0].transcript, sequence}
+                    );
+                }
+                if (settled || cancelled || failed) return;
+                let text = '';
+                // Native results retain their final prefix and replace only
+                // interim entries. Do not revisit that growing final prefix.
+                for (let index = lastFinalIndex + 1; index < event.results.length; index += 1) {
+                    text += event.results[index][0].transcript;
+                }
+                notify(
+                    onInterim,
+                    {text}
+                );
+            } catch (error) {
+                interrupt(
+                    recognitionError(
+                        'The browser speech recognition result could not be read.',
+                        'ARCANE_AI_INVALID_PROVIDER_RESULT',
+                        error
+                    )
+                );
+                abortNative();
+            }
+        }
+
+        function recognitionFailed(event) {
+            if (settled || cancelled || failed) return;
+            const error = recognitionError(
+                event.message || `Native browser speech recognition failed: ${event.error}.`,
+                'ARCANE_AI_SPEECH_RECOGNITION_FAILED',
+                event
+            );
+            error.reason = event.error;
+            interrupt(error);
+        }
+
+        function recognitionEnded() {
+            finish(receivedStart && !cancelled && !failed);
+        }
+
+        function start(
+            {signal: captureSignal} = {}
+        ) {
+            if (started || settled) return Promise.resolve(false);
+            started = true;
+            const starting = new Promise(
+                function waitForRecognitionStart(resolve) {
+                    resolveStarted = resolve;
+                }
+            );
+            signal = captureSignal ?? null;
+            if (signal?.aborted) {
+                cancel();
+                return starting;
+            }
+            try {
+                if (state === 'disposed' || disposeOperation) {
+                    throw recognitionError('The browser speech provider is disposed.', 'ARCANE_AI_PROVIDER_DISPOSED');
+                }
+                if (state !== 'ready' || unloadOperation || generation !== captureGeneration) {
+                    throw recognitionError('The browser speech provider is not ready.', 'ARCANE_AI_NOT_READY');
+                }
+                if (activeCapture !== null) {
+                    throw recognitionError('The browser speech provider is at capacity.', 'ARCANE_AI_PROVIDER_BUSY');
+                }
+                const Recognition = recognitionConstructor();
+                if (!Recognition) throw unavailableRecognition();
+                activeCapture = capture;
+                recognizer = new Recognition();
+                if (captureLanguage !== undefined) recognizer.lang = captureLanguage;
+                recognizer.continuous = continuous;
+                recognizer.interimResults = true;
+                recognizer.maxAlternatives = 1;
+                recognizer.onstart = recognitionStarted;
+                recognizer.onresult = recognitionResults;
+                recognizer.onerror = recognitionFailed;
+                recognizer.onend = recognitionEnded;
+                signal?.addEventListener(
+                    'abort',
+                    cancel,
+                    {once: true}
+                );
+                publishState('starting');
+                if (settled || cancelled || failed) return starting;
+                nativeStarted = true;
+                // This call stays in the initiating user gesture. No model
+                // loading, permission preflight, or promise precedes it.
+                recognizer.start();
+            } catch (error) {
+                interrupt(
+                    recognitionError(
+                        'Native browser speech recognition could not start.',
+                        is.string(error?.code) ? error.code : 'ARCANE_AI_SPEECH_RECOGNITION_START_FAILED',
+                        error
+                    )
+                );
+                finish(false);
+            }
+            return starting;
+        }
+
+        function stop() {
+            if (settled || stopping || cancelled || failed) return done;
+            if (!started || !nativeStarted) return cancel();
+            stopping = true;
+            publishState('stopping');
+            if (settled || cancelled || failed) return done;
+            try {
+                recognizer.stop();
+            } catch (error) {
+                interrupt(
+                    recognitionError(
+                        'Native browser speech recognition could not stop.',
+                        'ARCANE_AI_SPEECH_RECOGNITION_STOP_FAILED',
+                        error
+                    )
+                );
+                abortNative();
+            }
+            return done;
+        }
+
+        const capture = {start, stop, cancel, destroy: cancel, done};
+        return capture;
+    }
+
+    const provider = {
+        protocol: 'arcane-ai-provider/2',
+        role: 'stt',
+        id,
+        localOnly: false,
+        maxConcurrentRequests: 1,
+
+        catalog() {
+            return [{id: modelId, providerId: id, role: 'stt', localOnly: false}];
+        },
+
+        async inspect(selection, context = {}) {
+            assertContext(context);
+            assertSelection(selection);
+            if (state === 'disposed' || disposeOperation) {
+                return {
+                    available: false,
+                    code: 'ARCANE_AI_PROVIDER_DISPOSED',
+                    message: 'The browser speech provider is disposed.'
+                };
+            }
+            if (!recognitionConstructor()) {
+                const error = unavailableRecognition();
+                return {available: false, code: error.code, message: error.message};
+            }
+            return {available: true, authority: authority()};
+        },
+
+        status,
+        createCapture,
+
+        async load(context = {}) {
+            assertContext(context);
+            if (state === 'disposed' || disposeOperation) {
+                throw recognitionError('The browser speech provider is disposed.', 'ARCANE_AI_PROVIDER_DISPOSED');
+            }
+            if (unloadOperation) {
+                throw recognitionError('The browser speech provider is unloading.', 'ARCANE_AI_OPERATION_SUPERSEDED');
+            }
+            if (!recognitionConstructor()) {
+                state = 'error';
+                throw unavailableRecognition();
+            }
+            state = 'ready';
+            return status();
+        },
+
+        async request(context = {}) {
+            assertContext(context);
+            throw recognitionError(
+                'Native browser speech recognition accepts live microphone capture only; arbitrary audio files cannot be transcribed.',
+                'ARCANE_AI_SPEECH_INPUT_UNSUPPORTED'
+            );
+        },
+
+        unload(context = {}) {
+            assertContext(context);
+            if (state === 'disposed') {
+                return Promise.resolve(
+                    status()
+                );
+            }
+            if (unloadOperation) return unloadOperation;
+            state = 'unloading';
+            generation += 1;
+            const capture = activeCapture;
+            unloadOperation = Promise.resolve(capture?.done).then(
+                function finishRecognitionUnload() {
+                    state = 'unloaded';
+                    unloadOperation = null;
+                    return status();
+                }
+            );
+            capture?.cancel();
+            return unloadOperation;
+        },
+
+        dispose(context = {}) {
+            assertContext(context);
+            if (state === 'disposed') {
+                return Promise.resolve(
+                    status()
+                );
+            }
+            if (disposeOperation) return disposeOperation;
+            disposeOperation = provider.unload(context).then(
+                function finishRecognitionDispose() {
+                    state = 'disposed';
+                    disposeOperation = null;
+                    return status();
+                }
+            );
+            return disposeOperation;
+        }
+    };
+    return provider;
+}

package/browser-runtime/ai/browser-speech.mjs

@@ -10,6 +10,7 @@ export {
   createBrowserKokoroProvider,
   createBrowserWhisperProvider,
 } from "./browser-speech-providers.mjs";
+export {createBrowserSpeechRecognitionProvider} from './browser-speech-recognition.mjs';
 export {
   createTwinCloudTTSProvider,
   createTwinCloudTTSProvider as createDigitalOceanFalTTSProvider,

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

@@ -1,11 +1,87 @@
 # Browser speech providers
 
-`arcane-os/ai/browser-speech` supplies caller-selected Whisper speech-to-text,
-Kokoro text-to-speech, and TWiN Cloud text-to-speech providers. Its local path
+`arcane-os/ai/browser-speech` supplies caller-selected Whisper or native Web
+Speech recognition, Kokoro text-to-speech, and TWiN Cloud text-to-speech providers. Its local path
 provides artifact storage, live module routing, role Workers, provider/2
 adapters, bounded parallel TTS synthesis, audio normalization, cancellation,
 and cleanup.
 
+## Native browser speech recognition
+
+Select the browser's `SpeechRecognition` or `webkitSpeechRecognition` service
+explicitly. It may use a remote browser service, so this provider declares
+`localOnly:false`; it is never substituted for Whisper automatically. The
+application owns the provider/model identifiers and saved Profile selection.
+
+```javascript
+import {createBrowserSpeechRecognitionProvider} from 'arcane-os/ai/browser-speech';
+
+async function selectBrowserRecognition(ai, signal) {
+    const provider = createBrowserSpeechRecognitionProvider(
+        {id: 'WEB_SPEECH', model: {id: 'WEB_SPEECH'}}
+    );
+    await ai.configureSpeechProvider('stt', provider, {modelId: 'WEB_SPEECH', signal});
+}
+```
+
+Configuration and activation use the existing independent STT lifecycle.
+Construction and `catalog()` succeed when the native API is absent;
+`inspect()` reports unavailable and `load()` reports an unsupported error.
+Neither factory, configuration nor load opens a microphone, downloads a
+model, accesses storage, or changes TTS, typing, existing defaults, or saved
+data. Browser/OS availability, microphone permission, language support and
+service connectivity remain native platform requirements across Windows,
+Linux, macOS and Android hosts.
+
+After STT activation, the existing `speech.html` and `voice-transcription.html`
+recording controls select live capture automatically. `speech.html` retains
+every final result and emits one complete `speech-transcription-complete`
+message when capture ends. Its live display retains finalized words alongside
+the current interim text while speaking. The voice component appends each final result
+through its existing ordered save queue. Interim text appears only in a
+transient surface and never enters a save or completion event. A custom voice
+component `transcribe(file,context)` callback retains the existing clip path.
+Final segments waiting behind an application save remain visible in that
+transient surface until the ordered queue appends them to the main transcript.
+
+For direct use, `ai.supportsTranscriptionCapture()` detects the selected
+provider's capture capability. `ai.createTranscriptionCapture(options)` returns
+`null` for a file-only provider or a single-use capture handle with
+`start({signal})`, `stop()`, `cancel()`, `destroy()` and `done`.
+Options are `{language,continuous,onSegment,onInterim,onState,onError}`;
+`onSegment({text,sequence})` receives each complete final result once, and
+`onInterim({text})` receives the current mutable hypothesis. Callbacks are
+observational and never delay native capture. The voice component, rather than
+the capture callback, owns asynchronous ordered application saves.
+
+Call `start()` directly from the initiating user gesture. Its promise resolves
+to whether native capture actually started. `stop()` asks the browser to stop
+listening and finish recognition, retaining final results through native `end`;
+`stop()` and `done` resolve `true` for normal native completion and `false` for
+cancellation or failure after capture settlement. Runtime cleanup failure
+rejects the runtime handle's promises. `cancel()`, an aborted signal,
+provider replacement, unload, and disposal request native `abort()` and suppress
+late text. Capture is an owned busy STT operation; it is never delayed into a
+request queue that would lose the gesture. Natural native `end` stops the
+session without automatic restart. The user can start another session.
+If native `abort()` itself throws, the complete failure remains observable and
+the capture stays owned until native `end`; requesting abort is not evidence
+that the browser microphone has disconnected.
+
+Missing API reports `ARCANE_AI_SPEECH_RECOGNITION_UNAVAILABLE`; file input
+reports `ARCANE_AI_SPEECH_INPUT_UNSUPPORTED`. Native service errors use
+`ARCANE_AI_SPEECH_RECOGNITION_FAILED`, retain the browser reason and complete
+event as their cause, and remain available in developer diagnostics. Shared
+ordinary controls show concise failure status. Confirmed final words received
+before a service failure remain deliverable; explicit cancellation or
+supersession suppresses the pending chat submission.
+
+This API captures live microphone speech. `AI.fetchSTT(file)` remains the
+Whisper/file-provider contract; native recognition rejects file transcription
+honestly rather than recording again or silently switching providers. See the
+[Web Speech specification](https://webaudio.github.io/web-speech-api/#speechreco-methods)
+for native stop/abort behavior.
+
 <a id="digitalocean-fal-text-to-speech"></a>
 
 ## TWiN Cloud text-to-speech
@@ -971,6 +1047,7 @@ records; this contract does not freeze them or shorten their content.
 | Native WebView | Conditional | Available when the WebView exposes the browser APIs above. It does not invoke Core speech. |
 | Node | Remote adapter available; local execution unavailable | TWiN Cloud uses Fetch and Blob. The local providers have no SDK Node speech-storage, Worker, or audio-decoder host. |
 | Remote TTS | Explicitly selected | TWiN Cloud uses standard Fetch and Blob with an application-owned key; no Worker, OPFS, or local model is needed for this adapter. |
+| Native browser STT | Explicitly selected, conditional | Requires `SpeechRecognition` or `webkitSpeechRecognition` and native microphone/service availability. No Worker, OPFS, or SDK model download; locality is not promised. |
 
 STT and TTS own independent provider lifecycles. A failure or cancellation in
 one role does not disable the other role or authorize a fallback provider.
@@ -982,6 +1059,7 @@ import {
   BROWSER_SPEECH_ARTIFACT_GRAPH_PROTOCOL,
   BROWSER_SPEECH_ARTIFACT_PROTOCOL,
   createBrowserKokoroProvider,
+  createBrowserSpeechRecognitionProvider,
   createBrowserSpeechArtifactGraph,
   createBrowserSpeechAuthority,
   createBrowserWhisperProvider,