@hachej/boring-ui-kit 0.4.25 → 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.
 
@@ -80,9 +80,15 @@ The default schema includes headings, lists, task lists, quotes, code and text m
 
 Where the page has Web Audio, the recording is a 16 kHz mono 16-bit WAV (`audio/wav`, 32 kB/s), not MediaRecorder's webm: a webm carries the browser's clock, and one whose timestamps jumped was refused by every OpenAI transcription model. `start()` resolves `recording` once the first sound arrives, so a host showing "recording" never loses the first words; no sound within `firstSoundMs` (5 s) refuses as `busy`. A context the browser keeps suspended (no user activation, e.g. a hold begun on `touchstart`) records that take with MediaRecorder as before; `audioContext: null` always does. `encodeWav` and `downsample` are exported.
 
-`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.
+`progress()` returns current elapsed milliseconds, PCM RMS level, paused state and pause capability (null outside a capture). `pause()`/`resume()` return false when unavailable/ended. PCM pause keeps the microphone open but stops appending frames: elapsed time and WAV duration exclude paused samples. MediaRecorder fallback exposes no level or pause, never fabricated telemetry.
 
-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`.
+`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
 
@@ -146,6 +152,37 @@ A submit the host refused before admission (status 402 `submission-refused`, for
 
 `@hachej/boring-ui-kit/chat-view` holds the chat's presentation rules once, so the registry items (`pi-chat`, `pi-ambient`) keep only their markup. It imports Pi types only: no React, no files or agent code. `derive(view, options)` turns a native `ConversationView` into display rows (cards, activity steps, questions, approvals, artifacts) and the run state; its card content type is generic, and the items fix it to React nodes. `waits(part)`, `waitingPart(rows)` and `waitingForAnswer(rows)` are the one rule for "waiting for the person": a committed question with no result, or an approval with no result and no decision (a decided approval is not waiting). `preparing(...)` is when the natural presentation's single status shows. `pendingNotice` and `finishNotice` give the words of the run toasts and system notifications from one table, `defaultNoticeText`, which a surface can replace to localize them. Evidence: `test/packages/ui-chat-view.test.mjs`.
 
+`@hachej/boring-ui-kit/chat-text` holds the chat's text grammar once: pure string functions, no React, files or agent code. `mentionToken(value)` writes an `@` mention (quoted when the value has whitespace, a quote or a backslash) and `mentionedPaths(text)`, `MENTION_TOKEN` and `pieces(text, options)` read mentions back, with the same parser as `mentionedPaths` of `@hachej/boring-agent/mentions`; `hasMention` and `removeMention` edit a draft; `slashItems`, `slashGroup` and `slashQuery` drive the `/` menu, `mentionTrigger` the `@` picker. `appendToDraft(draft, text)` adds text at the end of a draft with one space, and `prependToDraft(draft, text)` puts a refused message back on its own line before it. `fileKind`, `isUploadPath`, `isVoicePath`, `displayName`, `visibleParts`, `isLongPaste` and `looksLikeMarkdown` classify attachments and pastes. The shared chat writes and finds member mentions with it (`memberMention`). `kindMentionDraft(text, { kinds })` projects editable composer text plus its hidden kind-token spellings from the full native draft, leaving file tokens visible. `writeKindMentionDraft(text, tokens, skills?)` keeps a leading registered skill first, then prefixes complete hidden tokens before the remaining editable text so unfinished quoted input cannot consume them; `skills` is the registered name list, parsed by the same `pieces` grammar. `mentionKind(value, { kinds })` resolves an app-registered `prefix:path` token without depending on its renderer; `withoutMentions(text)` consumes all tokens for voice sends, while `withoutKindMentions(text, { kinds })` drops only registered app tokens from refused-message restoration. See [App mention kinds](../../registry/README.md#app-mention-kinds) for the React config. Evidence: `test/packages/ui-chat-text.test.mjs`.
+
+`@hachej/boring-ui-kit/chat-react` provides `useRunNotifications(controller, store, options)`, `watchConversation(controller, store, options)` and `createNotificationStore()`. Both adapters use one transition over the existing controller's `subscribe`/`getSnapshot`, with no execution lifecycle ownership. `options` supplies `conversationId`, `title`, `question(call)` and optional localized `text` (`NoticeText`); `enabled`, `suppress()` and `onOutcome()` are optional. Questions notify even without a run; approval decisions dismiss input notices; disconnected snapshots neither complete work nor consume transitions. The first connected observation establishes a baseline (and reports pending input), never invents a past completion. Suppression consumes a transition without pushing a toast. Detaching releases only the subscription. The store is transient presentation, not durable delivery. This is host UI policy over native views, not a Pi execution extension. Existing registry notification exports remain available. Evidence: `test/packages/ui-run-notifications.test.mjs`.
+
+`chat-view` also owns artifact descriptors and parsing (`parseArtifact`, `detectArtifact`, `recogniseArtifact`), `pendingPresents` and `createPresentAcks`. `artifactVersions(view, detect?)` lists newest conversation results first, even when retried calls reuse an ordinal. `follows(descriptor, versions)` compares the newest revision for that artifact key. `collectArtifacts` remains oldest first for compatibility.
+
+### Chat React hooks
+
+`@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.
+- `useTranscriptWindow(rows, first = 60, more = 40, history?, automatic = true)` (alias `useTranscript`) returns `hidden`, `visible`, `reveal`, `revealTo`, `reset`, `loaded`, `scrollRef` and `sentinelRef`. Give `scrollRef` the host scroll element. The hook owns only the paging window and top sentinel, not scroll position or follow-bottom. Registry `session.useTranscript` combines it with the app's shadcn MessageScroller, the only actual scroll/anchor owner. `useRowChunks(rows, size = 20)` retains run boundaries and unchanged row arrays for that scroller.
+- `useChatDraft(controller, key)` keeps the existing per-conversation localStorage policy under `pi-chat:draft:<key>`; undefined opts out, blocked storage never blocks typing. The host must scope the key by owner when needed and clear sensitive drafts on logout. `useChatPlacement` / `readChatPlacement` report the last surviving presenter's docked/floating registration; placement is advisory, never authorization.
+- `useRemoteChat({ conversationId, endpoint, fetch, identity, requestContext?, transport?, webSocket? })` returns connecting/offline/ready with the concrete native controller, transport actions and configure. Selection keys include the conversation, resolved URL, identity IDs and transport; new identity objects alone do not reconnect. Current fetch/context callbacks are read after commit; each submit merges current placement alongside the original screen context. Failed acquisition retries every second; transport reconnect remains the existing remote client's responsibility.
+- `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.
+
+
 ### Native conversation history
 
 `loadEarlier()` reads one native page through `Conversation.entries`. `snapshot.history` distinguishes disabled, idle, loading, ready and error states. Each request contains at most 40 native entries. The controller accumulates pages in display order for the person's current browsing session and retains an opaque native continuation cursor. It clears that cache on history invalidation or `clearHistory()`; loading never restores records to model context. The first request captures the greatest observed active entry ID as an inclusive upper bound; later writes do not move that bound. Parent-owned fork entries remain valid native history.

package/dist/chat-artifacts.d.ts

@@ -0,0 +1,157 @@
+import type { ConversationView } from '@earendil-works/pi-durable';
+import type { ToolCall, ToolResultMessage } from '@earendil-works/pi-ai';
+/**
+ * An artifact a tool call made (or a running `present` call is making), as the chat places it. `descriptor` is the host'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;
+export declare const ARTIFACT_TYPES: readonly ["markdown", "html", "svg", "code", "canvas"];
+export type ArtifactType = typeof ARTIFACT_TYPES[number];
+/** Structural twin of the `ResourceLocator` in `@hachej/boring-files`. */
+export interface ArtifactTarget {
+    readonly resource: {
+        readonly providerId: string;
+        readonly path: string;
+    };
+    readonly view: {
+        readonly kind: 'published';
+    } | {
+        readonly kind: 'working';
+        readonly viewId: string;
+    };
+}
+export interface ArtifactDescriptor {
+    readonly schema: 'boring.artifact';
+    readonly version: 1;
+    /** Set by the artifact tools; the descriptor of `present` has none (the file path is its identity). */
+    readonly id?: string;
+    readonly title: string;
+    readonly type: ArtifactType;
+    readonly mediaType: string;
+    readonly language?: string;
+    readonly target: ArtifactTarget;
+    /** The revision this message produced. */
+    readonly revision: string;
+    /** The 1-based version number of this artifact (artifact tools only). */
+    readonly ordinal?: number;
+}
+/** What identifies an artifact across its versions: its id, or for a presented file its path. */
+export declare const artifactKey: (artifact: Pick<ArtifactDescriptor, "id" | "target">) => string;
+export declare const PRESENT_TOOL = "present";
+/** A `present` call with no result yet, while its conversation runs: its answer ID (`[assistantEntryId, callId]`) and the path it names. */
+export interface PendingPresent {
+    readonly id: string;
+    readonly callId: string;
+    readonly path: string;
+}
+/** The path a `present` call or a page acknowledgement names, as the server compares it (a leading `./` is the same file). */
+export declare const presentPath: (path: string) => string;
+/**
+ * The `present` calls still waiting for the page (the server's view-open record, `@hachej/boring-agent/artifacts`). Mirrors
+ * the preview's pending-call scan (the feedback plug-in's `pendingBrowserTasks`): a call with no result, in a conversation that is running.
+ */
+export declare function pendingPresents(view: {
+    readonly entries: readonly {
+        readonly id: number | bigint | string;
+        readonly model?: readonly unknown[] | undefined;
+    }[];
+    readonly docs?: Readonly<Record<string, unknown>>;
+} | undefined): readonly PendingPresent[];
+/** Strict shape check of an untrusted value. Returns a fresh copy or undefined. */
+export declare function parseArtifact(value: unknown): ArtifactDescriptor | undefined;
+/**
+ * The descriptor a successful tool result carries: the host's `detect` first, then the `artifact` key of a JSON text result.
+ * Failed results never produce one, and a host callback that throws or returns something malformed is ignored. Without
+ * the host's `detect`, only a result of `present` counts: any other tool whose text happens
+ * to be that JSON (an MCP tool, `cat x.json`) cannot forge a card. A host with renamed tools says so in `detect`.
+ */
+export declare function detectArtifact(call: ToolCall, result: ToolResultMessage, detect?: ArtifactDetect | undefined): ArtifactDescriptor | undefined;
+/** The title a still-running `present` call announces in its streamed arguments: the file name. */
+export declare function pendingTitle(call: ToolCall): string | undefined;
+/** What a still-running `present` call will show: the file path. */
+export declare function pendingId(call: ToolCall): string | undefined;
+/**
+ * Every artifact version a conversation's tool results produced, oldest first. Hosts use it to list the versions known
+ * from the conversation (a version switcher); the chat itself shows only the last version of an artifact per turn.
+ */
+export declare function collectArtifacts(view: ConversationView | undefined, detect?: ArtifactDetect | undefined): ArtifactDescriptor[];
+/** What the host's chat answer returns: the kind is all the presents bookkeeping reads. */
+export interface PresentAnswer {
+    readonly kind: string;
+}
+export interface PresentAcksHost {
+    /** The chat's `answer` (the transport's `?op=answer`); undefined when the host has none. */
+    readonly answer: (id: string, answer: string) => Promise<PresentAnswer> | undefined;
+    /** Open the file in the panel; false when the panel refuses (unsaved changes the person keeps). */
+    readonly open: (path: string) => boolean;
+    /** This page's identity in the acknowledgement. */
+    readonly instanceId: string;
+    /** Test seams: the wait between retries and the clock of the retry bound. Default: real timers. */
+    readonly wait?: (ms: number) => Promise<void>;
+    readonly now?: () => number;
+}
+/** The page's state of the presents it must answer, as `AgentWorkspace` reads it on each change. */
+export interface PresentContext {
+    /** The person closed the panel in this turn. */
+    readonly closedThisTurn: boolean;
+    /** The open file has unsaved edits. */
+    readonly unsaved: boolean;
+    /** The screen is a phone (the panel is a sheet and is not opened for an agent). */
+    readonly narrow: boolean;
+    /** `autoOpen`: when false the panel is not opened for an agent; the call waits for a manual open. */
+    readonly autoOpen: boolean;
+    /** Whether the panel already shows this file. */
+    readonly showing: (path: string) => boolean;
+}
+/**
+ * The page's side of the view-open acknowledgement. A `present` call is confirmed only by a viewer's mount report (`shown`) of the
+ * revision it names. A call is decided once; an answer the server denies (a revision the page showed before the agent wrote a new one)
+ * keeps the call waiting for the next mount report, and an answer is retried briefly while the server has not recorded the call yet.
+ */
+export declare function createPresentAcks(host: PresentAcksHost): {
+    /** A viewer mounted and shows `path` at `revision`: confirms the calls waiting for that file. */
+    shown(view: {
+        readonly path: string;
+        readonly revision: string;
+    }): void;
+    /** A viewer could not show `path` (a kind's `onFailed`, or its renderer threw): refuses the calls waiting for that file with `reason`. */
+    failed(view: {
+        readonly path: string;
+        readonly reason: string;
+    }): void;
+    /** A viewer stopped showing `path` at `revision` (it unmounted, or a custom viewer or the canvas took the file): it no longer confirms. */
+    hidden(view: {
+        readonly path: string;
+        readonly revision: string;
+    }): void;
+    /** The presents the server waits for: each is decided once, in order. Decided calls and waits that are no longer live are forgotten. */
+    consider(calls: readonly PendingPresent[], context: PresentContext): void;
+    /** Calls still waiting for a mount (test and debugging view). */
+    waiting: () => readonly string[];
+};
+/** What `createPresentAcks` returns. */
+export type PresentAcks = ReturnType<typeof createPresentAcks>;
+/**
+ * The artifact a tool call made, as the chat places it: a finished call that carries a descriptor (its own, or one the host's `detect`
+ * finds) is ready; a `present` call still running while its conversation runs (`running`) is presenting. Any other call has none.
+ */
+export declare function recogniseArtifact(call: ToolCall, result: ToolResultMessage | undefined, running: boolean, detect: ArtifactDetect | undefined): ChatArtifact | undefined;
+/** Every version, newest conversation result first. Ordinals can tie across retries and never determine recency. */
+export declare function artifactVersions(view: ConversationView | undefined, detect?: ArtifactDetect): ArtifactDescriptor[];
+/** Whether this descriptor is the newest known revision of its artifact, never an ordinal comparison. */
+export declare function follows(descriptor: ArtifactDescriptor, versions: readonly ArtifactDescriptor[]): boolean;
+/** The number of user messages in the current native view, used to retain a manual close until the next turn. */
+export declare function artifactTurn(view: ConversationView | undefined): number;
+//# sourceMappingURL=chat-artifacts.d.ts.map

package/dist/chat-artifacts.js

@@ -0,0 +1,274 @@
+/*
+ * Artifacts in the chat: substantial content (a document, an HTML page, an SVG, code, a canvas) that the transcript shows as a
+ * card and the host opens in its own panel. The descriptor and `parseArtifact` mirror `@hachej/boring-agent/artifacts` on purpose: the UI
+ * cannot import that package (it carries Pi runtime code). Keep the two validators in step;
+ * `test/contracts/pi-chat-source.test.mjs` checks that they accept and refuse the same values.
+ */
+export const ARTIFACT_TYPES = ['markdown', 'html', 'svg', 'code', 'canvas'];
+/** What identifies an artifact across its versions: its id, or for a presented file its path. */
+export const artifactKey = (artifact) => artifact.id ?? artifact.target.resource.path;
+export const PRESENT_TOOL = 'present';
+/** The path a `present` call or a page acknowledgement names, as the server compares it (a leading `./` is the same file). */
+export const presentPath = (path) => path.replace(/^\.\//, '');
+/**
+ * The `present` calls still waiting for the page (the server's view-open record, `@hachej/boring-agent/artifacts`). Mirrors
+ * the preview's pending-call scan (the feedback plug-in's `pendingBrowserTasks`): a call with no result, in a conversation that is running.
+ */
+export function pendingPresents(view) {
+    if (!view)
+        return [];
+    const live = view.docs?.['pi.live'];
+    if (!live?.run)
+        return [];
+    const calls = new Map();
+    for (const entry of view.entries)
+        for (const message of entry.model ?? []) {
+            const item = message;
+            if (item.role === 'assistant' && Array.isArray(item.content)) {
+                for (const part of item.content) {
+                    const path = part.arguments?.['path'];
+                    if (part.type === 'toolCall' && part.name === PRESENT_TOOL && typeof part.id === 'string' && typeof path === 'string') {
+                        calls.set(part.id, { id: JSON.stringify([Number(entry.id), part.id]), callId: part.id, path: presentPath(path) });
+                    }
+                }
+            }
+            if (item.role === 'toolResult' && typeof item.toolCallId === 'string')
+                calls.delete(item.toolCallId);
+        }
+    return [...calls.values()];
+}
+const ID = /^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/;
+const LANGUAGE = /^[A-Za-z0-9+#._-]{1,32}$/;
+const isObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+const hasOnly = (value, keys) => Object.keys(value).every(key => keys.includes(key));
+/** Strict shape check of an untrusted value. Returns a fresh copy or undefined. */
+export function parseArtifact(value) {
+    if (!isObject(value) || !hasOnly(value, ['schema', 'version', 'id', 'title', 'type', 'mediaType', 'language', 'target', 'revision', 'ordinal']))
+        return undefined;
+    const { id, title, type, mediaType, language, target, revision, ordinal } = value;
+    if (value['schema'] !== 'boring.artifact' || value['version'] !== 1)
+        return undefined;
+    if (id !== undefined && (typeof id !== 'string' || !ID.test(id)))
+        return undefined;
+    if (typeof title !== 'string' || !title.trim() || title.length > 200)
+        return undefined;
+    if (typeof type !== 'string' || !ARTIFACT_TYPES.includes(type))
+        return undefined;
+    if (typeof mediaType !== 'string' || !/^[a-z0-9][a-z0-9!#$&^_.+-]*\/[a-z0-9][a-z0-9!#$&^_.+-]*$/i.test(mediaType))
+        return undefined;
+    if (language !== undefined && (typeof language !== 'string' || !LANGUAGE.test(language)))
+        return undefined;
+    if (typeof revision !== 'string' || !revision || revision.length > 256)
+        return undefined;
+    if (ordinal !== undefined && (typeof ordinal !== 'number' || !Number.isSafeInteger(ordinal) || ordinal < 1))
+        return undefined;
+    if (!isObject(target) || !hasOnly(target, ['resource', 'view']) || !isObject(target['resource']) || !hasOnly(target['resource'], ['providerId', 'path']))
+        return undefined;
+    const { providerId, path } = target['resource'];
+    if (typeof providerId !== 'string' || !providerId || typeof path !== 'string' || !path || path.length > 512)
+        return undefined;
+    const view = target['view'];
+    if (!isObject(view))
+        return undefined;
+    let parsedView;
+    if (view['kind'] === 'published' && hasOnly(view, ['kind']))
+        parsedView = { kind: 'published' };
+    else if (view['kind'] === 'working' && hasOnly(view, ['kind', 'viewId']) && typeof view['viewId'] === 'string' && view['viewId'])
+        parsedView = { kind: 'working', viewId: view['viewId'] };
+    else
+        return undefined;
+    return { schema: 'boring.artifact', version: 1, ...(id === undefined ? {} : { id }), title, type: type, mediaType, ...(language === undefined ? {} : { language: language }),
+        target: { resource: { providerId, path }, view: parsedView }, revision, ...(ordinal === undefined ? {} : { ordinal }) };
+}
+const textOf = (result) => result.content.map(part => part.type === 'text' ? part.text : '').join('');
+/**
+ * The descriptor a successful tool result carries: the host's `detect` first, then the `artifact` key of a JSON text result.
+ * Failed results never produce one, and a host callback that throws or returns something malformed is ignored. Without
+ * the host's `detect`, only a result of `present` counts: any other tool whose text happens
+ * to be that JSON (an MCP tool, `cat x.json`) cannot forge a card. A host with renamed tools says so in `detect`.
+ */
+export function detectArtifact(call, result, detect) {
+    if (result.isError)
+        return undefined;
+    if (detect) {
+        try {
+            const found = parseArtifact(detect(call, result));
+            if (found)
+                return found;
+        }
+        catch { /* a faulty host callback shows no card */ }
+    }
+    if (call.name !== PRESENT_TOOL)
+        return undefined;
+    const text = textOf(result);
+    if (!text.includes('"boring.artifact"'))
+        return undefined;
+    try {
+        const value = JSON.parse(text);
+        return isObject(value) ? parseArtifact(value['artifact']) : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The title a still-running `present` call announces in its streamed arguments: the file name. */
+export function pendingTitle(call) {
+    const path = call.arguments['path'];
+    const title = typeof path === 'string' ? path.slice(path.lastIndexOf('/') + 1) : undefined;
+    return title?.trim() ? title.trim().slice(0, 200) : undefined;
+}
+/** What a still-running `present` call will show: the file path. */
+export function pendingId(call) {
+    const path = call.arguments['path'];
+    return typeof path === 'string' && path ? path.replace(/^(\.\/)+/, '') : undefined;
+}
+/**
+ * Every artifact version a conversation's tool results produced, oldest first. Hosts use it to list the versions known
+ * from the conversation (a version switcher); the chat itself shows only the last version of an artifact per turn.
+ */
+export function collectArtifacts(view, detect) {
+    const calls = new Map(), found = [];
+    for (const entry of view?.entries ?? [])
+        for (const message of entry.model ?? []) {
+            if (message.role === 'assistant')
+                for (const part of message.content) {
+                    if (part.type === 'toolCall')
+                        calls.set(part.id, part);
+                }
+            else if (message.role === 'toolResult') {
+                const call = calls.get(message.toolCallId);
+                const descriptor = call && detectArtifact(call, message, detect);
+                if (descriptor)
+                    found.push(descriptor);
+            }
+        }
+    return found;
+}
+/**
+ * The page's side of the view-open acknowledgement. A `present` call is confirmed only by a viewer's mount report (`shown`) of the
+ * revision it names. A call is decided once; an answer the server denies (a revision the page showed before the agent wrote a new one)
+ * keeps the call waiting for the next mount report, and an answer is retried briefly while the server has not recorded the call yet.
+ */
+export function createPresentAcks(host) {
+    const decided = new Set();
+    /** Calls waiting for their file's mount report: answer ID to path. */
+    const mounting = new Map();
+    const wait = host.wait ?? (ms => new Promise(resolve => setTimeout(resolve, ms)));
+    const now = host.now ?? (() => Date.now());
+    /** The last mount report: the file on screen and its revision. */
+    let lastShown;
+    /** Sends one answer; returns the server's outcome kind, or undefined when it was not sent. Retries while the record is not written yet. */
+    async function send(id, body) {
+        const until = now() + 3000;
+        for (;;) {
+            try {
+                const sent = host.answer(id, JSON.stringify(body));
+                if (sent === undefined)
+                    return undefined;
+                const outcome = await sent;
+                if (outcome.kind !== 'unknown-question' || now() > until)
+                    return outcome.kind;
+            }
+            catch {
+                return undefined; /* the call ends at its deadline as unconfirmed */
+            }
+            await wait(20);
+        }
+    }
+    /** Confirms a shown revision. The call keeps its entry while the answer is in flight, so a mount during the flight still confirms it. */
+    async function confirm(id, path, revision) {
+        const kind = await send(id, { kind: 'opened', instanceId: host.instanceId, path, revision });
+        // Only an accepted or conflicting answer ends the call. A denial (another revision), a failed request or an unrecorded call keeps it waiting for a later mount or a live-call check.
+        if (kind === 'answered' || kind === 'conflict')
+            mounting.delete(id);
+    }
+    /** Refuses a waiting call; like `confirm`, only an accepted or conflicting answer ends it. */
+    async function refuse(id, reason) {
+        const kind = await send(id, { kind: 'refused', reason });
+        if (kind === 'answered' || kind === 'conflict')
+            mounting.delete(id);
+    }
+    return {
+        /** A viewer mounted and shows `path` at `revision`: confirms the calls waiting for that file. */
+        shown(view) {
+            for (const [id, path] of mounting)
+                if (path === view.path)
+                    void confirm(id, path, view.revision);
+            lastShown = view;
+        },
+        /** A viewer could not show `path` (a kind's `onFailed`, or its renderer threw): refuses the calls waiting for that file with `reason`. */
+        failed(view) {
+            if (lastShown?.path === view.path)
+                lastShown = undefined;
+            const reason = view.reason.trim().slice(0, 200) || 'the view failed';
+            for (const [id, path] of mounting)
+                if (path === view.path)
+                    void refuse(id, reason);
+        },
+        /** A viewer stopped showing `path` at `revision` (it unmounted, or a custom viewer or the canvas took the file): it no longer confirms. */
+        hidden(view) {
+            if (lastShown?.path === view.path && lastShown.revision === view.revision)
+                lastShown = undefined;
+        },
+        /** The presents the server waits for: each is decided once, in order. Decided calls and waits that are no longer live are forgotten. */
+        consider(calls, context) {
+            const live = new Set(calls.map(call => call.id));
+            for (const id of decided)
+                if (!live.has(id))
+                    decided.delete(id);
+            for (const id of mounting.keys())
+                if (!live.has(id))
+                    mounting.delete(id);
+            for (const call of calls) {
+                if (decided.has(call.id))
+                    continue;
+                decided.add(call.id);
+                if (context.closedThisTurn)
+                    void send(call.id, { kind: 'refused', reason: 'closed by user' });
+                else if (context.unsaved)
+                    void send(call.id, { kind: 'refused', reason: 'unsaved changes' });
+                else if (context.narrow)
+                    void send(call.id, { kind: 'refused', reason: 'narrow screen' });
+                else {
+                    mounting.set(call.id, call.path);
+                    if (lastShown?.path === call.path && context.showing(call.path))
+                        void confirm(call.id, call.path, lastShown.revision);
+                    else if (context.autoOpen && !host.open(call.path)) {
+                        mounting.delete(call.id);
+                        void send(call.id, { kind: 'refused', reason: 'unsaved changes' });
+                    }
+                }
+            }
+        },
+        /** Calls still waiting for a mount (test and debugging view). */
+        waiting: () => [...mounting.keys()],
+    };
+}
+/**
+ * The artifact a tool call made, as the chat places it: a finished call that carries a descriptor (its own, or one the host's `detect`
+ * finds) is ready; a `present` call still running while its conversation runs (`running`) is presenting. Any other call has none.
+ */
+export function recogniseArtifact(call, result, running, detect) {
+    if (result) {
+        const artifact = detectArtifact(call, result, detect);
+        if (!artifact)
+            return undefined;
+        // A tool whose own result carries the descriptor is replaced by its card; a host-detected card is shown in addition to the step.
+        return { state: 'ready', id: artifactKey(artifact), title: artifact.title, path: artifact.target.resource.path, own: detectArtifact(call, result) !== undefined, descriptor: artifact };
+    }
+    if (running && call.name === PRESENT_TOOL)
+        return { state: 'presenting', id: pendingId(call), title: pendingTitle(call), path: undefined, own: true, descriptor: undefined };
+    return undefined;
+}
+/** Every version, newest conversation result first. Ordinals can tie across retries and never determine recency. */
+export function artifactVersions(view, detect) {
+    return collectArtifacts(view, detect).reverse();
+}
+/** Whether this descriptor is the newest known revision of its artifact, never an ordinal comparison. */
+export function follows(descriptor, versions) {
+    return descriptor.revision === versions.find(version => artifactKey(version) === artifactKey(descriptor))?.revision;
+}
+/** The number of user messages in the current native view, used to retain a manual close until the next turn. */
+export function artifactTurn(view) {
+    return (view?.entries ?? []).reduce((count, entry) => count + (entry.model ?? []).filter(message => message.role === 'user').length, 0);
+}

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 };
+}