@hachej/boring-ui-kit 0.4.4 → 0.4.6

package/README.md

@@ -12,6 +12,8 @@ Lost or malformed acknowledgements stay unknown. `actions.reconcile()` uses reta
 
 Historical scaffold tests install/typecheck packed headless UI and UI+files in clean consumers without Pi or an agent package. Candidate runtime installation qualification is recorded separately in the [implementation checkpoint](../../docs/implementation/PARTIAL.md). Import interfaces with `import type`.
 
+For read-only content without a resource client or controller, select the lightweight [`artifact-viewer`](#read-only-artifactviewer) entry. It needs only React and Marked, not files, Pi, Tiptap, canvas or pdfjs.
+
 See [scaffold guide](../../docs/contracts/SCAFFOLD.md) and [audit](../../docs/contracts/ABSTRACTION-REVIEW.md).
 
 ## Exact proposals and commands
@@ -68,6 +70,14 @@ The default schema includes headings, lists, task lists, quotes, code and text m
 
 `test/packages/ui-markdown-editor.test.mjs`, `test/packages/ui-markdown-navigation.test.mjs` and `test/packages/ui-markdown-mounted.test.mjs` and `test/packages/ui-markdown-proposals.test.mjs` drive the real React/Tiptap renderer, DOM selections and SQLite provider. `npm run test:editor-consumer` requires `npm_config_cache` pointing to a writable cache with the pinned archives; it installs actual package tarballs, checks declarations with `skipLibCheck: false`, drives the controls and bundles for browsers without Pi or server filesystem imports. These checks do not establish browser layout, caret, IME or accessibility qualification. Chromium journeys remain pending.
 
+## Optional microphone capture
+
+`createVoiceCapture` from `@hachej/boring-ui-kit/voice-capture` records browser audio without React, files or Pi. Call `start()` from a person's gesture. It feature-detects microphone access and returns a recording or a typed refusal. `stop()` returns the Blob, recorded MIME type, page-clock sample times and `truncated`; `cancel()` discards audio and releases only this capture's microphone tracks, including a permission request that finishes late.
+
+`maxMs` caps capture at five minutes by default. Reaching the cap stops the microphone; callers still choose when to consume the recording through `stop()`. Transcription and persistence remain host capabilities. The existing `@hachej/boring-feedback/page` capture API re-exports this implementation unchanged. The headless root imports neither entry.
+
+The [registry voice-message guide](../../registry/README.md#voice-messages-in-pi-chat) describes PiChat's optional hold-to-send composition. Public capture behavior runs in `test/packages/ui.test.mjs`, compatibility in `test/packages/feedback-voice.test.mjs`, and dependency-free installation in `test/scaffold/isolated-ui.test.mjs`.
+
 ## Document marks
 
 `@hachej/boring-ui-kit/markdown-quote` exports `captureMarkdownQuote` and
@@ -202,6 +212,24 @@ Mounted `tools.propose` accepts the same complete edits as the headless command
 
 `test/compatibility/canvas-mounted-native.test.mjs` composes selection and proposals with real native ToolTasks. `npm run canvas:journey:commands` requires `CHROMIUM` and permitted loopback sockets; it checks real desktop/phone viewport geometry with fictional assets. Production fonts, licensing, egress and CSS isolation remain separate qualifications.
 
+## Read-only ArtifactViewer
+
+```tsx
+import { ArtifactViewer } from '@hachej/boring-ui-kit/artifact-viewer';
+
+<ArtifactViewer name="fictional-guide.md" mimeType="text/markdown" content="# Fictional guide" />;
+```
+
+`ArtifactViewerProps` accepts `name`, `mimeType`, optional `content: string | Uint8Array`, `url`, `className` and `renderPdf`. Install the existing optional React and Marked peers when selecting this entry. It has no ResourceClient, controller, editing, syntax highlighter or agent integration. The host supplies authorized content and owns URL access policy and layout; mounting grants no file or execution authority.
+
+Normalized MIME selects Markdown, HTML, images and PDF, with filename fallback. Other text/code is an escaped `<pre>` without highlighting. Byte text requires valid UTF-8 without NUL; leading U+FEFF is preserved. Binary audio/video does not become a text preview. Missing or unreadable content displays “Preview unavailable.” Replace byte arrays when changing content rather than mutating them in place.
+
+Markdown uses a private Marked parser, then the same passive HTML allowlist as `HtmlViewer`. Both HTML types render in an empty-sandbox, no-referrer iframe with the fixed restrictive CSP. Links become spans; scripts, attributes, styles, images and external resources are omitted, including Markdown images. The [HTML preview limits](#optional-html-source-and-preview) apply; Markdown input is also limited to 262,144 UTF-16 units before parsing. There is no raw HTML fallback. URL-only Markdown, HTML and text are unavailable: the entry never fetches or embeds them unsanitized.
+
+Images use `<img>` and PDFs use the browser's native sandboxed iframe. `content` takes precedence over `url`; content creates an owned Blob URL, revoked on replacement or unmount. Host URLs are borrowed and never revoked. Relative, HTTP(S), blob and matching image/PDF data URLs are supported; other URL schemes are refused. Supply `renderPdf: (props: ArtifactPdfProps) => ReactNode` to use a trusted host renderer instead, receiving the current `{ name, url }`. The entry does not load pdfjs. Browser-native PDF support and sandbox restrictions vary by browser; it provides no page controls or PDF text extraction.
+
+`test/packages/ui-artifact-viewer.test.mjs` renders fictional fixtures through the built public entry and checks its browser import graph. `npm run test:artifact-viewer-consumer` installs the kit tarball with only React/Marked and test tooling, checks strict declarations, repeats those DOM tests and bundles without files, controllers, Tiptap, canvas, pdfjs or agent code. DOM structure tests do not qualify browser CSP enforcement, parser inertness, egress or native PDF rendering.
+
 ## Optional HTML source and preview
 
 Both `MarkdownEditor` and `HtmlViewer` accept optional `components` bindings for host buttons, inputs, textareas and the selection bubble. Installed registry recipes supply the consumer's unchanged shadcn components. Bindings forward refs and native input events. Omitting them retains unstyled native HTML for direct package consumers; it is not installed-block design qualification. See the [registry theming contract](../../registry/README.md#styling).

package/dist/artifact-viewer.d.ts

@@ -0,0 +1,18 @@
+import type { ReactNode } from 'react';
+export interface ArtifactPdfProps {
+    readonly name: string;
+    readonly url: string;
+}
+export interface ArtifactViewerProps {
+    readonly name: string;
+    readonly mimeType: string;
+    /** Content takes precedence over a URL. Byte content must be replaced, not mutated in place. */
+    readonly content?: string | Uint8Array;
+    /** Borrowed host URL; used only for images and PDF, never fetched for text previews. */
+    readonly url?: string;
+    readonly className?: string;
+    /** Trusted host presentation, for example a separately installed pdfjs renderer. */
+    readonly renderPdf?: (props: ArtifactPdfProps) => ReactNode;
+}
+export declare function ArtifactViewer(props: ArtifactViewerProps): import("react").JSX.Element;
+//# sourceMappingURL=artifact-viewer.d.ts.map

package/dist/artifact-viewer.js

@@ -0,0 +1,125 @@
+'use client';
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { useLayoutEffect, useRef, useState } from 'react';
+import { Marked } from 'marked';
+import { passiveHtml } from './passive-html.js';
+const markdown = new Marked();
+const imageTypes = { png: 'image/png', jpg: 'image/jpeg', jpeg: 'image/jpeg', gif: 'image/gif', webp: 'image/webp', svg: 'image/svg+xml', bmp: 'image/bmp', avif: 'image/avif' };
+function artifactType(name, mimeType) {
+    const mime = mimeType.split(';')[0].trim().toLowerCase();
+    if (mime === 'text/markdown' || mime === 'text/x-markdown')
+        return { kind: 'markdown', mimeType: mime };
+    if (mime === 'text/html')
+        return { kind: 'html', mimeType: mime };
+    if (mime === 'application/pdf')
+        return { kind: 'pdf', mimeType: mime };
+    if (mime.startsWith('image/'))
+        return { kind: 'image', mimeType: mime };
+    if (/^(?:audio|video)\//.test(mime))
+        return undefined;
+    const basename = name.slice(name.lastIndexOf('/') + 1), dot = basename.lastIndexOf('.');
+    const extension = dot === -1 ? '' : basename.slice(dot + 1).toLowerCase();
+    if (extension === 'md' || extension === 'markdown')
+        return { kind: 'markdown', mimeType: 'text/markdown' };
+    if (extension === 'html' || extension === 'htm')
+        return { kind: 'html', mimeType: 'text/html' };
+    if (extension === 'pdf')
+        return { kind: 'pdf', mimeType: 'application/pdf' };
+    const imageType = Object.hasOwn(imageTypes, extension) ? imageTypes[extension] : undefined;
+    if (imageType)
+        return { kind: 'image', mimeType: imageType };
+    if (/^(?:mp4|webm|mov|m4v|ogg|ogv|mp3|wav)$/.test(extension))
+        return undefined;
+    return { kind: 'text', mimeType: mime };
+}
+function decodeText(content) {
+    if (content === undefined)
+        return undefined;
+    if (typeof content === 'string')
+        return content.includes('\0') ? undefined : content;
+    if (content.includes(0))
+        return undefined;
+    try {
+        return new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(content);
+    }
+    catch {
+        return undefined;
+    }
+}
+function Unavailable() {
+    return _jsx("p", { role: "status", children: "Preview unavailable." });
+}
+function PassiveArtifact({ name, text, kind }) {
+    const container = useRef(null);
+    const [ready, setReady] = useState(false);
+    useLayoutEffect(() => {
+        const host = container.current;
+        if (!host)
+            return;
+        host.replaceChildren();
+        try {
+            if (text.length > 262_144)
+                throw new RangeError('Artifact preview source exceeds its limit');
+            const source = passiveHtml(kind === 'markdown' ? markdown.parse(text, { async: false }) : text, host.ownerDocument);
+            const frame = host.ownerDocument.createElement('iframe');
+            frame.setAttribute('sandbox', '');
+            frame.referrerPolicy = 'no-referrer';
+            frame.title = name;
+            frame.srcdoc = source;
+            host.replaceChildren(frame);
+            setReady(true);
+        }
+        catch {
+            host.replaceChildren();
+            setReady(false);
+        }
+        return () => { host.replaceChildren(); };
+    }, [name, text, kind]);
+    return _jsxs(_Fragment, { children: [!ready && _jsx(Unavailable, {}), _jsx("div", { ref: container })] });
+}
+function mediaUrl(url, kind) {
+    if (!url)
+        return undefined;
+    try {
+        const protocol = new URL(url, 'https://artifact.invalid/').protocol;
+        if (['https:', 'http:', 'blob:'].includes(protocol))
+            return url;
+        if (protocol === 'data:' && (kind === 'image' ? /^data:image\//i : /^data:application\/pdf(?:;|,)/i).test(url))
+            return url;
+    }
+    catch { /* A malformed host URL has no preview. */ }
+    return undefined;
+}
+function MediaArtifact({ name, kind, mimeType, content, url, renderPdf }) {
+    const [made, setMade] = useState();
+    useLayoutEffect(() => {
+        if (content === undefined) {
+            setMade(undefined);
+            return;
+        }
+        try {
+            const blob = new Blob([typeof content === 'string' ? content : new Uint8Array(content)], { type: mimeType });
+            const objectUrl = URL.createObjectURL(blob);
+            setMade({ content, mimeType, url: objectUrl });
+            return () => { URL.revokeObjectURL(objectUrl); };
+        }
+        catch {
+            setMade(undefined);
+        }
+    }, [content, mimeType]);
+    const selectedUrl = content === undefined ? mediaUrl(url, kind) : made?.content === content && made.mimeType === mimeType ? made.url : undefined;
+    if (!selectedUrl)
+        return _jsx(Unavailable, {});
+    if (kind === 'image')
+        return _jsx("img", { src: selectedUrl, alt: name, referrerPolicy: "no-referrer" });
+    return renderPdf ? renderPdf({ name, url: selectedUrl }) : _jsx("iframe", { src: selectedUrl, title: name, sandbox: "", referrerPolicy: "no-referrer" });
+}
+export function ArtifactViewer(props) {
+    const type = artifactType(props.name, props.mimeType);
+    const text = type && type.kind !== 'image' && type.kind !== 'pdf' ? decodeText(props.content) : undefined;
+    return _jsx("section", { "data-boring": "artifact-viewer", className: props.className, "aria-label": props.name, children: !type ? _jsx(Unavailable, {}) : type.kind === 'image' || type.kind === 'pdf'
+            ? _jsx(MediaArtifact, { ...props, kind: type.kind, mimeType: type.mimeType })
+            : text === undefined ? _jsx(Unavailable, {}) : type.kind === 'text'
+                ? _jsx("pre", { children: text })
+                : _jsx(PassiveArtifact, { name: props.name, text: text, kind: type.kind }) });
+}

package/dist/html-preview.d.ts

@@ -1,2 +1,2 @@
-export declare function passiveHtml(source: string, document: Document): string;
+export { passiveHtml } from './passive-html.js';
 //# sourceMappingURL=html-preview.d.ts.map

package/dist/html-preview.js

@@ -1,47 +1 @@
-const formatting = new Set(['p', 'div', 'span', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'blockquote', 'pre', 'code', 'strong', 'em', 'b', 'i', 'u', 's', 'small', 'sub', 'sup', 'kbd', 'samp', 'var', 'mark', 'ul', 'ol', 'li', 'dl', 'dt', 'dd', 'table', 'caption', 'thead', 'tbody', 'tfoot', 'tr', 'th', 'td', 'section', 'article', 'header', 'footer', 'main', 'aside', 'figure', 'figcaption', 'br', 'hr']);
-const htmlNamespace = 'http://www.w3.org/1999/xhtml';
-const prefix = '<!doctype html><html><head><meta http-equiv="Content-Security-Policy" content="default-src \'none\'; base-uri \'none\'; form-action \'none\'"><meta charset="utf-8"><meta name="referrer" content="no-referrer"><meta name="format-detection" content="telephone=no,email=no,address=no"><title>HTML preview</title></head><body>';
-export function passiveHtml(source, document) {
-    if (source.length > 262_144)
-        throw new RangeError('HTML preview source exceeds its limit');
-    const template = document.createElement('template');
-    template.innerHTML = source;
-    let nodes = 0, length = prefix.length;
-    const output = [prefix];
-    function emit(text) {
-        length += text.length;
-        if (length > 1_048_576)
-            throw new RangeError('HTML preview output exceeds its limit');
-        output.push(text);
-    }
-    function visit(node, depth) {
-        if (++nodes > 20_000 || depth > 128)
-            throw new RangeError('HTML preview structure exceeds its limit');
-        if (node.nodeType === 3) {
-            emit((node.textContent ?? '').replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;'));
-            return;
-        }
-        if (node.nodeType !== 1 || !('namespaceURI' in node) || node.namespaceURI !== htmlNamespace || !('localName' in node) || typeof node.localName !== 'string')
-            return;
-        if (node.localName === 'html' || node.localName === 'head' || node.localName === 'body') {
-            for (let child = node.firstChild; child; child = child.nextSibling)
-                visit(child, depth + 1);
-            return;
-        }
-        const tag = node.localName === 'a' ? 'span' : node.localName;
-        if (!formatting.has(tag))
-            return;
-        emit('<' + tag + '>');
-        if (tag === 'br' || tag === 'hr')
-            return;
-        if (tag === 'pre')
-            emit('\n');
-        for (let child = node.firstChild; child; child = child.nextSibling)
-            visit(child, depth + 1);
-        emit('</' + tag + '>');
-    }
-    for (let child = template.content.firstChild; child; child = child.nextSibling)
-        visit(child, 0);
-    emit('</body></html>');
-    return output.join('');
-}
+export { passiveHtml } from './passive-html.js';

package/dist/passive-html.d.ts

@@ -0,0 +1,2 @@
+export declare function passiveHtml(source: string, document: Document): string;
+//# sourceMappingURL=passive-html.d.ts.map

package/dist/passive-html.js

@@ -0,0 +1,47 @@
+const formatting = new Set(['p', 'div', 'span', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'blockquote', 'pre', 'code', 'strong', 'em', 'b', 'i', 'u', 's', 'small', 'sub', 'sup', 'kbd', 'samp', 'var', 'mark', 'ul', 'ol', 'li', 'dl', 'dt', 'dd', 'table', 'caption', 'thead', 'tbody', 'tfoot', 'tr', 'th', 'td', 'section', 'article', 'header', 'footer', 'main', 'aside', 'figure', 'figcaption', 'br', 'hr']);
+const htmlNamespace = 'http://www.w3.org/1999/xhtml';
+const prefix = '<!doctype html><html><head><meta http-equiv="Content-Security-Policy" content="default-src \'none\'; base-uri \'none\'; form-action \'none\'"><meta charset="utf-8"><meta name="referrer" content="no-referrer"><meta name="format-detection" content="telephone=no,email=no,address=no"><title>HTML preview</title></head><body>';
+export function passiveHtml(source, document) {
+    if (source.length > 262_144)
+        throw new RangeError('HTML preview source exceeds its limit');
+    const template = document.createElement('template');
+    template.innerHTML = source;
+    let nodes = 0, length = prefix.length;
+    const output = [prefix];
+    function emit(text) {
+        length += text.length;
+        if (length > 1_048_576)
+            throw new RangeError('HTML preview output exceeds its limit');
+        output.push(text);
+    }
+    function visit(node, depth) {
+        if (++nodes > 20_000 || depth > 128)
+            throw new RangeError('HTML preview structure exceeds its limit');
+        if (node.nodeType === 3) {
+            emit((node.textContent ?? '').replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;'));
+            return;
+        }
+        if (node.nodeType !== 1 || !('namespaceURI' in node) || node.namespaceURI !== htmlNamespace || !('localName' in node) || typeof node.localName !== 'string')
+            return;
+        if (node.localName === 'html' || node.localName === 'head' || node.localName === 'body') {
+            for (let child = node.firstChild; child; child = child.nextSibling)
+                visit(child, depth + 1);
+            return;
+        }
+        const tag = node.localName === 'a' ? 'span' : node.localName;
+        if (!formatting.has(tag))
+            return;
+        emit('<' + tag + '>');
+        if (tag === 'br' || tag === 'hr')
+            return;
+        if (tag === 'pre')
+            emit('\n');
+        for (let child = node.firstChild; child; child = child.nextSibling)
+            visit(child, depth + 1);
+        emit('</' + tag + '>');
+    }
+    for (let child = template.content.firstChild; child; child = child.nextSibling)
+        visit(child, 0);
+    emit('</body></html>');
+    return output.join('');
+}

package/dist/voice-capture.d.ts

@@ -0,0 +1,43 @@
+/** Why the microphone could not be used, for a short human message: `denied` (the person or the browser refused the permission),
+ * `no-microphone`, `busy` (in use or could not be opened), `insecure` (http on a name other than localhost: no media devices at all),
+ * `unsupported` (no MediaRecorder, or it cannot record this microphone), `failed` (anything else). */
+export type VoiceRefusal = 'denied' | 'no-microphone' | 'busy' | 'insecure' | 'unsupported' | 'failed';
+export type VoiceStart = {
+    readonly kind: 'recording';
+} | {
+    readonly kind: 'refused';
+    readonly reason: string;
+    readonly code?: VoiceRefusal;
+};
+export interface VoiceRecording {
+    readonly audio: Blob;
+    readonly mimeType: string;
+    /** Page time (`performance.now()` ms) of the first recorded sample. */
+    readonly startedAt: number;
+    readonly endedAt: number;
+    /** The recording reached `maxMs` and stopped on its own. */
+    readonly truncated: boolean;
+}
+export interface VoiceCapture {
+    readonly start: () => Promise<VoiceStart>;
+    /** Ends the recording and returns it; null when nothing was recorded (never started, cancelled, or empty). */
+    readonly stop: () => Promise<VoiceRecording | null>;
+    /** Ends the recording, releases the microphone and discards the audio. */
+    readonly cancel: () => void;
+}
+export interface VoiceCaptureOptions {
+    readonly getUserMedia?: (constraints: MediaStreamConstraints) => Promise<MediaStream>;
+    /** Longest recording in milliseconds (default 5 minutes); the recording stops there and `stop()` reports `truncated`. */
+    readonly maxMs?: number;
+    /** The page clock (default `performance.now()`). */
+    readonly now?: () => number;
+}
+export declare const DEFAULT_MAX_VOICE_MS: number;
+/** Container types tried in order; the first the browser records wins. */
+export declare const VOICE_MIME_TYPES: readonly ["audio/webm;codecs=opus", "audio/webm", "audio/mp4", "audio/ogg;codecs=opus"];
+/** The browser's microphone, or null where the page cannot have one (insecure origin, no media devices). */
+export declare function browserGetUserMedia(): ((constraints: MediaStreamConstraints) => Promise<MediaStream>) | null;
+/** Short human messages, one per refusal; each says what to do next. */
+export declare const VOICE_REFUSALS: Readonly<Record<VoiceRefusal, string>>;
+export declare function createVoiceCapture(options?: VoiceCaptureOptions): VoiceCapture;
+//# sourceMappingURL=voice-capture.d.ts.map

package/dist/voice-capture.js

@@ -0,0 +1,186 @@
+// Shared browser microphone capture. Chat keeps the audio; feedback also uses the page-clock time of the first recorded sample
+// to align speech with the pointer.
+//
+// Microphone access (getUserMedia) exists only in secure contexts (https or localhost) and needs the person's permission. The
+// capture never opens it on load: only `start()`, called from the person's click, does, through an injectable `getUserMedia`
+// whose default feature-detects `navigator.mediaDevices.getUserMedia` and refuses with a reason when it is missing. A host that
+// owns microphone policy passes its own. `npm run check` (scripts/check-platform-apis.mjs) allowlists this file on that condition.
+//
+// The clock. MediaRecorder hands audio over late and in chunks, so neither its `start` event nor a chunk's arrival says when the
+// first recorded sample was heard. `npm run feedback:voice-sync` (tools/feedback-voice-sync.mjs) measured seven candidate
+// strategies in Chromium against an independent reader of the same microphone; the page time read immediately before
+// `MediaRecorder.start()` was the most accurate (2–4 ms mean, under 9 ms max over three batches, with the fake device's dropped
+// time removed), while the `start` event is about 60 ms late (up to 125 ms) and stop-minus-duration 30–40 ms late. So
+// `startedAt` is that time.
+// `endedAt` is `startedAt` plus the decoded duration when the page can decode the recording, else the `stop` event's time.
+// Measured in Chromium only; a microphone that warms up after getUserMedia resolves (no audio yet when recording starts) would
+// make `startedAt` early by the warm-up.
+export const DEFAULT_MAX_VOICE_MS = 5 * 60_000;
+/** Container types tried in order; the first the browser records wins. */
+export const VOICE_MIME_TYPES = ['audio/webm;codecs=opus', 'audio/webm', 'audio/mp4', 'audio/ogg;codecs=opus'];
+/** The browser's microphone, or null where the page cannot have one (insecure origin, no media devices). */
+export function browserGetUserMedia() {
+    if (typeof globalThis.navigator?.mediaDevices?.getUserMedia !== 'function')
+        return null;
+    const devices = globalThis.navigator.mediaDevices;
+    return constraints => devices.getUserMedia(constraints);
+}
+/** Short human messages, one per refusal; each says what to do next. */
+export const VOICE_REFUSALS = {
+    denied: 'Microphone blocked. Allow it for this site in the browser, then press Record again.',
+    'no-microphone': 'No microphone found. Connect one, then press Record again.',
+    busy: 'The microphone is busy or could not be opened. Close other apps using it and try again.',
+    insecure: 'Recording needs a secure page (https or localhost).',
+    unsupported: 'This browser cannot record audio here.',
+    failed: 'The microphone could not be started.',
+};
+const refused = (code, detail) => ({ kind: 'refused', code, reason: detail ? `${VOICE_REFUSALS[code]} (${detail})` : VOICE_REFUSALS[code] });
+function refusalOf(error) {
+    const name = error?.name;
+    if (name === 'NotAllowedError' || name === 'PermissionDeniedError' || name === 'SecurityError')
+        return refused('denied');
+    if (name === 'NotFoundError' || name === 'DevicesNotFoundError' || name === 'OverconstrainedError')
+        return refused('no-microphone');
+    if (name === 'NotReadableError' || name === 'TrackStartError' || name === 'AbortError')
+        return refused('busy');
+    return refused('failed', error instanceof Error ? error.message : String(error));
+}
+/** Media devices missing on a plain-http page: the usual reason is an insecure origin (http on a name that is not local; a local
+ * http page has them). Wording only; the capability itself is feature-detected (`browserGetUserMedia`). */
+const plainHttpPage = () => globalThis.location?.protocol === 'http:';
+const release = (stream) => { for (const track of stream?.getTracks() ?? [])
+    track.stop(); };
+/** Duration in milliseconds of recorded audio, when the page can decode it (OfflineAudioContext or AudioContext). */
+async function decodedMs(audio) {
+    try {
+        const Offline = globalThis.OfflineAudioContext;
+        if (typeof Offline !== 'function' || audio.size === 0)
+            return null;
+        const context = new Offline(1, 1, 48_000);
+        const buffer = await context.decodeAudioData(await audio.arrayBuffer());
+        return Number.isFinite(buffer.duration) ? buffer.duration * 1000 : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function createVoiceCapture(options = {}) {
+    const now = options.now ?? (() => performance.now());
+    const maxMs = options.maxMs ?? DEFAULT_MAX_VOICE_MS;
+    let session = null;
+    let opening = false;
+    let cancelledWhileOpening = false;
+    const finish = (current, truncated) => {
+        if (current.timer !== null) {
+            clearTimeout(current.timer);
+            current.timer = null;
+        }
+        if (truncated)
+            current.truncated = true;
+        if (current.recorder.state !== 'inactive') {
+            try {
+                current.recorder.stop();
+            }
+            catch { /* already stopping */ }
+        }
+    };
+    return {
+        async start() {
+            if (session || opening)
+                return { kind: 'refused', code: 'failed', reason: 'Already recording.' };
+            const Recorder = globalThis.MediaRecorder;
+            const open = options.getUserMedia ?? browserGetUserMedia();
+            // No media devices on an insecure origin: say that, not "no microphone" (the person can fix the address, not the hardware).
+            if (!open)
+                return refused(plainHttpPage() ? 'insecure' : 'unsupported');
+            if (typeof Recorder !== 'function')
+                return refused('unsupported', 'no MediaRecorder');
+            // getUserMedia is called synchronously from here, inside the person's click (no await before it), so browsers that tie the
+            // permission prompt to a user gesture show it.
+            opening = true;
+            cancelledWhileOpening = false;
+            let stream;
+            try {
+                stream = await open({ audio: true });
+            }
+            catch (error) {
+                opening = false;
+                return refusalOf(error);
+            }
+            if (cancelledWhileOpening) {
+                opening = false;
+                release(stream);
+                return { kind: 'refused', code: 'failed', reason: 'Cancelled before the microphone opened.' };
+            }
+            const supported = (type) => { try {
+                return typeof Recorder.isTypeSupported !== 'function' || Recorder.isTypeSupported(type);
+            }
+            catch {
+                return false;
+            } };
+            const preferred = VOICE_MIME_TYPES.find(supported);
+            let recorder;
+            try {
+                recorder = preferred ? new Recorder(stream, { mimeType: preferred }) : new Recorder(stream);
+            }
+            catch (error) {
+                opening = false;
+                release(stream);
+                return refused('unsupported', error instanceof Error ? error.message : String(error));
+            }
+            let settle;
+            const current = {
+                stream, recorder, mimeType: preferred ?? '', chunks: [], startedAt: null, stoppedAt: null, truncated: false, timer: null,
+                stopped: new Promise(resolve => { settle = resolve; }), cancelled: false,
+            };
+            recorder.addEventListener('dataavailable', event => { if (event.data && event.data.size > 0)
+                current.chunks.push(event.data); });
+            recorder.addEventListener('stop', () => { current.stoppedAt = now(); release(stream); settle(); });
+            recorder.addEventListener('error', () => { current.stoppedAt ??= now(); release(stream); settle(); });
+            try {
+                current.startedAt = now();
+                recorder.start(1000);
+            }
+            catch (error) {
+                opening = false;
+                release(stream);
+                return refused('failed', error instanceof Error ? error.message : String(error));
+            }
+            if (Number.isFinite(maxMs) && maxMs > 0)
+                current.timer = setTimeout(() => finish(current, true), maxMs);
+            session = current;
+            opening = false;
+            return { kind: 'recording' };
+        },
+        async stop() {
+            const current = session;
+            if (!current)
+                return null;
+            finish(current, false);
+            await current.stopped;
+            session = null;
+            if (current.cancelled)
+                return null;
+            const mimeType = current.recorder.mimeType || current.mimeType || current.chunks[0]?.type || 'audio/webm';
+            const audio = new Blob(current.chunks, { type: mimeType });
+            if (audio.size === 0)
+                return null;
+            const startedAt = current.startedAt ?? current.stoppedAt ?? now();
+            const duration = await decodedMs(audio);
+            const endedAt = duration === null ? Math.max(startedAt, current.stoppedAt ?? now()) : startedAt + duration;
+            return { audio, mimeType, startedAt, endedAt, truncated: current.truncated };
+        },
+        cancel() {
+            const current = session;
+            if (opening)
+                cancelledWhileOpening = true;
+            if (!current)
+                return;
+            session = null;
+            current.cancelled = true;
+            current.chunks.length = 0;
+            finish(current, false);
+            release(current.stream);
+        },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hachej/boring-ui-kit",
-  "version": "0.4.4",
+  "version": "0.4.6",
   "license": "MIT",
   "private": false,
   "type": "module",
@@ -55,6 +55,10 @@
       "types": "./dist/native-chat.d.ts",
       "import": "./dist/native-chat.js"
     },
+    "./voice-capture": {
+      "types": "./dist/voice-capture.d.ts",
+      "import": "./dist/voice-capture.js"
+    },
     "./shared-chat": {
       "types": "./dist/shared-chat/index.d.ts",
       "import": "./dist/shared-chat/index.js"
@@ -79,6 +83,10 @@
       "types": "./dist/html-viewer.d.ts",
       "import": "./dist/html-viewer.js"
     },
+    "./artifact-viewer": {
+      "types": "./dist/artifact-viewer.d.ts",
+      "import": "./dist/artifact-viewer.js"
+    },
     "./experience": {
       "types": "./dist/experience.d.ts",
       "import": "./dist/experience.js"
@@ -126,7 +134,7 @@
     }
   },
   "peerDependencies": {
-    "@hachej/boring-files": "^0.4.4",
+    "@hachej/boring-files": "^0.4.6",
     "@earendil-works/pi-durable": "~1.2.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",

package/r/agent-target.json

@@ -4,15 +4,15 @@
   "title": "Point and dictate on app data",
   "description": "Tap explicitly marked JSON app context, dictate once and show the same app agent’s native reply without opening chat. Host-controlled presentation; no feedback report or second controller.",
   "dependencies": [
-    "@hachej/boring-ui-kit@^0.4.4",
-    "@hachej/boring-feedback@^0.4.4",
+    "@hachej/boring-ui-kit@^0.4.6",
+    "@hachej/boring-feedback@^0.4.6",
     "@earendil-works/pi-durable@~1.2.0",
     "react@^19.0.0",
     "react-dom@^19.0.0"
   ],
   "registryDependencies": [
-    "https://cdn.jsdelivr.net/npm/@hachej/boring-ui-kit@0.4.4/r/app-shell.json",
-    "https://cdn.jsdelivr.net/npm/@hachej/boring-ui-kit@0.4.4/r/pi-chat.json",
+    "https://cdn.jsdelivr.net/npm/@hachej/boring-ui-kit@0.4.6/r/app-shell.json",
+    "https://cdn.jsdelivr.net/npm/@hachej/boring-ui-kit@0.4.6/r/pi-chat.json",
     "button",
     "card",
     "message",