@hachej/boring-ui-kit 0.4.29 → 0.4.30

package/README.md

@@ -16,6 +16,12 @@ For read-only content without a resource client or controller, select the lightw
 
 See [scaffold guide](../../docs/contracts/SCAFFOLD.md) and [audit](../../docs/contracts/ABSTRACTION-REVIEW.md).
 
+## Business task board
+
+`@hachej/boring-ui-kit/task-board` is a dependency-free host-record model: `TaskRecord`, `TaskState`, `TaskFilter`, `selectTasks`, `taskReference`, `taskFromUrl`, `taskUrl` and `TASK_STATES`. `selectTasks(tasks, { filter, currentUser, limit })` filters then sorts newest-first without mutating input. `mine` requires the host adapter's `requesterId`; it is never an authorization boundary. These business tasks are not native Pi execution tasks. The model also accepts host display metadata (`age`, `requester`, `refiner`, `captureCount`, `folder`), question `askedBy`/`askedAt`, and file `kind: 'markdown' | 'mockup' | 'capture'`. These fields never determine ownership. `deriveTaskStatus` prioritizes the native viewer flag, explicit `waiting_on.type: 'builder'`, then high risk; unknown status yields `none`. `taskStatusLabel(status, locale?, viewerAction?)` supplies EN/FR question versus confirmation wording without inferring workflow authority.
+
+Copyable `TaskBoard`, `TaskDetail`, `TaskRequestCard` (also `TaskCard`) and `TaskStatusChip` presentation lives in the [`task-board` registry item](../../registry/README.md#task-board-task-board), using the app's Base UI controls/tokens. The [feature map](../../features/task-board.md) and [fictional example](../../examples/task-board/README.md) drive responsive columns/detail, URL navigation and compact own-request rows.
+
 ## Exact proposals and commands
 
 `actions.propose(selection, edits, summary)` retains an immutable proposal with its exact resource/scope/view/revision, viewer instance/epoch, buffer version, before/after text and ordered edits. It performs no publication and preserves existing human text. Every nonempty `find` must occur once; a missing or ambiguous edit rejects the entire transform.

package/dist/chat-artifacts.d.ts

@@ -1,5 +1,8 @@
 import type { ConversationView } from '@earendil-works/pi-durable';
 import type { ToolCall, ToolResultMessage } from '@earendil-works/pi-ai';
+import type { TaskArtifactDescriptor, TaskSubject } from './task-artifacts.js';
+export { createTaskArtifact, parseTaskArtifact, parseTaskSubject, taskSubjectKey } from './task-artifacts.js';
+export type { TaskArtifactDescriptor, TaskSubject } from './task-artifacts.js';
 /**
  * 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.
@@ -48,14 +51,34 @@ export interface ArtifactDescriptor {
     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 type PresentedArtifact = ArtifactDescriptor | TaskArtifactDescriptor;
+export declare const artifactKey: (artifact: Pick<ArtifactDescriptor, "id" | "target"> | TaskArtifactDescriptor) => string;
+/** File revisions are retained history; a task reference has no invented revision. */
+export declare const artifactVersionKey: (artifact: PresentedArtifact) => string;
+export declare function parsePresentedArtifact(value: unknown): PresentedArtifact | undefined;
 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 {
+export type PendingPresent = {
     readonly id: string;
     readonly callId: string;
+} & ({
     readonly path: string;
-}
+} | {
+    readonly subject: TaskSubject;
+});
+export type PresentationShown = ({
+    readonly path: string;
+    readonly revision: string;
+} | {
+    readonly subject: TaskSubject;
+});
+export type PresentationFailed = ({
+    readonly path: string;
+} | {
+    readonly subject: TaskSubject;
+}) & {
+    readonly reason: 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;
 /**
@@ -77,7 +100,7 @@ export declare function parseArtifact(value: unknown): ArtifactDescriptor | unde
  * 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;
+export declare function detectArtifact(call: ToolCall, result: ToolResultMessage, detect?: ArtifactDetect | undefined): PresentedArtifact | 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. */
@@ -86,7 +109,7 @@ 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[];
+export declare function collectArtifacts(view: ConversationView | undefined, detect?: ArtifactDetect | undefined): PresentedArtifact[];
 /** What the host's chat answer returns: the kind is all the presents bookkeeping reads. */
 export interface PresentAnswer {
     readonly kind: string;
@@ -96,6 +119,8 @@ export interface PresentAcksHost {
     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;
+    /** Open a host task reference; absent: it stays pending until a manual mount or deadline. */
+    readonly openTask?: ((subject: TaskSubject) => boolean) | undefined;
     /** 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. */
@@ -114,6 +139,7 @@ export interface PresentContext {
     readonly autoOpen: boolean;
     /** Whether the panel already shows this file. */
     readonly showing: (path: string) => boolean;
+    readonly showingTask?: ((subject: TaskSubject) => boolean) | undefined;
 }
 /**
  * The page's side of the view-open acknowledgement. A `present` call is confirmed only by a viewer's mount report (`shown`) of the
@@ -122,20 +148,11 @@ export interface PresentContext {
  */
 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;
+    shown(view: PresentationShown): 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;
+    failed(view: PresentationFailed): 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;
+    hidden(view: PresentationShown): 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). */
@@ -149,9 +166,9 @@ export type PresentAcks = ReturnType<typeof createPresentAcks>;
  */
 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[];
+export declare function artifactVersions(view: ConversationView | undefined, detect?: ArtifactDetect): PresentedArtifact[];
 /** 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;
+export declare function follows(descriptor: PresentedArtifact, versions: readonly PresentedArtifact[]): 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

@@ -1,3 +1,5 @@
+import { parseTaskArtifact, parseTaskSubject, taskSubjectKey } from './task-artifacts.js';
+export { createTaskArtifact, parseTaskArtifact, parseTaskSubject, taskSubjectKey } from './task-artifacts.js';
 /*
  * 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
@@ -5,9 +7,12 @@
  * `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 artifactKey = (artifact) => 'subject' in artifact ? taskSubjectKey(artifact.subject) : artifact.id ?? artifact.target.resource.path;
+/** File revisions are retained history; a task reference has no invented revision. */
+export const artifactVersionKey = (artifact) => JSON.stringify([artifactKey(artifact), artifact.type === 'task' ? null : artifact.revision]);
+export function parsePresentedArtifact(value) { return parseArtifact(value) ?? parseTaskArtifact(value); }
 export const PRESENT_TOOL = 'present';
+const presentationKey = (value) => 'subject' in value ? taskSubjectKey(value.subject) : JSON.stringify(['file', presentPath(value.path)]);
 /** 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(/^\.\//, '');
 /**
@@ -26,9 +31,13 @@ export function pendingPresents(view) {
             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) });
+                    const path = part.arguments?.['path'], subject = parseTaskSubject(part.arguments);
+                    if (part.type === 'toolCall' && part.name === PRESENT_TOOL && typeof part.id === 'string') {
+                        const binding = { id: JSON.stringify([Number(entry.id), part.id]), callId: part.id };
+                        if (typeof path === 'string')
+                            calls.set(part.id, { ...binding, path: presentPath(path) });
+                        else if (subject)
+                            calls.set(part.id, { ...binding, subject });
                     }
                 }
             }
@@ -92,7 +101,7 @@ export function detectArtifact(call, result, detect) {
         return undefined;
     if (detect) {
         try {
-            const found = parseArtifact(detect(call, result));
+            const found = parsePresentedArtifact(detect(call, result));
             if (found)
                 return found;
         }
@@ -101,11 +110,11 @@ export function detectArtifact(call, result, detect) {
     if (call.name !== PRESENT_TOOL)
         return undefined;
     const text = textOf(result);
-    if (!text.includes('"boring.artifact"'))
+    if (!text.includes('"boring.artifact"') && !text.includes('"boring.task"'))
         return undefined;
     try {
         const value = JSON.parse(text);
-        return isObject(value) ? parseArtifact(value['artifact']) : undefined;
+        return isObject(value) ? parsePresentedArtifact(value['artifact']) : undefined;
     }
     catch {
         return undefined;
@@ -113,12 +122,18 @@ export function detectArtifact(call, result, detect) {
 }
 /** The title a still-running `present` call announces in its streamed arguments: the file name. */
 export function pendingTitle(call) {
+    const subject = parseTaskSubject(call.arguments);
+    if (subject)
+        return 'task' in subject ? subject.task : subject.tasks.filter === 'mine' ? 'My requests' : subject.tasks.filter === 'waiting-on-me' ? 'Waiting on me' : 'Tasks';
     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 subject = parseTaskSubject(call.arguments);
+    if (subject)
+        return taskSubjectKey(subject);
     const path = call.arguments['path'];
     return typeof path === 'string' && path ? path.replace(/^(\.\/)+/, '') : undefined;
 }
@@ -155,8 +170,8 @@ export function createPresentAcks(host) {
     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;
+    /** Independent mounted subjects retain their own evidence until that viewer hides or fails. */
+    const mounted = new Map();
     /** 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;
@@ -176,8 +191,8 @@ export function createPresentAcks(host) {
         }
     }
     /** 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 });
+    async function confirm(id, view) {
+        const kind = await send(id, { kind: 'opened', instanceId: host.instanceId, ...view });
         // 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);
@@ -191,24 +206,24 @@ export function createPresentAcks(host) {
     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;
+            for (const [id, call] of mounting)
+                if (presentationKey(call) === presentationKey(view))
+                    void confirm(id, view);
+            mounted.set(presentationKey(view), 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;
+            mounted.delete(presentationKey(view));
             const reason = view.reason.trim().slice(0, 200) || 'the view failed';
-            for (const [id, path] of mounting)
-                if (path === view.path)
+            for (const [id, call] of mounting)
+                if (presentationKey(call) === presentationKey(view))
                     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;
+            const shown = mounted.get(presentationKey(view));
+            if (shown && ('subject' in view || ('revision' in shown && shown.revision === view.revision)))
+                mounted.delete(presentationKey(view));
         },
         /** 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) {
@@ -227,15 +242,17 @@ export function createPresentAcks(host) {
                     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)
+                else if (context.narrow && !('subject' in call))
                     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.set(call.id, call);
+                    const showing = 'subject' in call ? context.showingTask?.(call.subject) : context.showing(call.path);
+                    const shown = mounted.get(presentationKey(call));
+                    if (shown && showing)
+                        void confirm(call.id, shown);
+                    else if (context.autoOpen && ('subject' in call ? host.openTask?.(call.subject) === false : !host.open(call.path))) {
                         mounting.delete(call.id);
-                        void send(call.id, { kind: 'refused', reason: 'unsaved changes' });
+                        void send(call.id, { kind: 'refused', reason: 'subject' in call ? 'task viewer unavailable' : 'unsaved changes' });
                     }
                 }
             }
@@ -254,7 +271,7 @@ export function recogniseArtifact(call, result, running, 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 };
+        return { state: 'ready', id: artifactKey(artifact), title: artifact.title, path: artifact.type === 'task' ? undefined : 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 };
@@ -266,7 +283,8 @@ export function artifactVersions(view, detect) {
 }
 /** 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;
+    const newest = versions.find(version => artifactKey(version) === artifactKey(descriptor));
+    return newest !== undefined && artifactVersionKey(descriptor) === artifactVersionKey(newest);
 }
 /** The number of user messages in the current native view, used to retain a manual close until the next turn. */
 export function artifactTurn(view) {

package/dist/chat-react.d.ts

@@ -1,5 +1,5 @@
 import type { ChatController } from './native-chat.js';
-import type { ArtifactDescriptor, ArtifactDetect, PresentAcksHost } from './chat-view.js';
+import type { PresentedArtifact, ArtifactDetect, PresentAcksHost, PresentationShown, PresentationFailed, TaskSubject } from './chat-view.js';
 export { useChatDraft } from './chat-react-draft.js';
 export { useControllerPerConversation } from './chat-react-controller.js';
 export type { ControllerPerConversationOptions, ConversationControllerState } from './chat-react-controller.js';
@@ -17,19 +17,15 @@ export declare function useRunNotifications(controller: RunNotificationSource, s
 /** Selects the authorized native view using the controller's own cached snapshot and subscription. Borrows its lifetime. */
 export declare function useChatView<T>(controller: ChatController | undefined, select: (view: ReturnType<ChatController['getSnapshot']>['view']) => T): T;
 export interface ArtifactSelection {
-    readonly descriptor: ArtifactDescriptor;
+    readonly descriptor: PresentedArtifact;
     readonly follow: boolean;
 }
-export interface ArtifactShown {
-    readonly path: string;
-    readonly revision: string;
+export type ArtifactShown = PresentationShown & {
     readonly hidden?: true;
-}
-export interface ArtifactFailed {
-    readonly path: string;
-    readonly revision: string;
-    readonly reason: string;
-}
+};
+export type ArtifactFailed = PresentationFailed & {
+    readonly revision?: string;
+};
 export interface ArtifactFollowOptions {
     readonly controller: ChatController | undefined;
     readonly conversationId?: string | undefined;
@@ -42,17 +38,19 @@ export interface ArtifactFollowOptions {
     readonly narrow?: (() => boolean) | undefined;
     readonly showing: (path: string) => boolean;
     readonly openPresent: (path: string) => boolean;
+    readonly openTask?: ((subject: TaskSubject) => boolean) | undefined;
+    readonly showingTask?: ((subject: TaskSubject) => boolean) | undefined;
     readonly answer?: PresentAcksHost['answer'] | undefined;
 }
 /** One version/follow/auto-open and present-ack rule for every chat surface. Mount evidence must come from the viewer. */
 export declare function useArtifactFollow(options: ArtifactFollowOptions): {
-    versions: ArtifactDescriptor[];
+    versions: PresentedArtifact[];
     turn: number;
-    known: ArtifactDescriptor[];
-    shown: ArtifactDescriptor | undefined;
-    open: (descriptor: ArtifactDescriptor) => void;
-    isOpen: (descriptor: ArtifactDescriptor) => boolean;
-    select: (version: ArtifactDescriptor | "latest") => void;
+    known: PresentedArtifact[];
+    shown: PresentedArtifact | undefined;
+    open: (descriptor: PresentedArtifact) => void;
+    isOpen: (descriptor: PresentedArtifact) => boolean;
+    select: (version: PresentedArtifact | "latest") => void;
     recordClosed: () => void;
     onShown: (shown: ArtifactShown) => void;
     onFailed: (failed: ArtifactFailed) => void;

package/dist/chat-react.js

@@ -1,7 +1,7 @@
 'use client';
 /** Opt-in UI projection over the native controller; owns no Pi execution or controller lifetime. */
 import { useCallback, useEffect, useId, useLayoutEffect, useMemo, useRef, useSyncExternalStore } from 'react';
-import { artifactKey, artifactTurn, artifactVersions, createPresentAcks, follows, pendingPresents, presentPath } from './chat-view.js';
+import { artifactKey, artifactVersionKey, artifactTurn, artifactVersions, createPresentAcks, follows, pendingPresents, presentPath } from './chat-view.js';
 export { useChatDraft } from './chat-react-draft.js';
 export { useControllerPerConversation } from './chat-react-controller.js';
 export { chunkKeys, useRowChunks, useTranscript, useTranscriptWindow, PAGE_FIRST, PAGE_MORE, CHUNK } from './chat-react-transcript.js';
@@ -43,12 +43,13 @@ export function useArtifactFollow(options) {
     const acks = useMemo(() => createPresentAcks({ instanceId,
         answer: (id, body) => current() ? latest.current.answer?.(id, body) : undefined,
         open: path => current() && latest.current.openPresent(path),
+        openTask: subject => current() && latest.current.openTask?.(subject) !== false,
     }), [current, instanceId]);
     useLayoutEffect(() => { binding.active = true; return () => { binding.active = false; }; }, [binding]);
     useEffect(() => {
         if (!controller || conversationId === undefined)
             return;
-        const keys = versions.map(version => JSON.stringify([artifactKey(version), version.revision]));
+        const keys = versions.map(artifactVersionKey);
         const known = seen.current.get(conversationId);
         if (!known) {
             seen.current.set(conversationId, new Set(keys));
@@ -66,24 +67,24 @@ export function useArtifactFollow(options) {
             return;
         acks.consider(calls, { closedThisTurn: closedInTurn.current.get(conversationId) === turn,
             unsaved: latest.current.unsaved?.() === true, narrow: latest.current.narrow?.() === true, autoOpen,
-            showing: path => latest.current.showing(path) });
+            showing: path => latest.current.showing(path), showingTask: subject => latest.current.showingTask?.(subject) === true });
     }, [acks, calls, conversationId, turn, autoOpen, options.answer]);
     const onShown = useCallback((shown) => {
         if (!current())
             return;
-        const report = { path: presentPath(shown.path), revision: shown.revision };
+        const report = 'subject' in shown ? { subject: shown.subject } : { path: presentPath(shown.path), revision: shown.revision };
         if (shown.hidden)
             acks.hidden(report);
         else
             acks.shown(report);
     }, [acks, current]);
     const onFailed = useCallback((failed) => { if (current())
-        acks.failed({ ...failed, path: presentPath(failed.path) }); }, [acks, current]);
+        acks.failed('subject' in failed ? failed : { ...failed, path: presentPath(failed.path) }); }, [acks, current]);
     const recordClosed = useCallback(() => { if (conversationId !== undefined)
         closedInTurn.current.set(conversationId, turn); }, [conversationId, turn]);
     const open = useCallback((descriptor) => latest.current.onOpen({ descriptor, follow: follows(descriptor, versions) }), [versions]);
     const isOpen = useCallback((descriptor) => Boolean(active && artifactKey(active.descriptor) === artifactKey(descriptor) &&
-        (active.follow ? follows(descriptor, versions) : descriptor.revision === active.descriptor.revision)), [active, versions]);
+        (active.follow ? follows(descriptor, versions) : artifactVersionKey(descriptor) === artifactVersionKey(active.descriptor))), [active, versions]);
     const known = useMemo(() => active ? versions.filter(version => artifactKey(version) === artifactKey(active.descriptor)) : [], [active, versions]);
     const shown = active ? active.follow ? known[0] ?? active.descriptor : active.descriptor : undefined;
     const select = useCallback((version) => {

package/dist/task-artifacts.d.ts

@@ -0,0 +1,22 @@
+/** A host-owned task reference, not a file, execution task, permission or mutation. */
+export type TaskSubject = {
+    readonly task: string;
+} | {
+    readonly tasks: {
+        readonly filter: 'all' | 'mine' | 'waiting-on-me';
+    };
+};
+export interface TaskArtifactDescriptor {
+    readonly schema: 'boring.task';
+    readonly version: 1;
+    readonly type: 'task';
+    readonly title: string;
+    readonly subject: TaskSubject;
+}
+/** Strict, detached reference parsing; the host still authenticates and resolves the task. */
+export declare function parseTaskSubject(value: unknown): TaskSubject | undefined;
+/** The browser and server use the same exact subject identity for presentation acknowledgements. */
+export declare function taskSubjectKey(subject: TaskSubject): string;
+export declare function parseTaskArtifact(value: unknown): TaskArtifactDescriptor | undefined;
+export declare function createTaskArtifact(subject: TaskSubject): TaskArtifactDescriptor;
+//# sourceMappingURL=task-artifacts.d.ts.map

package/dist/task-artifacts.js

@@ -0,0 +1,34 @@
+const object = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+const only = (value, keys) => Object.keys(value).every(key => keys.includes(key));
+/** Strict, detached reference parsing; the host still authenticates and resolves the task. */
+export function parseTaskSubject(value) {
+    if (!object(value))
+        return undefined;
+    if (only(value, ['task']) && typeof value['task'] === 'string' && /^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/.test(value['task']))
+        return { task: value['task'] };
+    const tasks = value['tasks'];
+    if (!only(value, ['tasks']) || !object(tasks) || !only(tasks, ['filter']))
+        return undefined;
+    const filter = tasks['filter'];
+    return filter === 'all' || filter === 'mine' || filter === 'waiting-on-me' ? { tasks: { filter } } : undefined;
+}
+/** The browser and server use the same exact subject identity for presentation acknowledgements. */
+export function taskSubjectKey(subject) {
+    return 'task' in subject ? JSON.stringify(['task', subject.task]) : JSON.stringify(['tasks', subject.tasks.filter]);
+}
+export function parseTaskArtifact(value) {
+    if (!object(value) || !only(value, ['schema', 'version', 'type', 'title', 'subject']))
+        return undefined;
+    if (value['schema'] !== 'boring.task' || value['version'] !== 1 || value['type'] !== 'task')
+        return undefined;
+    const title = value['title'], subject = parseTaskSubject(value['subject']);
+    if (typeof title !== 'string' || !title.trim() || title.length > 200 || !subject)
+        return undefined;
+    return { schema: 'boring.task', version: 1, type: 'task', title, subject };
+}
+export function createTaskArtifact(subject) {
+    const parsed = parseTaskSubject(subject);
+    if (!parsed)
+        throw new TypeError('Invalid task subject');
+    return { schema: 'boring.task', version: 1, type: 'task', title: 'task' in parsed ? parsed.task : parsed.tasks.filter === 'mine' ? 'My requests' : parsed.tasks.filter === 'waiting-on-me' ? 'Waiting on me' : 'Tasks', subject: parsed };
+}

package/dist/task-board.d.ts

@@ -0,0 +1,83 @@
+/** Business requests supplied by the host, not Pi execution tasks. No fetching, mutation or authorization lives here. */
+export declare const TASK_STATES: readonly ["waiting", "working", "open", "done", "closed"];
+export type TaskState = typeof TASK_STATES[number];
+export type TaskFilter = 'all' | 'mine' | 'waiting-on-me';
+export interface TaskQuestion {
+    readonly id: string;
+    readonly text: string;
+    /** Host-supplied display identity and timestamp for the question. */
+    readonly askedBy?: string;
+    readonly askedAt?: string;
+    readonly options?: readonly (string | {
+        readonly label: string;
+        readonly value: string;
+    })[];
+    readonly answer?: string;
+    /** Display identity supplied by the host, not inferred from the current viewer. */
+    readonly answeredBy?: string;
+    /** Optional host answer timestamp; newest answers first, otherwise latest source entries first. */
+    readonly answeredAt?: string;
+}
+export interface TaskFile {
+    /** Authorized workspace path supplied by the host adapter; never derived from the task id. */
+    readonly path: string;
+    readonly name?: string;
+    /** Presentation metadata, not permission to execute or load a file. */
+    readonly kind?: 'markdown' | 'mockup' | 'capture';
+}
+export interface TaskHistory {
+    readonly id?: string;
+    readonly at?: string;
+    readonly actor?: string;
+    readonly note: string;
+}
+export interface TaskRecord {
+    readonly id: string;
+    readonly number?: number | string;
+    readonly title: string;
+    readonly state: TaskState;
+    /** Host wording such as “À essayer”, independent of the five board columns. */
+    readonly status?: string;
+    /** The host adapter resolves the request's author; never inferred from an assignee. */
+    readonly requesterId?: string;
+    /** Host-formatted display metadata; identities here never determine ownership or filtering. */
+    readonly requester?: string;
+    readonly refiner?: string;
+    readonly age?: string;
+    /** Native viewer-relative projection, not inferred from waiting_on.who. */
+    readonly waiting_on_you?: boolean;
+    readonly waiting_on?: {
+        readonly who: string;
+        readonly question?: string;
+        readonly type?: 'builder' | 'person' | 'other';
+    };
+    readonly risk?: string;
+    readonly spec?: string;
+    readonly screen?: string;
+    readonly capture?: string;
+    /** Number of captures attached to the request, independent of the legacy capture description. */
+    readonly captureCount?: number;
+    /** Authorized workspace folder supplied by the host; never synthesized from the task reference. */
+    readonly folder?: string;
+    readonly questions?: readonly TaskQuestion[];
+    readonly files?: readonly TaskFile[];
+    readonly history?: readonly TaskHistory[];
+    readonly updated_at?: string;
+    readonly created_at?: string;
+}
+export type TaskSemanticStatus = 'waiting-on-viewer' | 'waiting-on-builder' | 'high-risk' | 'none';
+/** Single-pill presentation precedence: viewer, explicit builder, high risk. No workflow or authority is changed. */
+export declare function deriveTaskStatus(task: Pick<TaskRecord, 'waiting_on_you' | 'waiting_on' | 'risk'>): TaskSemanticStatus;
+/** Confirmation wording is explicit host context, never inferred from a question, title or free-form status. */
+export declare function taskStatusLabel(status: TaskSemanticStatus, locale?: 'en' | 'fr', viewerAction?: 'question' | 'confirmation'): string | undefined;
+export interface TaskSelection {
+    readonly filter?: TaskFilter;
+    readonly currentUser?: string;
+    readonly limit?: number;
+}
+/** Newest first, stable at equal/absent dates. Filtering is presentation, not an access boundary. */
+export declare function selectTasks(tasks: readonly TaskRecord[], { filter, currentUser, limit }?: TaskSelection): readonly TaskRecord[];
+export declare function taskReference(task: TaskRecord): string;
+export declare function taskFromUrl(url: string): string | null;
+export declare function taskUrl(url: string, id: string | null): string;
+//# sourceMappingURL=task-board.d.ts.map

package/dist/task-board.js

@@ -0,0 +1,42 @@
+/** Business requests supplied by the host, not Pi execution tasks. No fetching, mutation or authorization lives here. */
+export const TASK_STATES = ['waiting', 'working', 'open', 'done', 'closed'];
+/** Single-pill presentation precedence: viewer, explicit builder, high risk. No workflow or authority is changed. */
+export function deriveTaskStatus(task) {
+    if (task.waiting_on_you === true)
+        return 'waiting-on-viewer';
+    if (task.waiting_on?.type === 'builder')
+        return 'waiting-on-builder';
+    if (task.risk === 'high')
+        return 'high-risk';
+    return 'none';
+}
+/** Confirmation wording is explicit host context, never inferred from a question, title or free-form status. */
+export function taskStatusLabel(status, locale = 'en', viewerAction = 'question') {
+    switch (status) {
+        case 'waiting-on-viewer': return locale === 'fr' ? viewerAction === 'confirmation' ? 'À confirmer' : 'À vous' : 'Waiting on you';
+        case 'waiting-on-builder': return locale === 'fr' ? "Chez l'équipe" : 'Waiting on the builder';
+        case 'high-risk': return locale === 'fr' ? 'Risque élevé' : 'High risk';
+        default: return undefined;
+    }
+}
+/** Newest first, stable at equal/absent dates. Filtering is presentation, not an access boundary. */
+export function selectTasks(tasks, { filter = 'all', currentUser, limit } = {}) {
+    if (limit !== undefined && (!Number.isSafeInteger(limit) || limit < 0))
+        throw new RangeError('Task limit must be a nonnegative integer');
+    const date = (task) => { const value = Date.parse(task.updated_at ?? task.created_at ?? ''); return Number.isFinite(value) ? value : 0; };
+    const selected = tasks.filter(task => filter === 'mine' ? currentUser !== undefined && task.requesterId === currentUser : filter === 'waiting-on-me' ? task.state === 'waiting' && task.waiting_on_you === true : true)
+        .sort((a, b) => date(b) - date(a));
+    return limit === undefined ? selected : selected.slice(0, limit);
+}
+export function taskReference(task) {
+    return task.number === undefined ? task.id : String(task.number).startsWith('D-') ? String(task.number) : `D-${task.number}`;
+}
+export function taskFromUrl(url) { return new URL(url, 'https://task.invalid').searchParams.get('task'); }
+export function taskUrl(url, id) {
+    const next = new URL(url, 'https://task.invalid');
+    if (id === null)
+        next.searchParams.delete('task');
+    else
+        next.searchParams.set('task', id);
+    return next.href;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hachej/boring-ui-kit",
-  "version": "0.4.29",
+  "version": "0.4.30",
   "license": "MIT",
   "private": false,
   "type": "module",
@@ -147,10 +147,14 @@
     "./mark-store": {
       "types": "./dist/mark-store.d.ts",
       "import": "./dist/mark-store.js"
+    },
+    "./task-board": {
+      "types": "./dist/task-board.d.ts",
+      "import": "./dist/task-board.js"
     }
   },
   "peerDependencies": {
-    "@hachej/boring-files": "^0.4.29",
+    "@hachej/boring-files": "^0.4.30",
     "@earendil-works/pi-durable": "~1.4.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",