@hachej/boring-ui-kit 0.4.26 → 0.4.27

package/README.md

@@ -38,7 +38,7 @@ import { MarkdownEditor } from '@hachej/boring-ui-kit/markdown-editor';
 
 Install the pinned React, React DOM, Marked and Tiptap peers listed in this package's manifest when selecting this entry. They remain optional for headless consumers. The renderer borrows its controller; unmounting does not dispose it or close its resource client. The host owns selection, identity and teardown.
 
-Formatting defaults to the native Tiptap selection bubble on desktop and phone. The header’s **Formatting** icon toggles the full bar; unpressed means selection-only formatting. It remembers the choice for the viewer session, stays visible on phones with a 48px target and hides in Markdown mode. The **…** menu keeps **Formatted** / **Markdown**. Pass `formattingToolbar="pinned"` for the full desktop row (on phones it docks above the keyboard while editing). The built-in menu supports `locale="fr"`. Installed recipes supply real shadcn Base UI menu items through the optional `components.markdownMenu` binding. Keyboard shortcuts and Markdown input rules remain available. Rich formatting and Markdown source controls share controller state. Mounting, switching modes and projecting remote text never serialize the original buffer. Genuine rich edits serialize the changed block range through Tiptap; untouched source spans are retained verbatim.
+Formatting defaults to the native Tiptap selection bubble on desktop and phone. The header’s **Formatting** icon toggles the full bar; unpressed means selection-only formatting. It remembers the choice for the viewer session, stays visible on phones with a 48px target and hides in Markdown mode. The **…** menu keeps **Formatted** / **Markdown**. Pass `formattingToolbar="pinned"` for the full desktop row (on phones it docks above the keyboard while editing). `locale="fr"` translates everything the editor draws itself (status, Save, save and conflict alerts, toolbar and source-box accessible names, proposals, draft recovery); `labels={{ saved: 'Enregistré', sourceName: title => title }}` overrides single words of either set (`markdownEditorLabels.en` lists every key). Text the host supplies (`title`, `placeholder`, a save result's `reason`) is shown as given. Installed recipes supply real shadcn Base UI menu items through the optional `components.markdownMenu` binding. Keyboard shortcuts and Markdown input rules remain available. Rich formatting and Markdown source controls share controller state. Mounting, switching modes and projecting remote text never serialize the original buffer. Genuine rich edits serialize the changed block range through Tiptap; untouched source spans are retained verbatim.
 
 Formatted opens documents with YAML front matter, raw HTML/comments, footnotes, reference links, CRLF and style variants (`*` bullets, four-space nesting, underscore emphasis and setext headings). Front matter is an editable literal code block. HTML and definitions are quiet raw blocks; inline HTML and references are inert source atoms, never executable HTML. A save without editing preserves the original bytes. Paragraph/heading/list-item source metadata also keeps unchanged spelling through edits and native undo. Edited content follows its existing heading style and document markers where valid; intraword emphasis uses stars when underscores would change its meaning. CRLF is edited as LF and restored on write. The existing legacy ` `-only paragraph cleanup remains.
 
@@ -84,6 +84,10 @@ Where the page has Web Audio, the recording is a 16 kHz mono 16-bit WAV (`audio/
 
 `maxMs` caps captured audio 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.
 
+`@hachej/boring-ui-kit/chat-react/voice` adds the optional React voice orchestration without adding microphone capture to core `chat-react` imports: `useVoiceAttempt<Data, Phase>()` owns attempt identities, abort signals, microphone cleanup and sample-based elapsed time, input levels and pause/resume. `start(data, maxMs?)` begins from the gesture; `stop(attempt)` retains the recording; `remove(attempt)` cancels only that attempt. `useDictation({ transcribe, onText, labels, maxMs?, target? })` trims transcription and delivers it only while the attempt still belongs to the selected target. Cancel, finish during permission, target replacement and unmount fence late results. Supply the eight voice labels (`DictationLabels`); the registry adapter supplies its English/French table. `voiceRefusalLabel` in `chat-text` is the one refusal-to-label-key map.
+
+`useVoiceMessage({ controller, config, attachments?, labels, admitted?, activeController? })` uses that same capture lifecycle, uploads and transcribes in parallel on release, and submits one native `followUp` with the audio mention and transcript. It preserves typed drafts, successful upload/transcription halves and exact native draft/request identity for uncertain admission; native reconciliation, not a new voice retry, resolves unknown sends. `useChatVoice({ controller, voice, attachments?, labels, onDone })` selects text-only draft/auto or retained message mode for a shell, including native send, draft restore and completion callbacks. Both lower-level hooks accept the capture's `maxMs` semantics: five minutes by default, nonpositive/nonfinite disables the cap, and the cap stops the microphone without automatically delivering text or sending. These are browser preparation hooks over the existing native controller, not Pi execution extensions. Evidence: `test/packages/ui-chat-react-voice.test.mjs`.
+
 The [registry voice-message guide](../../registry/README.md#voice-messages-in-pi-chat) describes PiChat's optional tap-to-record 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
@@ -158,6 +162,15 @@ A submit the host refused before admission (status 402 `submission-refused`, for
 
 `@hachej/boring-ui-kit/chat-react` is opt-in React presentation over the existing `ChatController.subscribe/getSnapshot` seam, never a Pi executor or a second store. `useArtifactFollow` takes the controller, conversation ID, active descriptor/follow selection and host opening/guard callbacks. It returns versions, `open`, `isOpen`, `select`, `recordClosed` and viewer `onShown`/`onFailed` callbacks. Initial artifacts do not auto-open; new ones may when `autoOpen` is enabled (default false), unless the host reports a narrow screen, unsaved work or a close in this turn. Call `recordClosed` only after the host's leave guard accepts. A present is acknowledged with only the revision the viewer reports after it loads and mounts; unmount reports use `hidden: true`, failures refuse, and absent reports stay unconfirmed. Controller/conversation changes fence old reports and retries. The host retains its controller and execution lifetime. Evidence: `test/packages/ui-chat-react.test.mjs`, `test/packages/ui-present-ack.test.mjs`.
 
+`useChatSession<Content>({ controller, activeController, mode, labels, ...features })` is the headless session. `labels` is the small `ChatSessionLabels` contract (no built-in locale or UI); renderers use generic `Content`, with optional tool-name renderers before the catch-all. The hook returns `state`, `derived`, active/archived `rows`, `files`, `queued`, `queueActions`, connection/loading/working/waiting/send readiness, errors and actions. Optional `artifacts.recognise` enables artifact derivation; the registry enables it only when its card is installed. Files are observed conversation references opened by host callbacks, not a filesystem or a new file store.
+
+- `send()` uses native `followUp`; `putBack(text, images)` preserves later typing. Optional `feedback` attaches notes with exact native restore content. The existing `mentions.kinds` rules are preserved: native sends keep app tokens, refused drafts restore words/images without app chips, and app cards are excluded from observed files. Unknown admission stays blocked for native reconcile/retry; the hook never creates a retry identity.
+- `queueActions.edit/steer` withdraw first and refuse already-placed messages; steer preserves the current draft. `upload(files)` uses host `attachments.upload` (paths become mentions; images native attachments), legacy `onFiles` or host-owned `onPickFiles`. `pending`, `picked`, `pickMention`, `dismissUpload` drive presentation. `pasteText({ text, start, end })` uploads Markdown/text and supplies a pending cancel action that restores the captured paste without deleting intervening edits. Paste coordinates address editable text, retaining hidden app tokens and the existing leading `slash.skills` order on cancel; the composer decides paste thresholds through `chat-text`.
+- `currentModel`, `currentEffort`, `changing`, `changeError`, `changeModel`, `changeEffort` and `dismissChangeError` drive optional host pickers; accepted choices stay optimistic until the native watch agrees. `activateMention` checks the current command catalog and connection; host authorization is still separate.
+- **Ownership:** mount one session per controller (key/remount on replacement, as the registry does), keep `activeController.current` bound to the host's current controller, and supply stable host configs where possible. The hook connects on mount, detaches its subscription and aborts only its own uploads on unmount. It never disposes the borrowed controller, stops Pi work or owns a Harness. `afterSend` and `onFocus` are event callbacks; DOM refs, JSX, pickers and composer slots stay in the registry. Nothing is exported by the files/Pi/agent-free root.
+
+Public-output/StrictMode evidence: `test/packages/ui-chat-session.test.mjs`. `pi-chat/session.useChatSession` retains its presentation adapter API and old contract type imports for one release. `ChatConnectionNotice` and `ChatStatusLine` in `pi-chat/notice` are reusable presentation shared by PiChat and Ambient; Ambient's host connection-error renderer now survives both full and compact notices. `test/ui/ambient-position.test.mjs` drives the public Ambient component and status matrix.
+
 The same entry exports the shared chat hooks (not from the headless root):
 
 - `useChatView(controller, select)` selects the native `view` (possibly undefined) through the existing `subscribe/getSnapshot`; selection is memoized by view and selector identity. It borrows the controller and introduces no store. Keep a selector stable to avoid repeated derivation.
@@ -167,7 +180,7 @@ The same entry exports the shared chat hooks (not from the headless root):
 - `useControllerPerConversation({ key, create, connect?, dispose?, retryMs? })` is shared selected-adapter ownership, not a Pi lifecycle. Use a stable key including source/owner/options; undefined acquires nothing. It returns connecting/offline/ready and preserves the factory's concrete controller type. It disposes only what the factory creates (including late results and StrictMode mounts), awaits async teardown on retry, and releases retry timers on selection change. A custom `dispose` releases any additional owned transport; teardown errors are reported to the console. It never aborts native work or closes a borrowed source/Harness. `useSharedChat` uses it without changing its existing connect-on-session-mount behavior.
 - `useConversationsClient({ endpoint, fetch, activeId, onSelect, onChange?, pollMs? })` (alias `useConversations`) returns the headless list and reload/search/create/rename/archive/delete/fork callbacks once the first list arrives. Polling defaults to four seconds; fetch and selection callbacks remain host-owned. Registry `ConversationsConfig` adds presentation-only row actions.
 
-Public hook/StrictMode evidence: `test/packages/ui-chat-react-hooks.test.mjs`. Existing `test/contracts/chat-placement*.test.mjs` and `test/ui/pi-chat-draft.test.mjs` also drive the compatibility entry points. Browser scroll and installed consumers are separate gates; session send/upload/model logic remains in the registry pending its own extraction.
+Public hook/StrictMode evidence: `test/packages/ui-chat-react-hooks.test.mjs`. Existing `test/contracts/chat-placement*.test.mjs` and `test/ui/pi-chat-draft.test.mjs` also drive the compatibility entry points. Browser scroll and installed consumers are separate gates.
 
 
 ### Native conversation history

package/dist/chat-dictation.d.ts

@@ -0,0 +1,27 @@
+import { voiceRefusalLabel } from './chat-text.js';
+export type DictationPhase = 'idle' | 'starting' | 'recording' | 'transcribing';
+export interface Dictation {
+    readonly phase: DictationPhase;
+    readonly seconds: number;
+    readonly levels: readonly number[];
+    readonly paused: boolean;
+    readonly pause: (() => void) | undefined;
+    readonly resume: (() => void) | undefined;
+    readonly problem: string | undefined;
+    readonly start: () => void;
+    readonly finish: () => void;
+    readonly cancel: () => void;
+}
+export type DictationLabels = Readonly<Record<typeof voiceRefusalLabel[keyof typeof voiceRefusalLabel] | 'voiceNothingHeard' | 'voiceTranscribeFailed', string>>;
+export interface DictationOptions {
+    readonly transcribe: ((audio: Blob, signal: AbortSignal) => Promise<string>) | undefined;
+    readonly onText: (text: string, signal: AbortSignal) => void | Promise<void>;
+    readonly labels: DictationLabels;
+    /** Capture stops at this limit; transcription still waits for finish (default five minutes). */
+    readonly maxMs?: number | undefined;
+    /** Changing the target drops pending permission/transcription instead of inserting into the new subject. */
+    readonly target?: unknown;
+}
+/** Gesture-started dictation over the shared attempt lifecycle; host callbacks and labels are captured per attempt. */
+export declare function useDictation(options: DictationOptions): Dictation;
+//# sourceMappingURL=chat-dictation.d.ts.map

package/dist/chat-dictation.js

@@ -0,0 +1,71 @@
+'use client';
+import { useCallback, useLayoutEffect, useRef, useState } from 'react';
+import { voiceRefusalLabel } from './chat-text.js';
+import { useVoiceAttempt } from './voice-attempt.js';
+/** Gesture-started dictation over the shared attempt lifecycle; host callbacks and labels are captured per attempt. */
+export function useDictation(options) {
+    const latest = useRef(options);
+    useLayoutEffect(() => { latest.current = options; });
+    const [problem, setProblem] = useState();
+    const core = useVoiceAttempt({
+        valid: item => latest.current.target === item.options.target,
+        refused: result => setProblem(latest.current.labels[voiceRefusalLabel[result.code ?? 'failed']]),
+    });
+    const actions = useRef(core);
+    useLayoutEffect(() => { actions.current = core; });
+    const cancel = useCallback(() => { actions.current.clear(); setProblem(undefined); }, []);
+    // A committed subject change releases pending microphone permission and aborts transcription.
+    useLayoutEffect(() => cancel(), [options.target, cancel]);
+    const start = useCallback(() => {
+        const selected = latest.current;
+        if (!selected.transcribe || actions.current.current().length)
+            return;
+        setProblem(undefined);
+        actions.current.start({ options: selected }, selected.maxMs);
+    }, []);
+    const finish = useCallback(() => {
+        const api = actions.current, item = api.current()[0];
+        if (!item || !api.valid(item))
+            return;
+        if (item.phase === 'starting') {
+            cancel();
+            return;
+        }
+        if (item.phase !== 'recording')
+            return;
+        const selected = item.options;
+        void (async () => {
+            try {
+                const recording = await api.stop(item);
+                if (!api.valid(item))
+                    return;
+                if (!recording) {
+                    setProblem(selected.labels.voiceNothingHeard);
+                    return;
+                }
+                const text = (await selected.transcribe(recording.audio, item.abort.signal)).trim();
+                if (!api.valid(item))
+                    return;
+                if (!text) {
+                    setProblem(selected.labels.voiceNothingHeard);
+                    return;
+                }
+                await selected.onText(text, item.abort.signal);
+            }
+            catch {
+                if (api.valid(item))
+                    setProblem(selected.labels.voiceTranscribeFailed);
+            }
+            finally {
+                if (api.valid(item))
+                    api.remove(item);
+            }
+        })();
+    }, [cancel]);
+    const item = core.attempts[0];
+    return { phase: item?.phase === 'processing' ? 'transcribing' : item?.phase ?? 'idle', seconds: item?.seconds ?? 0,
+        levels: item?.levels ?? [], paused: item?.paused ?? false,
+        pause: item?.phase === 'recording' && item.canPause ? () => core.pause(item) : undefined,
+        resume: item?.phase === 'recording' && item.canPause ? () => core.resume(item) : undefined,
+        problem, start, finish, cancel };
+}

package/dist/chat-react-session.d.ts

@@ -0,0 +1,170 @@
+import type { ToolCall, ToolResultMessage } from '@earendil-works/pi-ai';
+import type { ChatAttachment, ChatController } from './native-chat.js';
+import type { ChatCard, DeriveOptions, Mode, QueuedMessage, Row } from './chat-view.js';
+/** A conversation's observed file; opening remains a host operation, not workspace ownership. */
+export interface ConversationFile {
+    readonly id: string;
+    readonly name: string;
+    readonly open: (() => void) | undefined;
+}
+export interface ModelRef {
+    readonly provider: string;
+    readonly modelId: string;
+}
+export interface PastedText {
+    readonly text: string;
+    readonly start: number;
+    readonly end: number;
+}
+export interface UploadResult {
+    readonly path?: string;
+    readonly image?: {
+        readonly data: string;
+        readonly mimeType: string;
+    };
+    readonly name: string;
+}
+export interface PendingUpload {
+    readonly id: string;
+    readonly name: string;
+    readonly state: 'uploading' | 'failed';
+    readonly error?: string;
+    readonly cancel?: (() => void) | undefined;
+    readonly restoreWhile?: string | undefined;
+}
+export type FilesHandler = (files: readonly File[], target: Pick<ReturnType<ChatController['getSnapshot']>, 'identity' | 'conversationId'> & {
+    readonly signal: AbortSignal;
+}) => Promise<readonly ChatAttachment[]>;
+export interface QueueActions {
+    readonly edit?: ((item: QueuedMessage) => Promise<void>) | undefined;
+    readonly steer?: ((item: QueuedMessage) => Promise<void>) | undefined;
+}
+/** Send-time feedback only; the annotate button and its state remain host presentation. */
+export interface ChatSessionFeedback {
+    readonly count: number;
+    readonly attach: (text: string) => Promise<{
+        readonly kind: 'ok';
+        readonly text: string;
+    } | {
+        readonly kind: 'refused';
+        readonly reason: string;
+    }>;
+    readonly sent: () => void;
+}
+export interface ChatSessionLabels {
+    readonly connectionFailed: string;
+    readonly actionFailedShort: string;
+    readonly imageAttachment: string;
+    readonly queueLocked: string;
+    readonly tooLate: string;
+    readonly waitToSteer: string;
+    readonly steerRefused: string;
+    readonly steerFailed: string;
+    readonly uploadFailedShort: string;
+    readonly pastedFileName: (stamp: string) => string;
+    readonly changeRefused: string;
+}
+export interface ChatSessionOptions<Content = unknown> extends Partial<DeriveOptions<Content>> {
+    readonly controller: ChatController;
+    /** Surfaces remount on controller replacement. Late effects/actions also check this live binding. */
+    readonly activeController: {
+        readonly current: ChatController;
+    };
+    readonly mode: Mode;
+    readonly labels: ChatSessionLabels;
+    readonly actions?: {
+        readonly withdraw?: ((id: QueuedMessage['id']) => Promise<unknown>) | undefined;
+    } | undefined;
+    readonly toolRenderers?: Readonly<Record<string, (call: ToolCall, result: ToolResultMessage | undefined) => ChatCard<Content> | undefined>> | undefined;
+    readonly artifacts?: (NonNullable<DeriveOptions<Content>['artifacts']> & {
+        readonly open?: ((artifact: never) => void) | undefined;
+    }) | undefined;
+    readonly mentions?: {
+        readonly open?: ((path: string) => void) | undefined;
+        readonly kinds?: Readonly<Record<string, unknown>> | undefined;
+    } | undefined;
+    readonly slash?: {
+        readonly skills?: readonly {
+            readonly name: string;
+        }[] | undefined;
+    } | undefined;
+    readonly onOpenFile?: ((path: string) => void) | undefined;
+    readonly onOpenImage?: ((image: ChatAttachment['content']) => void) | undefined;
+    readonly onFiles?: FilesHandler | undefined;
+    readonly onPickFiles?: ((files: readonly File[]) => void) | undefined;
+    readonly attachments?: {
+        readonly upload: (files: File[], signal: AbortSignal) => Promise<readonly UploadResult[]>;
+    } | undefined;
+    readonly model?: {
+        readonly change: (model: ModelRef) => Promise<void>;
+    } | undefined;
+    readonly effort?: {
+        readonly change: (level: string) => Promise<void>;
+    } | undefined;
+    readonly commandMentions?: {
+        readonly commands: readonly {
+            readonly name: string;
+            readonly behavior: 'execute' | 'insert';
+        }[];
+        readonly onActivate: (command: {
+            readonly name: string;
+            readonly behavior: 'execute' | 'insert';
+        }) => void;
+    } | undefined;
+    readonly feedback?: ChatSessionFeedback | undefined;
+    readonly afterSend?: (() => void) | undefined;
+    /** Focus is presentation; called only by actions, never during render. */
+    readonly onFocus?: (() => void) | undefined;
+}
+/** Headless session over the public native controller snapshot/commands. Borrows it; cleanup only aborts this hook's uploads. */
+export declare function useChatSession<Content = unknown>(options: ChatSessionOptions<Content>): {
+    state: import("./native-chat.js").ChatSnapshot;
+    derived: import("./chat-view.js").Derived<Content>;
+    rows: Row<Content>[];
+    queued: {
+        id: import("@earendil-works/pi-durable").SubmissionId;
+        mode: "steer" | "followUp";
+        content: import("@earendil-works/chord").JsonRepresentation<import("@earendil-works/pi-durable").UserInput>;
+        entry?: import("@earendil-works/chord").JsonRepresentation<import("@earendil-works/pi-durable").InputEntry>;
+    }[];
+    queueActions: QueueActions | undefined;
+    working: boolean;
+    waitingForAnswer: boolean;
+    connected: boolean;
+    sendBlocked: boolean;
+    error: string | null;
+    setError: import("react").Dispatch<import("react").SetStateAction<string | null>>;
+    report: (cause: unknown) => void;
+    act: (action: () => Promise<unknown>) => void;
+    current: () => boolean;
+    files: ConversationFile[];
+    empty: boolean;
+    loading: boolean;
+    developer: boolean;
+    natural: boolean;
+    send: () => void;
+    putBack: (text: string, images: readonly ChatAttachment[]) => void;
+    upload: (files: readonly File[], paste?: {
+        readonly restore: () => void;
+        readonly after: string;
+    }) => Promise<void>;
+    pasteText: (paste: PastedText) => void;
+    picked: readonly string[];
+    pending: readonly PendingUpload[];
+    uploading: number;
+    activateMention: (command: {
+        readonly name: string;
+        readonly behavior: "execute" | "insert";
+    }) => void;
+    pickMention: (path: string) => void;
+    dismissUpload: (id: string) => void;
+    currentModel: ModelRef | undefined;
+    currentEffort: string | undefined;
+    changing: "model" | "effort" | null;
+    changeError: string | null;
+    dismissChangeError: () => void;
+    changeModel: (next: ModelRef) => Promise<void>;
+    changeEffort: (next: string) => Promise<void>;
+};
+export type ChatSession<Content = unknown> = ReturnType<typeof useChatSession<Content>>;
+//# sourceMappingURL=chat-react-session.d.ts.map