@hachej/boring-ui-kit 0.4.25 → 0.4.27

package/dist/chat-react.js

@@ -0,0 +1,95 @@
+'use client';
+/** Opt-in UI projection over the native controller; owns no Pi execution or controller lifetime. */
+import { useCallback, useEffect, useId, useLayoutEffect, useMemo, useRef, useSyncExternalStore } from 'react';
+import { artifactKey, artifactTurn, artifactVersions, createPresentAcks, follows, pendingPresents, presentPath } from './chat-view.js';
+export { useChatDraft } from './chat-react-draft.js';
+export { useControllerPerConversation } from './chat-react-controller.js';
+export { chunkKeys, useRowChunks, useTranscript, useTranscriptWindow, PAGE_FIRST, PAGE_MORE, CHUNK } from './chat-react-transcript.js';
+export { useChatPlacement, readChatPlacement, useRemoteChat } from './chat-react-remote.js';
+export { useConversationsClient, useConversations } from './chat-react-conversations.js';
+import { watchConversation } from './run-notifications.js';
+export { createNotificationStore, watchConversation } from './run-notifications.js';
+/** The foreground adapter of watchConversation, with the same connected-only transition rules and borrowed lifecycle. */
+export function useRunNotifications(controller, store, options) {
+    const latest = useRef(options);
+    useLayoutEffect(() => { latest.current = options; });
+    useEffect(() => watchConversation(controller, store, () => latest.current), [controller, store, options.conversationId]);
+}
+const subscribeNothing = () => () => { };
+/** Selects the authorized native view using the controller's own cached snapshot and subscription. Borrows its lifetime. */
+export function useChatView(controller, select) {
+    const getView = useCallback(() => controller?.getSnapshot().view, [controller]);
+    const view = useSyncExternalStore(controller?.subscribe ?? subscribeNothing, getView, () => undefined);
+    return useMemo(() => select(view), [view, select]);
+}
+const identityView = (view) => view;
+/** One version/follow/auto-open and present-ack rule for every chat surface. Mount evidence must come from the viewer. */
+export function useArtifactFollow(options) {
+    const { controller, conversationId, detect, active, autoOpen = false } = options;
+    const view = useChatView(controller, identityView);
+    const versions = useMemo(() => artifactVersions(view, detect), [view, detect]);
+    const turn = useMemo(() => artifactTurn(view), [view]);
+    const calls = useMemo(() => pendingPresents(view), [view]);
+    const latest = useRef(options);
+    // Latest host callbacks are used only by effects and event handlers, never to derive render output.
+    latest.current = options;
+    const seen = useRef(new Map());
+    const closedInTurn = useRef(new Map());
+    const instanceId = useId();
+    // A controller/conversation switch cannot carry a mount report, delayed callback or retry into the new binding.
+    // Child layout effects may report a committed mount before this hook's layout effect; teardown then fences delayed reports.
+    const binding = useMemo(() => ({ active: true, controller, conversationId }), [controller, conversationId]);
+    const current = useCallback(() => binding.active && latest.current.controller === binding.controller && latest.current.conversationId === binding.conversationId, [binding]);
+    const acks = useMemo(() => createPresentAcks({ instanceId,
+        answer: (id, body) => current() ? latest.current.answer?.(id, body) : undefined,
+        open: path => current() && latest.current.openPresent(path),
+    }), [current, instanceId]);
+    useLayoutEffect(() => { binding.active = true; return () => { binding.active = false; }; }, [binding]);
+    useEffect(() => {
+        if (!controller || conversationId === undefined)
+            return;
+        const keys = versions.map(version => JSON.stringify([artifactKey(version), version.revision]));
+        const known = seen.current.get(conversationId);
+        if (!known) {
+            seen.current.set(conversationId, new Set(keys));
+            return;
+        }
+        const fresh = versions.filter((_, index) => !known.has(keys[index]));
+        for (const key of keys)
+            known.add(key);
+        if (!autoOpen || !fresh.length || latest.current.unsaved?.() || latest.current.narrow?.() || closedInTurn.current.get(conversationId) === turn)
+            return;
+        latest.current.onOpen({ descriptor: fresh[0], follow: true });
+    }, [versions, controller, conversationId, turn, autoOpen]);
+    useEffect(() => {
+        if (!options.answer || conversationId === undefined)
+            return;
+        acks.consider(calls, { closedThisTurn: closedInTurn.current.get(conversationId) === turn,
+            unsaved: latest.current.unsaved?.() === true, narrow: latest.current.narrow?.() === true, autoOpen,
+            showing: path => latest.current.showing(path) });
+    }, [acks, calls, conversationId, turn, autoOpen, options.answer]);
+    const onShown = useCallback((shown) => {
+        if (!current())
+            return;
+        const report = { path: presentPath(shown.path), revision: shown.revision };
+        if (shown.hidden)
+            acks.hidden(report);
+        else
+            acks.shown(report);
+    }, [acks, current]);
+    const onFailed = useCallback((failed) => { if (current())
+        acks.failed({ ...failed, path: presentPath(failed.path) }); }, [acks, current]);
+    const recordClosed = useCallback(() => { if (conversationId !== undefined)
+        closedInTurn.current.set(conversationId, turn); }, [conversationId, turn]);
+    const open = useCallback((descriptor) => latest.current.onOpen({ descriptor, follow: follows(descriptor, versions) }), [versions]);
+    const isOpen = useCallback((descriptor) => Boolean(active && artifactKey(active.descriptor) === artifactKey(descriptor) &&
+        (active.follow ? follows(descriptor, versions) : descriptor.revision === active.descriptor.revision)), [active, versions]);
+    const known = useMemo(() => active ? versions.filter(version => artifactKey(version) === artifactKey(active.descriptor)) : [], [active, versions]);
+    const shown = active ? active.follow ? known[0] ?? active.descriptor : active.descriptor : undefined;
+    const select = useCallback((version) => {
+        if (active)
+            latest.current.onOpen(version === 'latest' ? { descriptor: known[0] ?? active.descriptor, follow: true } : { descriptor: version, follow: false });
+    }, [active, known]);
+    return { versions, turn, known, shown, open, isOpen, select, recordClosed, onShown, onFailed };
+}
+export { useChatSession } from './chat-react-session.js';

package/dist/chat-text.d.ts

@@ -0,0 +1,131 @@
+/**
+ * Optional chat text rules: the grammar of what a person types and what a message shows. Pure string functions; no React, files, agent
+ * or controller runtime. Registry items (pi-chat, pi-chat-slash, pi-chat-markdown, pi-chat-voice, shared-chat, ...) call these and keep
+ * no copy, so a composer, a bubble and the shared chat agree on one `@mention` syntax.
+ */
+/** Where a `/` menu entry comes from. Skills and host commands are grouped separately in the menu. */
+export type SlashSource = 'local' | 'extension' | 'prompt' | 'skill';
+/** The unified `/` menu entry. */
+export interface SlashItem {
+    readonly name: string;
+    readonly description: string;
+    readonly source: SlashSource;
+    readonly sourcePlugin?: string;
+}
+/** The commands and skills a `/` menu lists (the item's `SlashConfig` is assignable to it). */
+export interface SlashEntries {
+    readonly commands?: readonly {
+        readonly name: string;
+        readonly description?: string | undefined;
+        readonly sourcePlugin?: string | undefined;
+    }[] | undefined;
+    readonly skills?: readonly {
+        readonly name: string;
+        readonly description: string;
+        readonly sourcePlugin?: string | undefined;
+    }[] | undefined;
+}
+/** The `/` menu entries: host commands first, then skills. */
+export declare function slashItems(config: SlashEntries): SlashItem[];
+/** The group an item lives under in the filter chips: skills, its plugin, or `built-in`. */
+export declare function slashGroup(item: Pick<SlashItem, 'source' | 'sourcePlugin'>): string;
+/** `/` opens the menu only when the text before the caret is one `/token`, as in v2. */
+export declare function slashQuery(text: string, caret: number): string | null;
+export interface MentionTrigger {
+    readonly query: string;
+    readonly start: number;
+    readonly end: number;
+}
+/** An `@` at the start or after whitespace, up to the caret. */
+export declare function mentionTrigger(text: string, caret: number): MentionTrigger | null;
+/**
+ * The text of a mention of `path` (a workspace path or a shared-chat member id). A value with whitespace, a quote or a backslash is
+ * written in double quotes, `@"docs/Meeting notes.md"`, with `\` and `"` escaped, because a bare mention ends at a space and a bare `\`
+ * is not an escape. Any other value stays bare (`@docs/plan.md`).
+ */
+export declare function mentionToken(path: string): string;
+/**
+ * The `@` tokens of a message, bare or quoted: group 1 is the character before the `@` (or the start), group 2 the quoted body (escapes
+ * still in it), group 3 the bare path. `mentionedPaths` of `@hachej/boring-agent/mentions` parses the same syntax (a contract test keeps
+ * them equal).
+ */
+export declare const MENTION_TOKEN: RegExp;
+/** The distinct values a message mentions, in order. The same result as the agent's `mentionedPaths`. */
+export declare function mentionedPaths(text: string): string[];
+/** Whether the draft already holds a mention of `path`. */
+export declare function hasMention(text: string, path: string): boolean;
+/** The draft without its mention of `path` (and the space after it). */
+export declare function removeMention(text: string, path: string): string;
+/** A registered prefix wins only for that kind; ordinary file paths keep their existing presentation. */
+export declare function mentionKind<Kind>(value: string, config: {
+    readonly kinds?: Readonly<Record<string, Kind>> | undefined;
+} | undefined): {
+    readonly kind: Kind;
+    readonly path: string;
+} | undefined;
+/** The composer's editable text and hidden app tokens, derived only from the full draft. File tokens remain editable text. */
+export declare function kindMentionDraft<Kind>(text: string, config: {
+    readonly kinds?: Readonly<Record<string, Kind>> | undefined;
+} | undefined): {
+    readonly text: string;
+    readonly tokens: readonly string[];
+};
+/** Keep an explicit leading skill first, then complete hidden tokens before any unfinished quoted input. */
+export declare function writeKindMentionDraft(text: string, tokens: readonly string[], skills?: readonly string[]): string;
+/** Consume every draft token for voice sends, including repeated references to the same path. */
+export declare function withoutMentions(text: string): string;
+/** Refused messages restore the words, never the app card chips. File mentions retain their existing recovery behaviour. */
+export declare function withoutKindMentions<Kind>(text: string, config: {
+    readonly kinds?: Readonly<Record<string, Kind>> | undefined;
+} | undefined): string;
+/**
+ * The draft with `text` added at its end: a space between them unless the draft is empty or already ends in whitespace. Dictation,
+ * voice transcripts, picked mentions and app targets all append this way.
+ */
+export declare function appendToDraft(draft: string, text: string): string;
+/** The draft with `text` put back before it on its own line (a refused or withdrawn message); whitespace-only parts are dropped. */
+export declare function prependToDraft(draft: string, text: string): string;
+export type Piece = {
+    readonly text: string;
+    readonly kind?: 'mention' | 'skill';
+    readonly value?: string;
+};
+/** Upload paths are `uploads/<name>`: the attachments of a message, shown as cards rather than as text. */
+export declare const isUploadPath: (path: string) => boolean;
+export type FileKind = 'document' | 'image' | 'pdf' | 'sheet' | 'slides' | 'audio' | 'file';
+/** The card's kind, from the extension alone. */
+export declare function fileKind(path: string): FileKind;
+/** Recorded voice uses a reserved upload filename prefix; other audio remains a plain file card. */
+export declare const isVoicePath: (path: string) => boolean;
+/** The name a card shows: the upload's file name without the random suffix `uploadPath` adds (`report-1a2b3c4d.pdf` is `report.pdf`). */
+export declare function displayName(path: string): string;
+/**
+ * The pieces a message shows once `hidden` ones are taken out: a space that a removed piece leaves at a join is dropped, and the ends are
+ * trimmed where it was. The message's own text is not changed, only what the bubble draws.
+ */
+export declare function visibleParts(parts: readonly Piece[], hidden: (part: Piece) => boolean): Piece[];
+/** Paste-to-file thresholds: a paste with more characters or more lines than these becomes a file. Defaults 2000 and 40. */
+export interface PasteToFile {
+    readonly minChars?: number | undefined;
+    readonly minLines?: number | undefined;
+}
+/** Whether pasted text is long enough to become a file. `more` than the limits: the characters, or the lines, of the text. */
+export declare function isLongPaste(text: string, limits?: PasteToFile): boolean;
+/** Markdown in pasted text: a heading, a list or quote item, a fence, a table row, emphasis or a link. Anything else is plain text. */
+export declare function looksLikeMarkdown(text: string): boolean;
+/** Split a sent message into plain text, `@path` mentions and a leading `/skill` token. */
+export declare function pieces(text: string, options: {
+    readonly mentions: boolean;
+    readonly skills: readonly string[];
+    readonly uploads?: boolean;
+}): Piece[];
+/** The presentation label key for a microphone refusal; labels remain host-owned. */
+export declare const voiceRefusalLabel: {
+    readonly denied: "voiceDenied";
+    readonly 'no-microphone': "voiceNoMicrophone";
+    readonly busy: "voiceBusy";
+    readonly insecure: "voiceInsecure";
+    readonly unsupported: "voiceUnsupported";
+    readonly failed: "voiceStartFailed";
+};
+//# sourceMappingURL=chat-text.d.ts.map

package/dist/chat-text.js

@@ -0,0 +1,220 @@
+/**
+ * Optional chat text rules: the grammar of what a person types and what a message shows. Pure string functions; no React, files, agent
+ * or controller runtime. Registry items (pi-chat, pi-chat-slash, pi-chat-markdown, pi-chat-voice, shared-chat, ...) call these and keep
+ * no copy, so a composer, a bubble and the shared chat agree on one `@mention` syntax.
+ */
+/** The `/` menu entries: host commands first, then skills. */
+export function slashItems(config) {
+    return [
+        ...(config.commands ?? []).map((command) => ({ name: command.name, description: command.description ?? '', source: 'local', ...(command.sourcePlugin ? { sourcePlugin: command.sourcePlugin } : {}) })),
+        ...(config.skills ?? []).map((skill) => ({ name: skill.name, description: skill.description, source: 'skill', ...(skill.sourcePlugin ? { sourcePlugin: skill.sourcePlugin } : {}) })),
+    ];
+}
+/** The group an item lives under in the filter chips: skills, its plugin, or `built-in`. */
+export function slashGroup(item) {
+    if (item.source === 'skill')
+        return 'skills';
+    return item.sourcePlugin || 'built-in';
+}
+/** `/` opens the menu only when the text before the caret is one `/token`, as in v2. */
+export function slashQuery(text, caret) {
+    const match = /^\/(\S*)$/.exec(text.slice(0, caret));
+    return match ? match[1] : null;
+}
+/** An `@` at the start or after whitespace, up to the caret. */
+export function mentionTrigger(text, caret) {
+    const before = text.slice(0, caret);
+    const match = /(^|\s)@(\S*)$/.exec(before);
+    // A typed opening quote (`@"Meeting`) is not part of the search; the token starts at the `@` either way.
+    return match ? { query: match[2].replace(/^"/, ''), start: before.length - match[2].length - 1, end: caret } : null;
+}
+/**
+ * The text of a mention of `path` (a workspace path or a shared-chat member id). A value with whitespace, a quote or a backslash is
+ * written in double quotes, `@"docs/Meeting notes.md"`, with `\` and `"` escaped, because a bare mention ends at a space and a bare `\`
+ * is not an escape. Any other value stays bare (`@docs/plan.md`).
+ */
+export function mentionToken(path) {
+    return /[\s"\\]/.test(path) ? `@"${path.replace(/[\\"]/g, '\\$&')}"` : `@${path}`;
+}
+/**
+ * The `@` tokens of a message, bare or quoted: group 1 is the character before the `@` (or the start), group 2 the quoted body (escapes
+ * still in it), group 3 the bare path. `mentionedPaths` of `@hachej/boring-agent/mentions` parses the same syntax (a contract test keeps
+ * them equal).
+ */
+export const MENTION_TOKEN = /(^|\s)@(?:"((?:[^"\\]|\\.)*)"|([^\s]+))/g;
+/** The value of one `MENTION_TOKEN` match: a quoted body unescaped, a bare one without trailing sentence punctuation. */
+const mentionValue = (match) => match[2] !== undefined ? match[2].replace(/\\(.)/g, '$1') : match[3].replace(/[.,;:!?)\]}'"]+$/, '');
+/** The distinct values a message mentions, in order. The same result as the agent's `mentionedPaths`. */
+export function mentionedPaths(text) {
+    const found = new Set();
+    for (const match of text.matchAll(MENTION_TOKEN)) {
+        const value = mentionValue(match);
+        if (value)
+            found.add(value);
+    }
+    return [...found];
+}
+const escape = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+/** Whether the draft already holds a mention of `path`. */
+export function hasMention(text, path) {
+    return pieces(text, { mentions: true, skills: [] }).some(piece => piece.kind === 'mention' && piece.value === path);
+}
+/** The draft without its mention of `path` (and the space after it). */
+export function removeMention(text, path) {
+    let removed = false, gap = false;
+    return pieces(text, { mentions: true, skills: [] }).map(piece => {
+        if (!removed && piece.kind === 'mention' && piece.value === path) {
+            removed = true;
+            gap = true;
+            return '';
+        }
+        if (gap) {
+            gap = false;
+            return piece.text.replace(/^ /, '');
+        }
+        return piece.text;
+    }).join('').replace(/^[ ]+/, '');
+}
+/** A registered prefix wins only for that kind; ordinary file paths keep their existing presentation. */
+export function mentionKind(value, config) {
+    const match = /^([a-z][a-z0-9-]*):(.+)$/s.exec(value);
+    const kind = match && config?.kinds && Object.hasOwn(config.kinds, match[1]) ? config.kinds[match[1]] : undefined;
+    return kind ? { kind, path: match[2] } : undefined;
+}
+/** The composer's editable text and hidden app tokens, derived only from the full draft. File tokens remain editable text. */
+export function kindMentionDraft(text, config) {
+    const hidden = new Set(), tokens = [];
+    let offset = 0;
+    for (const piece of pieces(text, { mentions: true, skills: [] })) {
+        const end = offset + piece.text.length;
+        if (piece.kind === 'mention' && mentionKind(piece.value, config)) {
+            tokens.push(piece.text);
+            for (let at = offset; at < end; at++)
+                hidden.add(at);
+            if (offset > 0 && text[offset - 1] === ' ' && !hidden.has(offset - 1))
+                hidden.add(offset - 1);
+            else if (text[end] === ' ')
+                hidden.add(end);
+        }
+        offset = end;
+    }
+    return { text: text.split('').filter((_, at) => !hidden.has(at)).join(''), tokens };
+}
+/** Keep an explicit leading skill first, then complete hidden tokens before any unfinished quoted input. */
+export function writeKindMentionDraft(text, tokens, skills = []) {
+    if (!tokens.length)
+        return text;
+    const leading = pieces(text, { mentions: false, skills })[0];
+    if (leading?.kind === 'skill')
+        return `${leading.text} ${tokens.join(' ')}${text.slice(leading.text.length)}`;
+    return `${tokens.join(' ')}${text ? ` ${text}` : ''}`;
+}
+/** Consume every draft token for voice sends, including repeated references to the same path. */
+export function withoutMentions(text) {
+    const words = visibleParts(pieces(text, { mentions: true, skills: [] }), piece => piece.kind === 'mention').map(piece => piece.text).join('').replace(/^[ ]+/, '');
+    return words.trim() ? words : '';
+}
+/** Refused messages restore the words, never the app card chips. File mentions retain their existing recovery behaviour. */
+export function withoutKindMentions(text, config) {
+    return visibleParts(pieces(text, { mentions: true, skills: [] }), piece => piece.kind === 'mention' && Boolean(mentionKind(piece.value, config))).map(piece => piece.text).join('').replace(/^[ ]+/, '');
+}
+/**
+ * The draft with `text` added at its end: a space between them unless the draft is empty or already ends in whitespace. Dictation,
+ * voice transcripts, picked mentions and app targets all append this way.
+ */
+export function appendToDraft(draft, text) {
+    return `${draft}${draft === '' || /\s$/.test(draft) ? '' : ' '}${text}`;
+}
+/** The draft with `text` put back before it on its own line (a refused or withdrawn message); whitespace-only parts are dropped. */
+export function prependToDraft(draft, text) {
+    return [text, draft].filter(value => value.trim()).join('\n');
+}
+/** Upload paths are `uploads/<name>`: the attachments of a message, shown as cards rather than as text. */
+export const isUploadPath = (path) => path.startsWith('uploads/');
+const KIND_BY_EXTENSION = {
+    png: 'image', jpg: 'image', jpeg: 'image', gif: 'image', webp: 'image', svg: 'image', bmp: 'image', avif: 'image',
+    pdf: 'pdf',
+    webm: 'audio', ogg: 'audio', m4a: 'audio', mp4: 'audio', mp3: 'audio', wav: 'audio',
+    csv: 'sheet', tsv: 'sheet', xls: 'sheet', xlsx: 'sheet', xlsm: 'sheet', ods: 'sheet', numbers: 'sheet',
+    ppt: 'slides', pptx: 'slides', odp: 'slides', key: 'slides',
+    md: 'document', markdown: 'document', txt: 'document', doc: 'document', docx: 'document', odt: 'document', rtf: 'document',
+};
+/** The card's kind, from the extension alone. */
+export function fileKind(path) {
+    const extension = /\.([^./]+)$/.exec(path)?.[1]?.toLowerCase() ?? '';
+    return KIND_BY_EXTENSION[extension] ?? 'file';
+}
+/** Recorded voice uses a reserved upload filename prefix; other audio remains a plain file card. */
+export const isVoicePath = (path) => /^uploads\/voice-[^/]+$/.test(path) && fileKind(path) === 'audio';
+/** The name a card shows: the upload's file name without the random suffix `uploadPath` adds (`report-1a2b3c4d.pdf` is `report.pdf`). */
+export function displayName(path) {
+    const name = path.slice(path.lastIndexOf('/') + 1);
+    return name.replace(/-[0-9a-f]{8}(?=\.[^.]*$|$)/i, '');
+}
+/**
+ * The pieces a message shows once `hidden` ones are taken out: a space that a removed piece leaves at a join is dropped, and the ends are
+ * trimmed where it was. The message's own text is not changed, only what the bubble draws.
+ */
+export function visibleParts(parts, hidden) {
+    const out = [];
+    let gap = false;
+    for (const part of parts) {
+        if (hidden(part)) {
+            gap = true;
+            continue;
+        }
+        const prev = out[out.length - 1];
+        const joins = gap && part.kind === undefined && (prev === undefined || (prev.kind === undefined && /\s$/.test(prev.text)));
+        out.push(joins ? { text: part.text.replace(/^\s+/, '') } : part);
+        gap = false;
+    }
+    const last = out[out.length - 1];
+    if (gap && last && last.kind === undefined)
+        out[out.length - 1] = { text: last.text.replace(/\s+$/, '') };
+    return out.filter(part => part.kind !== undefined || part.text !== '');
+}
+/** Whether pasted text is long enough to become a file. `more` than the limits: the characters, or the lines, of the text. */
+export function isLongPaste(text, limits = {}) {
+    const { minChars = 2000, minLines = 40 } = limits;
+    return text.length > minChars || text.split('\n').length > minLines;
+}
+/** Markdown in pasted text: a heading, a list or quote item, a fence, a table row, emphasis or a link. Anything else is plain text. */
+export function looksLikeMarkdown(text) {
+    return /^\s{0,3}(#{1,6}\s|[-*+]\s|\d+[.)]\s|>\s|```|~~~)/m.test(text) || /\*\*[^*\n]+\*\*|\]\([^)\n]+\)|^\|.*\|\s*$/m.test(text);
+}
+/** Split a sent message into plain text, `@path` mentions and a leading `/skill` token. */
+export function pieces(text, options) {
+    const found = [];
+    const skill = options.skills.length ? new RegExp(`^/(${options.skills.map(escape).join('|')})(?=\\s|$)`).exec(text) : null;
+    if (skill)
+        found.push({ start: 0, end: skill[0].length, kind: 'skill', value: skill[1] });
+    if (options.mentions || options.uploads) {
+        for (const match of text.matchAll(MENTION_TOKEN)) {
+            // A quoted path keeps its punctuation (the closing quote ends it); a bare one drops trailing punctuation, as a sentence would.
+            const quoted = match[2] !== undefined;
+            const path = mentionValue(match);
+            if (!path || (!options.mentions && !isUploadPath(path)))
+                continue;
+            const start = match.index + match[1].length;
+            const end = quoted ? match.index + match[0].length : start + 1 + path.length;
+            found.push({ start, end, kind: 'mention', value: path });
+        }
+    }
+    const out = [];
+    let cursor = 0;
+    for (const item of found.sort((a, b) => a.start - b.start)) {
+        if (item.start < cursor)
+            continue;
+        if (item.start > cursor)
+            out.push({ text: text.slice(cursor, item.start) });
+        out.push({ text: text.slice(item.start, item.end), kind: item.kind, value: item.value });
+        cursor = item.end;
+    }
+    if (cursor < text.length)
+        out.push({ text: text.slice(cursor) });
+    return out;
+}
+/** The presentation label key for a microphone refusal; labels remain host-owned. */
+export const voiceRefusalLabel = {
+    denied: 'voiceDenied', 'no-microphone': 'voiceNoMicrophone', busy: 'voiceBusy', insecure: 'voiceInsecure', unsupported: 'voiceUnsupported', failed: 'voiceStartFailed',
+};

package/dist/chat-view.d.ts

@@ -34,23 +34,7 @@ export interface ToolEntry<Content = unknown> {
     readonly status: ToolStatus;
     readonly custom?: Content;
 }
-/**
- * An artifact a tool call made (or a running `present` call is making), as the chat places it. `descriptor` is the artifacts item's own
- * value: the chat hands it back to the host's `open` and `isOpen` and never reads it.
- */
-export interface ChatArtifact {
-    readonly state: 'presenting' | 'ready';
-    /** One card per id in a reply: the last version, at the place of its last step. */
-    readonly id: string | undefined;
-    readonly title: string | undefined;
-    /** The workspace path, for the conversation's file list. */
-    readonly path: string | undefined;
-    /** The tool's own result carries it, so its card replaces the step; a host-detected one is shown in addition to the step. */
-    readonly own: boolean;
-    readonly descriptor: unknown;
-}
-/** Finds an artifact descriptor a finished call's result does not carry itself (the host's `detect`). */
-export type ArtifactDetect = (call: ToolCall, result: ToolResultMessage) => unknown;
+import type { ArtifactDetect, ChatArtifact } from './chat-artifacts.js';
 /** The artifact a call made, or that a running call (`running`) is making; undefined for any other call. */
 export type ArtifactRecognise = (call: ToolCall, result: ToolResultMessage | undefined, running: boolean, detect: ArtifactDetect | undefined) => ChatArtifact | undefined;
 /**
@@ -275,4 +259,5 @@ export declare function finishNotice(rows: readonly Row<unknown>[], text?: Notic
     readonly kind: 'done' | 'error';
     readonly summary: string;
 } | undefined;
+export * from './chat-artifacts.js';
 //# sourceMappingURL=chat-view.d.ts.map

package/dist/chat-view.js

@@ -391,3 +391,4 @@ export function finishNotice(rows, text = defaultNoticeText) {
         return { kind: 'error', summary: last.errorMessage ?? text.runFailed };
     return { kind: 'done', summary: summaryOf(last?.text ?? '') || text.finished };
 }
+export * from './chat-artifacts.js';

package/dist/chat-voice-message.d.ts

@@ -0,0 +1,65 @@
+import type { ChatController } from './native-chat.js';
+import type { Dictation, DictationLabels } from './chat-dictation.js';
+export type VoicePhase = 'starting' | 'recording' | 'processing' | 'transcribe-failed' | 'upload-failed' | 'sending' | 'unconfirmed' | 'blocked';
+export interface PendingVoice {
+    readonly id: number;
+    readonly path: string | undefined;
+    readonly phase: VoicePhase;
+    readonly seconds: number;
+    readonly retry: () => void;
+    readonly audioOnly: (() => void) | undefined;
+    readonly discard: () => void;
+}
+export interface VoiceMessageHandle {
+    readonly canStart: boolean;
+    readonly phase: VoicePhase | 'idle';
+    readonly seconds: number;
+    readonly captureSequence: number;
+    readonly levels?: readonly number[];
+    readonly paused?: boolean;
+    readonly pause?: (() => void) | undefined;
+    readonly resume?: (() => void) | undefined;
+    readonly problem: string | undefined;
+    readonly pending: readonly PendingVoice[];
+    readonly start: () => void;
+    readonly finish: () => void;
+    readonly cancel: () => void;
+}
+export interface VoiceMessageConfig {
+    readonly transcribe: (audio: Blob, signal: AbortSignal) => Promise<string>;
+    readonly maxMs?: number;
+    readonly upload?: (files: File[], signal: AbortSignal) => Promise<readonly {
+        readonly path?: string;
+    }[]>;
+}
+export interface VoiceRecorderOptions {
+    readonly controller: ChatController | undefined;
+    readonly config: VoiceMessageConfig | undefined;
+    readonly attachments?: {
+        readonly upload: NonNullable<VoiceMessageConfig['upload']>;
+    } | undefined;
+    readonly labels: DictationLabels;
+    readonly admitted?: (() => void) | undefined;
+    readonly activeController?: {
+        readonly current: ChatController;
+    } | undefined;
+}
+/** Local admission preparation only. Native send/reconcile owns the submission; uploaded bytes stay in the host workspace. */
+export declare function useVoiceMessage({ controller, config, attachments, labels, admitted, activeController }: VoiceRecorderOptions): VoiceMessageHandle;
+export interface ChatVoiceOptions {
+    readonly controller: ChatController | undefined;
+    readonly voice: (VoiceMessageConfig & {
+        readonly send?: 'auto' | 'draft' | 'message';
+    }) | undefined;
+    readonly attachments?: VoiceRecorderOptions['attachments'];
+    readonly labels: DictationLabels;
+    readonly onDone: (outcome: 'sent' | 'drafted') => void;
+}
+export interface ChatVoiceHandle extends Dictation {
+    readonly pending?: readonly PendingVoice[];
+    readonly captureSequence?: number;
+    readonly canStart?: boolean;
+}
+/** Selects retained voice messages or text-only dictation without putting send/draft policy in copied shells. */
+export declare function useChatVoice({ controller, voice, attachments, labels, onDone }: ChatVoiceOptions): ChatVoiceHandle;
+//# sourceMappingURL=chat-voice-message.d.ts.map