@hachej/boring-ui-kit 0.4.24 → 0.4.26

package/README.md

@@ -80,9 +80,11 @@ 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.
+
+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 +148,28 @@ 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`.
+
+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; session send/upload/model logic remains in the registry pending its own extraction.
+
+
 ### 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/bin/boring-ui-blocks.mjs

@@ -4,14 +4,14 @@
 //
 //   npx boring-ui-blocks check [--design <dir>...] [--manifest <path>] [--cwd <app web dir>] [--json]
 //   npx boring-ui-blocks update [--version <v>] [--registry <url>] [--dry-run] [--manifest <path>] [--cwd <dir>]
-//   npx boring-ui-blocks add <shadcn add arguments...> [--manifest <path>] [--cwd <dir>]
+//   npx boring-ui-blocks add <shadcn add arguments...> [--overwrite] [--manifest <path>] [--cwd <dir>]
 //   npx boring-ui-blocks manifest [--manifest <path>] [--cwd <dir>]
 //   npx boring-ui-blocks help    (also --help: the usage and which items to add; exit 0)
 //
 // `check` writes nothing. `add`, `update` and `manifest` write the shadcn files they install and the manifest, nothing else.
 import { createHash } from 'node:crypto';
-import { existsSync, readFileSync, readdirSync, realpathSync, writeFileSync } from 'node:fs';
-import { join, relative, resolve, sep } from 'node:path';
+import { existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, writeFileSync } from 'node:fs';
+import { dirname, join, relative, resolve, sep } from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 
@@ -158,12 +158,24 @@ export function checkBlocks(app, components = appPaths(app).components) {
 /** The generated shadcn files under the `ui` alias (`.js/.jsx/.ts/.tsx/.css`) and their sha256, by path relative to it. */
 const uiHashes = ui => new Map(files(ui).filter(path => /\.(?:[jt]sx?|css)$/.test(path)).map(path => [posix(relative(ui, path)), { path, hash: sha256(path) }]));
 
+/** Records the given generated ui files in the manifest (`add` after a kept file: only what it created). Other entries and keys are kept. */
+export function recordFiles(app, paths, manifest = MANIFEST) {
+  const { ui } = appPaths(app);
+  const path = resolve(app, manifest);
+  const kept = existsSync(path) ? JSON.parse(readFileSync(path, 'utf8')) : { generatedBy: 'boring-ui-blocks', dir: posix(relative(app, ui)) };
+  const hashes = { ...kept.files };
+  for (const file of paths) hashes[posix(relative(ui, file))] = sha256(file);
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, `${JSON.stringify({ ...kept, files: Object.fromEntries(Object.entries(hashes).sort(([a], [b]) => a.localeCompare(b))) }, null, 2)}\n`);
+}
+
 /** (Re)writes the manifest (`manifest`, default SHADCN-GENERATED.json next to components.json): `files` is replaced, other keys are kept. */
 export function writeManifest(app, manifest = MANIFEST) {
   const { ui } = appPaths(app);
   const path = resolve(app, manifest);
   const hashes = Object.fromEntries([...uiHashes(ui)].map(([name, { hash }]) => [name, hash]));
   const kept = existsSync(path) ? JSON.parse(readFileSync(path, 'utf8')) : { generatedBy: 'boring-ui-blocks', dir: posix(relative(app, ui)) };
+  mkdirSync(dirname(path), { recursive: true });
   writeFileSync(path, `${JSON.stringify({ ...kept, files: hashes }, null, 2)}\n`);
   return Object.keys(hashes).length;
 }
@@ -215,18 +227,20 @@ export function check(app, design = [], manifest = MANIFEST) {
   return { version, blocks: blocks.map(block => block.name), violations };
 }
 
-const USAGE = `usage: boring-ui-blocks check [--design <dir>...] [--manifest <path>] [--cwd <dir>] [--json] | update [--version <v>] [--registry <url>] [--dry-run] [--manifest <path>] [--cwd <dir>] | add <shadcn add args...> [--manifest <path>] [--cwd <dir>] | manifest [--manifest <path>] [--cwd <dir>] | help\n\n` +
+const USAGE = `usage: boring-ui-blocks check [--design <dir>...] [--manifest <path>] [--cwd <dir>] [--json] | update [--version <v>] [--registry <url>] [--dry-run] [--manifest <path>] [--cwd <dir>] | add <shadcn add args...> [--overwrite] [--manifest <path>] [--cwd <dir>] | manifest [--manifest <path>] [--cwd <dir>] | help\n\n` +
   'Blocks: pi-app is the whole agent app with every chat feature and viewer. pi-chat is the core chat only: add pi-chat-plugins for every ' +
   'feature, or one of pi-chat-markdown, pi-chat-slash, pi-chat-mentions, pi-chat-pickers, pi-chat-voice, pi-chat-attachments, ' +
   'pi-chat-question, pi-chat-approval, pi-chat-subagent and pi-artifacts. Viewers are viewer-frame plus viewer-markdown, viewer-html, ' +
   'viewer-image, viewer-pdf and viewer-code, loaded by kind. update reinstalls only installed items: ' +
-  'add the new ones an app uses once (registry/README.md, "From one item to small items").';
-const FLAGS = { check: ['design', 'manifest', 'json'], update: ['version', 'registry', 'dry-run', 'manifest'], manifest: ['manifest'] };
+  'add the new ones an app uses once (registry/README.md, "From one item to small items"). add never prompts: a file that already exists ' +
+  'with other content is kept and listed (exit 1) unless --overwrite replaces it; identical files are left alone.';
+const FLAGS = { check: ['design', 'manifest', 'json'], update: ['version', 'registry', 'dry-run', 'manifest'], manifest: ['manifest'], add: ['manifest', 'overwrite'] };
 
 function parse(command, rest) {
   const flags = { design: [], pass: [] };
   for (let i = 0; i < rest.length; i++) {
     const name = rest[i].startsWith('--') ? rest[i].slice(2) : null;
+    if (command === 'add' && (name === 'overwrite' || rest[i] === '-o')) { flags.overwrite = true; continue; }
     if (command === 'add' && name !== 'cwd' && name !== 'manifest') { flags.pass.push(rest[i]); continue; }
     if (!name || !FLAGS[command]?.includes(name) && name !== 'cwd') throw new Error(`unknown argument ${rest[i]}`);
     if (name === 'json') flags.json = true;
@@ -267,13 +281,30 @@ function restoreSpecifiers(before, app, log) {
   if (restored.size) log(`kept the version specifiers of ${[...restored].sort().join(', ')} (the CLI had rewritten them)`);
 }
 
-function shadcnAdd(app, args, log) {
-  const argv = ['-y', SHADCN, 'add', ...args];
+/** The files the shadcn CLI may write for a block (the components, ui, lib and hooks aliases) and their bytes, before it runs. */
+function snapshotFiles(app) {
+  const { aliases = {} } = readJson(join(app, 'components.json')) ?? {};
+  const alias = (name, fallback) => join(app, existsSync(join(app, 'src')) ? 'src' : '', (aliases[name] ?? fallback).replace(/^[@~]\//, ''));
+  const { components, ui } = appPaths(app);
+  return new Map([...new Set([components, ui, alias('lib', '@/lib'), alias('hooks', '@/hooks')])].flatMap(dir => files(dir)).map(path => [path, readFileSync(path)]));
+}
+
+/**
+ * Runs the shadcn CLI without a terminal: stdin is closed and the CLI always gets `--overwrite --yes`, so it never asks. With
+ * `overwrite` false a file that existed with other content is put back afterwards and returned in `skipped`; identical files are never touched.
+ * `created` is the generated ui files the run newly wrote.
+ */
+function shadcnAdd(app, args, log, overwrite) {
+  const argv = ['-y', SHADCN, 'add', ...args.filter(arg => !['--yes', '-y', '--overwrite'].includes(arg)), '--overwrite', '--yes'];
   log(`npx ${argv.join(' ')}`);
-  const before = specifiers(app);
-  const result = spawnSync('npx', argv, { cwd: app, stdio: 'inherit', shell: process.platform === 'win32' });
+  const before = specifiers(app), existing = snapshotFiles(app);
+  const result = spawnSync('npx', argv, { cwd: app, stdio: ['ignore', 'inherit', 'inherit'], shell: process.platform === 'win32' });
   restoreSpecifiers(before, app, log);
-  return result.status ?? 1;
+  const skipped = overwrite ? [] : [...existing].filter(([path, bytes]) => existsSync(path) && !readFileSync(path).equals(bytes));
+  for (const [path, bytes] of skipped) writeFileSync(path, bytes);
+  const { ui } = appPaths(app);
+  const created = files(ui).filter(path => /\.(?:[jt]sx?|css)$/.test(path) && !existing.has(path));
+  return { status: result.status ?? 1, skipped: skipped.map(([path]) => path), created };
 }
 
 const line = v => `${v.check} ${v.rule} ${v.file}${v.line ? `:${v.line}:${v.column}` : ''} ${v.detail}`;
@@ -300,7 +331,13 @@ export function main(argv, cwd = process.cwd(), log = console.log, error = conso
     if (command === 'add') {
       appPaths(app);
       if (!flags.pass.length) throw new Error('add needs shadcn add arguments');
-      const status = shadcnAdd(app, flags.pass, log);
+      const { status, skipped, created } = shadcnAdd(app, flags.pass, log, flags.overwrite);
+      if (skipped.length) {
+        // The files the run created are the app's new generated files: record them, so `check` does not call them unknown. The kept ones stay unrecorded.
+        if (created.length) recordFiles(app, created, flags.manifest ?? MANIFEST);
+        error(`kept ${skipped.length} existing file(s) that differ from the registry (pass --overwrite to replace them; only the files add created were recorded in the manifest):\n${skipped.map(path => `  ${posix(relative(app, path))}`).join('\n')}`);
+        return status || 1;
+      }
       if (status === 0) log(`${flags.manifest ?? MANIFEST}: ${writeManifest(app, flags.manifest)} file(s)`);
       return status;
     }
@@ -309,7 +346,7 @@ export function main(argv, cwd = process.cwd(), log = console.log, error = conso
     const base = (flags.registry ?? itemBase(flags.version ?? installed)).replace(/\/$/, '');
     const items = blocks.map(block => `${base}/${block.name}.json`);
     if (flags.dryRun) { log(`npx -y ${SHADCN} add ${items.join(' ')} --overwrite --yes`); return 0; }
-    const status = shadcnAdd(app, [...items, '--overwrite', '--yes'], log);
+    const { status } = shadcnAdd(app, items, log, true);
     if (status === 0) log(`${flags.manifest ?? MANIFEST}: ${writeManifest(app, flags.manifest)} file(s)`);
     return status;
   } catch (cause) {

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