arcane-os 0.2.1 → 0.2.3

package/docs/reference/runtime-components.md

@@ -29,7 +29,7 @@ A component file does not register its own custom element. The `<html-import>` h
 | [`assistant-panel.html`](#assistant-panelhtml) | Reusable assistant drawer, message area, composer, pending/streaming/empty/error state, and actions. | `open()`<br>`close()`<br>`toggle()`<br>`send()`<br>`clear()`<br>`setState()`<br>`focusComposer()`<br>`scrollToEnd()` | `assistant-ready`<br>`assistant-send`<br>`assistant-clear` | DOM-normalized; caller/provider results remain external |
 | [`calculator.html`](#calculatorhtml) | Calculator keypad and result/error event surface backed by CalculatorEngine. | `calculate()` | `calculator-ready`<br>`calculation-complete`<br>`calculation-error` | Normalized Calculation/error events |
 | [`chart.html`](#charthtml) | Accessible uPlot line, area, or point chart with normalized options and rows. | `configure()`<br>`populate()`<br>`setData()`<br>`addData()`<br>`update()`<br>`destroy()` | `chart-ready`<br>`chart-remove` | Options/rows normalized; uPlot rendering is vendor-native |
-| [`chat.html`](#chathtml) | Shared chat, file upload, streaming, speech, language, availability, and conversation-timebox surface. | `streamMessage()`<br>`setMessageProgress()`<br>`setAIAvailability()`<br>`setInitialSpeechMuted()`<br>`setConversationComplete()`<br>`bindConversationTimebox()`<br>`submitMessage()`<br>`sendMessage()`<br>`languageChanged()` | `chat-ready`<br>`chat-send-message`<br>`chat-send-error`<br>`chat-file-uploaded`<br>`chat-language-changed`<br>`conversation-timebox-error` | UI state normalized; AI/storage/media behavior mixed |
+| [`chat.html`](#chathtml) | Shared chat, visible selected-model activation request, file upload, streaming, speech, language, availability, and conversation-timebox surface. | `streamMessage()`<br>`setMessageProgress()`<br>`setAIAvailability()`<br>`setInitialSpeechMuted()`<br>`setConversationComplete()`<br>`bindConversationTimebox()`<br>`submitMessage()`<br>`sendMessage()`<br>`languageChanged()`<br>`requestAIActivation()`<br>`destroy()` | `chat-ready`<br>`chat-send-message`<br>`chat-send-error`<br>`chat-file-uploaded`<br>`chat-language-changed`<br>`chat-ai-activation-request`<br>`chat-ai-activation-error`<br>`conversation-timebox-error` | UI/runtime state and explicit user activation intent normalized; AI/storage/media behavior mixed |
 | [`conversation-view.html`](#conversation-viewhtml) | Provider-neutral conversation display, advisory actions, composer, busy state, and status. | `setConversation()`<br>`setBusy()`<br>`setStatus()`<br>`clearComposer()` | `conversation-view-ready`<br>`communication-send`<br>`communication-advisory-action` | DOM-normalized |
 | [`dashboard-config.html`](#dashboard-confightml) | Selects which normalized chart definitions are visible on a dashboard. | `configure()`<br>`setDefinitions()`<br>`setVisibility()`<br>`getChartOptions()`<br>`getEffectiveVisibility()`<br>`open()`<br>`close()` | `dashboard-config-ready`<br>`dashboard-config-opened`<br>`dashboard-config-closed`<br>`dashboard-config-change` | Fully normalized definitions and visibility |
 | [`data-maintenance.html`](#data-maintenancehtml) | Runs destructive cleanup of empty chats and memories inside the current app data scope. | `open()` | `data-maintenance-ready`<br>`data-maintenance-complete` | Normalized counts; DBOPFS failures mixed |
@@ -53,7 +53,7 @@ A component file does not register its own custom element. The `<html-import>` h
 | [`screen-capture.html`](#screen-capturehtml) | Presents image, video, or GIF display-capture workflow. | `capture()` | `screen-capture-ready`<br>`screen-capture-result` | State/result normalized; media permission/codec failures mixed |
 | [`source-code-viewer.html`](#source-code-viewerhtml) | Renders line-addressable source code with load, error, focus, and state behavior. | `configure()`<br>`load()`<br>`render()`<br>`clear()`<br>`fail()`<br>`focus()`<br>`focusLine()` | `source-code-viewer-ready`<br>`source-code-viewer-state` | Normalized source/state |
 | [`source-explanation.html`](#source-explanationhtml) | Presents an evidence finding, source selection, explanation, and save state. | `showFinding()`<br>`populate()`<br>`selectSource()`<br>`markSaved()` | `source-explanation-ready`<br>`source-explanation-save`<br>`source-explanation-source-selected` | DOM-normalized |
-| [`speech.html`](#speechhtml) | Coordinates speech controls, transcription completion, mute state, and microphone availability. | `configure()`<br>`setAvailability()`<br>`setMuted(); availability`<br>`muted`<br>`initialMuted`<br>`componentReady properties` | `speech-ready`<br>`speech-transcription-complete`<br>`speech-microphone-unavailable` | UI state normalized; AI/media behavior mixed |
+| [`speech.html`](#speechhtml) | Coordinates explicit STT activation, speech controls, transcription completion, mute state, and microphone availability. | `configure()`<br>`setAvailability()`<br>`setMuted()`<br>`requestSTTActivation()`<br>`destroy()`<br>`availability`<br>`muted`<br>`initialMuted`<br>`componentReady` | `speech-ready`<br>`speech-transcription-complete`<br>`speech-transcription-error`<br>`speech-transcription-cancelled`<br>`speech-microphone-unavailable`<br>`speech-stt-activation-request`<br>`speech-stt-activation-error`<br>`speech-tts-lifecycle-error` | Sticky runtime speech readiness, explicit STT activation, request cancellation, and TTS mute lifecycle intent normalized; provider/model authority and media behavior remain external |
 | [`summary-strip.html`](#summary-striphtml) | Displays compact selectable KPI or summary items. | `configure()`<br>`setItems()`<br>`updateItem()`<br>`clear()` | `summary-strip-ready`<br>`summary-strip-change`<br>`summary-strip-select` | DOM-normalized |
 | [`table.html`](#tablehtml) | Builds and updates a simple header/body table. | `buildHeader()`<br>`buildTable()` | `table-ready`<br>`header-update`<br>`body-update` | DOM-normalized |
 | [`task-progress.html`](#task-progresshtml) | Runs and displays a task list with started/change/complete/error state. | `configure()`<br>`setTasks()`<br>`updateTask()`<br>`runTasks()`<br>`clear()` | `task-progress-ready`<br>`task-progress-started`<br>`task-progress-change`<br>`task-progress-complete`<br>`task-progress-error` | Task state normalized; injected task results mixed |
@@ -61,7 +61,7 @@ A component file does not register its own custom element. The `<html-import>` h
 | [`theme-editor.html`](#theme-editorhtml) | Edits, previews, saves, and resets semantic custom theme tokens. | `configure()`<br>`getTheme()`<br>`setTheme()`<br>`setBusy()`<br>`setStatus()` | `theme-editor-ready`<br>`theme-preview`<br>`theme-save`<br>`theme-reset` | Fully normalized Theme values |
 | [`theme-switcher.html`](#theme-switcherhtml) | Selects and refreshes system, light, dark, or custom theme mode. | `setMode()`<br>`refresh()` | No component-specific event | Preference/native appearance behavior mixed; no component-ready contract |
 | [`unified-inbox.html`](#unified-inboxhtml) | Displays provider-neutral communication threads with active/loading state. | `configure()`<br>`setThreads()`<br>`setActive()`<br>`setLoading()` | `unified-inbox-ready`<br>`inbox-refresh`<br>`thread-select` | DOM-normalized |
-| [`voice-transcription.html`](#voice-transcriptionhtml) | Records segmented microphone audio, transcribes, persists, and completes a combined transcript. | `configure()`<br>`startRecording()`<br>`stopRecording()`<br>`save()`<br>`completeTranscription()/complete()`<br>`clear()`<br>`reset()`<br>`destroy()` | `voice-transcription-ready`<br>`voice-transcription-state`<br>`voice-transcription-segment`<br>`voice-transcription-change`<br>`voice-transcription-complete`<br>`speech-transcription-complete` | State/text normalized; media/provider behavior mixed |
+| [`voice-transcription.html`](#voice-transcriptionhtml) | Records segmented microphone audio only after authoritative STT admission, exposes explicit selected-STT activation, transcribes with cancellation, persists, and completes a combined transcript. | `configure()`<br>`requestSTTActivation()`<br>`startRecording()`<br>`stopRecording()`<br>`save()`<br>`completeTranscription()/complete()`<br>`clear()`<br>`reset()`<br>`destroy()` | `voice-transcription-ready`<br>`voice-transcription-state`<br>`voice-transcription-segment`<br>`voice-transcription-change`<br>`voice-transcription-complete`<br>`speech-transcription-complete`<br>`speech-transcription-cancelled`<br>`speech-stt-activation-request`<br>`speech-stt-activation-error` | Sticky runtime STT readiness, explicit activation, request cancellation, and state/text are normalized; media/provider behavior remains external |
 | [`weather-widget.html`](#weather-widgethtml) | Displays normalized current and daily weather with refresh intent. | `setWeather()`<br>`clear()` | `weather-widget-ready`<br>`weather-refresh` | Display normalized; provider supplied externally |
 | [`web-navigator.html`](#web-navigatorhtml) | Guards embedded/external navigation and surfaces allow/block/open intents. | `configure()`<br>`navigate()`<br>`currentUrl()` | `web-navigator-ready`<br>`web-navigate`<br>`web-navigation-blocked`<br>`web-open-external` | Navigation intent/decision normalized; browser navigation result platform-native |
 
@@ -177,24 +177,63 @@ Shared dependencies: [`ChartLibrary.js`](runtime-modules.md#chartlibraryjs), [`C
 
 ### Overview
 
-Shared chat, file upload, streaming, speech, language, availability, and conversation-timebox surface.
+Shared chat, visible selected-model activation request, file upload, streaming,
+speech, language, availability, and conversation-timebox surface.
 
 ### Public surface
 
-Methods/properties: `streamMessage()`, `setMessageProgress()`, `setAIAvailability()`, `setInitialSpeechMuted()`, `setConversationComplete()`, `bindConversationTimebox()`, `submitMessage()`, `sendMessage()`, `languageChanged()`.
+Methods/properties: `streamMessage()`, `setMessageProgress()`,
+`setAIAvailability()`, `setInitialSpeechMuted()`,
+`setConversationComplete()`, `bindConversationTimebox()`, `submitMessage()`,
+`sendMessage()`, `languageChanged()`, `requestAIActivation()`, and `destroy()`.
 
 `sendMessage(text)` and `languageChanged(text)` are host-overridable async
 extension callbacks. The component installs warning-only defaults when the host
 does not supply them; applications may instead consume the corresponding
 `chat-send-message` and `chat-language-changed` events.
 
-Events: `chat-ready`, `chat-send-message`, `chat-send-error`, `chat-file-uploaded`, `chat-language-changed`, `conversation-timebox-error`.
-
-Shared dependencies: [`MD.js`](runtime-modules.md#mdjs), [`File.js`](runtime-entities.md#filejs), [`ConversationTimebox.js`](runtime-modules.md#conversationtimeboxjs).
+`setAIAvailability()` remains an LLM compatibility input, but selected sticky
+`AIRuntimeState` LLM state wins over that boolean. STT and TTS readiness always
+comes from sticky runtime role state; the method never forwards compatibility
+speech booleans or synthesizes ready speech roles without an admitted, loaded
+provider.
+
+When a selected LLM route is `unloaded` or in `error`, the component exposes a
+keyboard-operable Start/Try again control while Send stays disabled. During
+`loading`, the control becomes Cancel loading and reflects sticky progress.
+The default `requestAIActivation(intent)` forwards frozen
+`{role:'llm',action:'load'|'unload',reason:'user'}` to
+`requestAIRuntimeIntent()`. A host may replace that callback.
+
+Before the callback, the component dispatches the bubbles/composed/cancelable
+`chat-ai-activation-request` event with frozen `{intent,state}` detail.
+`preventDefault()` suppresses the callback. A callback failure dispatches the
+bubbles/composed, noncancelable `chat-ai-activation-error` event with frozen
+`{request,error,message}`. A recognized canceled load whose current route is
+`unloaded` or `unloading` is not reported as an activation error.
+
+`destroy()` aborts the component's AI-runtime-state subscription, destroys the
+activation controller, removes its `pagehide` listener, calls the optional
+speech controller's `destroy()`, sets `ready` to `false`, and returns
+`undefined`. It does not initiate a provider load or unload.
+
+Events: `chat-ready`, `chat-send-message`, `chat-send-error`,
+`chat-file-uploaded`, `chat-language-changed`,
+`chat-ai-activation-request`, `chat-ai-activation-error`, and
+`conversation-timebox-error`.
+
+Shared dependencies: [`MD.js`](runtime-modules.md#mdjs), [`File.js`](runtime-entities.md#filejs), [`ConversationTimebox.js`](runtime-modules.md#conversationtimeboxjs), [`AIRuntimeState.js`](runtime-modules.md#airuntimestatejs).
 
 ### Availability and normalization
 
-**Browser and supported native WebViews.** UI state normalized; AI/storage/media behavior mixed. HTMLImport + DOM; injected Arcane/provider modules where listed. Native methods remain subject to the bound app's capabilities. [Deep protocol details](protocols.md).
+**Browser and supported native WebViews.** UI and provider-runtime state are
+normalized; AI/storage/media behavior remains mixed. The component emits no
+activation request on import or startup. After the user operates the visible
+control and the component event is not canceled, it publishes a
+capability-neutral user intent; a provider/runtime owner decides whether and
+how to execute the requested load or unload. HTMLImport + DOM; injected
+Arcane/provider modules where listed. Native methods remain subject to the
+bound app's capabilities. [Deep protocol details](protocols.md).
 
 ### Example
 
@@ -812,19 +851,74 @@ Events: `source-explanation-ready`, `source-explanation-save`, `source-explanati
 
 ### Overview
 
-Coordinates speech controls, transcription completion, mute state, and microphone availability.
+Coordinates explicit speech-to-text activation, speech controls, transcription
+completion, mute state, and microphone availability.
 
 ### Public surface
 
-Methods/properties: `configure()`, `setAvailability()`, `setMuted(); availability`, `muted`, `initialMuted`, `componentReady properties`.
-
-Events: `speech-ready`, `speech-transcription-complete`, `speech-microphone-unavailable`.
-
-Shared dependencies: [`AI.js`](runtime-modules.md#aijs), [`DBLS.js`](runtime-modules.md#dblsjs).
+Methods/properties: `configure()`, `setAvailability()`, `setMuted()`,
+`requestSTTActivation()`, `destroy()`, `availability`, `muted`, `initialMuted`,
+and `componentReady`.
+
+Events: `speech-ready`, `speech-transcription-complete`,
+`speech-transcription-error`, `speech-transcription-cancelled`,
+`speech-microphone-unavailable`, `speech-stt-activation-request`,
+`speech-stt-activation-error`, and `speech-tts-lifecycle-error`.
+
+Shared dependencies: [`AI.js`](runtime-modules.md#aijs),
+[`AIRuntimeState.js`](runtime-modules.md#airuntimestatejs),
+[`ComponentContracts.js`](runtime-modules.md#componentcontractsjs), and
+[`DBLS.js`](runtime-modules.md#dblsjs).
+
+The Hold to talk control remains disabled unless sticky STT state is `ready`,
+the role is not busy, and microphone capture is available. For an explicitly
+selected STT route, a separate keyboard-operable control presents Start
+transcription while `unloaded`, Cancel loading while `loading`, a disabled
+Canceling state while `unloading`, and Try again with the sticky error while
+`error`. Selected-unloaded, busy, and error states are shown as distinct facts;
+none is treated as ready.
+
+The default `requestSTTActivation(intent)` forwards the frozen
+`{role:'stt',action:'load'|'unload',reason:'user'}` record to
+`requestAIRuntimeIntent()`. Before calling it, the component emits a bubbling,
+composed, cancelable `speech-stt-activation-request` event with frozen
+`{intent,state}` detail. `preventDefault()` suppresses the callback and intent.
+Callback failure emits `speech-stt-activation-error` with frozen
+`{request,error,message}` detail. Cancel loading publishes an `unload` intent;
+only subsequent sticky `unloading` or `unloaded` state confirms lifecycle
+progress, and callback return never proves provider work stopped.
+
+The component emits no activation request on import or state observation.
+Provider registration and selection remain inert, and default
+`startTranscription=false` does not request STT during runtime startup. The
+provider/runtime owner decides whether and how to execute a user intent; the
+component never selects a runtime or model, downloads artifacts, reloads after
+failure, or falls back to another provider.
+
+`setAvailability()` is compatibility-only for microphone and negative
+unselected-role reports. Positive STT/TTS booleans cannot manufacture a ready
+role, and no compatibility value can replace a selected sticky role. Hold to
+talk stays disabled without sticky ready STT, and compatibility input cannot
+enable a no-selection TTS role or bypass explicit TTS activation.
+
+Each transcription request owns an `AbortController`; its signal is passed as
+the third argument to `AI.fetchSTT()`. Cancel, a newer capture, and `destroy()`
+abort that controller and suppress late results. This proves request delivery
+was canceled, not that an uncooperative provider stopped underlying work.
+
+User Unmute calls the shared `AI.setSpeechMuted(false)` lifecycle owner before
+or with publishing the TTS load intent, so the runtime can legally load TTS.
+Mute calls `AI.setSpeechMuted(true)`, stops playback, cancels active TTS work,
+and unloads the selected TTS role. Lifecycle failures remain visible through
+`speech-tts-lifecycle-error` and sticky role state.
 
 ### Availability and normalization
 
-**Browser and supported native WebViews.** UI state normalized; AI/media behavior mixed. HTMLImport + DOM; injected Arcane/provider modules where listed. Native methods remain subject to the bound app's capabilities. [Deep protocol details](protocols.md).
+**Browser and supported native WebViews.** UI/runtime state and explicit user
+STT activation intent are normalized; provider/model authority and media
+behavior remain external. HTMLImport + DOM; injected Arcane/provider modules
+where listed. Native methods remain subject to the bound app's capabilities.
+[Deep protocol details](protocols.md).
 
 ### Example
 
@@ -1020,19 +1114,81 @@ Events: `unified-inbox-ready`, `inbox-refresh`, `thread-select`.
 
 ### Overview
 
-Records segmented microphone audio, transcribes, persists, and completes a combined transcript.
+Records segmented microphone audio only after authoritative STT admission,
+exposes explicit selected-STT activation, transcribes with cancellation,
+persists, and completes a combined transcript.
 
 ### Public surface
 
-Methods/properties: `configure()`, `startRecording()`, `stopRecording()`, `save()`, `completeTranscription()/complete()`, `clear()`, `reset()`, `destroy()`.
+Methods/properties: `configure()`, `requestSTTActivation()`, `startRecording()`,
+`stopRecording()`, `save()`, `completeTranscription()/complete()`, `clear()`,
+`reset()`, `destroy()`.
 
-Events: `voice-transcription-ready`, `voice-transcription-state`, `voice-transcription-segment`, `voice-transcription-change`, `voice-transcription-complete`, `speech-transcription-complete`.
+Events: `voice-transcription-ready`, `voice-transcription-state`,
+`voice-transcription-segment`, `voice-transcription-change`,
+`voice-transcription-complete`, `speech-transcription-complete`,
+`speech-transcription-cancelled`, `speech-stt-activation-request`, and
+`speech-stt-activation-error`.
 
-Shared dependencies: [`MD.js`](runtime-modules.md#mdjs), [`ComponentContracts.js`](runtime-modules.md#componentcontractsjs), [`AI.js`](runtime-modules.md#aijs).
+Shared dependencies: [`MD.js`](runtime-modules.md#mdjs),
+[`ComponentContracts.js`](runtime-modules.md#componentcontractsjs),
+[`AIRuntimeState.js`](runtime-modules.md#airuntimestatejs), and
+[`AI.js`](runtime-modules.md#aijs).
 
 ### Availability and normalization
 
-**Browser and supported native WebViews.** State/text normalized; media/provider behavior mixed. HTMLImport + DOM; injected Arcane/provider modules where listed. Native methods remain subject to the bound app's capabilities. [Deep protocol details](protocols.md).
+**Browser and supported native WebViews.** The component subscribes
+synchronously to sticky `AIRuntimeState.roles.stt`; its recording Start button
+and public `startRecording()` both fail closed unless that role is exactly
+`ready` and not busy. A configured `transcribe(file,context)` callback remains
+request plumbing rather than readiness authority. Its context now includes the
+owned `signal` additively. The default route calls
+`AI.fetchSTT(file,undefined,signal)` so the callback position remains valid and
+readiness loss or destruction can abort delivery.
+
+For a selected `unloaded`, `loading`, `unloading`, or `error` role, the component
+keeps recording Start disabled and presents the same keyboard-operable Start
+transcription/Try again or Cancel loading control as `speech.html`. Both use the
+shared `createSTTActivationController()` contract. User operation emits the
+cancelable `speech-stt-activation-request` event with frozen `{intent,state}`;
+`preventDefault()` suppresses the callback. The default
+`requestSTTActivation(intent)` publishes the frozen
+`{role:'stt',action:'load'|'unload',reason:'user'}` intent. Callback failure emits
+`speech-stt-activation-error` with frozen `{request,error,message}`. Import and
+state observation emit no activation request and never begin a model download.
+
+If sticky readiness is lost during microphone acquisition, capture, or the STT
+request, the component invalidates the session, aborts the owned request signal,
+releases media, discards late completion, and emits
+`speech-transcription-cancelled` with frozen `{reason:'runtime-unready'}`. A
+current provider cancellation returns the component workflow to `idle` and
+emits the same event with `reason:'stt-provider-request-cancelled'`; destroying
+an active capture or transcription emits `reason:'component-destroyed'`.
+Stale teardown results remain suppressed. A
+current save failure, including `AbortError`, enters the visible `error` state.
+Readiness loss after transcription has finished does not invalidate an already
+pending application save or completion callback: its settlement remains
+observable, while any new recording remains gated by current sticky readiness.
+Assigning `value` or calling `configure({initialValue})` explicitly supersedes
+an in-flight microphone start, STT request, save, or completion. The component
+advances its generation, aborts owned STT delivery, releases owned media, emits
+`speech-transcription-cancelled` with
+`reason:'transcript-replaced'`, and suppresses
+late settlement before publishing the assigned transcript. Assigning transcript
+text during active recording preserves that recording and changes the transcript
+to which the captured segment will be appended.
+`destroy()` aborts the state subscription, cancels active work, removes the
+activation listener, sets component `ready` to `false`, and returns `true`;
+repeated destruction is
+idempotent. Destruction is terminal: Start, activation, and Complete remain
+disabled and status remains unavailable. `voice-transcription-state` detail is
+the frozen `{message,state,stt}` record, where `state` remains the component
+workflow and `stt` is the authoritative immutable role record. Transcript
+completion stays available when STT is unavailable before destruction.
+State/text, explicit activation, and request cancellation are normalized;
+provider/model authority and media behavior remain external. HTMLImport + DOM;
+injected Arcane/provider modules where listed.
+Native methods remain subject to the bound app's capabilities. [Deep protocol details](protocols.md).
 
 ### Example