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

<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 shared 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 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 in a mutable complete record. A source 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 before a requested operation, 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 projected 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

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.

Example

<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.

Example

<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.

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.

Example

<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, ComponentContracts.js.

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.

Example

<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(), bindSession(), submitMessage(), submitToolResult(), submitToolResults(), sendMessage(), languageChanged(), requestAIActivation(), session, sessionStatus, pendingTool, pendingTools, pendingToolCall, pendingToolCalls, modelName, 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 mutable complete source {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.

bindSession({ai,session,sessionOptions}) accepts exactly one of a public AI API module or an existing compatible session, restores the UI transcript when available, and uses provider-safe history as its restoration fallback. The transcript is a masked vertical scroll viewport; status and composer remain outside it. Initial restoration and every user, assistant, tool, streaming, progress, or failure mutation scrolls that viewport to its true bottom. Each restored or new message uses a separate semantic <time> element at the card's lower-right with an ISO datetime, full local title, and local 24-hour HH:MM text.

Assistant structural calls render their nonempty function.arguments.message as ordinary visible progress. The exact call name and argument string are retained inside a collapsed Tool call details inspection surface. Displaying a call does not settle it or enable another user turn. submitToolResults({results,request?},{operationId?,signal?}) atomically settles the current ordered pending-call set. results supplies exactly one {toolCallId,status,message,persist?} record for every pending ID, without duplicates or omissions. status is executed, declined, cancelled, or not-executed; every result in the batch uses the same persistence choice. The method preserves pending order, persists and renders every human-readable status plus complete message as matching role:'tool' requests, and then renders one assistant continuation. Live submission and restored history both require nonblank user-facing result content; accepted text is preserved exactly rather than trimmed or rewritten.

submitToolResult({toolCallId?,status,message,persist?,request?},{operationId?,signal?}) is the single-call method. It infers the only pending ID when omitted and rejects when zero or multiple calls are pending; parallel calls must use submitToolResults(). Optional plain-object request contains per-turn generation choices forwarded through the session; a visibility-only host can use request:{toolChoice:'none'} after a not-executed result so that continuation cannot open another tool loop. Session-owned messages, signal, and streaming state remain unavailable through that field. Its terminal chat-session-message event releases the completed request ownership before publication, so a listener may call submitToolResult() immediately without a timer or microtask workaround. Internal protocol diagnostics remain in the developer console; they are not inserted as assistant content, and a rejected user draft is restored without losing its text.

Visible Chat failure copy is opt-in: only an Error deliberately marked userSafe:true may provide its nonblank userMessage or message. Every unknown provider, protocol, dispatch, persistence, or settlement failure keeps its complete Error object in the developer console and diagnostic event while the transcript and status use a generic user outcome. New diagnostic codes therefore cannot become conversational text merely because they are absent from a finite internal-error list.

streamMessage(text,id,isThinking) accepts text content only. An Error supplied as a stream chunk is logged and rejected rather than stringified into the transcript; any other nontext chunk fails with ARCANE_CHAT_STREAM_CONTENT_INVALID. setMessageProgress() preserves explicit string labels/status, but routes Error objects through the same user-safe copy boundary and otherwise displays generic progress text while logging the exact diagnostic value. Finite fractional and over-total progress remains visible in the status text and accessibility description; only the decorative track width is constrained to its visual range.

pendingTools is the mutable ordered array of actionable {id,name,message} summaries and never exposes raw arguments. pendingTool is that single-call summary only when exactly one call is pending. pendingToolCalls exposes complete copied call envelopes for an explicitly selected inspection or host settlement surface, while pendingToolCall is its single-call view. These pending-call views exist only for the active transient protocol. Durable history stores each tool's required user-facing message as an ordinary role:'tool' record with optional public name and result status; it stores no call envelope or ID and therefore does not recreate a pending executable call after reload. submitToolResult() and submitToolResults() accept status as the public result term; disposition remains an accepted input spelling. When a submitted turn uses persist:false, Chat may show its cards while that one operation is active, then removes them when the operation settles; neither the input nor response remains in the retained transcript or model context.

For streaming sessions, every provisional structural card and the terminal result must preserve the same choice, ordered call position, exact ID, type, function name, argument string, and extension fields. A changed or omitted observed call fails with AI_CHAT_STREAM_TOOL_CALL_MISMATCH; the provisional card is removed and the prior pending-call state is restored instead of leaving a ghost card or a false settlement.

setAIAvailability() remains a current LLM availability 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 standalone speech booleans or synthesizes ready speech roles without a selected, 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 inside the same activation area. Progress is indeterminate until a real finite positive total exists. A complete provider-reported completed, total, and unit measure is informational and remains visible without gating activation. modelName supplies the application-owned display label without moving model policy into the component. The default requestAIActivation(intent) forwards mutable {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 mutable complete {intent,state} detail. preventDefault() suppresses the callback. A callback failure dispatches the bubbles/composed, noncancelable chat-ai-activation-error event with mutable complete {request,error,message}. A recognized canceled load whose current route is unloaded or unloading is not reported as an activation error.

On pagehide, a BFCache-persisted page retains the component and its session, speech, listeners, and provider state. A matching persisted pageshow refreshes the current availability UI without rebinding or duplicating listeners. Nonpersisted pagehide remains terminal and calls destroy().

destroy() aborts the component's AI-runtime-state subscription, destroys the activation controller, removes both page lifecycle listeners, calls the optional speech controller's destroy(), sets ready to false, and returns true; later calls return false. It does not initiate a provider load or unload.

Chat listens for the bound (or current global) AI runtime's ai-tts-failure event and forwards its complete Error and exact operation boundary to speech.reportTTSError(). Playback-start or playback-resume failures can occur after Chat's streamTTS() preparation promise has resolved. SDK 0.5.12 adds a waitForPlayback:true mode for the terminal result of the segments submitted by one invocation; Chat continues to feed chunks without waiting for playback. Runtime mute, cancellation, permission waiting, and stale generations remain non-errors.

Each visible model chunk is forwarded to AI.streamTTS(text) in arrival order. The AI owner automatically removes repeated formatting marks from an outbound speech-input copy before the configured segmentation, admits completed segments to bounded synthesis immediately, and schedules the contiguous ready audio prefix on the audio clock. Chat retains the original Markdown for display and storage and owns no second speech queue. No app option selects or disables this cleanup. Single punctuation, ordinary repeated punctuation, language, and voice retain their existing behavior.

Events: chat-ready, chat-session-bound, chat-session-message, chat-session-error, 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 preserve the complete error detail, with the boundary code and any distinct dependency causeCode. File projections preserve the complete live File and its authored metadata. Language and LLM activation requests are cancelable before their host callbacks. Every public detail remains mutable.

Shared dependencies: MD.js, File.js, ConversationTimebox.js, AIRuntimeState.js.

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.

Example

<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.

Example

<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, WaitForComponent.js.

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.

Example

<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, WaitForComponent.js.

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.

Example

<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.

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.

Example

<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.

Availability and normalization

Browser and supported native WebViews. Complete directory paths and native selection/error content are preserved without trimming, character caps, or a generic control-character gate. The provider or operating system owns any platform-specific path failure. HTMLImport + DOM; injected Arcane/provider modules where listed. Native methods remain subject to the bound app's capabilities. Deep protocol details.

Example

<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.

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.

Example

<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. Complete picker, drop, and API selections are preserved; multiple remains a picker hint and maxFiles remains compatible configuration rather than a rejection or discard gate. Browser File/drop errors are mixed. HTMLImport + DOM; injected Arcane/provider modules where listed. Native methods remain subject to the bound app's capabilities. Deep protocol details.

Example

<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.

Example

<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, File.js, WaitForComponent.js.

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.

Example

<html-import
  id="file-manager.html"
  href="/arcane/components/file-manager.html">
</html-import>

header.html

Overview

Shared 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.

Example

<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.

Example

<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.

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.

Example

<html-import
  id="local-ai-status.html"
  href="/arcane/components/local-ai-status.html">
</html-import>

markdown-document.html

Overview

Renders and navigates a complete 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.

Availability and normalization

Browser and supported native WebViews. Complete Markdown and state are normalized; malformed input and Marked/DOM failures remain visible. HTMLImport

• DOM; injected Arcane/provider modules where listed. Native methods remain subject to the bound app's capabilities. Deep protocol details.

Example

<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, ComponentContracts.js.

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.

Example

<html-import
  id="markdown-editor.html"
  href="/arcane/components/markdown-editor.html">
</html-import>

media-embed.html

Overview

Loads a parsed YouTube video or playlist embed and exposes an external-platform action. Ordinary YouTube hosting is the default; configure({privacyEnhanced:true}) explicitly selects the privacy-enhanced host.

Public surface

Methods/properties: configure(), load(), destroy().

Events: media-embed-ready, media-load, media-error, media-open-platform.

Shared dependencies: YouTubeMedia.js.

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.

Example

<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.

Example

<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.

Example

<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.

Example

<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. Complete item inventories and fields are preserved while missing identity/date records remain non-renderable. HTMLImport + DOM; injected Arcane/provider modules where listed. Native methods remain subject to the bound app's capabilities. Deep protocol details.

Example

<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. Complete node, edge, lane, label, and summary inventories are preserved; edges still require existing endpoints. HTMLImport + DOM; injected Arcane/provider modules where listed. Native methods remain subject to the bound app's capabilities. Deep protocol details.

Example

<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.

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.

Example

<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. Complete mutable source/state is rendered without character or line caps; malformed control-character metadata still fails honestly. HTMLImport + DOM; injected Arcane/provider modules where listed. Native methods remain subject to the bound app's capabilities. Deep protocol details.

Example

<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.

Example

<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(), 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, AIRuntimeState.js, ComponentContracts.js, and DBLS.js.

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.

Only captured microphone input that completes the selected STT route emits speech-transcription-complete. A transient capture rejection reports speech-microphone-unavailable but remains locally retryable; an observed permission-denied state disables capture until the browser reports that the permission is available again, at which point the microphone-owned status is cleared.

The default requestSTTActivation(intent) forwards the mutable {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 mutable complete {intent,state} detail. preventDefault() suppresses the callback and intent. Callback failure emits speech-stt-activation-error with mutable complete {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.

Provider and runtime failures use generic visible speech status unless their Error owner explicitly marks nonblank copy with userSafe:true. Complete unknown diagnostics remain available through the developer console and error events; they do not become control labels or status text by default. The same boundary applies to STT activation, transcription, TTS lifecycle, synthesis, and playback failures.

reportTTSError() recognizes synthesis, decode, playback-start, and playback-resume. It mutes and stops the failed operation, preserves sticky provider readiness, and emits speech-synthesis-error with the exact boundary, stable reason/code, generic user-safe status, and complete Error in the local event detail.

• synthesis: tts-synthesis-rejected / ARCANE_SPEECH_TTS_SYNTHESIS_REQUEST_REJECTED;
• decode: tts-decode-rejected / ARCANE_SPEECH_TTS_DECODE_REJECTED;
• playback-start: tts-playback-start-rejected / ARCANE_SPEECH_TTS_PLAYBACK_START_REJECTED;
• playback-resume: tts-playback-resume-rejected / ARCANE_SPEECH_TTS_PLAYBACK_RESUME_REJECTED.

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.

Each transcription request owns an AbortController; its signal is passed as the second 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.

Each microphone attempt also owns one capture generation and one operation id from the initial getUserMedia() request through transcription settlement. A release while permission is still pending retires only that generation because the browser request cannot be canceled synchronously. If that stale request later resolves, the component stops its returned stream without clearing a newer press, status, operation id, or retry. Active capture finalization checks both the generation and operation id, and successful transcription retains the same capture operation id rather than inventing a second correlation boundary.

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. Configured initialMuted:false records that same unmute intent even when the TTS route is still unselected or loading; the component remains publicly muted until the selected role reaches ready, then applies the preserved intent. 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.

A BFCache-persisted pagehide retains the component, active provider state, microphone permission observation, and listeners. On persisted pageshow, the component resynchronizes the current AI mute state and rerenders its controls and status without duplicating activation or provider work. Nonpersisted pagehide remains terminal and destroys the component.

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, ARCANE_SPEECH_TTS_DECODE_REJECTED, ARCANE_SPEECH_TTS_PLAYBACK_START_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, tts-decode-rejected, tts-playback-start-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.

Example

<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.

Example

<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.

Example

<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.

Example

<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.

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.

Example

<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.

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.

Example

<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.

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.

Example

<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.

Example

<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 readiness, 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, ComponentContracts.js, AIRuntimeState.js, and AI.js.

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 remain unavailable 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,signal) so 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 mutable complete {intent,state}; preventDefault() suppresses the callback. The default requestSTTActivation(intent) publishes the mutable {role:'stt',action:'load'|'unload',reason:'user'} intent. Callback failure emits speech-stt-activation-error with mutable complete {request,error,message}. Import and state observation emit no activation request and never begin a model download. Unknown provider/runtime diagnostics remain complete in the developer console and error events, while controls use generic visible outcomes unless the Error owner explicitly marks nonblank copy with userSafe:true.

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 source-local 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. On a BFCache-persisted pagehide, the component and its owned state remain live. A persisted pageshow rerenders the retained authoritative state without restarting capture, transcription, or activation. Nonpersisted pagehide retains terminal destruction. 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 mutable complete {message,state,stt} record, where state remains the component workflow and stt is the authoritative mutable 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.

Example

<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.

Example

<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.

Example

<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.