@hachej/boring-ui-kit 0.4.26 → 0.4.28

package/dist/chat-react-session.js

@@ -0,0 +1,367 @@
+'use client';
+import { useEffect, useLayoutEffect, useMemo, useRef, useState, useSyncExternalStore } from 'react';
+import { derive, isFileBlock, object, queuedMessages, waitingForAnswer as waitsForAnswer } from './chat-view.js';
+import { appendToDraft, displayName, kindMentionDraft, looksLikeMarkdown, mentionKind, mentionToken, pieces, prependToDraft, withoutKindMentions, writeKindMentionDraft } from './chat-text.js';
+/** Headless session over the public native controller snapshot/commands. Borrows it; cleanup only aborts this hook's uploads. */
+export function useChatSession(options) {
+    const { controller, activeController: active, mode, presentation, actions, renderEntry, hideLine, renderTool: catchAll, toolRenderers, groupTool, subagent, onOpenImage, onFiles, mentions, slash, attachments, model, effort, artifacts, afterSend, feedback, onOpenFile, onPickFiles, commandMentions, onFocus, labels } = options;
+    const state = useSyncExternalStore(controller.subscribe, controller.getSnapshot, controller.getSnapshot);
+    const [error, setError] = useState(null);
+    const [uploading, setUploading] = useState(0);
+    const [picked, setPicked] = useState([]);
+    const [pending, setPending] = useState([]);
+    const [changing, setChanging] = useState(null);
+    const [changeError, setChangeError] = useState(null);
+    const [optimistic, setOptimistic] = useState({});
+    const uploadIds = useRef(0);
+    const uploads = useRef(new Set()), mounted = useRef(false);
+    const current = () => mounted.current && active.current === controller && !controller.getSnapshot().disposed;
+    // The latest text, for a connection failure that lands after the labels changed.
+    const latestLabels = useRef(labels);
+    useLayoutEffect(() => { latestLabels.current = labels; });
+    useEffect(() => {
+        mounted.current = true;
+        const live = uploads.current;
+        // A controller disposed before mount throws synchronously; the chat then renders its disposed state.
+        if (!controller.getSnapshot().disposed)
+            void controller.connect().catch(cause => {
+                if (mounted.current && active.current === controller && !controller.getSnapshot().disposed)
+                    setError(cause instanceof Error ? cause.message : latestLabels.current.connectionFailed);
+            });
+        return () => { mounted.current = false; for (const upload of live)
+            upload.abort(); live.clear(); };
+    }, [controller, active]);
+    const natural = presentation === 'natural';
+    // A tool's own renderer comes first; `renderTool` stays the catch-all.
+    const renderTool = useMemo(() => toolRenderers ? (call, result) => (Object.hasOwn(toolRenderers, call.name) ? toolRenderers[call.name]?.(call, result) : undefined) ?? catchAll?.(call, result) : catchAll, [toolRenderers, catchAll]);
+    const developer = mode === 'developer' && !natural;
+    // Only the recogniser takes part in deriving rows; which card is open changes without rebuilding them.
+    const recognise = artifacts?.recognise, detect = artifacts?.detect;
+    const artifactDetect = useMemo(() => recognise ? { recognise, detect } : undefined, [recognise, detect]);
+    const derived = useMemo(() => derive(state.view, { mode, presentation, hideLine, renderEntry, renderTool, groupTool, artifacts: artifactDetect, subagent }), [state.view, mode, presentation, hideLine, renderEntry, renderTool, groupTool, artifactDetect, subagent]);
+    const queued = useMemo(() => queuedMessages(state.view), [state.view]);
+    const { run } = derived;
+    const earlier = useMemo(() => {
+        if (!state.view || !('entries' in state.history))
+            return [];
+        const activeIds = new Set(state.view.entries.map(entry => entry.id));
+        const entries = state.history.entries.filter(entry => !activeIds.has(entry.id));
+        return derive({ ...state.view, entries, docs: {} }, { mode, presentation, hideLine, renderEntry: undefined, renderTool: undefined, groupTool: undefined, artifacts: artifactDetect, subagent }).rows
+            .map(row => ({ ...row, key: `history:${row.key}`, historical: true }));
+    }, [state.view, state.history, mode, presentation, hideLine, artifactDetect, subagent]);
+    const rows = useMemo(() => [...earlier, ...derived.rows], [earlier, derived.rows]);
+    const files = useMemo(() => {
+        const found = new Map();
+        const open = onOpenFile ?? mentions?.open;
+        const add = (path) => {
+            if (mentionKind(path, mentions))
+                return;
+            const normalized = path.replace(/^\.\//, '');
+            const id = `file:${normalized}`;
+            if (!found.has(id))
+                found.set(id, { id, name: displayName(normalized), open: open ? () => open(normalized) : undefined });
+        };
+        for (const path of picked)
+            add(path);
+        for (const item of state.draft.attachments)
+            found.set(`draft:${item.id}`, { id: `draft:${item.id}`, name: item.name, open: onOpenImage ? () => onOpenImage(item.content) : undefined });
+        for (const row of derived.rows) {
+            if (row.type === 'user') {
+                const content = typeof row.message.content === 'string' ? [{ type: 'text', text: row.message.content }] : row.message.content;
+                for (const [index, part] of content.entries()) {
+                    if (part.type === 'text' && !isFileBlock(part.text))
+                        for (const piece of pieces(part.text, { mentions: true, skills: [] })) {
+                            if (piece.kind === 'mention' && piece.value)
+                                add(piece.value);
+                        }
+                    if (part.type === 'image') {
+                        const id = `image:${row.key}:${index}`;
+                        found.set(id, { id, name: labels.imageAttachment, open: onOpenImage ? () => onOpenImage(part) : undefined });
+                    }
+                }
+            }
+            if (row.type !== 'assistant')
+                continue;
+            for (const part of row.parts) {
+                if (part.kind === 'artifact' && part.artifact.state === 'ready' && part.artifact.path !== undefined) {
+                    const descriptor = part.artifact.descriptor, id = `file:${part.artifact.path.replace(/^\.\//, '')}`;
+                    found.set(id, { id, name: displayName(part.artifact.path), open: artifacts?.open ? () => artifacts.open?.(descriptor) : undefined });
+                }
+                if (!natural && part.kind === 'tool' && part.entry.result && !part.entry.result.isError && ['read', 'write', 'edit'].includes(part.entry.call.name)) {
+                    const path = part.entry.call.arguments['path'];
+                    if (typeof path === 'string')
+                        add(path);
+                }
+            }
+        }
+        return [...found.values()];
+    }, [derived.rows, natural, picked, state.draft.attachments, artifacts, onOpenFile, mentions, onOpenImage, labels.imageAttachment]);
+    const report = (cause) => { if (current())
+        setError(cause instanceof Error ? cause.message : labels.actionFailedShort); };
+    const act = (action) => {
+        setError(null);
+        try {
+            void action().catch(report);
+        }
+        catch (cause) {
+            report(cause);
+        }
+    };
+    // A send being confirmed does not block the next one: the controller empties the composer at once and queues the next message behind it.
+    // Only a submission whose outcome is unknown blocks, until it is checked or retried.
+    const unconfirmed = state.send.kind === 'unknown';
+    const connected = state.connection.kind === 'connected';
+    const sendBlocked = uploading > 0 || state.disposed || !connected || unconfirmed;
+    /** Puts a message back into the composer ahead of whatever is there now (nothing is dropped). */
+    const putBack = (text, images) => {
+        if (controller.getSnapshot().disposed)
+            return;
+        const draft = controller.getSnapshot().draft;
+        controller.setText(prependToDraft(draft.text, withoutKindMentions(text, mentions)));
+        if (images.length)
+            controller.setAttachments([...images, ...draft.attachments.filter(item => !images.some(image => image.id === item.id))]);
+    };
+    const working = Boolean(run);
+    const waitingForAnswer = waitsForAnswer(derived.rows);
+    const send = () => {
+        if (sendBlocked || !current())
+            return;
+        const attach = feedback && feedback.count > 0 ? feedback.attach : undefined;
+        if (attach) {
+            // The pending feedback goes with this message: the host attaches it to the text, then the native send reads the draft.
+            act(async () => {
+                // Like any send, the composer empties at once; the person's own text comes back if the feedback or the message is refused.
+                const typed = controller.getSnapshot().draft;
+                controller.setText('');
+                controller.setAttachments([]);
+                let attached;
+                try {
+                    attached = await attach(typed.text);
+                }
+                catch (cause) {
+                    putBack(typed.text, typed.attachments);
+                    throw cause;
+                }
+                if (attached.kind === 'refused') {
+                    putBack(typed.text, typed.attachments);
+                    throw new Error(attached.reason);
+                }
+                if (!current()) {
+                    putBack(typed.text, typed.attachments);
+                    return;
+                }
+                try {
+                    const submission = await controller.send('followUp', { text: attached.text, attachments: typed.attachments, restore: { text: withoutKindMentions(typed.text, mentions), attachments: typed.attachments } });
+                    if (submission)
+                        feedback?.sent();
+                }
+                catch (cause) {
+                    putBack(typed.text, typed.attachments);
+                    throw cause;
+                }
+            });
+            afterSend?.();
+            onFocus?.();
+            return;
+        }
+        const typed = controller.getSnapshot().draft;
+        const words = withoutKindMentions(typed.text, mentions);
+        if (words !== typed.text) {
+            controller.setText('');
+            controller.setAttachments([]);
+            act(async () => {
+                try {
+                    await controller.send('followUp', { text: typed.text, attachments: typed.attachments, restore: { text: words, attachments: typed.attachments } });
+                }
+                catch (cause) {
+                    putBack(words, typed.attachments);
+                    throw cause;
+                }
+            });
+        }
+        else
+            act(() => controller.send('followUp'));
+        afterSend?.();
+        onFocus?.();
+    };
+    // A queued message is taken back (withdrawn) before it is edited or steered; if Pi already placed it, that is reported and nothing is lost.
+    async function takeBack(item) {
+        if (!actions?.withdraw)
+            throw new Error(labels.queueLocked);
+        const outcome = await actions.withdraw(item.id);
+        if (outcome === 'already_placed' || outcome === 'settled')
+            throw new Error(labels.tooLate);
+    }
+    const queuedContent = (item) => {
+        const parts = Array.isArray(item.content) ? item.content : [];
+        const text = typeof item.content === 'string' ? item.content : parts.flatMap(part => part?.type === 'text' && typeof part.text === 'string' && !isFileBlock(part.text) ? [part.text] : []).join('\n');
+        const images = parts.flatMap((part, index) => part?.type === 'image' && typeof part.data === 'string' && typeof part.mimeType === 'string'
+            ? [{ id: `queued-${String(item.id)}-${index}`, name: `image-${index + 1}`, content: { type: 'image', data: part.data, mimeType: part.mimeType } }] : []);
+        return { text, images };
+    };
+    const queueActions = actions?.withdraw ? {
+        edit: async (item) => {
+            await takeBack(item);
+            const { text, images } = queuedContent(item), draft = controller.getSnapshot().draft;
+            controller.setText(prependToDraft(draft.text, text));
+            if (images.length)
+                controller.setAttachments([...draft.attachments, ...images]);
+            onFocus?.();
+        },
+        steer: async (item) => {
+            if (sendBlocked)
+                throw new Error(labels.waitToSteer);
+            await takeBack(item);
+            const { text, images } = queuedContent(item);
+            // Sent as explicit content, so the person's own draft is never touched; a refused steer comes back into the composer (the controller
+            // puts it back), an unknown one is held for checking.
+            try {
+                const submission = await controller.send('steer', { text, attachments: images });
+                if (!submission && current() && controller.getSnapshot().send.kind === 'blocked')
+                    setError(labels.steerRefused);
+            }
+            catch (cause) {
+                putBack(text, images);
+                if (current())
+                    setError(cause instanceof Error ? cause.message : labels.steerFailed);
+            }
+        },
+    } : undefined;
+    const addMentions = (paths) => {
+        const text = controller.getSnapshot().draft.text;
+        controller.setText(`${appendToDraft(text, paths.map(mentionToken).join(' '))} `);
+        setPicked(value => [...new Set([...value, ...paths])]);
+    };
+    /** Uploads files; `restore` (a pasted text) is what their pending cards undo: it abandons the upload and puts the text back. */
+    async function upload(files, paste) {
+        if (!files.length || !current())
+            return;
+        if (onPickFiles) {
+            onPickFiles(files);
+            return;
+        }
+        if (!onFiles && !attachments)
+            return;
+        const abort = new AbortController();
+        uploads.current.add(abort);
+        setUploading(value => value + 1);
+        const ids = files.map(() => `upload-${++uploadIds.current}`);
+        const settle = (failure) => setPending(items => failure === undefined ? items.filter(item => !ids.includes(item.id))
+            : items.map(item => ids.includes(item.id) ? { ...item, state: 'failed', error: failure } : item));
+        const cancel = paste && (() => { abort.abort(); setPending(items => items.filter(item => !ids.includes(item.id))); paste.restore(); });
+        setPending(items => [...items, ...files.map((file, index) => ({ id: ids[index], name: file.name, state: 'uploading',
+                ...(cancel && paste ? { cancel, restoreWhile: paste.after } : {}) }))]);
+        try {
+            let added = [];
+            let paths = [];
+            if (attachments) {
+                for (const result of await attachments.upload([...files], abort.signal)) {
+                    if (result.image)
+                        added = [...added, { id: `image-${Date.now()}-${++uploadIds.current}`, name: result.name, content: { type: 'image', data: result.image.data, mimeType: result.image.mimeType } }];
+                    else if (result.path)
+                        paths = [...paths, result.path];
+                }
+            }
+            else
+                added = await onFiles(files, { identity: state.identity, conversationId: state.conversationId, signal: abort.signal });
+            if (current() && !abort.signal.aborted) {
+                if (added.length)
+                    controller.setAttachments([...controller.getSnapshot().draft.attachments, ...added]);
+                if (paths.length)
+                    addMentions(paths);
+                settle();
+            }
+        }
+        catch (cause) {
+            if (!abort.signal.aborted) {
+                settle(cause instanceof Error ? cause.message : labels.uploadFailedShort);
+                if (!attachments)
+                    report(cause);
+            }
+        }
+        finally {
+            uploads.current.delete(abort);
+            if (current())
+                setUploading(value => value - 1);
+        }
+    }
+    /** A paste the composer took: saved as a file under `uploads/` (Send then references it). Cancelling puts the text back where it was pasted. */
+    const pasteText = (paste) => {
+        if (!attachments || !current())
+            return;
+        const at = new Date(), two = (value) => String(value).padStart(2, '0');
+        const stamp = `${at.getFullYear()}-${two(at.getMonth() + 1)}-${two(at.getDate())} ${two(at.getHours())}-${two(at.getMinutes())}-${two(at.getSeconds())}`;
+        const markdown = looksLikeMarkdown(paste.text);
+        const file = new File([paste.text], `${labels.pastedFileName(stamp)}${markdown ? '.md' : '.txt'}`, { type: markdown ? 'text/markdown' : 'text/plain' });
+        // The pasted text replaces its selection when the paste is accepted, so the draft shows what is left. Restoring inserts the text at
+        // the same place and deletes nothing: whatever was typed since stays.
+        const draft = kindMentionDraft(controller.getSnapshot().draft.text, mentions);
+        const start = Math.max(0, Math.min(paste.start, draft.text.length)), end = Math.min(Math.max(paste.end, start), draft.text.length);
+        const after = writeKindMentionDraft(`${draft.text.slice(0, start)}${draft.text.slice(end)}`, draft.tokens, slash?.skills?.map(skill => skill.name));
+        controller.setText(after);
+        const restore = () => {
+            if (!current())
+                return;
+            const now = kindMentionDraft(controller.getSnapshot().draft.text, mentions);
+            const at = Math.min(start, now.text.length);
+            controller.setText(writeKindMentionDraft(`${now.text.slice(0, at)}${paste.text}${now.text.slice(at)}`, now.tokens, slash?.skills?.map(skill => skill.name)));
+            onFocus?.();
+        };
+        void upload([file], { restore, after });
+    };
+    const agentDoc = object(state.view?.docs['pi.agent']);
+    const currentModel = object(agentDoc?.['model']);
+    const viewModel = typeof currentModel?.['provider'] === 'string' && typeof currentModel['modelId'] === 'string' ? { provider: currentModel['provider'], modelId: currentModel['modelId'] } : undefined;
+    const viewEffort = typeof agentDoc?.['thinkingLevel'] === 'string' ? agentDoc['thinkingLevel'] : undefined;
+    // Show the accepted choice until the watch delivers it, so the label does not flicker back.
+    useEffect(() => {
+        const same = optimistic.model && viewModel && optimistic.model.provider === viewModel.provider && optimistic.model.modelId === viewModel.modelId;
+        // eslint-disable-next-line react-hooks/set-state-in-effect -- drops the optimistic choice once the watch delivers it; runs only when it matches, so it settles
+        if (same || (optimistic.effort !== undefined && optimistic.effort === viewEffort))
+            setOptimistic(value => ({ ...(same ? {} : value.model ? { model: value.model } : {}), ...(optimistic.effort === viewEffort ? {} : value.effort ? { effort: value.effort } : {}) }));
+        // eslint-disable-next-line react-hooks/exhaustive-deps -- viewModel is rebuilt every render; its provider and modelId are what it compares
+    }, [optimistic, viewModel?.provider, viewModel?.modelId, viewEffort]);
+    // eslint-disable-next-line react-hooks/set-state-in-effect -- cleared text drops the picked mentions once, after commit; the updater keeps an empty list as is
+    useEffect(() => { if (!state.draft.text)
+        setPicked(value => value.length ? [] : value); }, [state.draft.text]);
+    async function change(kind, apply, accepted, rejected) {
+        if (changing || !current())
+            return;
+        setChanging(kind);
+        setChangeError(null);
+        try {
+            await apply();
+            if (current())
+                accepted();
+        }
+        catch (cause) {
+            if (current()) {
+                rejected();
+                setChangeError(cause instanceof Error && cause.message ? cause.message : labels.changeRefused);
+            }
+        }
+        finally {
+            if (current())
+                setChanging(null);
+        }
+    }
+    const activateMention = (command) => {
+        if (!current() || controller.getSnapshot().connection.kind !== 'connected')
+            return;
+        const catalog = commandMentions;
+        const selected = catalog?.commands.find(item => item.name === command.name && item.behavior === command.behavior);
+        if (catalog && selected)
+            act(async () => catalog.onActivate({ name: selected.name, behavior: selected.behavior }));
+    };
+    const empty = connected && !state.view?.entries.length && !rows.length;
+    const loading = (state.connection.kind === 'idle' || state.connection.kind === 'connecting') && !state.view;
+    return { state, derived, rows, queued, queueActions, working, waitingForAnswer, connected, sendBlocked, error, setError, report, act, current,
+        files, empty, loading, developer, natural, send, putBack, upload, pasteText, picked, pending, uploading, activateMention,
+        pickMention: (path) => setPicked(value => value.includes(path) ? value : [...value, path]),
+        dismissUpload: (id) => setPending(items => items.filter(item => item.id !== id)),
+        currentModel: optimistic.model ?? viewModel, currentEffort: optimistic.effort ?? viewEffort,
+        changing, changeError, dismissChangeError: () => setChangeError(null),
+        changeModel: (next) => change('model', () => model.change(next), () => setOptimistic(value => ({ ...value, model: next })), () => { }),
+        changeEffort: (next) => change('effort', () => effort.change(next), () => setOptimistic(value => ({ ...value, effort: next })), () => { }),
+    };
+}

package/dist/chat-react.d.ts

@@ -57,4 +57,6 @@ export declare function useArtifactFollow(options: ArtifactFollowOptions): {
     onShown: (shown: ArtifactShown) => void;
     onFailed: (failed: ArtifactFailed) => void;
 };
+export { useChatSession } from './chat-react-session.js';
+export type { ChatSession, ChatSessionOptions, ChatSessionLabels, ChatSessionFeedback, ConversationFile, ModelRef, PastedText, UploadResult, PendingUpload, FilesHandler, QueueActions } from './chat-react-session.js';
 //# sourceMappingURL=chat-react.d.ts.map

package/dist/chat-react.js

@@ -92,3 +92,4 @@ export function useArtifactFollow(options) {
     }, [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

@@ -119,4 +119,13 @@ export declare function pieces(text: string, options: {
     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

@@ -214,3 +214,7 @@ export function pieces(text, options) {
         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-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