arcane-os 0.3.0 → 0.3.2

package/docs/reference/runtime-components.md

@@ -1,1366 +0,0 @@
-# Arcane runtime component catalog
-
-Arcane components are reusable HTML fragments loaded through the shared `<html-import>` element. They are browser UI, so they run in an ordinary supported browser renderer and in native Arcane WebViews. They do not run in Node or as cloud services.
-
-A component file does not register its own custom element. The `<html-import>` host fetches the fragment from the same origin, attaches an open shadow root, runs its inline scripts with `this` bound to the host, and publishes `html-import-ready` or `html-import-error`. Component methods and properties are attached to that host.
-
-## Basic loading pattern
-
-```html
-<script type="module">
-  import '/arcane/modules/HTMLImport.js';
-</script>
-
-<html-import id="widget" href="/arcane/components/weather-widget.html"></html-import>
-
-<script type="module">
-  const widget = document.querySelector('#widget');
-  widget.addEventListener('html-import-ready', () => {
-      console.log('Component methods are attached.', typeof widget.setWeather);
-  }, {once: true});
-</script>
-```
-
-## Shared semantic-event and lifecycle contract
-
-Except for the legacy `header.html` and platform-owned `theme-switcher.html`,
-each component owns exactly one source created through
-`createArcaneEventSource(host,{source:'arcane.component.<name>',eventTypes})`.
-That source publishes synchronously to the realm's branded
-`globalThis.arcaneEvents` authority. Component DOM events are one-way
-compatibility projections of the same canonical occurrence; they are never
-republished into the authority. Every projected detail has the canonical
-`occurrenceId`, `arcaneSource`, `instanceId`, and `operationId` fields and a
-frozen outer record. A compatibility payload's existing `source` field remains
-source-local and may differ from `arcaneSource`; the payload may additionally
-retain source-local browser or provider objects.
-
-When a component uses a cancelable event as an admission gate, cancellation on
-either the canonical occurrence or its DOM projection makes the publication
-unaccepted, and the component does not continue the guarded operation. A
-cancelable compatibility notification emitted after committed work does not
-roll that work back unless its component section explicitly says otherwise.
-Asynchronous work keeps its own `AbortSignal`, operation generation, and
-promise ownership; canonical publication is synchronous and does not become an
-async queue.
-
-Every singleton-backed component publishes its ready event only after its host
-members are installed. Its idempotent `destroy()` (unless a more specific
-return is documented) disposes the canonical source and marks the host
-unready. Cleanup of owned listeners, pending work, nested subscriptions, and
-controllers is component-specific and is stated below where it forms part of
-that component's public contract. Removing an `<html-import>` host calls an
-imported component's `destroy()` through `HTMLImport`; callers that invoke
-`destroy()` directly retain responsibility for removing the element when
-appropriate.
-
-## Canonical inventory
-
-| Component | Capability | Principal methods | Events | Normalization |
-| --- | --- | --- | --- | --- |
-| [`app-bar.html`](#app-barhtml) | Responsive application navigation, route state, status, and trailing actions. | `setNavigation()`<br>`setActiveRoute()`<br>`setStatus()`<br>`refresh()`<br>`destroy()` | `app-bar-ready` | DOM-normalized |
-| [`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()`<br>`destroy()` | `assistant-ready`<br>`assistant-opened`<br>`assistant-closed`<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()`<br>`destroy()` | `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, 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-file-upload-error`<br>`chat-language-changed`<br>`chat-language-change-error`<br>`chat-ai-activation-request`<br>`chat-ai-activation-error`<br>`chat-speech-synthesis-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()`<br>`destroy()` | `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()`<br>`destroy()` | `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()`<br>`destroy()` | `data-maintenance-ready`<br>`data-maintenance-complete` | Normalized counts; DBOPFS failures mixed |
-| [`data-view.html`](#data-viewhtml) | Opens a generic modal-style data view around an injected provider. | `beforeOpen()`<br>`open()`<br>`destroy()` | `data-view-ready` | DOM-native result |
-| [`directory-picker.html`](#directory-pickerhtml) | Presents the provider-owned OS directory chooser with change/cancel/error states. | `configure()`<br>`focus()`<br>`select()`<br>`destroy()` | `directory-picker-ready`<br>`directory-picker-change`<br>`directory-picker-cancel`<br>`directory-picker-error` | Strict normalized native selection/error |
-| [`document-inspector.html`](#document-inspectorhtml) | Inspects PDF, text, or source documents and records review state. | `loadDocument()`<br>`selectView()`<br>`markSaved()`<br>`destroy()` | `document-inspector-ready`<br>`document-review-change` | Document state normalized; browser document APIs mixed |
-| [`file-drop.html`](#file-drophtml) | Acquires files by drag/drop or picker and presents busy, progress, error, and cleared state. | `configure()`<br>`openPicker()`<br>`clear()`<br>`setBusy()`<br>`setError()`<br>`setProgress()`<br>`destroy()` | `file-drop-ready`<br>`file-drop-selected`<br>`file-drop-progress`<br>`file-drop-state`<br>`file-drop-error` | State normalized; browser File/drop errors mixed |
-| [`file-inspector.html`](#file-inspectorhtml) | Displays file metadata, preview, busy/error state, and caller-defined actions. | `configure()`<br>`show()`<br>`clear()`<br>`setActions()`<br>`setBusy()`<br>`setError()`<br>`setPreview()`<br>`destroy()` | `file-inspector-ready`<br>`file-inspector-action`<br>`file-inspector-change`<br>`file-inspector-cleared`<br>`file-inspector-error` | State normalized; preview/provider behavior mixed |
-| [`file-manager.html`](#file-managerhtml) | Browses, filters, selects, opens, and acts on app-scoped files. | `setProvider()`<br>`loadAll()`<br>`setFilter()`<br>`select()`<br>`clearSelection()`<br>`destroy()` | `file-manager-ready`<br>`file-manager-select`<br>`file-manager-open`<br>`file-manager-action` | Selection/filter state normalized; storage/provider behavior mixed |
-| [`header.html`](#headerhtml) | Legacy title bar with history, reload, online marker, presentation labels, and 988 link. | None | No component-specific event | Browser/platform-native behavior; no component-ready contract |
-| [`integration-settings.html`](#integration-settingshtml) | Edits non-secret communication service configuration and service actions. | `configure()`<br>`getValues()`<br>`setStatus()`<br>`destroy()` | `integration-settings-ready`<br>`integration-settings-save`<br>`integration-settings-close`<br>`integration-action` | Normalized non-secret values |
-| [`local-ai-status.html`](#local-ai-statushtml) | Presents local-AI standby, failure, recovery, guidance, retry, and dismissal states. | `configure()`<br>`begin()`<br>`present()`<br>`destroy()`<br>`hidden` | `local-ai-status-ready`<br>`local-ai-status-dismissed`<br>`local-ai-retry` | Fully normalized LocalAIReadiness report |
-| [`markdown-document.html`](#markdown-documenthtml) | Safely renders and navigates a Markdown document with focusable fragments. | `configure()`<br>`load()`<br>`render()`<br>`clear()`<br>`fail()`<br>`focus()`<br>`focusFragment()`<br>`destroy()` | `markdown-document-ready`<br>`markdown-document-state`<br>`markdown-document-loading`<br>`markdown-document-rendered`<br>`markdown-document-empty`<br>`markdown-document-error`<br>`markdown-document-navigate` | State/sanitized output normalized; Marked/DOM failures mixed |
-| [`markdown-editor.html`](#markdown-editorhtml) | Configurable Markdown authoring, toolbar, preview, title, and save surface. | `configure()`<br>`focus()`<br>`clear()`<br>`saveEntry()`<br>`destroy()` | `markdown-editor-ready`<br>`markdown-editor-change`<br>`markdown-editor-saved` | Editor values normalized; injected save result mixed |
-| [`media-embed.html`](#media-embedhtml) | Loads a validated YouTube video or playlist embed and exposes external-platform action. | `configure()`<br>`load()`<br>`destroy()` | `media-embed-ready`<br>`media-load`<br>`media-error`<br>`media-open-platform` | URL/error normalized; iframe/platform behavior native |
-| [`modal.html`](#modalhtml) | Generic modal with population, open/close, actions, and sequential task execution. | `populate()`<br>`open()`<br>`close()`<br>`runTasks()`<br>`destroy()` | `modal-ready`<br>`modal-opened`<br>`modal-closed`<br>`modal-action` | Modal state normalized; injected task results mixed |
-| [`output-panel.html`](#output-panelhtml) | Presents status, output, body, coverage, actions, pending, error, and cleared states. | `configure()`<br>`setOutput()`<br>`setBody()`<br>`setCoverage()`<br>`setActions()`<br>`setPending()`<br>`setStatus()`<br>`setError()`<br>`clear()`<br>`destroy()` | `output-panel-ready`<br>`output-panel-state`<br>`output-panel-change`<br>`output-panel-action`<br>`output-panel-error`<br>`output-panel-cleared` | DOM-normalized |
-| [`preferences-form.html`](#preferences-formhtml) | Builds a schema-driven preferences form with submit, reset, busy, and status behavior. | `configure()`<br>`getValues()`<br>`setValues()`<br>`setBusy()`<br>`setStatus()`<br>`destroy()` | `preferences-form-ready`<br>`preferences-change`<br>`preferences-submit`<br>`preferences-reset` | Normalized form values |
-| [`record-timeline.html`](#record-timelinehtml) | Displays chronological records/evidence and emits open actions. | `setItems()`<br>`populate()`<br>`destroy()` | `record-timeline-ready`<br>`record-timeline-open` | DOM-normalized |
-| [`relationship-board.html`](#relationship-boardhtml) | Displays normalized relationship nodes/edges in graph and list forms. | `setGraph()`<br>`populate()`<br>`destroy()` | `relationship-board-ready`<br>`relationship-node-open`<br>`relationship-edge-open` | DOM-normalized |
-| [`screen-capture.html`](#screen-capturehtml) | Presents image, video, or GIF display-capture workflow. | `capture` (`ScreenCapture` instance)<br>`destroy()` | `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()`<br>`destroy()` | `source-code-viewer-ready`<br>`source-code-viewer-state`<br>`source-code-viewer-state-loading`<br>`source-code-viewer-state-ready`<br>`source-code-viewer-state-empty`<br>`source-code-viewer-state-error` | 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()`<br>`destroy()` | `source-explanation-ready`<br>`source-explanation-save`<br>`source-explanation-source-selected` | DOM-normalized |
-| [`speech.html`](#speechhtml) | Coordinates explicit STT activation, speech controls, transcription completion, mute state, and microphone availability. | `configure()`<br>`setAvailability()`<br>`setMuted()`<br>`reportTTSError()`<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`<br>`speech-synthesis-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()`<br>`destroy()` | `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()`<br>`destroy()` | `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()`<br>`destroy()` | `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 |
-| [`terminal-workspace.html`](#terminal-workspacehtml) | Presents multiple terminal sessions, output, active selection, theme, and terminal actions. | `configure()`<br>`addSession()`<br>`removeSession()`<br>`activateSession()`<br>`append()`<br>`clear()`<br>`setState()`<br>`setTheme()`<br>`focus()`<br>`destroy()` | `terminal-workspace-ready`<br>`terminal-submit`<br>`terminal-interrupt`<br>`terminal-clear`<br>`terminal-session-new`<br>`terminal-session-close`<br>`terminal-session-select`<br>`terminal-settings` | UI/session state normalized; native command results supplied externally |
-| [`theme-editor.html`](#theme-editorhtml) | Edits, previews, saves, and resets semantic custom theme tokens. | `configure()`<br>`getTheme()`<br>`setTheme()`<br>`setBusy()`<br>`setStatus()`<br>`destroy()` | `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()`<br>`destroy()` | `unified-inbox-ready`<br>`inbox-refresh`<br>`thread-select` | DOM-normalized |
-| [`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()`<br>`destroy()` | `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()`<br>`destroy()` | `web-navigator-ready`<br>`web-navigate`<br>`web-navigation-blocked`<br>`web-open-external` | Navigation intent/decision normalized; browser navigation result platform-native |
-
-## app-bar.html
-
-### Overview
-
-Responsive application navigation, route state, status, and trailing actions.
-
-### Public surface
-
-Methods/properties: `setNavigation()`, `setActiveRoute()`, `setStatus()`, `refresh()`, `destroy()`.
-
-Events: `app-bar-ready`.
-
-Slots: `brand-mark`, `product-name`, `navigation`, `status`, `trailing`.
-
-### Availability and normalization
-
-**Browser and supported native WebViews.** DOM-normalized. HTMLImport + DOM; injected Arcane/provider modules where listed. Native methods remain subject to the bound app's capabilities. [Deep protocol details](protocols.md).
-
-### Example
-
-```html
-<html-import
-  id="app-bar.html"
-  href="/arcane/components/app-bar.html">
-</html-import>
-```
-
-## assistant-panel.html
-
-### Overview
-
-Reusable assistant drawer, message area, composer, pending/streaming/empty/error state, and actions.
-
-### Public surface
-
-Methods/properties: `open()`, `close()`, `toggle()`, `send()`, `clear()`, `setState()`, `focusComposer()`, `scrollToEnd()`, `destroy()`.
-
-Events: `assistant-ready`, `assistant-opened`, `assistant-closed`,
-`assistant-send`, `assistant-clear`.
-
-Slots: `title`, `subtitle`, `identity`, `messages/message`, `composer`, `actions`, `pending`, `streaming`, `empty`, `error`, `footer`.
-
-### Availability and normalization
-
-**Browser and supported native WebViews.** DOM-normalized; caller/provider results 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
-
-```html
-<html-import
-  id="assistant-panel.html"
-  href="/arcane/components/assistant-panel.html">
-</html-import>
-```
-
-## calculator.html
-
-### Overview
-
-Calculator keypad and result/error event surface backed by CalculatorEngine.
-
-### Public surface
-
-Methods/properties: `calculate()`, `destroy()`.
-
-Events: `calculator-ready`, `calculation-complete`, `calculation-error`.
-
-Shared dependencies: [`CalculatorEngine.js`](runtime-modules.md#calculatorenginejs).
-
-### Availability and normalization
-
-**Browser and supported native WebViews.** Normalized Calculation/error events. HTMLImport + DOM; injected Arcane/provider modules where listed. Native methods remain subject to the bound app's capabilities. [Deep protocol details](protocols.md).
-
-### Example
-
-```html
-<html-import
-  id="calculator.html"
-  href="/arcane/components/calculator.html">
-</html-import>
-```
-
-## chart.html
-
-### Overview
-
-Accessible uPlot line, area, or point chart with normalized options and rows.
-
-### Public surface
-
-Methods/properties: `configure()`, `populate()`, `setData()`, `addData()`, `update()`, `destroy()`.
-
-Events: `chart-ready`, `chart-remove`.
-
-Shared dependencies: [`ChartLibrary.js`](runtime-modules.md#chartlibraryjs), [`ComponentContracts.js`](runtime-modules.md#componentcontractsjs).
-
-### Availability and normalization
-
-**Browser and supported native WebViews.** Options/rows normalized; uPlot rendering is vendor-native. HTMLImport + DOM; injected Arcane/provider modules where listed. Native methods remain subject to the bound app's capabilities. [Deep protocol details](protocols.md).
-
-### Example
-
-```html
-<html-import
-  id="chart.html"
-  href="/arcane/components/chart.html">
-</html-import>
-```
-
-## chat.html
-
-### Overview
-
-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()`, `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.
-
-`submitMessage(textOverride='',context={})` returns `Promise<boolean>`.
-`context` accepts `source`, `preserveDraft`, `synthetic`, an optional exact
-`operationId`, and an optional caller-owned `AbortSignal`. The component owns a
-derived signal for each submission, supplies it in the frozen compatibility
-`{message,context}` detail, and aborts it on canonical/DOM cancellation,
-component destruction, or caller cancellation. `chat-send-message` is
-cancelable and is the gate before `sendMessage(text,context)`; a canceled event
-never reaches the host callback. Rejected host promises are observed as
-`chat-send-error`, and stale settlement after abort or destruction is
-suppressed.
-
-`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-file-upload-error`, `chat-language-changed`,
-`chat-language-change-error`, `chat-ai-activation-request`,
-`chat-ai-activation-error`, `chat-speech-synthesis-error`, and
-`conversation-timebox-error`.
-
-All chat operation ids have the form
-`<component-instance-id>:<kind>:<sequence>`. The stable public reasons are
-`chat-ready`, `message-submission-requested`,
-`message-submission-cancelled`, `caller-signal-aborted`,
-`component-destroyed`, `host-message-submission-rejected`,
-`file-storage-completed`, `file-storage-rejected`,
-`language-change-requested`, `language-change-callback-rejected`,
-`language-model-activation-requested`,
-`language-model-activation-rejected`, `speech-synthesis-rejected`, and
-`conversation-timebox-delivery-rejected`.
-
-The stable chat boundary codes are:
-
-- `ARCANE_CHAT_MESSAGE_SUBMISSION_ABORTED` for the owned submission signal;
-- `ARCANE_CHAT_LANGUAGE_MODEL_ACTIVATION_REQUEST_REJECTED`;
-- `ARCANE_CHAT_HOST_MESSAGE_SUBMISSION_REJECTED`;
-- `ARCANE_CHAT_FILE_STORAGE_REJECTED`;
-- `ARCANE_CHAT_LANGUAGE_CHANGE_CALLBACK_REJECTED`;
-- `ARCANE_CHAT_SPEECH_SYNTHESIS_REQUEST_REJECTED`;
-- `ARCANE_CHAT_CONVERSATION_TIMEBOX_DELIVERY_REJECTED`.
-
-Error projections expose the boundary `code` and include `causeCode` only when
-the rejected dependency supplies a distinct code. File projections expose only
-size/type metadata canonically while retaining the live `File` locally.
-Language and LLM activation request projections are cancelable gates before
-their host callbacks. Every public detail is frozen by the canonical authority.
-
-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 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
-
-```html
-<html-import
-  id="chat.html"
-  href="/arcane/components/chat.html">
-</html-import>
-```
-
-## conversation-view.html
-
-### Overview
-
-Provider-neutral conversation display, advisory actions, composer, busy state, and status.
-
-### Public surface
-
-Methods/properties: `setConversation()`, `setBusy()`, `setStatus()`, `clearComposer()`, `destroy()`.
-
-Events: `conversation-view-ready`, `communication-send`, `communication-advisory-action`.
-
-### Availability and normalization
-
-**Browser and supported native WebViews.** DOM-normalized. HTMLImport + DOM; injected Arcane/provider modules where listed. Native methods remain subject to the bound app's capabilities. [Deep protocol details](protocols.md).
-
-### Example
-
-```html
-<html-import
-  id="conversation-view.html"
-  href="/arcane/components/conversation-view.html">
-</html-import>
-```
-
-## dashboard-config.html
-
-### Overview
-
-Selects which normalized chart definitions are visible on a dashboard.
-
-### Public surface
-
-Methods/properties: `configure()`, `setDefinitions()`, `setVisibility()`, `getChartOptions()`, `getEffectiveVisibility()`, `open()`, `close()`, `destroy()`.
-
-Events: `dashboard-config-ready`, `dashboard-config-opened`, `dashboard-config-closed`, `dashboard-config-change`.
-
-Shared dependencies: [`ComponentContracts.js`](runtime-modules.md#componentcontractsjs), [`WaitForComponent.js`](runtime-modules.md#waitforcomponentjs).
-
-### Availability and normalization
-
-**Browser and supported native WebViews.** Fully normalized definitions and visibility. HTMLImport + DOM; injected Arcane/provider modules where listed. Native methods remain subject to the bound app's capabilities. [Deep protocol details](protocols.md).
-
-### Example
-
-```html
-<html-import
-  id="dashboard-config.html"
-  href="/arcane/components/dashboard-config.html">
-</html-import>
-```
-
-## data-maintenance.html
-
-### Overview
-
-Runs destructive cleanup of empty chats and memories inside the current app data scope.
-
-### Public surface
-
-Methods/properties: `open()`, `destroy()`.
-
-Events: `data-maintenance-ready`, `data-maintenance-complete`.
-
-Shared dependencies: [`DataMaintenance.js`](runtime-modules.md#datamaintenancejs), [`WaitForComponent.js`](runtime-modules.md#waitforcomponentjs).
-
-### Availability and normalization
-
-**Browser and supported native WebViews.** Normalized counts; DBOPFS failures mixed. HTMLImport + DOM; injected Arcane/provider modules where listed. Native methods remain subject to the bound app's capabilities. [Deep protocol details](protocols.md).
-
-### Example
-
-```html
-<html-import
-  id="data-maintenance.html"
-  href="/arcane/components/data-maintenance.html">
-</html-import>
-```
-
-## data-view.html
-
-### Overview
-
-Opens a generic modal-style data view around an injected provider.
-
-### Public surface
-
-Methods/properties: `beforeOpen()`, `open()`, `destroy()`.
-
-Events: `data-view-ready`.
-
-Shared dependencies: [`WaitForComponent.js`](runtime-modules.md#waitforcomponentjs).
-
-### Availability and normalization
-
-**Browser and supported native WebViews.** DOM-native result. HTMLImport + DOM; injected Arcane/provider modules where listed. Native methods remain subject to the bound app's capabilities. [Deep protocol details](protocols.md).
-
-### Example
-
-```html
-<html-import
-  id="data-view.html"
-  href="/arcane/components/data-view.html">
-</html-import>
-```
-
-## directory-picker.html
-
-### Overview
-
-Presents the provider-owned OS directory chooser with change/cancel/error states.
-
-### Public surface
-
-Methods/properties: `configure()`, `focus()`, `select()`, `destroy()`.
-
-Events: `directory-picker-ready`, `directory-picker-change`, `directory-picker-cancel`, `directory-picker-error`.
-
-Shared dependencies: [`DirectoryPicker.js`](runtime-modules.md#directorypickerjs).
-
-### Availability and normalization
-
-**Browser and supported native WebViews.** Strict normalized native selection/error. HTMLImport + DOM; injected Arcane/provider modules where listed. Native methods remain subject to the bound app's capabilities. [Deep protocol details](protocols.md).
-
-### Example
-
-```html
-<html-import
-  id="directory-picker.html"
-  href="/arcane/components/directory-picker.html">
-</html-import>
-```
-
-## document-inspector.html
-
-### Overview
-
-Inspects PDF, text, or source documents and records review state.
-
-### Public surface
-
-Methods/properties: `loadDocument()`, `selectView()`, `markSaved()`, `destroy()`.
-
-Events: `document-inspector-ready`, `document-review-change`.
-
-Shared dependencies: [`MD.js`](runtime-modules.md#mdjs).
-
-### Availability and normalization
-
-**Browser and supported native WebViews.** Document state normalized; browser document APIs mixed. HTMLImport + DOM; injected Arcane/provider modules where listed. Native methods remain subject to the bound app's capabilities. [Deep protocol details](protocols.md).
-
-### Example
-
-```html
-<html-import
-  id="document-inspector.html"
-  href="/arcane/components/document-inspector.html">
-</html-import>
-```
-
-## file-drop.html
-
-### Overview
-
-Acquires files by drag/drop or picker and presents busy, progress, error, and cleared state.
-
-### Public surface
-
-Methods/properties: `configure()`, `openPicker()`, `clear()`, `setBusy()`, `setError()`, `setProgress()`, `destroy()`.
-
-Events: `file-drop-ready`, `file-drop-selected`, `file-drop-progress`, `file-drop-state`, `file-drop-error`.
-
-### Availability and normalization
-
-**Browser and supported native WebViews.** State normalized; browser File/drop errors mixed. HTMLImport + DOM; injected Arcane/provider modules where listed. Native methods remain subject to the bound app's capabilities. [Deep protocol details](protocols.md).
-
-### Example
-
-```html
-<html-import
-  id="file-drop.html"
-  href="/arcane/components/file-drop.html">
-</html-import>
-```
-
-## file-inspector.html
-
-### Overview
-
-Displays file metadata, preview, busy/error state, and caller-defined actions.
-
-### Public surface
-
-Methods/properties: `configure()`, `show()`, `clear()`, `setActions()`, `setBusy()`, `setError()`, `setPreview()`, `destroy()`.
-
-Events: `file-inspector-ready`, `file-inspector-action`, `file-inspector-change`, `file-inspector-cleared`, `file-inspector-error`.
-
-Slots: `title`, `preview`, `metadata`, `actions`.
-
-### Availability and normalization
-
-**Browser and supported native WebViews.** State normalized; preview/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).
-
-### Example
-
-```html
-<html-import
-  id="file-inspector.html"
-  href="/arcane/components/file-inspector.html">
-</html-import>
-```
-
-## file-manager.html
-
-### Overview
-
-Browses, filters, selects, opens, and acts on app-scoped files.
-
-### Public surface
-
-Methods/properties: `setProvider()`, `loadAll()`, `setFilter()`, `select()`, `clearSelection()`, `destroy()`.
-
-Events: `file-manager-ready`, `file-manager-select`, `file-manager-open`, `file-manager-action`.
-
-Shared dependencies: [`DBOPFS.js`](runtime-modules.md#dbopfsjs), [`File.js`](runtime-entities.md#filejs), [`WaitForComponent.js`](runtime-modules.md#waitforcomponentjs).
-
-### Availability and normalization
-
-**Browser and supported native WebViews.** Selection/filter state normalized; storage/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).
-
-### Example
-
-```html
-<html-import
-  id="file-manager.html"
-  href="/arcane/components/file-manager.html">
-</html-import>
-```
-
-## header.html
-
-### Overview
-
-Legacy title bar with history, reload, online marker, presentation labels, and 988 link.
-
-### Public surface
-
-This fragment declares no public host method.
-
-This fragment declares no component-specific readiness or action event; use the loader's `html-import-ready` only to know that import execution completed.
-
-### Availability and normalization
-
-**Browser and supported native WebViews.** Browser/platform-native behavior; no component-ready contract. HTMLImport + DOM; injected Arcane/provider modules where listed. Native methods remain subject to the bound app's capabilities. [Deep protocol details](protocols.md).
-
-### Example
-
-```html
-<html-import
-  id="header.html"
-  href="/arcane/components/header.html">
-</html-import>
-```
-
-## integration-settings.html
-
-### Overview
-
-Edits non-secret communication service configuration and service actions.
-
-### Public surface
-
-Methods/properties: `configure()`, `getValues()`, `setStatus()`, `destroy()`.
-
-Events: `integration-settings-ready`, `integration-settings-save`, `integration-settings-close`, `integration-action`.
-
-### Availability and normalization
-
-**Browser and supported native WebViews.** Normalized non-secret values. HTMLImport + DOM; injected Arcane/provider modules where listed. Native methods remain subject to the bound app's capabilities. [Deep protocol details](protocols.md).
-
-### Example
-
-```html
-<html-import
-  id="integration-settings.html"
-  href="/arcane/components/integration-settings.html">
-</html-import>
-```
-
-## local-ai-status.html
-
-### Overview
-
-Presents local-AI standby, failure, recovery, guidance, retry, and dismissal states.
-
-### Public surface
-
-Methods/properties: `configure()`, `begin()`, `present()`, `destroy()`, and the `hidden` property.
-
-Events: `local-ai-status-ready`, `local-ai-status-dismissed`, `local-ai-retry`.
-
-Shared dependencies: [`LocalAIReadiness.js`](runtime-modules.md#localaireadinessjs).
-
-### Availability and normalization
-
-**Browser and supported native WebViews.** Fully normalized LocalAIReadiness report. HTMLImport + DOM; injected Arcane/provider modules where listed. Native methods remain subject to the bound app's capabilities. [Deep protocol details](protocols.md).
-
-### Example
-
-```html
-<html-import
-  id="local-ai-status.html"
-  href="/arcane/components/local-ai-status.html">
-</html-import>
-```
-
-## markdown-document.html
-
-### Overview
-
-Safely renders and navigates a Markdown document with focusable fragments.
-
-### Public surface
-
-Methods/properties: `configure()`, `load()`, `render()`, `clear()`, `fail()`, `focus()`, `focusFragment()`, `destroy()`.
-
-Events: `markdown-document-ready`, `markdown-document-state`,
-`markdown-document-loading`, `markdown-document-rendered`,
-`markdown-document-empty`, `markdown-document-error`, and
-`markdown-document-navigate`.
-
-Shared dependencies: [`MD.js`](runtime-modules.md#mdjs).
-
-### Availability and normalization
-
-**Browser and supported native WebViews.** State/sanitized output normalized; Marked/DOM failures mixed. HTMLImport + DOM; injected Arcane/provider modules where listed. Native methods remain subject to the bound app's capabilities. [Deep protocol details](protocols.md).
-
-### Example
-
-```html
-<html-import
-  id="markdown-document.html"
-  href="/arcane/components/markdown-document.html">
-</html-import>
-```
-
-## markdown-editor.html
-
-### Overview
-
-Configurable Markdown authoring, toolbar, preview, title, and save surface.
-
-### Public surface
-
-Methods/properties: `configure()`, `focus()`, `clear()`, `saveEntry()`, `destroy()`.
-
-Events: `markdown-editor-ready`, `markdown-editor-change`, `markdown-editor-saved`.
-
-Shared dependencies: [`MD.js`](runtime-modules.md#mdjs), [`ComponentContracts.js`](runtime-modules.md#componentcontractsjs).
-
-### Availability and normalization
-
-**Browser and supported native WebViews.** Editor values normalized; injected save result mixed. HTMLImport + DOM; injected Arcane/provider modules where listed. Native methods remain subject to the bound app's capabilities. [Deep protocol details](protocols.md).
-
-### Example
-
-```html
-<html-import
-  id="markdown-editor.html"
-  href="/arcane/components/markdown-editor.html">
-</html-import>
-```
-
-## media-embed.html
-
-### Overview
-
-Loads a validated YouTube video or playlist embed and exposes external-platform action.
-
-### Public surface
-
-Methods/properties: `configure()`, `load()`, `destroy()`.
-
-Events: `media-embed-ready`, `media-load`, `media-error`, `media-open-platform`.
-
-Shared dependencies: [`YouTubeMedia.js`](runtime-modules.md#youtubemediajs).
-
-### Availability and normalization
-
-**Browser and supported native WebViews.** URL/error normalized; iframe/platform behavior native. HTMLImport + DOM; injected Arcane/provider modules where listed. Native methods remain subject to the bound app's capabilities. [Deep protocol details](protocols.md).
-
-### Example
-
-```html
-<html-import
-  id="media-embed.html"
-  href="/arcane/components/media-embed.html">
-</html-import>
-```
-
-## modal.html
-
-### Overview
-
-Generic modal with population, open/close, actions, and sequential task execution.
-
-### Public surface
-
-Methods/properties: `populate()`, `open()`, `close()`, `runTasks()`, `destroy()`.
-
-Events: `modal-ready`, `modal-opened`, `modal-closed`, `modal-action`.
-
-Slots: `header`, `body`, `footer`.
-
-### Availability and normalization
-
-**Browser and supported native WebViews.** Modal state normalized; injected task results mixed. HTMLImport + DOM; injected Arcane/provider modules where listed. Native methods remain subject to the bound app's capabilities. [Deep protocol details](protocols.md).
-
-### Example
-
-```html
-<html-import
-  id="modal.html"
-  href="/arcane/components/modal.html">
-</html-import>
-```
-
-## output-panel.html
-
-### Overview
-
-Presents status, output, body, coverage, actions, pending, error, and cleared states.
-
-### Public surface
-
-Methods/properties: `configure()`, `setOutput()`, `setBody()`, `setCoverage()`, `setActions()`, `setPending()`, `setStatus()`, `setError()`, `clear()`, `destroy()`.
-
-Events: `output-panel-ready`, `output-panel-state`, `output-panel-change`, `output-panel-action`, `output-panel-error`, `output-panel-cleared`.
-
-Slots: `title`, `header-actions`, `body`, `coverage`, `actions`.
-
-### Availability and normalization
-
-**Browser and supported native WebViews.** DOM-normalized. HTMLImport + DOM; injected Arcane/provider modules where listed. Native methods remain subject to the bound app's capabilities. [Deep protocol details](protocols.md).
-
-### Example
-
-```html
-<html-import
-  id="output-panel.html"
-  href="/arcane/components/output-panel.html">
-</html-import>
-```
-
-## preferences-form.html
-
-### Overview
-
-Builds a schema-driven preferences form with submit, reset, busy, and status behavior.
-
-### Public surface
-
-Methods/properties: `configure()`, `getValues()`, `setValues()`, `setBusy()`, `setStatus()`, `destroy()`.
-
-Events: `preferences-form-ready`, `preferences-change`, `preferences-submit`, `preferences-reset`.
-
-### Availability and normalization
-
-**Browser and supported native WebViews.** Normalized form values. HTMLImport + DOM; injected Arcane/provider modules where listed. Native methods remain subject to the bound app's capabilities. [Deep protocol details](protocols.md).
-
-### Example
-
-```html
-<html-import
-  id="preferences-form.html"
-  href="/arcane/components/preferences-form.html">
-</html-import>
-```
-
-## record-timeline.html
-
-### Overview
-
-Displays chronological records/evidence and emits open actions.
-
-### Public surface
-
-Methods/properties: `setItems()`, `populate()`, `destroy()`.
-
-Events: `record-timeline-ready`, `record-timeline-open`.
-
-### Availability and normalization
-
-**Browser and supported native WebViews.** DOM-normalized. HTMLImport + DOM; injected Arcane/provider modules where listed. Native methods remain subject to the bound app's capabilities. [Deep protocol details](protocols.md).
-
-### Example
-
-```html
-<html-import
-  id="record-timeline.html"
-  href="/arcane/components/record-timeline.html">
-</html-import>
-```
-
-## relationship-board.html
-
-### Overview
-
-Displays normalized relationship nodes/edges in graph and list forms.
-
-### Public surface
-
-Methods/properties: `setGraph()`, `populate()`, `destroy()`.
-
-Events: `relationship-board-ready`, `relationship-node-open`, `relationship-edge-open`.
-
-### Availability and normalization
-
-**Browser and supported native WebViews.** DOM-normalized. HTMLImport + DOM; injected Arcane/provider modules where listed. Native methods remain subject to the bound app's capabilities. [Deep protocol details](protocols.md).
-
-### Example
-
-```html
-<html-import
-  id="relationship-board.html"
-  href="/arcane/components/relationship-board.html">
-</html-import>
-```
-
-## screen-capture.html
-
-### Overview
-
-Presents image, video, or GIF display-capture workflow.
-
-### Public surface
-
-Methods/properties: `capture` (the component-owned `ScreenCapture` instance) and `destroy()`.
-
-Events: `screen-capture-ready`, `screen-capture-result`.
-
-Ready uses operation id `screen-capture-ready-<component-instance-id>`;
-capture results use the current instance-owned generation. `destroy()`
-invalidates that generation, aborts UI listeners, revokes the preview URL,
-destroys the `ScreenCapture` instance, disposes the source, marks the host
-unready, and returns `true`; repeated calls return `false`.
-
-Shared dependencies: [`ScreenCapture.js`](runtime-modules.md#screencapturejs).
-
-### Availability and normalization
-
-**Browser and supported native WebViews.** State/result normalized; media permission/codec failures mixed. HTMLImport + DOM; injected Arcane/provider modules where listed. Native methods remain subject to the bound app's capabilities. [Deep protocol details](protocols.md).
-
-### Example
-
-```html
-<html-import
-  id="screen-capture.html"
-  href="/arcane/components/screen-capture.html">
-</html-import>
-```
-
-## source-code-viewer.html
-
-### Overview
-
-Renders line-addressable source code with load, error, focus, and state behavior.
-
-### Public surface
-
-Methods/properties: `configure()`, `load()`, `render()`, `clear()`, `fail()`, `focus()`, `focusLine()`, `destroy()`.
-
-Events: `source-code-viewer-ready`, `source-code-viewer-state`,
-`source-code-viewer-state-loading`, `source-code-viewer-state-ready`,
-`source-code-viewer-state-empty`, and `source-code-viewer-state-error`.
-
-### Availability and normalization
-
-**Browser and supported native WebViews.** Normalized source/state. HTMLImport + DOM; injected Arcane/provider modules where listed. Native methods remain subject to the bound app's capabilities. [Deep protocol details](protocols.md).
-
-### Example
-
-```html
-<html-import
-  id="source-code-viewer.html"
-  href="/arcane/components/source-code-viewer.html">
-</html-import>
-```
-
-## source-explanation.html
-
-### Overview
-
-Presents an evidence finding, source selection, explanation, and save state.
-
-### Public surface
-
-Methods/properties: `showFinding()`, `populate()`, `selectSource()`, `markSaved()`, `destroy()`.
-
-Events: `source-explanation-ready`, `source-explanation-save`, `source-explanation-source-selected`.
-
-### Availability and normalization
-
-**Browser and supported native WebViews.** DOM-normalized. HTMLImport + DOM; injected Arcane/provider modules where listed. Native methods remain subject to the bound app's capabilities. [Deep protocol details](protocols.md).
-
-### Example
-
-```html
-<html-import
-  id="source-explanation.html"
-  href="/arcane/components/source-explanation.html">
-</html-import>
-```
-
-## speech.html
-
-### Overview
-
-Coordinates explicit speech-to-text activation, speech controls, transcription
-completion, mute state, and microphone availability.
-
-### Public surface
-
-Methods/properties: `configure()`, `setAvailability()`, `setMuted()`,
-`reportTTSError(error,boundary='synthesis')`, `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`, `speech-tts-lifecycle-error`, and
-`speech-synthesis-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.
-
-Speech operation ids are
-`<component-instance-id>:<kind>:<sequence>`. Canonical cancellation reasons are
-`stt-role-unready`, `stt-provider-transcription-cancelled`, `stt-role-busy`,
-`microphone-unavailable`, `component-destroyed`, and
-`stt-transcription-cancelled`. Microphone capture-failure reasons are
-`microphone-input-missing`, `microphone-input-unavailable`,
-`microphone-capture-denied`, and `microphone-capture-rejected`. Component
-boundary codes are `ARCANE_SPEECH_MICROPHONE_CAPTURE_REJECTED`,
-`ARCANE_SPEECH_STT_TRANSCRIPTION_REQUEST_REJECTED`,
-`ARCANE_SPEECH_TTS_LOAD_REJECTED`, `ARCANE_SPEECH_TTS_UNLOAD_REJECTED`,
-`ARCANE_SPEECH_TTS_SYNTHESIS_REQUEST_REJECTED`, and
-`ARCANE_SPEECH_TTS_PLAYBACK_RESUME_REJECTED`. Each of those component-boundary
-public projections keeps the exact boundary in `code` and preserves a distinct
-string code from the browser, runtime, or provider additively as `causeCode`.
-A missing STT method therefore uses boundary
-`ARCANE_SPEECH_STT_TRANSCRIPTION_REQUEST_REJECTED` with
-`causeCode:'ARCANE_SPEECH_STT_RUNTIME_METHOD_UNAVAILABLE'`.
-
-Stable rejection reasons are `stt-transcription-rejected`,
-`tts-load-rejected`, `tts-unload-rejected`, `tts-synthesis-rejected`, and
-`tts-playback-resume-rejected`. Shared activation rejection uses
-`ARCANE_STT_ACTIVATION_REQUEST_REJECTED` and `activation-request-rejected`.
-
-### Availability and normalization
-
-**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
-
-```html
-<html-import
-  id="speech.html"
-  href="/arcane/components/speech.html">
-</html-import>
-```
-
-## summary-strip.html
-
-### Overview
-
-Displays compact selectable KPI or summary items.
-
-### Public surface
-
-Methods/properties: `configure()`, `setItems()`, `updateItem()`, `clear()`, `destroy()`.
-
-Events: `summary-strip-ready`, `summary-strip-change`, `summary-strip-select`.
-
-### Availability and normalization
-
-**Browser and supported native WebViews.** DOM-normalized. HTMLImport + DOM; injected Arcane/provider modules where listed. Native methods remain subject to the bound app's capabilities. [Deep protocol details](protocols.md).
-
-### Example
-
-```html
-<html-import
-  id="summary-strip.html"
-  href="/arcane/components/summary-strip.html">
-</html-import>
-```
-
-## table.html
-
-### Overview
-
-Builds and updates a simple header/body table.
-
-### Public surface
-
-Methods/properties: `buildHeader()`, `buildTable()`, `destroy()`.
-
-Events: `table-ready`, `header-update`, `body-update`.
-
-### Availability and normalization
-
-**Browser and supported native WebViews.** DOM-normalized. HTMLImport + DOM; injected Arcane/provider modules where listed. Native methods remain subject to the bound app's capabilities. [Deep protocol details](protocols.md).
-
-### Example
-
-```html
-<html-import
-  id="table.html"
-  href="/arcane/components/table.html">
-</html-import>
-```
-
-## task-progress.html
-
-### Overview
-
-Runs and displays a task list with started/change/complete/error state.
-
-### Public surface
-
-Methods/properties: `configure()`, `setTasks()`, `updateTask()`, `runTasks()`, `clear()`, `destroy()`.
-
-Events: `task-progress-ready`, `task-progress-started`, `task-progress-change`, `task-progress-complete`, `task-progress-error`.
-
-### Availability and normalization
-
-**Browser and supported native WebViews.** Task state normalized; injected task results mixed. HTMLImport + DOM; injected Arcane/provider modules where listed. Native methods remain subject to the bound app's capabilities. [Deep protocol details](protocols.md).
-
-### Example
-
-```html
-<html-import
-  id="task-progress.html"
-  href="/arcane/components/task-progress.html">
-</html-import>
-```
-
-## terminal-workspace.html
-
-### Overview
-
-Presents multiple terminal sessions, output, active selection, theme, and terminal actions.
-
-### Public surface
-
-Methods/properties: `configure()`, `addSession()`, `removeSession()`, `activateSession()`, `append()`, `clear()`, `setState()`, `setTheme()`, `focus()`, `destroy()`.
-
-Events: `terminal-workspace-ready`, `terminal-submit`, `terminal-interrupt`, `terminal-clear`, `terminal-session-new`, `terminal-session-close`, `terminal-session-select`, `terminal-settings`.
-
-Shared dependencies: [`AnsiText.js`](runtime-modules.md#ansitextjs).
-
-### Availability and normalization
-
-**Browser and supported native WebViews.** UI/session state normalized; native command results supplied externally. HTMLImport + DOM; injected Arcane/provider modules where listed. Native methods remain subject to the bound app's capabilities. [Deep protocol details](protocols.md).
-
-### Example
-
-```html
-<html-import
-  id="terminal-workspace.html"
-  href="/arcane/components/terminal-workspace.html">
-</html-import>
-```
-
-## theme-editor.html
-
-### Overview
-
-Edits, previews, saves, and resets semantic custom theme tokens.
-
-### Public surface
-
-Methods/properties: `configure()`, `getTheme()`, `setTheme()`, `setBusy()`, `setStatus()`, `destroy()`.
-
-Events: `theme-editor-ready`, `theme-preview`, `theme-save`, `theme-reset`.
-
-Shared dependencies: [`Theme.js`](runtime-entities.md#themejs).
-
-### Availability and normalization
-
-**Browser and supported native WebViews.** Fully normalized Theme values. HTMLImport + DOM; injected Arcane/provider modules where listed. Native methods remain subject to the bound app's capabilities. [Deep protocol details](protocols.md).
-
-### Example
-
-```html
-<html-import
-  id="theme-editor.html"
-  href="/arcane/components/theme-editor.html">
-</html-import>
-```
-
-## theme-switcher.html
-
-### Overview
-
-Selects and refreshes system, light, dark, or custom theme mode.
-
-### Public surface
-
-Methods/properties: `setMode()`, `refresh()`.
-
-This fragment declares no component-specific readiness or action event; use the loader's `html-import-ready` only to know that import execution completed.
-
-Shared dependencies: [`ThemeManager.js`](runtime-modules.md#thememanagerjs).
-
-### Availability and normalization
-
-**Browser and supported native WebViews.** Preference/native appearance behavior mixed; no component-ready contract. HTMLImport + DOM; injected Arcane/provider modules where listed. Native methods remain subject to the bound app's capabilities. [Deep protocol details](protocols.md).
-
-### Example
-
-```html
-<html-import
-  id="theme-switcher.html"
-  href="/arcane/components/theme-switcher.html">
-</html-import>
-```
-
-## unified-inbox.html
-
-### Overview
-
-Displays provider-neutral communication threads with active/loading state.
-
-### Public surface
-
-Methods/properties: `configure()`, `setThreads()`, `setActive()`, `setLoading()`, `destroy()`.
-
-Events: `unified-inbox-ready`, `inbox-refresh`, `thread-select`.
-
-### Availability and normalization
-
-**Browser and supported native WebViews.** DOM-normalized. HTMLImport + DOM; injected Arcane/provider modules where listed. Native methods remain subject to the bound app's capabilities. [Deep protocol details](protocols.md).
-
-### Example
-
-```html
-<html-import
-  id="unified-inbox.html"
-  href="/arcane/components/unified-inbox.html">
-</html-import>
-```
-
-## voice-transcription.html
-
-### Overview
-
-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()`, `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`,
-`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),
-[`AIRuntimeState.js`](runtime-modules.md#airuntimestatejs), and
-[`AI.js`](runtime-modules.md#aijs).
-
-### Availability and normalization
-
-**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`. Its local compatibility reason is
-`runtime-unready`, while its canonical/public reason is `stt-role-unready`. A
-busy role uses `stt-role-busy` in both views. A current provider cancellation
-returns the component workflow to `idle` with local
-`stt-provider-request-cancelled` and canonical/public
-`stt-provider-transcription-cancelled`; destruction uses
-`component-destroyed` in both views. Replacing configuration without an
-`initialValue` during active work uses `configuration-replaced` in both views.
-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
-
-```html
-<html-import
-  id="voice-transcription.html"
-  href="/arcane/components/voice-transcription.html">
-</html-import>
-```
-
-## weather-widget.html
-
-### Overview
-
-Displays normalized current and daily weather with refresh intent.
-
-### Public surface
-
-Methods/properties: `setWeather()`, `clear()`, `destroy()`.
-
-Events: `weather-widget-ready`, `weather-refresh`.
-
-### Availability and normalization
-
-**Browser and supported native WebViews.** Display normalized; provider supplied externally. HTMLImport + DOM; injected Arcane/provider modules where listed. Native methods remain subject to the bound app's capabilities. [Deep protocol details](protocols.md).
-
-### Example
-
-```html
-<html-import
-  id="weather-widget.html"
-  href="/arcane/components/weather-widget.html">
-</html-import>
-```
-
-## web-navigator.html
-
-### Overview
-
-Guards embedded/external navigation and surfaces allow/block/open intents.
-
-### Public surface
-
-Methods/properties: `configure()`, `navigate()`, `currentUrl()`, `destroy()`.
-
-Events: `web-navigator-ready`, `web-navigate`, `web-navigation-blocked`, `web-open-external`.
-
-### Availability and normalization
-
-**Browser and supported native WebViews.** Navigation intent/decision normalized; browser navigation result platform-native. HTMLImport + DOM; injected Arcane/provider modules where listed. Native methods remain subject to the bound app's capabilities. [Deep protocol details](protocols.md).
-
-### Example
-
-```html
-<html-import
-  id="web-navigator.html"
-  href="/arcane/components/web-navigator.html">
-</html-import>
-```
-
-## Readiness caveats
-
-`header.html` and `theme-switcher.html` do not currently publish a component-specific ready event/property. Consumers can observe `html-import-ready` for completed fragment execution and then feature-detect their methods. Other fragments publish the exact ready event listed above.