arcane-os 0.35.0 → 0.36.0

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## 0.36.0
+
+- Add optional continuous microphone capture to `voice-transcription` through
+  `configure({capture:{mode:'continuous'}})`. The AudioWorklet retains rolling
+  pre-roll and emits complete mono Float32 WAV segments at amplitude-based
+  pauses, periodic boundaries, and final stop. Manual capture remains the default.
+- Keep microphone capture independent of the ordered transcription/save queue.
+  Failed transcription retains its clip; a failed save retains its text and
+  retries only that save. Stop releases the microphone, flushes the final clip,
+  and drains accepted work. Explicit cancellation aborts callbacks and discards
+  outstanding clips. Optional simple Start/Stop controls preserve the default
+  Complete action and application-owned persistence.
+- Add async `file-manager.previewDescriptor(originalFile, context)` for complete
+  text, Markdown, HTML, JSON, conversation, nested collection, media and download
+  views. Media loaders run only on explicit selection; closing or replacing a
+  preview aborts pending work and releases owned media resources. Existing
+  `previewTransform` remains supported.
+- Add `directoryFilter` before DBOPFS key and metadata reads, with `data-view`
+  forwarding the preview/filter hooks before loading. Preserve complete native
+  JSONL text, MIME-based HTML/Markdown handling and original binary downloads.
+  Application schemas, record mapping, persistence and presentation choices remain
+  application-owned; no saved-data migration or provider/model default changes.
+
 ## 0.35.0
 
 - Add `DBOPFS.createCompressedPNG({tableNames, additionalTables, signal})` to

package/README.md

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

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

@@ -272,7 +272,7 @@
     {
       "file": "runtime/arcane/components/data-view.html",
       "name": "data-view.html",
-      "purpose": "Opens a generic modal-style data view around an injected provider.",
+      "purpose": "Opens a modal file view and forwards application-owned preview and directory-filter callbacks to the shared file manager.",
       "methods": [
         "beforeOpen()",
         "open()",
@@ -287,7 +287,7 @@
       ],
       "availability": "Browser and supported native WebViews",
       "transport": "HTMLImport + DOM; injected Arcane/provider modules where listed",
-      "normalization": "DOM-native result"
+      "normalization": "DOM-native result. Forwards previewDescriptor, previewTransform, directoryFilter, data-hidden-prefixes, and data-show-hidden before the child file manager first loads; reopening refreshes them before loadAll. beforeOpen runs before those values are consumed. The child owns neutral preview rendering, cancellation, and media cleanup; destroy also destroys the child and modal."
     },
     {
       "file": "runtime/arcane/components/directory-picker.html",
@@ -396,11 +396,12 @@
     {
       "file": "runtime/arcane/components/file-manager.html",
       "name": "file-manager.html",
-      "purpose": "Browses, filters, selects, opens, and acts on app-scoped files.",
+      "purpose": "Browses app-scoped files, filters directories before reads, and renders application-described complete document, conversation, collection, and media previews.",
       "methods": [
         "setProvider()",
         "loadAll()",
         "setFilter()",
+        "setDirectoryFilter()",
         "select()",
         "clearSelection()",
         "destroy()"
@@ -415,11 +416,12 @@
       "dependencies": [
         "DBOPFS.js",
         "File.js",
+        "MD.js",
         "WaitForComponent.js"
       ],
       "availability": "Browser and supported native WebViews",
       "transport": "HTMLImport + DOM; injected Arcane/provider modules where listed",
-      "normalization": "Selection/filter state normalized; storage/provider behavior mixed"
+      "normalization": "Selection/filter state and neutral previews normalized; storage/provider behavior mixed. Initial directoryFilter and setDirectoryFilter(fn|null) use false-only exclusion before built-in DBOPFS key/metadata reads; data-hidden-prefixes also applies to directories unless data-show-hidden is present. Existing file predicates preserve their first argument and receive optional directory/fileName/path/layout context. previewDescriptor(original File,{directory,fileName,extension,path,mimeType,signal}) may asynchronously return text/markdown/html/json content, conversation messages with role/content/real timestamp and optional name/status, collection items, or image/audio/pdf/download content as Blob/File or a lazy ({signal}) loader. Downloads require fileName; descriptors accept title and images accept alt. Lazy items load only on explicit request and retain item-local retry. Close, replacement, and destroy abort the preview signal, suppress late output, remove iframe srcdoc, stop audio, and revoke all owned object URLs. HTML preserves the exact string in iframe srcdoc; HTML/Markdown MIME fallback supports extensionless files. Nullish descriptors preserve previewTransform for JSON-family files and native previews; untransformed JSONL/NDJSON retains complete raw text, and other binary files download the original File."
     },
     {
       "file": "runtime/arcane/components/header.html",
@@ -988,12 +990,14 @@
     {
       "file": "runtime/arcane/components/voice-transcription.html",
       "name": "voice-transcription.html",
-      "purpose": "Records segmented microphone audio only after authoritative STT admission, exposes explicit selected-STT activation, transcribes with cancellation, persists, and completes a combined transcript.",
+      "purpose": "Records manual clips or optional continuous microphone audio with rolling pre-roll, pause/periodic segments, ordered transcription and saves, retained failures, retry, cancellation, and complete transcript delivery.",
       "methods": [
         "configure()",
         "requestSTTActivation()",
         "startRecording()",
         "stopRecording()",
+        "retryTranscription()",
+        "cancelRecording()",
         "save()",
         "completeTranscription()/complete()",
         "clear()",
@@ -1004,6 +1008,8 @@
         "voice-transcription-ready",
         "voice-transcription-state",
         "voice-transcription-segment",
+        "voice-transcription-empty",
+        "voice-transcription-error",
         "voice-transcription-change",
         "voice-transcription-complete",
         "speech-transcription-complete",
@@ -1016,11 +1022,12 @@
         "MD.js",
         "ComponentContracts.js",
         "AIRuntimeState.js",
+        "ContinuousVoiceCapture.js",
         "AI.js"
       ],
       "availability": "Browser and supported native WebViews",
       "transport": "HTMLImport + DOM; injected Arcane/provider modules where listed",
-      "normalization": "Sticky runtime STT readiness, explicit activation, request cancellation, state/text, and BFCache-preserving page lifecycle are normalized; persisted pageshow rerenders retained state without restarting work, while nonpersisted pagehide destroys; media/provider behavior remains external"
+      "normalization": "Sticky STT readiness and explicit activation; default manual capture; optional continuous amplitude-based capture with rolling pre-roll, ordered STT/save stages, retained failures, save-only retry, sequence-bearing segment events, and capture/processing/queued/errorPhase/error state. Complete text remains exact. Continuous stop flushes and drains; explicit cancel, transcript/configuration replacement, and destruction abort outstanding work and suppress late effects. Persisted pagehide stops and flushes continuous capture while retaining component state; persisted pageshow rerenders without restarting capture; nonpersisted pagehide destroys. Media/provider behavior remains external."
     },
     {
       "file": "runtime/arcane/components/weather-widget.html",

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

@@ -8,9 +8,9 @@
     "sdkVersion": "0.6.0",
     "protocol": "arcane/1"
   },
-  "artifactCount": 86,
-  "javascriptArtifactCount": 84,
-  "esmExportCount": 355,
+  "artifactCount": 88,
+  "javascriptArtifactCount": 86,
+  "esmExportCount": 356,
   "artifacts": [
     {
       "file": "runtime/arcane/modules/AI.js",
@@ -417,7 +417,7 @@
       "availability": "Cross-host with an injected event constructor outside DOM hosts",
       "protocol": "In-process only",
       "normalization": "Fully normalized labels, rows, definitions, visibility, formats, editor and voice options, plus capability-neutral STT activation intent and presentation state. Complete finite progress measures remain visible, including fractional and over-total values.",
-      "surface": "Constant sets plus normalization, complete finite-progress formatting, and explicit STT activation helpers."
+      "surface": "Constant sets plus normalization, complete finite-progress formatting, and explicit STT activation helpers. normalizeVoiceOptions preserves manual capture and standard controls by default and accepts continuous capture timing/activity options, simple controls, showComplete, and retry/cancel labels."
     },
     {
       "file": "runtime/arcane/modules/ConfiguredAIChatSession.js",
@@ -433,6 +433,19 @@
       "normalization": "Complete mutable session/result; declarations and emitted calls require nonempty user-facing arguments.message; ordered parallel calls and their exact IDs/names/arguments/extensions remain raw only through the active matching tool continuation, then settled recurrence becomes complete ordinary visible content; one atomic result batch must settle every pending ID; per-turn request options cannot replace session-owned messages or signal; persisted sequencing has stable coded failures; and provider rejection remains visible.",
       "surface": "default `ConfiguredAIChatSession`, named `normalizeStructuralToolCall`; constructor accepts complete initial messages and one unresolved ordered structural-call tail; history/clear/prepare/send; per-turn request overrides preserve session-owned messages/signal; every pending ID requires exactly one matching nonblank role=tool result in the same request batch; settled raw protocol does not recur."
     },
+    {
+      "file": "runtime/arcane/modules/ContinuousVoiceCapture.js",
+      "name": "ContinuousVoiceCapture.js",
+      "kind": "esm",
+      "exports": [
+        "default"
+      ],
+      "summary": "Owns continuous microphone capture with rolling pre-roll, activity-triggered pause/periodic segments, complete WAV delivery, final flush, and cancellation.",
+      "availability": "Browser / native WebView with getUserMedia, AudioContext, and AudioWorklet",
+      "protocol": "Native microphone and Web Audio lifecycle; internal VoiceCaptureWorklet MessagePort",
+      "normalization": "Complete mono Float32 WAV Blob segments with session-local sequence, pause/periodic/stop reason, and durationMs. Sound amplitude drives segmentation without semantic speech recognition. Inactive audio produces no segment, and periodic segments do not reuse samples. Stop releases microphone tracks immediately and waits for final flush; cancel releases capture and suppresses late callbacks.",
+      "surface": "default ContinuousVoiceCapture; constructor({preRollMs=1500,quietMs=2000,chunkMs=30000,activityThreshold=0.02,onSegment,onError,onState}); start({mediaConstraints={audio:true},signal}={}) resolves boolean; stop() resolves after final flush; cancel() and destroy() release the owned session."
+    },
     {
       "file": "runtime/arcane/modules/ConversationActionItems.js",
       "name": "ConversationActionItems.js",
@@ -1360,6 +1373,17 @@
       "normalization": "Presentation only.",
       "surface": "Load with a stylesheet link before rendering uPlot charts."
     },
+    {
+      "file": "runtime/arcane/modules/VoiceCaptureWorklet.js",
+      "name": "VoiceCaptureWorklet.js",
+      "kind": "worker",
+      "exports": [],
+      "summary": "Segments microphone samples on the audio rendering thread and transfers complete mono Float32 WAV clips to ContinuousVoiceCapture.",
+      "availability": "AudioWorkletGlobalScope",
+      "protocol": "AudioWorklet processor arcane-continuous-voice-capture and its owner-local MessagePort",
+      "normalization": "Rolling pre-roll, amplitude activity, quiet and periodic boundaries, sequence, complete WAV audio, and stop acknowledgement are owned here. Silence does not emit clips; adjacent periodic clips have no repeated samples.",
+      "surface": "No ESM exports. ContinuousVoiceCapture loads this static worklet, supplies processorOptions, receives segment messages, and requests stop followed by the stopped acknowledgement."
+    },
     {
       "file": "runtime/arcane/modules/WaitForComponent.js",
       "name": "WaitForComponent.js",

package/docs/reference/runtime-components.md

@@ -67,12 +67,12 @@ appropriate.
 | [`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 |
+| [`data-view.html`](#data-viewhtml) | Opens a modal file view and forwards application-owned preview and directory-filter callbacks. | `beforeOpen()`<br>`open()`<br>`destroy()` | `data-view-ready` | DOM-native result; preview/filter configuration reaches the child before loading |
 | [`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` | Complete plain-text paths and 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 complete file selections 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` | Complete selections preserved; 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 |
+| [`file-manager.html`](#file-managerhtml) | Browses app-scoped files, filters directories before reads, and renders application-described previews. | `setProvider()`<br>`loadAll()`<br>`setFilter()`<br>`setDirectoryFilter()`<br>`select()`<br>`clearSelection()`<br>`destroy()` | `file-manager-ready`<br>`file-manager-select`<br>`file-manager-open`<br>`file-manager-action` | Selection/filter state, neutral preview descriptors, cancellation, and media cleanup normalized; storage/provider behavior mixed |
 | [`header.html`](#headerhtml) | Shared 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 |
@@ -96,7 +96,7 @@ appropriate.
 | [`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 readiness, exposes explicit selected-STT activation, transcribes complete content 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 complete state/text are normalized; media/provider behavior remains external |
+| [`voice-transcription.html`](#voice-transcriptionhtml) | Records manual clips or optional continuous microphone audio with pause/periodic segments, ordered transcription and saves, retained failures, and complete transcript delivery. | `configure()`<br>`requestSTTActivation()`<br>`startRecording()`<br>`stopRecording()`<br>`retryTranscription()`<br>`cancelRecording()`<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-empty`<br>`voice-transcription-error`<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 STT readiness, capture/queue lifecycle, retry, cancellation, and complete 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 |
 
@@ -641,19 +641,33 @@ Shared dependencies: [`DataMaintenance.js`](runtime-modules.md#datamaintenancejs
 
 ### Overview
 
-Opens a generic modal-style data view around an injected provider.
+Opens a modal file view using the shared file manager. Applications supply their
+own record mappings through the same preview callbacks as the standalone
+[`file-manager.html`](#file-managerhtml).
 
 ### Public surface
 
 Methods/properties: `beforeOpen()`, `open()`, `destroy()`.
 
+Assign `previewDescriptor`, `previewTransform`, and `directoryFilter` on the
+host before opening. The component forwards those callbacks, comma-separated
+`data-hidden-prefixes`, and the presence of `data-show-hidden` to its child
+before the child's first load. Reopening refreshes those values before
+`loadAll()`, so changed callbacks and hidden-directory choices take effect.
+`beforeOpen()` is awaited before this configuration is consumed. `data-dirs`
+selects the initial directories; `data-layout` defaults to `files`.
+
 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).
+**Browser and supported native WebViews.** DOM-native result. Preview records
+and directory policy remain application-owned; the child owns rendering,
+preview cancellation, and media cleanup. `destroy()` also destroys the child
+file manager and modal. HTMLImport + DOM; native methods remain subject to the
+bound app's capabilities. [Deep protocol details](protocols.md).
 
 ### Example
 
@@ -779,7 +793,9 @@ Slots: `title`, `preview`, `metadata`, `actions`.
 
 ### Overview
 
-Browses, filters, selects, opens, and acts on app-scoped files.
+Browses, filters, selects, opens, and acts on app-scoped files. Optional neutral
+preview descriptors let an application display complete text, documents,
+conversations, and related media without adding its record schemas to the SDK.
 
 The default tree provider is initialized before storage readiness starts the
 first load. Already-ready DBOPFS loads immediately; otherwise the component
@@ -788,15 +804,93 @@ and `destroy()` cleanup, without delaying unrelated component startup.
 
 ### Public surface
 
-Methods/properties: `setProvider()`, `loadAll()`, `setFilter()`, `select()`, `clearSelection()`, `destroy()`.
+Methods/properties: `setProvider()`, `loadAll()`, `setFilter()`,
+`setDirectoryFilter()`, `select()`, `clearSelection()`, `destroy()`,
+`previewDescriptor`, `previewTransform`, `directoryFilter`.
+
+Assign `directoryFilter(entry, context)` before the first load, or call
+`setDirectoryFilter(fn|null)` to replace it and reload an initialized manager.
+Returning exactly `false` excludes a directory. Context is
+`{directory,fileName,path,layout}`; directory-level calls have an empty
+`fileName`. The built-in DBOPFS paths apply this predicate before reading an
+excluded directory's keys or file metadata. Tree-provider entries are also
+filtered before display and expansion; an injected provider still owns the
+reads inside its own `list()` implementation.
+
+Comma-separated `data-hidden-prefixes` now applies to directory names as well
+as the existing filename filtering. `data-show-hidden` disables the prefix
+rule, while the explicit directory predicate remains active. Existing
+`setFilter(fn|null)` and provider `filter` predicates retain their entry first
+argument and false-only exclusion behavior; their optional second argument
+is the same `{directory,fileName,path,layout}` context.
+
+`previewDescriptor(file, context)` receives the original opened `File`, not a
+serialized copy or a JSON-only projection. Context is
+`{directory,fileName,extension,path,mimeType,signal}`. It may return a descriptor
+or a promise for one. Returning `null` or `undefined` continues through the
+existing preview path. Application record parsing and mapping belong in this
+callback; the SDK supplies no conversation or media-storage schema.
+
+Each descriptor accepts an optional `title`. Supported shapes are:
+
+| Kind | Content |
+| --- | --- |
+| `text` | `content`: complete string, displayed as preformatted text |
+| `markdown` | `content`: complete Markdown string, rendered by the shared Markdown owner |
+| `html` | `content`: complete HTML string assigned unchanged to a titled iframe's `srcdoc` |
+| `json` | `content`: value displayed as formatted JSON |
+| `conversation` | `messages`: ordered `{role,content,timestamp,name?,status?}` records |
+| `collection` | `items`: ordered descriptors, including nested collections |
+| `image`, `audio`, `pdf`, `download` | `content`: a `Blob` or `File`, or a function receiving `{signal}` and resolving to one |
+
+Conversation `role` and complete Markdown `content` are strings. Optional
+`name` and `status` are displayed alongside the role and time. Valid supplied
+timestamps are displayed in local time with their real ISO datetime; absent
+timestamps display `Time unavailable`, and an unrecognized supplied timestamp
+is displayed as supplied. No timestamp is invented.
+
+Images may supply `alt`; downloads require `fileName`. A media/download
+function is lazy: only that item's explicit **Load** button invokes it, with
+the preview's abort signal. A failed item shows `Unable to load this item.`
+and makes the same button available for retry; sibling items remain visible.
+The shared logger receives the original error. Immediate
+Blobs render directly. Audio exposes native controls without autoplay. The
+component does not automatically read every related media variant.
+
+Closing the preview, opening another file, or destroying the manager aborts
+the preview signal, ignores late descriptor/loader results, stops owned audio,
+removes iframe `srcdoc`, and revokes every owned object URL, including those
+in nested collections.
+Applications should observe the supplied signal in their asynchronous reads.
+Descriptor and file-open failures show `Unable to open this file.` in the
+current modal and send the original error to the shared logger.
+
+When no descriptor is returned, the existing
+`previewTransform(parsed,{directory,extension,fileName})` callback remains
+available for JSON-family files. Native image, audio, PDF, HTML, Markdown,
+JSON, and text presentation remains available. HTML and Markdown also use
+`text/html` and `text/markdown` MIME routing when a filename has no matching
+extension. Routing compares the lowercase MIME essence without its parameters;
+the callback's `mimeType` and the file content remain unchanged.
+HTML uses its complete original string in `srcdoc` without an
+added sandbox policy; Markdown reads the complete original text before
+rendering. Untransformed JSONL/NDJSON shows its complete original text,
+including lines that are not JSON records. Other binary files offer a download
+of the original `File`.
+The larger file-preview dialog reuses `--modal-width`, `--modal-max-height`,
+and `--modal-padding`; applications can override those existing modal values.
 
 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).
+Shared dependencies: [`DBOPFS.js`](runtime-modules.md#dbopfsjs), [`File.js`](runtime-entities.md#filejs), [`MD.js`](runtime-modules.md#mdjs), [`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).
+**Browser and supported native WebViews.** Selection/filter state, neutral
+preview descriptors, complete content delivery, cancellation, and media
+cleanup are normalized; storage/provider behavior remains mixed. HTMLImport
+and DOM; injected Arcane/provider modules where listed. Native methods remain
+subject to the bound app's capabilities. [Deep protocol details](protocols.md).
 
 ### Example
 
@@ -1633,25 +1727,29 @@ Events: `unified-inbox-ready`, `inbox-refresh`, `thread-select`.
 
 ### Overview
 
-Records segmented microphone audio only after authoritative STT readiness,
-exposes explicit selected-STT activation, transcribes with cancellation,
-persists, and completes a combined transcript.
+Records manual clips by default, with optional continuous capture that cuts
+segments after quiet periods or at a periodic boundary. Transcription and
+application saves run in capture order while microphone capture continues.
+The component exposes explicit selected-STT activation, cancellation, retry,
+and completion of the combined transcript.
 
 ### Public surface
 
 Methods/properties: `configure()`, `requestSTTActivation()`, `startRecording()`,
-`stopRecording()`, `save()`, `completeTranscription()/complete()`, `clear()`,
-`reset()`, `destroy()`.
+`stopRecording()`, `retryTranscription()`, `cancelRecording()`, `save()`,
+`completeTranscription()/complete()`, `clear()`, `reset()`, `destroy()`.
 
 Events: `voice-transcription-ready`, `voice-transcription-state`,
-`voice-transcription-segment`, `voice-transcription-change`,
+`voice-transcription-segment`, `voice-transcription-empty`,
+`voice-transcription-error`, `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
+[`AIRuntimeState.js`](runtime-modules.md#airuntimestatejs),
+[`ContinuousVoiceCapture.js`](runtime-modules.md#continuousvoicecapturejs), and
 [`AI.js`](runtime-modules.md#aijs).
 
 ### Availability and normalization
@@ -1659,9 +1757,12 @@ Shared dependencies: [`MD.js`](runtime-modules.md#mdjs),
 **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
+`ready` and not busy. Once continuous capture starts, a busy STT lane does not
+interrupt the microphone session.
+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
+owned `signal` additively, and continuous clips also include their `sequence`.
+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
@@ -1682,7 +1783,7 @@ 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
+For the default manual mode, 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
@@ -1704,10 +1805,12 @@ 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
+text during active manual 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
+live. An active continuous microphone session requests its final stop and
+flush; the manual recording lifecycle is unchanged. 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
@@ -1715,7 +1818,8 @@ 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
+the mutable complete `{message,state,stt}` record, extended during a continuous
+session with `{capture,processing,queued,errorPhase,error}`, 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;
@@ -1723,6 +1827,69 @@ 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).
 
+### Continuous capture and controls
+
+`configure({capture:{mode:'continuous'}})` opts into the SDK's
+[`ContinuousVoiceCapture`](runtime-modules.md#continuousvoicecapturejs) owner.
+The default capture settings are `preRollMs:1500`, `quietMs:2000`,
+`chunkMs:30000`, and `activityThreshold:0.02`. These are audio amplitude and
+timing settings: the detector observes sound activity, including background
+noise, and does not perform semantic voice-activity recognition. The worklet
+keeps a rolling pre-roll, emits no clips containing only inactivity, and does
+not repeat samples across periodic segments. If `preRollMs` exceeds `chunkMs`,
+the first active clip preserves all that pre-roll and may exceed the periodic
+duration. Each emitted clip contains a
+complete mono Float32 WAV and a session-local sequence starting at one.
+
+The component runs one clip's transcription and save before the next clip's
+transcription. Captured clips wait in memory while STT is busy. With the
+default `persist:true`, `onSave({transcript,segment,sequence,signal})` or the
+existing `host.save` callback must resolve before that segment's success event
+and before the next clip proceeds. Returning `false` from a continuous save or
+completion callback reports that the application did not accept the operation.
+Text is preserved completely; the
+configured separator joins successful segments. An STT failure retains its
+audio. A save failure retains the successful text and exact save payload so
+`retryTranscription()` repeats only that save and does not retranscribe or
+append the segment again. Retry resumes the ordered queue after the retained
+stage succeeds. Waiting clips remain available if the selected STT role becomes
+unready. An in-flight STT request is aborted if its selected provider/model
+changes or becomes unready; its clip remains at the failed stage for explicit
+retry. A provider result with no text emits
+`voice-transcription-empty` and advances the queue without appending text.
+
+Continuous `stopRecording()` releases the microphone immediately, flushes the
+final active segment, and returns a promise that resolves `true` after the
+queue drains or `false` while a failure remains. Default manual
+`stopRecording()` keeps its synchronous boolean return. Complete waits for
+the continuous flush and all saves before calling
+`onComplete({transcript,signal})` or the existing `host.complete` callback.
+After a capture interruption, explicit completion can use the retained
+transcript once every queued clip has settled. A pending clip failure still
+prevents completion. Overlapping completion requests invoke the application
+callback once.
+`cancelRecording()` explicitly discards outstanding clips, aborts active
+callbacks, and suppresses late text, save, and completion delivery. Callbacks
+must observe the supplied signal to cancel their own external effects; an
+already accepted external save is not undone. Replacing configuration or the
+transcript explicitly cancels a continuous session and its outstanding clips.
+`clear()` refuses a retained queue; use the explicit Cancel action before
+discarding it.
+
+`voice-transcription-segment` and `speech-transcription-complete` retain their
+complete `{text,transcript}` detail and add `sequence` for continuous clips.
+State events distinguish `capture`, `processing`, queued clips, `errorPhase`,
+and the complete `error` from the existing workflow `state` and selected `stt`
+role. Errors remain visible and retryable without implicitly discarding audio.
+
+`controls:'simple'` uses one large primary Start/Stop button, and
+`showComplete:false` hides the secondary Complete action. Standard controls
+and the Complete action remain the defaults. `labels` can supply `start`,
+`stop`, `complete`, `retry`, and `cancel` strings. Applications can style the
+exposed parts `primary-action`, `stop-action`, `complete-action`,
+`retry-action`, `cancel-action`, `transcript`, `status`, `controls`, and
+`description` without reaching into the component's markup.
+
 ### Example
 
 ```html
@@ -1732,6 +1899,19 @@ Native methods remain subject to the bound app's capabilities. [Deep protocol de
 </html-import>
 ```
 
+After the component is ready, configure the selected capture mode and the
+application's real persistence callback:
+
+```javascript
+voice.configure({
+    capture:{mode:'continuous',preRollMs:1500,quietMs:2000,chunkMs:30000},
+    controls:'simple',
+    labels:{start:'Start recording',stop:'Stop recording'},
+    onSave:saveTranscript,
+    onComplete:completeTranscript
+});
+```
+
 ## weather-widget.html
 
 ### Overview