@hachej/boring-ui-kit 0.4.1 → 0.4.2

package/r/pi-chat.json

@@ -4,8 +4,8 @@
   "title": "Pi chat",
   "description": "A complete Tailwind chat over the borrowed native chat controller: composer, messages, one collapsible activity block per turn (tool calls and reasoning), message queue, history, a human-in-the-loop question card, an Approve / Deny card for host tools wrapped with requireApproval optional artifact cards that open generated content in the host's panel, and feedback cards for the opt-in feedback tool (lists, and Show offers that the host page resolves). Chat only: no layout. Owned, editable source; no AI SDK. The optional pi-ambient and pi-workspace blocks build on it.",
   "dependencies": [
-    "@hachej/boring-ui-kit@^0.4.1",
-    "@hachej/boring-files@^0.4.1",
+    "@hachej/boring-ui-kit@^0.4.2",
+    "@hachej/boring-files@^0.4.2",
     "react@^19.0.0",
     "react-dom@^19.0.0",
     "marked@^17.0.6",
@@ -19,8 +19,8 @@
     "@shadcn/react@0.3.1"
   ],
   "registryDependencies": [
-    "https://cdn.jsdelivr.net/npm/@hachej/boring-ui-kit@0.4.1/r/utils.json",
-    "https://cdn.jsdelivr.net/npm/@hachej/boring-ui-kit@0.4.1/r/button.json",
+    "https://cdn.jsdelivr.net/npm/@hachej/boring-ui-kit@0.4.2/r/utils.json",
+    "https://cdn.jsdelivr.net/npm/@hachej/boring-ui-kit@0.4.2/r/button.json",
     "trace",
     "message",
     "message-scroller",
@@ -71,7 +71,7 @@
     },
     {
       "path": "registry/pi-chat/artifact.ts",
-      "content": "import type { ConversationView } from '@earendil-works/pi-durable';\nimport type { ToolCall, ToolResultMessage } from '@earendil-works/pi-ai';\nimport type { ComponentType, ReactNode } from 'react';\n\n/*\n * Artifacts in the chat: substantial content (a document, an HTML page, an SVG, code, a canvas) that the transcript shows as a\n * card and the host opens in its own panel. The descriptor and `parseArtifact` mirror `@hachej/boring-agent/artifacts` on purpose: this\n * is a copied registry item and cannot import that package (it carries Pi runtime code). Keep the two validators in step;\n * `test/contracts/pi-chat-source.test.mjs` checks that they accept and refuse the same values.\n */\nexport const ARTIFACT_TYPES = ['markdown', 'html', 'svg', 'code', 'canvas'] as const;\nexport type ArtifactType = typeof ARTIFACT_TYPES[number];\n\n/** Structural twin of the `ResourceLocator` in `@hachej/boring-files`. */\nexport interface ArtifactTarget {\n  readonly resource: { readonly providerId: string; readonly path: string };\n  readonly view: { readonly kind: 'published' } | { readonly kind: 'working'; readonly viewId: string };\n}\nexport interface ArtifactDescriptor {\n  readonly schema: 'boring.artifact';\n  readonly version: 1;\n  /** Set by the artifact tools; the descriptor of `present` has none (the file path is its identity). */\n  readonly id?: string;\n  readonly title: string;\n  readonly type: ArtifactType;\n  readonly mediaType: string;\n  readonly language?: string;\n  readonly target: ArtifactTarget;\n  /** The revision this message produced. */\n  readonly revision: string;\n  /** The 1-based version number of this artifact (artifact tools only). */\n  readonly ordinal?: number;\n}\n\n/** What identifies an artifact across its versions: its id, or for a presented file its path. */\nexport const artifactKey = (artifact: Pick<ArtifactDescriptor, 'id' | 'target'>): string => artifact.id ?? artifact.target.resource.path;\n\n/** What an artifact kind's renderer receives: the artifact and its text at the revision shown. */\nexport interface ArtifactKindViewProps { readonly artifact: ArtifactDescriptor; readonly text: string }\n\n/**\n * An app's own kind of artifact (for example `.maquette.json` files): how its card and the panel name it, its icon, and optionally\n * how the panel draws it. Kinds are consulted in order before the built-in types; the first whose `match` is true wins. A kind\n * adds a presentation only: the descriptor, its type and how it is read are unchanged.\n */\nexport interface ArtifactKind {\n  /** True for the artifacts of this kind, for example `target => target.resource.path.endsWith('.maquette.json')`. */\n  readonly match: (target: ArtifactTarget, artifact: ArtifactDescriptor) => boolean;\n  /** The kind's name on the card and in the panel bar (\"Maquette\"). */\n  readonly label: string;\n  /** The card's icon (any component taking `className`, such as a lucide icon). The type's icon otherwise. */\n  readonly icon?: ComponentType<{ readonly className?: string; readonly 'aria-hidden'?: boolean | 'true' }> | undefined;\n  /** Draws the artifact in the panel (`AgentWorkspace`, `ArtifactPanel`) inside the standard viewer bar, with copy and download. */\n  readonly renderer?: ((props: ArtifactKindViewProps) => ReactNode) | undefined;\n}\n\n/** The first kind that matches the artifact; a `match` that throws counts as no match. */\nexport function artifactKind(artifact: ArtifactDescriptor, kinds: readonly ArtifactKind[] | undefined): ArtifactKind | undefined {\n  return kinds?.find(kind => { try { return kind.match(artifact.target, artifact); } catch { return false; } });\n}\n\n/** What the host passes to `PiChat` to turn artifact tool results into cards. */\nexport interface ArtifactsConfig {\n  /** The app's own artifact kinds (label, icon, renderer), consulted before the built-in types. */\n  readonly kinds?: readonly ArtifactKind[] | undefined;\n  /** The person clicked a card: show this artifact (and revision) in the host's panel. */\n  readonly open: (artifact: ArtifactDescriptor) => void;\n  /** True for the card whose artifact version is on display. */\n  readonly isOpen?: (artifact: ArtifactDescriptor) => boolean;\n  /** Recognise a descriptor in a successful tool result that does not carry one itself (for example a document save). */\n  readonly detect?: (call: ToolCall, result: ToolResultMessage) => ArtifactDescriptor | undefined;\n}\n\nexport const PRESENT_TOOL = 'present';\n\n/** A `present` call with no result yet, while its conversation runs: its answer ID (`[assistantEntryId, callId]`) and the path it names. */\nexport interface PendingPresent { readonly id: string; readonly callId: string; readonly path: string }\n\n/** The path a `present` call or a page acknowledgement names, as the server compares it (a leading `./` is the same file). */\nexport const presentPath = (path: string): string => path.replace(/^\\.\\//, '');\n\n/**\n * The `present` calls still waiting for the page (the server's view-open record, `@hachej/boring-agent/artifacts`). Mirrors\n * the preview's pending-call scan (the feedback plug-in's `pendingBrowserTasks`): a call with no result, in a conversation that is running.\n */\nexport 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[] {\n  if (!view) return [];\n  const live = view.docs?.['pi.live'] as { readonly run?: unknown } | undefined;\n  if (!live?.run) return [];\n  const calls = new Map<string, PendingPresent>();\n  for (const entry of view.entries) for (const message of entry.model ?? []) {\n    const item = message as { readonly role?: string; readonly content?: unknown; readonly toolCallId?: string };\n    if (item.role === 'assistant' && Array.isArray(item.content)) {\n      for (const part of item.content as { type?: string; id?: string; name?: string; arguments?: Record<string, unknown> }[]) {\n        const path = part.arguments?.['path'];\n        if (part.type === 'toolCall' && part.name === PRESENT_TOOL && typeof part.id === 'string' && typeof path === 'string') {\n          calls.set(part.id, { id: JSON.stringify([Number(entry.id), part.id]), callId: part.id, path: presentPath(path) });\n        }\n      }\n    }\n    if (item.role === 'toolResult' && typeof item.toolCallId === 'string') calls.delete(item.toolCallId);\n  }\n  return [...calls.values()];\n}\n\nconst ID = /^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/;\nconst LANGUAGE = /^[A-Za-z0-9+#._-]{1,32}$/;\nconst isObject = (value: unknown): value is Record<string, unknown> => value !== null && typeof value === 'object' && !Array.isArray(value);\nconst hasOnly = (value: Record<string, unknown>, keys: readonly string[]) => Object.keys(value).every(key => keys.includes(key));\n\n/** Strict shape check of an untrusted value. Returns a fresh copy or undefined. */\nexport function parseArtifact(value: unknown): ArtifactDescriptor | undefined {\n  if (!isObject(value) || !hasOnly(value, ['schema', 'version', 'id', 'title', 'type', 'mediaType', 'language', 'target', 'revision', 'ordinal'])) return undefined;\n  const { id, title, type, mediaType, language, target, revision, ordinal } = value;\n  if (value['schema'] !== 'boring.artifact' || value['version'] !== 1) return undefined;\n  if (id !== undefined && (typeof id !== 'string' || !ID.test(id))) return undefined;\n  if (typeof title !== 'string' || !title.trim() || title.length > 200) return undefined;\n  if (typeof type !== 'string' || !(ARTIFACT_TYPES as readonly string[]).includes(type)) return undefined;\n  if (typeof mediaType !== 'string' || !/^[a-z0-9][a-z0-9!#$&^_.+-]*\\/[a-z0-9][a-z0-9!#$&^_.+-]*$/i.test(mediaType)) return undefined;\n  if (language !== undefined && (typeof language !== 'string' || !LANGUAGE.test(language))) return undefined;\n  if (typeof revision !== 'string' || !revision || revision.length > 256) return undefined;\n  if (ordinal !== undefined && (typeof ordinal !== 'number' || !Number.isSafeInteger(ordinal) || ordinal < 1)) return undefined;\n  if (!isObject(target) || !hasOnly(target, ['resource', 'view']) || !isObject(target['resource']) || !hasOnly(target['resource'], ['providerId', 'path'])) return undefined;\n  const { providerId, path } = target['resource'];\n  if (typeof providerId !== 'string' || !providerId || typeof path !== 'string' || !path || path.length > 512) return undefined;\n  const view = target['view'];\n  if (!isObject(view)) return undefined;\n  let parsedView: ArtifactTarget['view'];\n  if (view['kind'] === 'published' && hasOnly(view, ['kind'])) parsedView = { kind: 'published' };\n  else if (view['kind'] === 'working' && hasOnly(view, ['kind', 'viewId']) && typeof view['viewId'] === 'string' && view['viewId']) parsedView = { kind: 'working', viewId: view['viewId'] };\n  else return undefined;\n  return { schema: 'boring.artifact', version: 1, ...(id === undefined ? {} : { id }), title, type: type as ArtifactType, mediaType, ...(language === undefined ? {} : { language: language as string }),\n    target: { resource: { providerId, path }, view: parsedView }, revision, ...(ordinal === undefined ? {} : { ordinal }) };\n}\n\nconst TYPE_LABEL: Record<ArtifactType, string> = { markdown: 'Document', html: 'HTML page', svg: 'SVG image', code: 'Code', canvas: 'Canvas' };\n/** The artifact's type name: the matching kind's label first, then the built-in name of its type. */\nexport function typeLabel(artifact: ArtifactDescriptor, kinds?: readonly ArtifactKind[]): string {\n  const kind = artifactKind(artifact, kinds);\n  if (kind) return kind.label;\n  return artifact.type === 'code' && artifact.language ? `Code · ${artifact.language}` : TYPE_LABEL[artifact.type];\n}\n\nconst textOf = (result: ToolResultMessage): string => result.content.map(part => part.type === 'text' ? part.text : '').join('');\n\n/**\n * The descriptor a successful tool result carries: the host's `detect` first, then the `artifact` key of a JSON text result.\n * Failed results never produce one, and a host callback that throws or returns something malformed is ignored. Without\n * the host's `detect`, only a result of `present` counts: any other tool whose text happens\n * to be that JSON (an MCP tool, `cat x.json`) cannot forge a card. A host with renamed tools says so in `detect`.\n */\nexport function detectArtifact(call: ToolCall, result: ToolResultMessage, detect?: ArtifactsConfig['detect']): ArtifactDescriptor | undefined {\n  if (result.isError) return undefined;\n  if (detect) {\n    try { const found = parseArtifact(detect(call, result)); if (found) return found; } catch { /* a faulty host callback shows no card */ }\n  }\n  if (call.name !== PRESENT_TOOL) return undefined;\n  const text = textOf(result);\n  if (!text.includes('\"boring.artifact\"')) return undefined;\n  try {\n    const value: unknown = JSON.parse(text);\n    return isObject(value) ? parseArtifact(value['artifact']) : undefined;\n  } catch { return undefined; }\n}\n\n/** The title a still-running `present` call announces in its streamed arguments: the file name. */\nexport function pendingTitle(call: ToolCall): string | undefined {\n  const path = (call.arguments as Record<string, unknown>)['path'];\n  const title = typeof path === 'string' ? path.slice(path.lastIndexOf('/') + 1) : undefined;\n  return title?.trim() ? title.trim().slice(0, 200) : undefined;\n}\n/** What a still-running `present` call will show: the file path. */\nexport function pendingId(call: ToolCall): string | undefined {\n  const path = (call.arguments as Record<string, unknown>)['path'];\n  return typeof path === 'string' && path ? path.replace(/^(\\.\\/)+/, '') : undefined;\n}\n\n/**\n * Every artifact version a conversation's tool results produced, oldest first. Hosts use it to list the versions known\n * from the conversation (a version switcher); the chat itself shows only the last version of an artifact per turn.\n */\nexport function collectArtifacts(view: ConversationView | undefined, detect?: ArtifactsConfig['detect']): ArtifactDescriptor[] {\n  const calls = new Map<string, ToolCall>(), found: ArtifactDescriptor[] = [];\n  for (const entry of view?.entries ?? []) for (const message of entry.model ?? []) {\n    if (message.role === 'assistant') for (const part of message.content) { if (part.type === 'toolCall') calls.set(part.id, part); }\n    else if (message.role === 'toolResult') {\n      const call = calls.get(message.toolCallId);\n      const descriptor = call && detectArtifact(call, message, detect);\n      if (descriptor) found.push(descriptor);\n    }\n  }\n  return found;\n}\n\n/** What the host's chat answer returns: the kind is all the presents bookkeeping reads. */\nexport interface PresentAnswer { readonly kind: string }\n\nexport interface PresentAcksHost {\n  /** The chat's `answer` (the transport's `?op=answer`); undefined when the host has none. */\n  readonly answer: (id: string, answer: string) => Promise<PresentAnswer> | undefined;\n  /** Open the file in the panel; false when the panel refuses (unsaved changes the person keeps). */\n  readonly open: (path: string) => boolean;\n  /** This page's identity in the acknowledgement. */\n  readonly instanceId: string;\n  /** Test seams: the wait between retries and the clock of the retry bound. Default: real timers. */\n  readonly wait?: (ms: number) => Promise<void>;\n  readonly now?: () => number;\n}\n\n/** The page's state of the presents it must answer, as `AgentWorkspace` reads it on each change. */\nexport interface PresentContext {\n  /** The person closed the panel in this turn. */\n  readonly closedThisTurn: boolean;\n  /** The open file has unsaved edits. */\n  readonly unsaved: boolean;\n  /** The screen is a phone (the panel is a sheet and is not opened for an agent). */\n  readonly narrow: boolean;\n  /** `autoOpen`: when false the panel is not opened for an agent; the call waits for a manual open. */\n  readonly autoOpen: boolean;\n  /** Whether the panel already shows this file. */\n  readonly showing: (path: string) => boolean;\n}\n\n/**\n * The page's side of the view-open acknowledgement. A `present` call is confirmed only by a viewer's mount report (`shown`) of the\n * 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)\n * keeps the call waiting for the next mount report, and an answer is retried briefly while the server has not recorded the call yet.\n */\nexport function createPresentAcks(host: PresentAcksHost) {\n  const decided = new Set<string>();\n  /** Calls waiting for their file's mount report: answer ID to path. */\n  const mounting = new Map<string, string>();\n  const wait = host.wait ?? (ms => new Promise<void>(resolve => setTimeout(resolve, ms)));\n  const now = host.now ?? (() => Date.now());\n  /** The last mount report: the file on screen and its revision. */\n  let lastShown: { readonly path: string; readonly revision: string } | undefined;\n\n  /** Sends one answer; returns the server's outcome kind, or undefined when it was not sent. Retries while the record is not written yet. */\n  async function send(id: string, body: Record<string, string>): Promise<string | undefined> {\n    const until = now() + 3000;\n    for (;;) {\n      try {\n        const sent = host.answer(id, JSON.stringify(body));\n        if (sent === undefined) return undefined;\n        const outcome = await sent;\n        if (outcome.kind !== 'unknown-question' || now() > until) return outcome.kind;\n      } catch { return undefined; /* the call ends at its deadline as unconfirmed */ }\n      await wait(20);\n    }\n  }\n  /** Confirms a shown revision. The call keeps its entry while the answer is in flight, so a mount during the flight still confirms it. */\n  async function confirm(id: string, path: string, revision: string): Promise<void> {\n    const kind = await send(id, { kind: 'opened', instanceId: host.instanceId, path, revision });\n    // 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.\n    if (kind === 'answered' || kind === 'conflict') mounting.delete(id);\n  }\n\n  return {\n    /** A viewer mounted and shows `path` at `revision`: confirms the calls waiting for that file. */\n    shown(view: { readonly path: string; readonly revision: string }): void {\n      for (const [id, path] of mounting) if (path === view.path) void confirm(id, path, view.revision);\n      lastShown = view;\n    },\n    /** A viewer stopped showing `path` at `revision` (it unmounted, or a custom viewer or the canvas took the file): it no longer confirms. */\n    hidden(view: { readonly path: string; readonly revision: string }): void {\n      if (lastShown?.path === view.path && lastShown.revision === view.revision) lastShown = undefined;\n    },\n    /** The presents the server waits for: each is decided once, in order. Decided calls and waits that are no longer live are forgotten. */\n    consider(calls: readonly PendingPresent[], context: PresentContext): void {\n      const live = new Set(calls.map(call => call.id));\n      for (const id of decided) if (!live.has(id)) decided.delete(id);\n      for (const id of mounting.keys()) if (!live.has(id)) mounting.delete(id);\n      for (const call of calls) {\n        if (decided.has(call.id)) continue;\n        decided.add(call.id);\n        if (context.closedThisTurn) void send(call.id, { kind: 'refused', reason: 'closed by user' });\n        else if (context.unsaved) void send(call.id, { kind: 'refused', reason: 'unsaved changes' });\n        else if (context.narrow) void send(call.id, { kind: 'refused', reason: 'narrow screen' });\n        else {\n          mounting.set(call.id, call.path);\n          if (lastShown?.path === call.path && context.showing(call.path)) void confirm(call.id, call.path, lastShown.revision);\n          else if (context.autoOpen && !host.open(call.path)) {\n            mounting.delete(call.id);\n            void send(call.id, { kind: 'refused', reason: 'unsaved changes' });\n          }\n        }\n      }\n    },\n    /** Calls still waiting for a mount (test and debugging view). */\n    waiting: (): readonly string[] => [...mounting.keys()],\n  };\n}\n\n/** What `createPresentAcks` returns. */\nexport type PresentAcks = ReturnType<typeof createPresentAcks>;\n",
+      "content": "import type { ConversationView } from '@earendil-works/pi-durable';\nimport type { ToolCall, ToolResultMessage } from '@earendil-works/pi-ai';\nimport type { ComponentType, ReactNode } from 'react';\n\n/*\n * Artifacts in the chat: substantial content (a document, an HTML page, an SVG, code, a canvas) that the transcript shows as a\n * card and the host opens in its own panel. The descriptor and `parseArtifact` mirror `@hachej/boring-agent/artifacts` on purpose: this\n * is a copied registry item and cannot import that package (it carries Pi runtime code). Keep the two validators in step;\n * `test/contracts/pi-chat-source.test.mjs` checks that they accept and refuse the same values.\n */\nexport const ARTIFACT_TYPES = ['markdown', 'html', 'svg', 'code', 'canvas'] as const;\nexport type ArtifactType = typeof ARTIFACT_TYPES[number];\n\n/** Structural twin of the `ResourceLocator` in `@hachej/boring-files`. */\nexport interface ArtifactTarget {\n  readonly resource: { readonly providerId: string; readonly path: string };\n  readonly view: { readonly kind: 'published' } | { readonly kind: 'working'; readonly viewId: string };\n}\nexport interface ArtifactDescriptor {\n  readonly schema: 'boring.artifact';\n  readonly version: 1;\n  /** Set by the artifact tools; the descriptor of `present` has none (the file path is its identity). */\n  readonly id?: string;\n  readonly title: string;\n  readonly type: ArtifactType;\n  readonly mediaType: string;\n  readonly language?: string;\n  readonly target: ArtifactTarget;\n  /** The revision this message produced. */\n  readonly revision: string;\n  /** The 1-based version number of this artifact (artifact tools only). */\n  readonly ordinal?: number;\n}\n\n/** What identifies an artifact across its versions: its id, or for a presented file its path. */\nexport const artifactKey = (artifact: Pick<ArtifactDescriptor, 'id' | 'target'>): string => artifact.id ?? artifact.target.resource.path;\n\n/**\n * What an artifact kind's renderer receives: the artifact and its text at the revision shown, and the page's URL fragment without `#`\n * (a link such as `#screen=2` can open a place inside the artifact; the panel follows its changes).\n */\nexport interface ArtifactKindViewProps { readonly artifact: ArtifactDescriptor; readonly text: string; readonly fragment?: string | undefined }\n\n/**\n * An app's own kind of artifact (for example `.maquette.json` files): how its card and the panel name it, its icon, and optionally\n * how the panel draws it. Kinds are consulted in order before the built-in types; the first whose `match` is true wins. A kind\n * adds a presentation only: the descriptor, its type and how it is read are unchanged.\n */\nexport interface ArtifactKind {\n  /** True for the artifacts of this kind, for example `target => target.resource.path.endsWith('.maquette.json')`. */\n  readonly match: (target: ArtifactTarget, artifact: ArtifactDescriptor) => boolean;\n  /** The kind's name on the card and in the panel bar (\"Maquette\"). */\n  readonly label: string;\n  /** The card's icon (any component taking `className`, such as a lucide icon). The type's icon otherwise. */\n  readonly icon?: ComponentType<{ readonly className?: string; readonly 'aria-hidden'?: boolean | 'true' }> | undefined;\n  /** Draws the artifact in the panel (`AgentWorkspace`, `ArtifactPanel`) inside the standard viewer bar, with copy and download. */\n  readonly renderer?: ((props: ArtifactKindViewProps) => ReactNode) | undefined;\n}\n\n/** The first kind that matches the artifact; a `match` that throws counts as no match. */\nexport function artifactKind(artifact: ArtifactDescriptor, kinds: readonly ArtifactKind[] | undefined): ArtifactKind | undefined {\n  return kinds?.find(kind => { try { return kind.match(artifact.target, artifact); } catch { return false; } });\n}\n\n/** What the host passes to `PiChat` to turn artifact tool results into cards. */\nexport interface ArtifactsConfig {\n  /** The app's own artifact kinds (label, icon, renderer), consulted before the built-in types. */\n  readonly kinds?: readonly ArtifactKind[] | undefined;\n  /** The person clicked a card: show this artifact (and revision) in the host's panel. */\n  readonly open: (artifact: ArtifactDescriptor) => void;\n  /** True for the card whose artifact version is on display. */\n  readonly isOpen?: (artifact: ArtifactDescriptor) => boolean;\n  /** Recognise a descriptor in a successful tool result that does not carry one itself (for example a document save). */\n  readonly detect?: (call: ToolCall, result: ToolResultMessage) => ArtifactDescriptor | undefined;\n}\n\nexport const PRESENT_TOOL = 'present';\n\n/** A `present` call with no result yet, while its conversation runs: its answer ID (`[assistantEntryId, callId]`) and the path it names. */\nexport interface PendingPresent { readonly id: string; readonly callId: string; readonly path: string }\n\n/** The path a `present` call or a page acknowledgement names, as the server compares it (a leading `./` is the same file). */\nexport const presentPath = (path: string): string => path.replace(/^\\.\\//, '');\n\n/**\n * The `present` calls still waiting for the page (the server's view-open record, `@hachej/boring-agent/artifacts`). Mirrors\n * the preview's pending-call scan (the feedback plug-in's `pendingBrowserTasks`): a call with no result, in a conversation that is running.\n */\nexport 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[] {\n  if (!view) return [];\n  const live = view.docs?.['pi.live'] as { readonly run?: unknown } | undefined;\n  if (!live?.run) return [];\n  const calls = new Map<string, PendingPresent>();\n  for (const entry of view.entries) for (const message of entry.model ?? []) {\n    const item = message as { readonly role?: string; readonly content?: unknown; readonly toolCallId?: string };\n    if (item.role === 'assistant' && Array.isArray(item.content)) {\n      for (const part of item.content as { type?: string; id?: string; name?: string; arguments?: Record<string, unknown> }[]) {\n        const path = part.arguments?.['path'];\n        if (part.type === 'toolCall' && part.name === PRESENT_TOOL && typeof part.id === 'string' && typeof path === 'string') {\n          calls.set(part.id, { id: JSON.stringify([Number(entry.id), part.id]), callId: part.id, path: presentPath(path) });\n        }\n      }\n    }\n    if (item.role === 'toolResult' && typeof item.toolCallId === 'string') calls.delete(item.toolCallId);\n  }\n  return [...calls.values()];\n}\n\nconst ID = /^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/;\nconst LANGUAGE = /^[A-Za-z0-9+#._-]{1,32}$/;\nconst isObject = (value: unknown): value is Record<string, unknown> => value !== null && typeof value === 'object' && !Array.isArray(value);\nconst hasOnly = (value: Record<string, unknown>, keys: readonly string[]) => Object.keys(value).every(key => keys.includes(key));\n\n/** Strict shape check of an untrusted value. Returns a fresh copy or undefined. */\nexport function parseArtifact(value: unknown): ArtifactDescriptor | undefined {\n  if (!isObject(value) || !hasOnly(value, ['schema', 'version', 'id', 'title', 'type', 'mediaType', 'language', 'target', 'revision', 'ordinal'])) return undefined;\n  const { id, title, type, mediaType, language, target, revision, ordinal } = value;\n  if (value['schema'] !== 'boring.artifact' || value['version'] !== 1) return undefined;\n  if (id !== undefined && (typeof id !== 'string' || !ID.test(id))) return undefined;\n  if (typeof title !== 'string' || !title.trim() || title.length > 200) return undefined;\n  if (typeof type !== 'string' || !(ARTIFACT_TYPES as readonly string[]).includes(type)) return undefined;\n  if (typeof mediaType !== 'string' || !/^[a-z0-9][a-z0-9!#$&^_.+-]*\\/[a-z0-9][a-z0-9!#$&^_.+-]*$/i.test(mediaType)) return undefined;\n  if (language !== undefined && (typeof language !== 'string' || !LANGUAGE.test(language))) return undefined;\n  if (typeof revision !== 'string' || !revision || revision.length > 256) return undefined;\n  if (ordinal !== undefined && (typeof ordinal !== 'number' || !Number.isSafeInteger(ordinal) || ordinal < 1)) return undefined;\n  if (!isObject(target) || !hasOnly(target, ['resource', 'view']) || !isObject(target['resource']) || !hasOnly(target['resource'], ['providerId', 'path'])) return undefined;\n  const { providerId, path } = target['resource'];\n  if (typeof providerId !== 'string' || !providerId || typeof path !== 'string' || !path || path.length > 512) return undefined;\n  const view = target['view'];\n  if (!isObject(view)) return undefined;\n  let parsedView: ArtifactTarget['view'];\n  if (view['kind'] === 'published' && hasOnly(view, ['kind'])) parsedView = { kind: 'published' };\n  else if (view['kind'] === 'working' && hasOnly(view, ['kind', 'viewId']) && typeof view['viewId'] === 'string' && view['viewId']) parsedView = { kind: 'working', viewId: view['viewId'] };\n  else return undefined;\n  return { schema: 'boring.artifact', version: 1, ...(id === undefined ? {} : { id }), title, type: type as ArtifactType, mediaType, ...(language === undefined ? {} : { language: language as string }),\n    target: { resource: { providerId, path }, view: parsedView }, revision, ...(ordinal === undefined ? {} : { ordinal }) };\n}\n\nconst TYPE_LABEL: Record<ArtifactType, string> = { markdown: 'Document', html: 'HTML page', svg: 'SVG image', code: 'Code', canvas: 'Canvas' };\n/** The artifact's type name: the matching kind's label first, then the built-in name of its type. */\nexport function typeLabel(artifact: ArtifactDescriptor, kinds?: readonly ArtifactKind[]): string {\n  const kind = artifactKind(artifact, kinds);\n  if (kind) return kind.label;\n  return artifact.type === 'code' && artifact.language ? `Code · ${artifact.language}` : TYPE_LABEL[artifact.type];\n}\n\nconst textOf = (result: ToolResultMessage): string => result.content.map(part => part.type === 'text' ? part.text : '').join('');\n\n/**\n * The descriptor a successful tool result carries: the host's `detect` first, then the `artifact` key of a JSON text result.\n * Failed results never produce one, and a host callback that throws or returns something malformed is ignored. Without\n * the host's `detect`, only a result of `present` counts: any other tool whose text happens\n * to be that JSON (an MCP tool, `cat x.json`) cannot forge a card. A host with renamed tools says so in `detect`.\n */\nexport function detectArtifact(call: ToolCall, result: ToolResultMessage, detect?: ArtifactsConfig['detect']): ArtifactDescriptor | undefined {\n  if (result.isError) return undefined;\n  if (detect) {\n    try { const found = parseArtifact(detect(call, result)); if (found) return found; } catch { /* a faulty host callback shows no card */ }\n  }\n  if (call.name !== PRESENT_TOOL) return undefined;\n  const text = textOf(result);\n  if (!text.includes('\"boring.artifact\"')) return undefined;\n  try {\n    const value: unknown = JSON.parse(text);\n    return isObject(value) ? parseArtifact(value['artifact']) : undefined;\n  } catch { return undefined; }\n}\n\n/** The title a still-running `present` call announces in its streamed arguments: the file name. */\nexport function pendingTitle(call: ToolCall): string | undefined {\n  const path = (call.arguments as Record<string, unknown>)['path'];\n  const title = typeof path === 'string' ? path.slice(path.lastIndexOf('/') + 1) : undefined;\n  return title?.trim() ? title.trim().slice(0, 200) : undefined;\n}\n/** What a still-running `present` call will show: the file path. */\nexport function pendingId(call: ToolCall): string | undefined {\n  const path = (call.arguments as Record<string, unknown>)['path'];\n  return typeof path === 'string' && path ? path.replace(/^(\\.\\/)+/, '') : undefined;\n}\n\n/**\n * Every artifact version a conversation's tool results produced, oldest first. Hosts use it to list the versions known\n * from the conversation (a version switcher); the chat itself shows only the last version of an artifact per turn.\n */\nexport function collectArtifacts(view: ConversationView | undefined, detect?: ArtifactsConfig['detect']): ArtifactDescriptor[] {\n  const calls = new Map<string, ToolCall>(), found: ArtifactDescriptor[] = [];\n  for (const entry of view?.entries ?? []) for (const message of entry.model ?? []) {\n    if (message.role === 'assistant') for (const part of message.content) { if (part.type === 'toolCall') calls.set(part.id, part); }\n    else if (message.role === 'toolResult') {\n      const call = calls.get(message.toolCallId);\n      const descriptor = call && detectArtifact(call, message, detect);\n      if (descriptor) found.push(descriptor);\n    }\n  }\n  return found;\n}\n\n/** What the host's chat answer returns: the kind is all the presents bookkeeping reads. */\nexport interface PresentAnswer { readonly kind: string }\n\nexport interface PresentAcksHost {\n  /** The chat's `answer` (the transport's `?op=answer`); undefined when the host has none. */\n  readonly answer: (id: string, answer: string) => Promise<PresentAnswer> | undefined;\n  /** Open the file in the panel; false when the panel refuses (unsaved changes the person keeps). */\n  readonly open: (path: string) => boolean;\n  /** This page's identity in the acknowledgement. */\n  readonly instanceId: string;\n  /** Test seams: the wait between retries and the clock of the retry bound. Default: real timers. */\n  readonly wait?: (ms: number) => Promise<void>;\n  readonly now?: () => number;\n}\n\n/** The page's state of the presents it must answer, as `AgentWorkspace` reads it on each change. */\nexport interface PresentContext {\n  /** The person closed the panel in this turn. */\n  readonly closedThisTurn: boolean;\n  /** The open file has unsaved edits. */\n  readonly unsaved: boolean;\n  /** The screen is a phone (the panel is a sheet and is not opened for an agent). */\n  readonly narrow: boolean;\n  /** `autoOpen`: when false the panel is not opened for an agent; the call waits for a manual open. */\n  readonly autoOpen: boolean;\n  /** Whether the panel already shows this file. */\n  readonly showing: (path: string) => boolean;\n}\n\n/**\n * The page's side of the view-open acknowledgement. A `present` call is confirmed only by a viewer's mount report (`shown`) of the\n * 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)\n * keeps the call waiting for the next mount report, and an answer is retried briefly while the server has not recorded the call yet.\n */\nexport function createPresentAcks(host: PresentAcksHost) {\n  const decided = new Set<string>();\n  /** Calls waiting for their file's mount report: answer ID to path. */\n  const mounting = new Map<string, string>();\n  const wait = host.wait ?? (ms => new Promise<void>(resolve => setTimeout(resolve, ms)));\n  const now = host.now ?? (() => Date.now());\n  /** The last mount report: the file on screen and its revision. */\n  let lastShown: { readonly path: string; readonly revision: string } | undefined;\n\n  /** Sends one answer; returns the server's outcome kind, or undefined when it was not sent. Retries while the record is not written yet. */\n  async function send(id: string, body: Record<string, string>): Promise<string | undefined> {\n    const until = now() + 3000;\n    for (;;) {\n      try {\n        const sent = host.answer(id, JSON.stringify(body));\n        if (sent === undefined) return undefined;\n        const outcome = await sent;\n        if (outcome.kind !== 'unknown-question' || now() > until) return outcome.kind;\n      } catch { return undefined; /* the call ends at its deadline as unconfirmed */ }\n      await wait(20);\n    }\n  }\n  /** Confirms a shown revision. The call keeps its entry while the answer is in flight, so a mount during the flight still confirms it. */\n  async function confirm(id: string, path: string, revision: string): Promise<void> {\n    const kind = await send(id, { kind: 'opened', instanceId: host.instanceId, path, revision });\n    // 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.\n    if (kind === 'answered' || kind === 'conflict') mounting.delete(id);\n  }\n\n  return {\n    /** A viewer mounted and shows `path` at `revision`: confirms the calls waiting for that file. */\n    shown(view: { readonly path: string; readonly revision: string }): void {\n      for (const [id, path] of mounting) if (path === view.path) void confirm(id, path, view.revision);\n      lastShown = view;\n    },\n    /** A viewer stopped showing `path` at `revision` (it unmounted, or a custom viewer or the canvas took the file): it no longer confirms. */\n    hidden(view: { readonly path: string; readonly revision: string }): void {\n      if (lastShown?.path === view.path && lastShown.revision === view.revision) lastShown = undefined;\n    },\n    /** The presents the server waits for: each is decided once, in order. Decided calls and waits that are no longer live are forgotten. */\n    consider(calls: readonly PendingPresent[], context: PresentContext): void {\n      const live = new Set(calls.map(call => call.id));\n      for (const id of decided) if (!live.has(id)) decided.delete(id);\n      for (const id of mounting.keys()) if (!live.has(id)) mounting.delete(id);\n      for (const call of calls) {\n        if (decided.has(call.id)) continue;\n        decided.add(call.id);\n        if (context.closedThisTurn) void send(call.id, { kind: 'refused', reason: 'closed by user' });\n        else if (context.unsaved) void send(call.id, { kind: 'refused', reason: 'unsaved changes' });\n        else if (context.narrow) void send(call.id, { kind: 'refused', reason: 'narrow screen' });\n        else {\n          mounting.set(call.id, call.path);\n          if (lastShown?.path === call.path && context.showing(call.path)) void confirm(call.id, call.path, lastShown.revision);\n          else if (context.autoOpen && !host.open(call.path)) {\n            mounting.delete(call.id);\n            void send(call.id, { kind: 'refused', reason: 'unsaved changes' });\n          }\n        }\n      }\n    },\n    /** Calls still waiting for a mount (test and debugging view). */\n    waiting: (): readonly string[] => [...mounting.keys()],\n  };\n}\n\n/** What `createPresentAcks` returns. */\nexport type PresentAcks = ReturnType<typeof createPresentAcks>;\n",
       "type": "registry:lib",
       "target": "components/pi-chat/artifact.ts"
     },
@@ -155,7 +155,7 @@
     },
     {
       "path": "registry/pi-chat/question-card.tsx",
-      "content": "'use client';\n\nimport { useEffect, useId, useRef, useState } from 'react';\nimport type { FormEvent } from 'react';\nimport type { ToolCall, ToolResultMessage } from '@earendil-works/pi-ai';\nimport { CheckIcon, MessageCircleQuestionIcon, SendIcon } from 'lucide-react';\nimport { Badge } from '@/components/ui/badge';\nimport { Button } from '@/components/ui/button';\nimport { Input } from '@/components/ui/input';\nimport { Toggle } from '@/components/ui/toggle';\nimport { Item, ItemContent, ItemDescription, ItemFooter, ItemMedia, ItemTitle } from '@/components/ui/item';\nimport { useChatText } from './labels';\n\n/** What the host answers when asked to resolve a pending question. */\nexport type AnswerOutcome = { readonly kind: 'answered' } | { readonly kind: 'denied' | 'conflict' | 'unknown-question'; readonly reason?: string };\nexport const ASK_USER_TOOL = 'ask_user';\n\n/** One question of a form: its text and its options (chips); every question of a form also takes free text. */\nexport interface FormQuestion { readonly question: string; readonly options: readonly string[] }\ninterface Question {\n  readonly question: string; readonly options: readonly string[]; readonly allowFreeText: boolean;\n  /** Several questions in one form (`questions`), answered together as one text. Empty for a single question. */\n  readonly items: readonly FormQuestion[];\n}\n\nconst strings = (value: unknown, max: number) => Array.isArray(value) ? value.filter((item): item is string => typeof item === 'string' && item.length > 0).slice(0, max) : [];\n\n/**\n * Read `{ question, options?, allowFreeText?, questions? }` defensively: model arguments are untrusted input. Free text is allowed\n * unless `allowFreeText` is `false` (and always when there are no options). `questions` (up to 8) makes a form.\n */\nexport function parseQuestion(call: ToolCall): Question {\n  const args = call.arguments as Record<string, unknown>;\n  const options = strings(args['options'], 6);\n  const items = Array.isArray(args['questions']) ? args['questions'].flatMap((item: unknown) => {\n    const value = item !== null && typeof item === 'object' ? item as Record<string, unknown> : {};\n    return typeof value['question'] === 'string' && value['question'] ? [{ question: value['question'], options: strings(value['options'], 6) }] : [];\n  }).slice(0, 8) : [];\n  return { question: typeof args['question'] === 'string' ? args['question'] : '', options, allowFreeText: args['allowFreeText'] !== false || options.length === 0, items };\n}\n\n/** The answers of a form as the one text the agent reads: each question, then its answer, or `skipped` when left blank. */\nexport function formAnswer(items: readonly FormQuestion[], values: readonly string[], skipped: string): string {\n  return items.map((item, i) => `${i + 1}. ${item.question}\\n→ ${values[i]?.trim() || skipped}`).join('\\n\\n');\n}\n\n/** The answered text from a result such as `{\"kind\":\"answered\",\"answer\":\"...\"}`; undefined when the call did not produce an answer. */\nexport function parseAnswer(result: ToolResultMessage | undefined): { readonly answer: string } | { readonly failure: string } | undefined {\n  if (!result) return undefined;\n  const text = result.content.map(part => part.type === 'text' ? part.text : '').join('');\n  if (!result.isError) {\n    try {\n      const value: unknown = JSON.parse(text);\n      if (value !== null && typeof value === 'object' && (value as { kind?: unknown }).kind === 'answered' && typeof (value as { answer?: unknown }).answer === 'string') return { answer: (value as { answer: string }).answer };\n    } catch { /* fall through to the failure text */ }\n  }\n  return { failure: text || 'The question was not answered.' };\n}\n\n\n/**\n * Human-in-the-loop question: writing (still generated, not answerable), pending (options and free text), then answered with the chosen\n * answer. With `questions` it is one form: each question has its option chips and a free-text field, and Answer sends one text\n * (`formAnswer`). It needs only a tool call and an `answer` callback, so a host can show it outside the chat too (for example in a\n * popover answering a request of its own); wrap it in `ChatTextProvider` for the chat's words there.\n */\nexport function QuestionCard({ call, result, answer, questionId, live = false }: {\n  readonly call: ToolCall;\n  readonly result: ToolResultMessage | undefined;\n  readonly questionId: string | undefined;\n  readonly answer?: ((questionId: string, answer: string) => Promise<AnswerOutcome>) | undefined;\n  /** The call is still being generated by the model: it cannot be answered yet. */\n  readonly live?: boolean;\n}) {\n  const { labels } = useChatText();\n  const question = parseQuestion(call);\n  const settled = parseAnswer(result);\n  const [sent, setSent] = useState<string | undefined>();\n  const [sending, setSending] = useState<string | undefined>();\n  const [refusal, setRefusal] = useState<string | undefined>();\n  const [text, setText] = useState('');\n  const [values, setValues] = useState<readonly string[]>([]);\n  const formId = useId();\n  const setValue = (i: number, value: string) => setValues(previous => question.items.map((_, j) => j === i ? value : previous[j] ?? ''));\n  const mounted = useRef(true);\n  useEffect(() => { mounted.current = true; return () => { mounted.current = false; }; }, []);\n  const current = settled && 'answer' in settled ? settled.answer : sent;\n  // `pending` means the question waits on the person; `writing` means the model is still generating it (options may be partial).\n  const state = settled ? ('failure' in settled ? 'failed' : 'answered') : sent !== undefined ? 'sent' : live ? 'writing' : 'pending';\n  const open = state === 'pending' || state === 'writing';\n\n  async function submit(value: string) {\n    const trimmed = value.trim();\n    if (!answer || !questionId || live || !trimmed || sending !== undefined) return;\n    setRefusal(undefined); setSending(trimmed);\n    try {\n      const outcome = await answer(questionId, trimmed);\n      if (outcome.kind === 'answered') setSent(trimmed);\n      else setRefusal(outcome.reason || labels.answerRefused(outcome.kind));\n    } catch (cause) { setRefusal(cause instanceof Error ? cause.message : labels.answerNotSent); }\n    finally { if (mounted.current) setSending(undefined); }\n  }\n  const onSubmit = (event: FormEvent) => { event.preventDefault(); void submit(text); };\n  const onSubmitForm = (event: FormEvent) => { event.preventDefault(); if (values.some(value => value.trim())) void submit(formAnswer(question.items, values, labels.skipped)); };\n  const busy = sending !== undefined || live;\n\n  const unavailable = !answer || !questionId || busy;\n\n  return <Item variant=\"outline\" size=\"sm\" render={<section />} data-testid=\"question-card\" data-state={state} data-call-id={call.id} aria-label={labels.question} className=\"my-2 text-start\">\n    <ItemMedia variant=\"icon\">\n      {state === 'answered' || state === 'sent' ? <CheckIcon aria-hidden=\"true\" /> : <MessageCircleQuestionIcon aria-hidden=\"true\" />}\n    </ItemMedia>\n    <ItemContent className=\"min-w-0 basis-0\">\n      <ItemDescription className=\"line-clamp-none\"><Badge variant={open ? 'outline' : 'secondary'}>{open ? labels.questionForYou : state === 'failed' ? labels.notAnswered : labels.answered}</Badge></ItemDescription>\n      <ItemTitle data-testid=\"question-text\" className=\"line-clamp-none [overflow-wrap:anywhere]\">{question.question || labels.askedQuestion}</ItemTitle>\n      {(state === 'answered' || state === 'sent') && current !== undefined && <ItemDescription className=\"line-clamp-none\">{labels.yourAnswer} <span data-testid=\"question-answer\" className=\"font-medium whitespace-pre-line text-foreground [overflow-wrap:anywhere]\">{current}</span>\n        {state === 'sent' && <span className=\"ms-2 text-xs\">{labels.waitingForAgent}</span>}</ItemDescription>}\n      {state === 'failed' && settled && 'failure' in settled && <p role=\"alert\" className=\"m-0 text-sm text-destructive\">{settled.failure}</p>}\n    </ItemContent>\n    {open && <ItemFooter className=\"flex-col items-stretch\">\n      {question.items.length > 0 ? <form data-testid=\"question-form\" onSubmit={onSubmitForm} className=\"flex flex-col gap-4\">\n        {question.items.map((item, i) => <div key={i} role=\"group\" aria-labelledby={`${formId}-${i}`} data-testid=\"question-item\" className=\"flex min-w-0 flex-col gap-2\">\n          <p id={`${formId}-${i}`} className=\"m-0 text-sm [overflow-wrap:anywhere]\"><span className=\"me-1 text-muted-foreground\">{i + 1}.</span>{item.question}</p>\n          {item.options.length > 0 && <div role=\"group\" aria-label={labels.answerOptions} className=\"flex flex-wrap gap-2\">\n            {item.options.map(option => <Toggle key={option} variant=\"outline\" data-testid=\"question-option\" data-option={option} disabled={unavailable}\n              pressed={values[i] === option} onPressedChange={pressed => setValue(i, pressed ? option : '')} className=\"h-auto min-h-11 max-w-full whitespace-normal py-2 text-start\">{option}</Toggle>)}\n          </div>}\n          <Input data-testid=\"question-input\" value={item.options.includes(values[i] ?? '') ? '' : values[i] ?? ''} maxLength={2000} disabled={unavailable}\n            placeholder={item.options.length ? labels.ownAnswer : labels.typeAnswer} aria-label={`${labels.yourAnswerInput} ${i + 1}`} onChange={event => setValue(i, event.currentTarget.value)} className=\"min-w-0\" />\n        </div>)}\n        <div><Button type=\"submit\" variant=\"default\" data-testid=\"question-submit\" disabled={unavailable || !values.some(value => value.trim())}><SendIcon data-icon=\"inline-start\" aria-hidden=\"true\" />{labels.answer}</Button></div>\n      </form> : <>\n        {question.options.length > 0 && <div role=\"group\" aria-label={labels.answerOptions} className=\"flex flex-col items-stretch gap-2\">\n          {question.options.map(option => <Button key={option} variant=\"outline\" data-testid=\"question-option\" data-option={option} disabled={unavailable}\n            onClick={() => { void submit(option); }} className=\"h-auto min-h-11 w-full justify-start whitespace-normal py-2 text-start\">{option}</Button>)}\n        </div>}\n        {question.allowFreeText && <form onSubmit={onSubmit} className=\"flex gap-2\">\n          <Input data-testid=\"question-input\" value={text} maxLength={2000} disabled={unavailable} placeholder={question.options.length ? labels.ownAnswer : labels.typeAnswer}\n            aria-label={labels.yourAnswerInput} onChange={event => setText(event.currentTarget.value)} className=\"min-w-0 flex-1\" />\n          <Button type=\"submit\" variant=\"default\" data-testid=\"question-submit\" disabled={unavailable || !text.trim()}><SendIcon data-icon=\"inline-start\" aria-hidden=\"true\" />{labels.answer}</Button>\n        </form>}\n      </>}\n      {live && <ItemDescription>{labels.stillWritingQuestion}</ItemDescription>}\n      {!answer && !live && <ItemDescription>{labels.answeringUnavailable}</ItemDescription>}\n      {refusal && <p role=\"alert\" data-testid=\"question-refusal\" className=\"m-0 text-sm text-destructive\">{refusal}</p>}\n    </ItemFooter>}\n  </Item>;\n}\n",
+      "content": "'use client';\n\nimport { useEffect, useId, useRef, useState } from 'react';\nimport type { FormEvent } from 'react';\nimport type { ToolCall, ToolResultMessage } from '@earendil-works/pi-ai';\nimport { CheckIcon, CircleSlashIcon, SendIcon } from 'lucide-react';\nimport { Button } from '@/components/ui/button';\nimport { Input } from '@/components/ui/input';\nimport { Alert, AlertDescription } from '@/components/ui/alert';\nimport { Card, CardContent, CardDescription, CardHeader, CardTitle } from '@/components/ui/card';\nimport { Item, ItemContent, ItemDescription, ItemMedia, ItemTitle } from '@/components/ui/item';\nimport { Spinner } from '@/components/ui/spinner';\nimport { useChatText } from './labels';\n\n/** What the host answers when asked to resolve a pending question. */\nexport type AnswerOutcome = { readonly kind: 'answered' } | { readonly kind: 'denied' | 'conflict' | 'unknown-question'; readonly reason?: string };\nexport const ASK_USER_TOOL = 'ask_user';\n\n/** One question of a form: its text and its options (chips); every question of a form also takes free text. */\nexport interface FormQuestion { readonly question: string; readonly options: readonly string[] }\ninterface Question {\n  readonly question: string; readonly options: readonly string[]; readonly allowFreeText: boolean;\n  /** Several questions in one form (`questions`), answered together as one text. Empty for a single question. */\n  readonly items: readonly FormQuestion[];\n}\n\nconst strings = (value: unknown, max: number) => Array.isArray(value) ? value.filter((item): item is string => typeof item === 'string' && item.length > 0).slice(0, max) : [];\n\n/**\n * Read `{ question, options?, allowFreeText?, questions? }` defensively: model arguments are untrusted input. Free text is allowed\n * unless `allowFreeText` is `false` (and always when there are no options). `questions` (up to 8) makes a form.\n */\nexport function parseQuestion(call: ToolCall): Question {\n  const args = call.arguments as Record<string, unknown>;\n  const options = strings(args['options'], 6);\n  const items = Array.isArray(args['questions']) ? args['questions'].flatMap((item: unknown) => {\n    const value = item !== null && typeof item === 'object' ? item as Record<string, unknown> : {};\n    return typeof value['question'] === 'string' && value['question'] ? [{ question: value['question'], options: strings(value['options'], 6) }] : [];\n  }).slice(0, 8) : [];\n  return { question: typeof args['question'] === 'string' ? args['question'] : '', options, allowFreeText: args['allowFreeText'] !== false || options.length === 0, items };\n}\n\n/** The answers of a form as the one text the agent reads: each question, then its answer, or `skipped` when left blank. */\nexport function formAnswer(items: readonly FormQuestion[], values: readonly string[], skipped: string): string {\n  return items.map((item, i) => `${i + 1}. ${item.question}\\n→ ${values[i]?.trim() || skipped}`).join('\\n\\n');\n}\n\n/** The answers of a `formAnswer` text, one per question; undefined when the text does not have that shape (then it is shown whole). */\nfunction splitFormAnswer(items: readonly FormQuestion[], text: string): readonly string[] | undefined {\n  const values: string[] = [];\n  let at = 0;\n  for (let i = 0; i < items.length; i++) {\n    const head = `${i + 1}. ${items[i]!.question}\\n→ `;\n    if (!text.startsWith(head, at)) return undefined;\n    at += head.length;\n    const end = i + 1 < items.length ? text.indexOf(`\\n\\n${i + 2}. ${items[i + 1]!.question}\\n→ `, at) : text.length;\n    if (end < 0) return undefined;\n    values.push(text.slice(at, end));\n    at = end + 2;\n  }\n  return values;\n}\n\n/** The answered text from a result such as `{\"kind\":\"answered\",\"answer\":\"...\"}`; undefined when the call did not produce an answer. */\nexport function parseAnswer(result: ToolResultMessage | undefined): { readonly answer: string } | { readonly failure: string } | undefined {\n  if (!result) return undefined;\n  const text = result.content.map(part => part.type === 'text' ? part.text : '').join('');\n  if (!result.isError) {\n    try {\n      const value: unknown = JSON.parse(text);\n      if (value !== null && typeof value === 'object' && (value as { kind?: unknown }).kind === 'answered' && typeof (value as { answer?: unknown }).answer === 'string') return { answer: (value as { answer: string }).answer };\n    } catch { /* fall through to the failure text */ }\n  }\n  return { failure: text || 'The question was not answered.' };\n}\n\n\n/**\n * Human-in-the-loop question: writing (still generated, not answerable), pending (options and free text), then answered with the chosen\n * answer. With `questions` it is one form: each question has its option chips and a free-text field, and Answer sends one text\n * (`formAnswer`). It needs only a tool call and an `answer` callback, so a host can show it outside the chat too (for example in a\n * popover answering a request of its own); wrap it in `ChatTextProvider` for the chat's words there.\n */\nexport function QuestionCard({ call, result, answer, questionId, live = false }: {\n  readonly call: ToolCall;\n  readonly result: ToolResultMessage | undefined;\n  readonly questionId: string | undefined;\n  readonly answer?: ((questionId: string, answer: string) => Promise<AnswerOutcome>) | undefined;\n  /** The call is still being generated by the model: it cannot be answered yet. */\n  readonly live?: boolean;\n}) {\n  const { labels } = useChatText();\n  const question = parseQuestion(call);\n  const settled = parseAnswer(result);\n  const [sent, setSent] = useState<string | undefined>();\n  const [sending, setSending] = useState<string | undefined>();\n  const [refusal, setRefusal] = useState<string | undefined>();\n  const [text, setText] = useState('');\n  const [values, setValues] = useState<readonly string[]>([]);\n  const formId = useId();\n  const setValue = (i: number, value: string) => setValues(previous => question.items.map((_, j) => j === i ? value : previous[j] ?? ''));\n  const mounted = useRef(true);\n  useEffect(() => { mounted.current = true; return () => { mounted.current = false; }; }, []);\n  const current = settled && 'answer' in settled ? settled.answer : sent;\n  // `pending` means the question waits on the person; `writing` means the model is still generating it (options may be partial).\n  const state = settled ? ('failure' in settled ? 'failed' : 'answered') : sent !== undefined ? 'sent' : live ? 'writing' : 'pending';\n  const open = state === 'pending' || state === 'writing';\n\n  async function submit(value: string) {\n    const trimmed = value.trim();\n    if (!answer || !questionId || live || !trimmed || sending !== undefined) return;\n    setRefusal(undefined); setSending(trimmed);\n    try {\n      const outcome = await answer(questionId, trimmed);\n      if (outcome.kind === 'answered') setSent(trimmed);\n      else setRefusal(outcome.reason || labels.answerRefused(outcome.kind));\n    } catch (cause) { setRefusal(cause instanceof Error ? cause.message : labels.answerNotSent); }\n    finally { if (mounted.current) setSending(undefined); }\n  }\n  const onSubmit = (event: FormEvent) => { event.preventDefault(); void submit(text); };\n  const onSubmitForm = (event: FormEvent) => { event.preventDefault(); if (values.some(value => value.trim())) void submit(formAnswer(question.items, values, labels.skipped)); };\n  const busy = sending !== undefined || live;\n\n  const unavailable = !answer || !questionId || busy;\n  // `m-0`: a host without a global preflight keeps the paragraph margin of ItemDescription.\n  const wrap = 'm-0 line-clamp-none [overflow-wrap:anywhere]';\n\n  if (!open) {\n    const values = question.items.length > 0 && current !== undefined ? splitFormAnswer(question.items, current) : undefined;\n    return <Item role=\"group\" data-testid=\"question-card\" data-state={state} data-call-id={call.id} aria-label={labels.question}>\n      <ItemMedia variant=\"icon\">\n        {state === 'answered' ? <CheckIcon role=\"img\" aria-label={labels.answered} /> : state === 'sent' ? <Spinner aria-label={labels.waitingForAgent} /> : <CircleSlashIcon role=\"img\" aria-label={labels.notAnswered} />}\n      </ItemMedia>\n      <ItemContent className=\"min-w-0\">\n        <ItemDescription data-testid=\"question-text\" className={wrap}>{question.question || labels.askedQuestion}</ItemDescription>\n        {values ? <div className=\"flex min-w-0 flex-col gap-2\">{question.items.map((item, i) => <div key={i} data-testid=\"question-answer-item\" className=\"flex min-w-0 flex-col gap-1\">\n          <ItemDescription className={wrap}>{item.question}</ItemDescription>\n          {values[i] === labels.skipped\n            ? <ItemDescription data-testid=\"question-answer\" data-skipped=\"true\" className={wrap}>{values[i]}</ItemDescription>\n            : <ItemTitle data-testid=\"question-answer\" className={wrap}>{values[i]}</ItemTitle>}\n        </div>)}</div>\n          : current !== undefined && <ItemTitle className={wrap}><span className=\"sr-only\">{labels.yourAnswer} </span><span data-testid=\"question-answer\" className=\"whitespace-pre-line\">{current}</span></ItemTitle>}\n        {state === 'failed' && settled && 'failure' in settled && <ItemDescription role=\"alert\" className={wrap}>{settled.failure}</ItemDescription>}\n      </ItemContent>\n    </Item>;\n  }\n\n  const option = (value: string, selected: boolean, onClick: () => void) => <Button key={value} variant={selected ? 'secondary' : 'outline'} data-testid=\"question-option\" data-option={value}\n    aria-pressed={question.items.length > 0 ? selected : undefined} disabled={unavailable} onClick={onClick} className=\"h-auto min-h-8 w-full justify-start whitespace-normal text-start\">\n    {selected && <CheckIcon data-icon=\"inline-start\" aria-hidden=\"true\" />}{value}\n  </Button>;\n\n  return <Card role=\"group\" data-testid=\"question-card\" data-state={state} data-call-id={call.id} aria-label={labels.question}>\n    <CardHeader>\n      <CardDescription>{labels.questionForYou}</CardDescription>\n      <CardTitle data-testid=\"question-text\" className=\"[overflow-wrap:anywhere]\">{question.question || labels.askedQuestion}</CardTitle>\n    </CardHeader>\n    <CardContent className=\"flex flex-col gap-4\">\n      {question.items.length > 0 ? <form data-testid=\"question-form\" onSubmit={onSubmitForm} className=\"flex flex-col gap-4\">\n        {question.items.map((item, i) => <div key={i} role=\"group\" aria-labelledby={`${formId}-${i}`} data-testid=\"question-item\" className=\"flex min-w-0 flex-col gap-2\">\n          <p id={`${formId}-${i}`} className=\"m-0 [overflow-wrap:anywhere]\">{i + 1}. {item.question}</p>\n          {item.options.length > 0 && <div role=\"group\" aria-label={labels.answerOptions} className=\"flex flex-col gap-2\">\n            {item.options.map(value => option(value, values[i] === value, () => setValue(i, values[i] === value ? '' : value)))}\n          </div>}\n          <Input data-testid=\"question-input\" value={item.options.includes(values[i] ?? '') ? '' : values[i] ?? ''} maxLength={2000} disabled={unavailable}\n            placeholder={item.options.length ? labels.ownAnswer : labels.typeAnswer} aria-label={`${labels.yourAnswerInput} ${i + 1}`} onChange={event => setValue(i, event.currentTarget.value)} />\n        </div>)}\n        <div><Button type=\"submit\" data-testid=\"question-submit\" disabled={unavailable || !values.some(value => value.trim())}><SendIcon data-icon=\"inline-start\" aria-hidden=\"true\" />{labels.answer}</Button></div>\n      </form> : <>\n        {question.options.length > 0 && <div role=\"group\" aria-label={labels.answerOptions} className=\"flex flex-col gap-2\">\n          {question.options.map(value => option(value, false, () => { void submit(value); }))}\n        </div>}\n        {question.allowFreeText && <form onSubmit={onSubmit} className=\"flex gap-2\">\n          <Input data-testid=\"question-input\" value={text} maxLength={2000} disabled={unavailable} placeholder={question.options.length ? labels.ownAnswer : labels.typeAnswer}\n            aria-label={labels.yourAnswerInput} onChange={event => setText(event.currentTarget.value)} />\n          <Button type=\"submit\" data-testid=\"question-submit\" disabled={unavailable || !text.trim()}><SendIcon data-icon=\"inline-start\" aria-hidden=\"true\" />{labels.answer}</Button>\n        </form>}\n      </>}\n      {live && <CardDescription>{labels.stillWritingQuestion}</CardDescription>}\n      {!answer && !live && <CardDescription>{labels.answeringUnavailable}</CardDescription>}\n      {refusal && <Alert variant=\"destructive\" data-testid=\"question-refusal\"><AlertDescription>{refusal}</AlertDescription></Alert>}\n    </CardContent>\n  </Card>;\n}\n",
       "type": "registry:component",
       "target": "components/pi-chat/question-card.tsx"
     },

package/r/pi-workspace.json

@@ -8,10 +8,10 @@
     "react-dom@^19.0.0"
   ],
   "registryDependencies": [
-    "https://cdn.jsdelivr.net/npm/@hachej/boring-ui-kit@0.4.1/r/theme.json",
-    "https://cdn.jsdelivr.net/npm/@hachej/boring-ui-kit@0.4.1/r/pi-chat.json",
-    "https://cdn.jsdelivr.net/npm/@hachej/boring-ui-kit@0.4.1/r/utils.json",
-    "https://cdn.jsdelivr.net/npm/@hachej/boring-ui-kit@0.4.1/r/dock.json",
+    "https://cdn.jsdelivr.net/npm/@hachej/boring-ui-kit@0.4.2/r/theme.json",
+    "https://cdn.jsdelivr.net/npm/@hachej/boring-ui-kit@0.4.2/r/pi-chat.json",
+    "https://cdn.jsdelivr.net/npm/@hachej/boring-ui-kit@0.4.2/r/utils.json",
+    "https://cdn.jsdelivr.net/npm/@hachej/boring-ui-kit@0.4.2/r/dock.json",
     "badge",
     "card"
   ],

package/r/provider-setup.json

@@ -9,8 +9,8 @@
     "lucide-react@^1.51.0"
   ],
   "registryDependencies": [
-    "https://cdn.jsdelivr.net/npm/@hachej/boring-ui-kit@0.4.1/r/theme.json",
-    "https://cdn.jsdelivr.net/npm/@hachej/boring-ui-kit@0.4.1/r/utils.json",
+    "https://cdn.jsdelivr.net/npm/@hachej/boring-ui-kit@0.4.2/r/theme.json",
+    "https://cdn.jsdelivr.net/npm/@hachej/boring-ui-kit@0.4.2/r/utils.json",
     "button",
     "input",
     "label",