@hachej/boring-ui-kit 0.4.3 → 0.4.4

package/dist/shared-chat/index.js

@@ -0,0 +1,255 @@
+import { randomUUID } from '@hachej/boring-files/platform';
+import { createChatOutbox } from '../chat-outbox.js';
+import { ChannelRequestError } from './error.js';
+export { ChannelRequestError } from './error.js';
+export { channelAvatarStates } from './source.js';
+/** Host-owned multi-party log, not a Pi conversation or an agent runtime. One adapter per selected conversation. */
+export function createSharedChat(source, options) {
+    const id = options.conversationId, limit = options.limit ?? 60;
+    let snapshot = Object.freeze({ identity: { runtimeId: 'shared-chat', scopeId: id, principalId: source.me.id }, conversationId: id,
+        connection: { kind: 'idle' }, draft: { text: '', attachments: [], version: 0 }, outbox: [], history: { kind: 'idle' }, send: { kind: 'idle' }, stop: 'idle', disposed: false,
+        shared: { me: structuredClone(source.me), members: [], messages: [], files: [], replyTo: undefined, status: 'reconnecting' } });
+    const listeners = new Set();
+    const outbox = createChatOutbox();
+    const replayable = new Set();
+    let unsubscribe, opening, paging, before;
+    let revision = 0;
+    const changed = new Map();
+    const publish = (change) => {
+        if (snapshot.disposed)
+            return;
+        snapshot = Object.freeze({ ...snapshot, ...change });
+        for (const listener of [...listeners])
+            listener();
+    };
+    const active = () => { if (snapshot.disposed)
+        throw new Error('Chat controller is disposed'); };
+    const merge = (messages, prepend = false) => {
+        // New stream events always win over an overlapping history read. Replacements keep the row's position and identity.
+        const existing = snapshot.shared.messages;
+        const all = prepend ? [...messages, ...existing] : [...existing, ...messages];
+        const byId = new Map();
+        for (const message of all) {
+            if (message.conversationId !== id)
+                continue;
+            if (message.clientId)
+                for (const [key, value] of byId)
+                    if (value.clientId === message.clientId && key !== message.id)
+                        byId.delete(key);
+            byId.set(message.id, structuredClone(message));
+        }
+        publish({ shared: { ...snapshot.shared, messages: [...byId.values()].sort((a, b) => Date.parse(a.at) - Date.parse(b.at)) } });
+    };
+    const acknowledge = (message) => {
+        if (message.conversationId !== id || snapshot.disposed)
+            return;
+        changed.set(message.id, ++revision);
+        merge([message]);
+        if (message.clientId) {
+            replayable.delete(message.clientId);
+            outbox.resolve(message.clientId, message);
+        }
+    };
+    const sendOne = (clientId, input) => {
+        void Promise.resolve().then(() => source.send({ ...input, mentions: [...input.mentions], ...(input.attachments ? { attachments: [...input.attachments] } : {}) })).then(message => {
+            if (snapshot.disposed)
+                return;
+            if (message.conversationId !== id || message.clientId !== clientId)
+                throw new Error('Shared send returned another clientId or conversation');
+            acknowledge(message);
+        }).catch(error => {
+            if (!outbox.get(clientId))
+                return;
+            replayable.delete(clientId);
+            if (error instanceof ChannelRequestError && error.refused && !error.retryable) {
+                outbox.reject(clientId, error);
+                return;
+            }
+            // An unconfirmed result retains its exact identity. Only an explicitly retryable failure may replay.
+            const retryable = error instanceof ChannelRequestError && error.retryable;
+            if (retryable)
+                replayable.add(clientId);
+            publish({ send: { kind: 'unknown', reason: error instanceof Error ? error.message : 'Channel send is unconfirmed', retryable } });
+        });
+    };
+    const replay = () => { for (const call of outbox.values())
+        if (replayable.has(call.input.clientId))
+            sendOne(call.input.clientId, call.input); };
+    async function refresh() {
+        // Walk backward to the newest known message, not just one page: a long disconnect must not drop a gap.
+        const known = new Set(snapshot.shared.messages.map(message => message.id));
+        let cursor;
+        const seen = new Set();
+        do {
+            const started = revision;
+            const page = await source.history(id, { limit, ...(cursor ? { before: cursor } : {}) });
+            if (snapshot.disposed)
+                return;
+            merge(page.messages.filter(message => (changed.get(message.id) ?? 0) <= started));
+            if (!known.size && cursor === undefined)
+                before = page.before;
+            if (!page.before || !known.size || page.messages.some(message => known.has(message.id)))
+                break;
+            if (seen.has(page.before))
+                throw new Error('Channel history cursor did not progress');
+            seen.add(page.before);
+            cursor = page.before;
+        } while (cursor);
+        publish({ history: { kind: 'ready', entries: [], hasMore: before !== undefined } });
+    }
+    const event = (event) => {
+        if (snapshot.disposed)
+            return;
+        revision++;
+        if (event.type === 'message')
+            acknowledge(event.message);
+        else if (event.type === 'delta' && event.conversationId === id) {
+            const message = snapshot.shared.messages.find(message => message.id === event.messageId);
+            if (message) {
+                changed.set(message.id, revision);
+                merge([{ ...message, text: (message.text ?? '') + event.text, streaming: true }]);
+            }
+        }
+        else if (event.type === 'step' && event.conversationId === id && Number.isSafeInteger(event.index) && event.index >= 0) {
+            const message = snapshot.shared.messages.find(message => message.id === event.messageId);
+            if (message) {
+                const steps = [...(message.steps ?? [])];
+                steps[event.index] = { ...event.step };
+                changed.set(message.id, revision);
+                merge([{ ...message, steps }]);
+            }
+        }
+        else if (event.type === 'presence') {
+            publish({ shared: { ...snapshot.shared, members: snapshot.shared.members.map(member => {
+                        const update = event.members.find(update => update.id === member.id);
+                        return update ? { ...member, presence: update.presence } : member;
+                    }) } });
+        }
+        else if (event.type === 'members' && event.conversationId === id)
+            publish({ shared: { ...snapshot.shared, members: structuredClone(event.members) } });
+    };
+    let reconnect;
+    const status = (value) => {
+        const previous = snapshot.shared.status;
+        publish({ shared: { ...snapshot.shared, status: value }, connection: { kind: value === 'live' ? 'connected' : 'reconnecting' } });
+        if (value === 'live' && previous !== 'live' && !opening && !reconnect) {
+            reconnect = refresh().then(replay).catch(error => publish({ connection: { kind: 'error', error } })).finally(() => { reconnect = undefined; });
+        }
+    };
+    const controller = {
+        getSnapshot: () => snapshot,
+        subscribe: (listener) => { listeners.add(listener); return () => { listeners.delete(listener); }; },
+        setText: (text) => { active(); publish({ draft: { ...snapshot.draft, text, version: snapshot.draft.version + 1 } }); },
+        setAttachments: (attachments) => { active(); publish({ draft: { ...snapshot.draft, attachments, version: snapshot.draft.version + 1 } }); },
+        setFiles: (files) => { active(); publish({ shared: { ...snapshot.shared, files: [...files] } }); },
+        setReplyTo: (messageId) => { active(); publish({ shared: { ...snapshot.shared, replyTo: messageId } }); },
+        clearHistory: () => { active(); },
+        loadEarlier: () => {
+            active();
+            if (paging)
+                return paging;
+            if (!before)
+                return Promise.resolve();
+            const cursor = before;
+            publish({ history: { kind: 'loading', entries: [], hasMore: true } });
+            paging = source.history(id, { before: cursor, limit }).then(page => {
+                if (page.before === cursor)
+                    throw new Error('Channel history cursor did not progress');
+                before = page.before;
+                merge(page.messages, true);
+                publish({ history: { kind: 'ready', entries: [], hasMore: before !== undefined } });
+            }).catch(error => publish({ history: { kind: 'error', entries: [], hasMore: true, error } })).finally(() => { paging = undefined; });
+            return paging;
+        },
+        connect: () => {
+            active();
+            if (opening)
+                return opening;
+            if (unsubscribe)
+                return Promise.resolve();
+            publish({ connection: { kind: 'connecting' } });
+            opening = Promise.resolve().then(async () => {
+                // Subscribe first: events arriving during the initial reads cannot fall through the history gap.
+                unsubscribe = source.subscribe(id, event, status);
+                const started = revision;
+                const members = await source.members(id);
+                if (snapshot.disposed)
+                    return;
+                if (started === revision || !snapshot.shared.members.length)
+                    publish({ shared: { ...snapshot.shared, members: structuredClone(members) } });
+                await refresh();
+                if (!snapshot.disposed)
+                    publish({ connection: { kind: snapshot.shared.status === 'live' ? 'connected' : 'reconnecting' } });
+            }).catch(error => { unsubscribe?.(); unsubscribe = undefined; publish({ connection: { kind: 'error', error } }); }).finally(() => { opening = undefined; });
+            return opening;
+        },
+        send: async (_whenBusy, input) => {
+            active();
+            const selected = input ?? snapshot.draft;
+            const files = [...snapshot.shared.files];
+            if (!selected.text.trim() && !selected.attachments?.length && !files.length)
+                return;
+            if (selected.attachments?.length)
+                throw new Error('Use shared file attachments, not native image payloads');
+            const clientId = randomUUID();
+            const mentions = snapshot.shared.members.filter(member => hasMemberMention(selected.text, member)).map(member => member.id);
+            const payload = { conversationId: id, text: selected.text, mentions, clientId, ...(snapshot.shared.replyTo ? { replyTo: snapshot.shared.replyTo } : {}), ...(files.length ? { attachments: files } : {}) };
+            const result = outbox.enqueue(clientId, payload);
+            publish({ shared: { ...snapshot.shared, files: [], replyTo: undefined }, ...(!input ? { draft: { text: '', attachments: [], version: snapshot.draft.version + 1 } } : {}), send: { kind: 'submitting' } });
+            sendOne(clientId, payload);
+            try {
+                const message = await result;
+                publish({ send: { kind: 'admitted' } });
+                return message;
+            }
+            catch (error) {
+                if (!snapshot.disposed && error instanceof ChannelRequestError && error.refused) {
+                    const current = snapshot.draft;
+                    publish({ send: { kind: 'blocked', reason: error.message }, draft: { ...current, text: [input?.restore?.text ?? selected.text, current.text].filter(Boolean).join('\n'), version: current.version + 1 },
+                        shared: { ...snapshot.shared, files: [...files, ...snapshot.shared.files], replyTo: snapshot.shared.replyTo ?? payload.replyTo } });
+                }
+                return undefined;
+            }
+        },
+        reconcile: async () => {
+            active();
+            await refresh();
+            for (const call of outbox.values()) {
+                const message = snapshot.shared.messages.find(message => message.clientId === call.input.clientId);
+                if (message)
+                    acknowledge(message);
+            }
+        },
+        retrySameRequest: async () => { active(); replay(); },
+        stop: async () => { throw new Error('Only the host controls when an agent speaks'); },
+        dispose: async () => {
+            if (snapshot.disposed)
+                return;
+            unsubscribe?.();
+            unsubscribe = undefined;
+            for (const call of outbox.values())
+                call.reject(new Error('Shared chat disposed'));
+            outbox.clear();
+            replayable.clear();
+            snapshot = Object.freeze({ ...snapshot, disposed: true, connection: { kind: 'closed' } });
+            for (const listener of [...listeners])
+                listener();
+            listeners.clear();
+            return undefined;
+        },
+        action: (card) => card.action ? source.action({ conversationId: id, requestId: card.requestId, actionId: card.action.id }) : Promise.resolve(),
+        remove: source.remove && source.canRemove ? (message) => source.canRemove?.(message) === true ? source.remove(message.id) : Promise.reject(new Error('Removal refused')) : undefined,
+        canRemove: (message) => Boolean(source.remove && source.canRemove?.(message)),
+    };
+    return controller;
+}
+/** The composer uses the existing quoted @ token grammar. Tokens carry stable member ids; picker labels show names. */
+export function memberMention(member) {
+    return /[\s"\\]/.test(member.id) ? `@"${member.id.replace(/[\\"]/g, '\\$&')}"` : `@${member.id}`;
+}
+function hasMemberMention(text, member) {
+    const token = memberMention(member);
+    return [...text.matchAll(/(^|\s)(@"(?:[^"\\]|\\.)*"|@[^\s]+)/g)].some(match => match[2] === token);
+}
+export { createFakeChannelSource } from './fake.js';
+export { createChannelSocket } from './socket.js';

package/dist/shared-chat/socket.d.ts

@@ -0,0 +1,20 @@
+import type { ChannelSource } from './source.js';
+type Routes = Pick<ChannelSource, 'conversations' | 'members' | 'history' | 'send' | 'action' | 'remove' | 'canRemove'>;
+export interface ChannelSocketOptions {
+    /** App URL, for example `https://app.example/`. RPC lives under `_channel`; `me` supplies the live space. */
+    readonly url: string | URL;
+    readonly fetch?: (request: Request) => Promise<Response>;
+    /** Host HTTP functions override the default routes independently. */
+    readonly routes?: Partial<Routes>;
+    /** Host subprotocol authentication may be supplied here. Closing a viewer closes only its own socket. */
+    readonly open?: (url: URL) => WebSocket;
+    readonly reconnectMs?: number;
+}
+export interface ChannelSocketSource extends ChannelSource {
+    readonly space: string;
+    readonly join: () => Promise<void>;
+}
+/** The platform app host's POST `_channel/<op>` and space WebSocket. Policy and identity remain at that host. */
+export declare function createChannelSocket(options: ChannelSocketOptions): Promise<ChannelSocketSource>;
+export {};
+//# sourceMappingURL=socket.d.ts.map

package/dist/shared-chat/socket.js

@@ -0,0 +1,114 @@
+import { z } from 'zod';
+import { randomUUID } from '@hachej/boring-files/platform';
+import { ChannelRequestError } from './error.js';
+const member = z.object({ id: z.string(), name: z.string(), kind: z.enum(['person', 'agent', 'admin']), role: z.union([z.enum(['owner', 'validator', 'member', 'admin']), z.templateLiteral(['agent:', z.string()])]).optional(), avatarUrl: z.string().optional(), presence: z.enum(['here', 'away']).optional() });
+const conversation = z.object({ id: z.string(), title: z.string(), kind: z.string(), members: z.array(z.string()) });
+const step = z.object({ label: z.string(), detail: z.string().optional(), status: z.enum(['running', 'done', 'failed']) });
+const message = z.object({ id: z.string(), conversationId: z.string(), author: z.string(), at: z.string(), via: z.string().optional(), text: z.string().optional(),
+    card: z.object({ requestId: z.string(), title: z.string(), line: z.string(), since: z.string().optional(), state: z.string().optional(), action: z.object({ id: z.string(), label: z.string() }).optional() }).optional(),
+    mentions: z.array(z.string()).optional(), replyTo: z.string().optional(), attachments: z.array(z.object({ path: z.string(), title: z.string().optional() })).optional(), steps: z.array(step).optional(), streaming: z.boolean().optional(),
+    removed: z.object({ by: z.string(), at: z.string() }).optional(), clientId: z.string().optional() });
+const event = z.discriminatedUnion('type', [z.object({ type: z.literal('message'), message }),
+    z.object({ type: z.literal('delta'), messageId: z.string(), conversationId: z.string(), text: z.string() }),
+    z.object({ type: z.literal('step'), messageId: z.string(), conversationId: z.string(), index: z.number().int().nonnegative(), step }),
+    z.object({ type: z.literal('presence'), members: z.array(z.object({ id: z.string(), presence: z.enum(['here', 'away']) })) }),
+    z.object({ type: z.literal('members'), conversationId: z.string(), members: z.array(member) })]);
+/** The platform app host's POST `_channel/<op>` and space WebSocket. Policy and identity remain at that host. */
+export async function createChannelSocket(options) {
+    const base = new URL(options.url, globalThis.location?.href);
+    base.pathname = base.pathname.replace(/\/$/, '') + '/';
+    const request = options.fetch ?? (request => globalThis.fetch(request));
+    const url = (path) => new URL(path, base);
+    const failure = z.object({ error: z.object({ code: z.string(), message: z.string(), retryable: z.boolean() }) });
+    async function rpc(op, input = {}) {
+        let response;
+        try {
+            response = await request(new Request(url(`_channel/${op}`), { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(input) }));
+        }
+        catch (error) {
+            throw new ChannelRequestError('network', error instanceof Error ? error.message : 'Channel connection was lost', true);
+        }
+        const body = await response.json().catch(() => undefined);
+        const rejected = failure.safeParse(body);
+        if (rejected.success) {
+            const error = rejected.data.error;
+            throw new ChannelRequestError(error.code, error.message, error.retryable, { refused: true });
+        }
+        if (!response.ok || body === undefined)
+            throw new ChannelRequestError('invalid-response', `Channel ${op} returned an invalid response (${response.status})`, false);
+        return body;
+    }
+    const bootstrap = z.object({ space: z.string().min(1), me: member }).parse(await rpc('me'));
+    const space = bootstrap.space, me = bootstrap.me;
+    return {
+        me, space,
+        conversations: options.routes?.conversations ?? (async () => z.array(conversation).parse(await rpc('conversations'))),
+        members: options.routes?.members ?? (async (conversationId) => z.array(member).parse(await rpc('members', { conversationId }))),
+        history: options.routes?.history ?? (async (conversationId, opts) => z.object({ messages: z.array(message), before: z.string().optional() }).parse(await rpc('history', { conversationId, ...opts }))),
+        send: options.routes?.send ?? (async (input) => {
+            if (input.attachments?.length)
+                throw new ChannelRequestError('unsupported-attachments', 'File attachments are not available here.', false, { refused: true });
+            const { conversationId, text, mentions, replyTo, clientId } = input;
+            return message.parse(await rpc('send', { conversationId, text, mentions, ...(replyTo === undefined ? {} : { replyTo }), clientId, idempotencyKey: clientId }));
+        }),
+        action: options.routes?.action ?? (async (input) => { await rpc('action', { ...input, idempotencyKey: randomUUID() }); }),
+        remove: options.routes?.remove ?? (async (messageId) => { await rpc('remove', { messageId }); }),
+        join: async () => { z.object({ space: z.string() }).parse(await rpc('join')); },
+        ...(options.routes?.canRemove ? { canRemove: options.routes.canRemove } : {}),
+        subscribe: (id, onEvent, onStatus) => {
+            let disposed = false, socket, retry, attempt = 0;
+            function connect() {
+                if (disposed)
+                    return;
+                onStatus?.('reconnecting');
+                const target = url(`spaces/${encodeURIComponent(space)}/live`);
+                target.protocol = target.protocol === 'https:' ? 'wss:' : 'ws:';
+                let current;
+                try {
+                    current = (options.open ?? (url => new WebSocket(url)))(target);
+                }
+                catch {
+                    lost();
+                    return;
+                }
+                socket = current;
+                current.onopen = () => { if (!disposed && current === socket) {
+                    attempt = 0;
+                    onStatus?.('live');
+                } };
+                current.onmessage = frame => {
+                    if (disposed || current !== socket || typeof frame.data !== 'string')
+                        return;
+                    const parsed = event.safeParse((() => { try {
+                        return JSON.parse(frame.data);
+                    }
+                    catch {
+                        return undefined;
+                    } })());
+                    if (parsed.success) {
+                        const update = parsed.data;
+                        if (update.type === 'presence' || (update.type === 'message' ? update.message.conversationId : update.conversationId) === id)
+                            onEvent(update);
+                    }
+                    else {
+                        current.close(1002, 'Invalid channel event');
+                    }
+                };
+                current.onerror = () => current.close();
+                current.onclose = () => { if (!disposed && current === socket) {
+                    socket = undefined;
+                    lost();
+                } };
+            }
+            function lost() {
+                if (disposed)
+                    return;
+                onStatus?.('offline');
+                clearTimeout(retry);
+                retry = setTimeout(connect, Math.min(30000, (options.reconnectMs ?? 1000) * 2 ** attempt++));
+            }
+            connect();
+            return () => { disposed = true; clearTimeout(retry); const current = socket; socket = undefined; current?.close(); };
+        },
+    };
+}

package/dist/shared-chat/source.d.ts

@@ -0,0 +1,117 @@
+export type Member = {
+    id: string;
+    name: string;
+    kind: 'person' | 'agent' | 'admin';
+    role?: 'owner' | 'validator' | 'member' | 'admin' | `agent:${string}`;
+    avatarUrl?: string;
+    presence?: 'here' | 'away';
+};
+export type Conversation = {
+    id: string;
+    title: string;
+    kind: 'main' | 'admin' | 'direct' | string;
+    members: string[];
+};
+export type Card = {
+    requestId: string;
+    title: string;
+    line: string;
+    since?: string;
+    state?: string;
+    action?: {
+        id: string;
+        label: string;
+    };
+};
+export type Step = {
+    label: string;
+    detail?: string;
+    status: 'running' | 'done' | 'failed';
+};
+export type AvatarState = 'working' | 'thinking' | 'waiting' | 'blocked' | 'done' | 'neutral';
+/** Host lifecycle ids affect presentation only. Missing and unknown ids have no indicator. */
+export declare const channelAvatarStates: Readonly<Record<string, AvatarState | undefined>>;
+export type ChannelMessage = {
+    id: string;
+    conversationId: string;
+    author: string;
+    at: string;
+    via?: string;
+    text?: string;
+    card?: Card;
+    mentions?: string[];
+    replyTo?: string;
+    attachments?: {
+        path: string;
+        title?: string;
+    }[];
+    steps?: Step[];
+    streaming?: boolean;
+    removed?: {
+        by: string;
+        at: string;
+    };
+    clientId?: string;
+};
+export type ChannelEvent = {
+    type: 'message';
+    message: ChannelMessage;
+} | {
+    type: 'delta';
+    messageId: string;
+    conversationId: string;
+    text: string;
+} | {
+    type: 'step';
+    messageId: string;
+    conversationId: string;
+    index: number;
+    step: Step;
+} | {
+    type: 'presence';
+    members: {
+        id: string;
+        presence: 'here' | 'away';
+    }[];
+} | {
+    type: 'members';
+    conversationId: string;
+    members: Member[];
+};
+export interface ChannelSource {
+    readonly me: Member;
+    readonly conversations: () => Promise<Conversation[]>;
+    readonly members: (conversationId: string) => Promise<Member[]>;
+    readonly history: (conversationId: string, opts: {
+        before?: string;
+        limit: number;
+    }) => Promise<{
+        messages: ChannelMessage[];
+        before?: string;
+    }>;
+    readonly send: (input: {
+        conversationId: string;
+        text: string;
+        mentions: string[];
+        replyTo?: string;
+        clientId: string;
+        attachments?: File[];
+    }) => Promise<ChannelMessage>;
+    readonly action: (input: {
+        conversationId: string;
+        requestId: string;
+        actionId: string;
+    }) => Promise<void>;
+    readonly remove?: (messageId: string) => Promise<void>;
+    readonly canRemove?: (message: ChannelMessage) => boolean;
+    readonly subscribe: (conversationId: string, onEvent: (event: ChannelEvent) => void, onStatus?: (status: 'live' | 'reconnecting' | 'offline') => void) => () => void;
+}
+export interface SharedChatState {
+    readonly me: Member;
+    readonly members: readonly Member[];
+    readonly messages: readonly ChannelMessage[];
+    readonly files: readonly File[];
+    readonly replyTo: string | undefined;
+    readonly status: 'live' | 'reconnecting' | 'offline';
+}
+//# sourceMappingURL=source.d.ts.map

package/dist/shared-chat/source.js

@@ -0,0 +1,6 @@
+/** Host lifecycle ids affect presentation only. Missing and unknown ids have no indicator. */
+export const channelAvatarStates = Object.freeze({
+    building: 'working', executing: 'working', checks: 'working', asked: 'thinking',
+    question: 'waiting', answer: 'waiting', review: 'waiting', preview: 'waiting',
+    platform: 'blocked', fixing: 'blocked', live: 'done', declined: 'neutral',
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hachej/boring-ui-kit",
-  "version": "0.4.3",
+  "version": "0.4.4",
   "license": "MIT",
   "private": false,
   "type": "module",
@@ -55,6 +55,10 @@
       "types": "./dist/native-chat.d.ts",
       "import": "./dist/native-chat.js"
     },
+    "./shared-chat": {
+      "types": "./dist/shared-chat/index.d.ts",
+      "import": "./dist/shared-chat/index.js"
+    },
     "./remote-chat": {
       "types": "./dist/remote-chat.d.ts",
       "import": "./dist/remote-chat.js"
@@ -111,10 +115,18 @@
       "types": "./dist/file-tree-view.d.ts",
       "import": "./dist/file-tree-view.js"
     },
-    "./file-tree.css": "./styles/file-tree.css"
+    "./file-tree.css": "./styles/file-tree.css",
+    "./markdown-quote": {
+      "types": "./dist/markdown-quote.d.ts",
+      "import": "./dist/markdown-quote.js"
+    },
+    "./mark-store": {
+      "types": "./dist/mark-store.d.ts",
+      "import": "./dist/mark-store.js"
+    }
   },
   "peerDependencies": {
-    "@hachej/boring-files": "^0.4.3",
+    "@hachej/boring-files": "^0.4.4",
     "@earendil-works/pi-durable": "~1.2.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",

package/r/agent-target.json

@@ -0,0 +1,36 @@
+{
+  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
+  "name": "agent-target",
+  "title": "Point and dictate on app data",
+  "description": "Tap explicitly marked JSON app context, dictate once and show the same app agent’s native reply without opening chat. Host-controlled presentation; no feedback report or second controller.",
+  "dependencies": [
+    "@hachej/boring-ui-kit@^0.4.4",
+    "@hachej/boring-feedback@^0.4.4",
+    "@earendil-works/pi-durable@~1.2.0",
+    "react@^19.0.0",
+    "react-dom@^19.0.0"
+  ],
+  "registryDependencies": [
+    "https://cdn.jsdelivr.net/npm/@hachej/boring-ui-kit@0.4.4/r/app-shell.json",
+    "https://cdn.jsdelivr.net/npm/@hachej/boring-ui-kit@0.4.4/r/pi-chat.json",
+    "button",
+    "card",
+    "message",
+    "bubble"
+  ],
+  "files": [
+    {
+      "path": "registry/agent-target/agent-target.tsx",
+      "content": "'use client';\n\n// Host presentation over the app's borrowed chat controller, not a feedback report or a second Pi lifecycle.\nimport { createPortal } from 'react-dom';\nimport { useCallback, useContext, useEffect, useLayoutEffect, useRef, useState } from 'react';\nimport type { CSSProperties } from 'react';\nimport type { EntryRecord, JsonObject, Submission } from '@earendil-works/pi-durable';\nimport type { NativeChatController } from '@hachej/boring-ui-kit/native-chat';\nimport { createPicker, createPrivacyPolicy, isExcluded } from '@hachej/boring-feedback/page';\nimport type { Picker } from '@hachej/boring-feedback/page';\nimport { Button } from '@/components/ui/button';\nimport { Card, CardContent, CardFooter, CardHeader, CardTitle } from '@/components/ui/card';\nimport { Message, MessageContent } from '@/components/ui/message';\nimport { Bubble, BubbleContent } from '@/components/ui/bubble';\nimport { useAgentLayer } from '../app-shell/agent-layer';\nimport { ScreenActiveContext } from '../app-shell/agent-context';\nimport { useDictation } from '../app-shell/use-dictation';\nimport { useVisualViewport } from '../app-shell/use-visual-viewport';\nimport { object } from '../pi-chat/rows';\nimport { agentTargetLabels } from './agent-target-labels';\nimport type { AgentTargetLabels } from './agent-target-labels';\n\nexport interface AgentTargetResult { readonly target: JsonObject; readonly reply: string; readonly ok: boolean }\nexport interface AgentTargetModeProps {\n  readonly enabled: boolean;\n  readonly transcribe: (audio: Blob, signal: AbortSignal) => Promise<string>;\n  readonly onSettled: (result: AgentTargetResult) => void;\n  readonly attribute?: string;\n  readonly labels?: Partial<AgentTargetLabels> | undefined;\n}\ntype Stage = 'dictating' | 'sending' | 'observing' | 'settled' | 'cancelled';\ninterface Session {\n  readonly target: JsonObject;\n  readonly block: string;\n  readonly element: Element;\n  readonly controller: NativeChatController;\n  readonly abort: AbortController;\n  readonly onSettled: AgentTargetModeProps['onSettled'];\n  readonly labels: AgentTargetLabels;\n  stage: Stage;\n}\ninterface Presentation { readonly element: Element; readonly stage: Stage; readonly reply: string; readonly problem?: string }\n\nfunction freeze(value: unknown): void {\n  if (value && typeof value === 'object') { for (const child of Object.values(value)) freeze(child); Object.freeze(value); }\n}\nfunction contextOf(element: Element, attribute: string, labels: AgentTargetLabels): { readonly target: JsonObject; readonly block: string } {\n  const raw = element.getAttribute(attribute) ?? '';\n  if (new TextEncoder().encode(raw).length > 1024) throw new Error(labels.contextTooLarge);\n  let target: unknown;\n  try { target = JSON.parse(raw); } catch { throw new Error(labels.invalidContext); }\n  if (!target || typeof target !== 'object' || Array.isArray(target)) throw new Error(labels.invalidContext);\n  const json = JSON.stringify(target).replace(/</g, '\\\\u003c');\n  if (new TextEncoder().encode(json).length > 1024) throw new Error(labels.contextTooLarge);\n  freeze(target);\n  return { target: target as JsonObject, block: `<target>${json}</target>` };\n}\nconst textOf = (entries: readonly EntryRecord[]): string => entries.flatMap(entry => (entry.model ?? []).flatMap(message => message.role === 'assistant'\n  ? message.content.flatMap(part => part.type === 'text' ? [part.text] : []) : [])).filter(Boolean).join('\\n\\n');\n\n/** A local observation only. Stream attribution uses native run inputs; settlement uses the native submission's exact answer entry. */\nfunction observe(session: Session, submission: Submission, show: (reply: string) => void, settle: (reply: string, ok: boolean, problem?: string) => void): void {\n  let timer: ReturnType<typeof setTimeout> | undefined;\n  const { controller, abort } = session;\n  const stream = () => {\n    if (abort.signal.aborted || session.stage !== 'observing') return;\n    const view = controller.getSnapshot().view;\n    const live = object(view?.docs['pi.live']), run = object(live?.['run']);\n    if (!Array.isArray(run?.['inputs']) || !run['inputs'].includes(submission.id)) return;\n    const generation = object(live?.['generation']), message = object(generation?.['message']);\n    const partial = Array.isArray(message?.['content']) ? message['content'].map(object).flatMap(part => part?.['type'] === 'text' && typeof part['text'] === 'string' ? [part['text']] : []).join('\\n') : '';\n    show([textOf((view?.entries ?? []).filter(entry => entry.byTaskId === run['taskId'])), partial].filter(Boolean).join('\\n\\n'));\n  };\n  const unsubscribe = controller.subscribe(stream);\n  const stop = () => { clearTimeout(timer); unsubscribe(); abort.signal.removeEventListener('abort', stop); };\n  abort.signal.addEventListener('abort', stop, { once: true });\n  const poll = async () => {\n    try {\n      const record = await controller.submissionStatus(submission);\n      if (abort.signal.aborted) return;\n      stream();\n      if (record.status === 'unanswered') { stop(); settle('', false, session.labels.unanswered); return; }\n      if (record.status === 'done' && record.type === 'input') {\n        const view = controller.getSnapshot().view;\n        const answer = view?.entries.find(entry => entry.id === record.answer);\n        if (answer) {\n          const entries = answer.byTaskId === undefined ? [answer] : view!.entries.filter(entry => entry.byTaskId === answer.byTaskId);\n          stop(); settle(textOf(entries), true); return;\n        }\n        // A coalesced watch may arrive after status. An unavailable answer stays unconfirmed, never guessed from neighbouring text.\n      }\n      if (!abort.signal.aborted) timer = setTimeout(() => { void poll(); }, 150);\n    } catch {\n      stop();\n      if (!abort.signal.aborted) settle('', false, session.labels.observationFailed);\n    }\n  };\n  stream();\n  void poll();\n}\n\n/** Tap only explicitly marked app data, dictate once and show its native answer without opening the app's chat. */\nexport function AgentTargetMode({ enabled, transcribe, onSettled, labels, attribute = 'data-agent-target' }: AgentTargetModeProps) {\n  const words = { ...agentTargetLabels, ...labels };\n  const { agent } = useAgentLayer();\n  const active = useContext(ScreenActiveContext);\n  const viewport = useVisualViewport();\n  const session = useRef<Session | null>(null);\n  const picker = useRef<Picker | null>(null);\n  const box = useRef<HTMLDivElement>(null);\n  const latest = useRef({ onSettled, words });\n  latest.current = { onSettled, words };\n  const [shown, setShown] = useState<Presentation | null>(null);\n  const [place, setPlace] = useState<CSSProperties>();\n  const settle = (selected: Session, reply: string, ok: boolean, problem?: string) => {\n    if (session.current !== selected || selected.abort.signal.aborted || selected.stage === 'settled') return;\n    selected.stage = 'settled';\n    setShown({ element: selected.element, stage: 'settled', reply, ...(problem ? { problem } : {}) });\n    selected.onSettled({ target: selected.target, reply, ok });\n  };\n  const dictation = useDictation({ transcribe, labels: words, onText: async spoken => {\n    const selected = session.current;\n    if (!selected || selected.stage !== 'dictating') return;\n    selected.stage = 'sending';\n    setShown({ element: selected.element, stage: 'sending', reply: '' });\n    let submission: Submission | undefined;\n    try {\n      await selected.controller.connect();\n      if (selected.abort.signal.aborted || session.current !== selected) return;\n      submission = await selected.controller.send('followUp', { text: `${selected.block}\\n\\n${spoken}`, restore: { text: spoken } });\n    }\n    catch {\n      if (selected.abort.signal.aborted || session.current !== selected) return;\n      const snapshot = selected.controller.getSnapshot();\n      if (!snapshot.disposed) {\n        const draft = snapshot.draft.text;\n        selected.controller.setText(`${draft}${draft && !/\\s$/.test(draft) ? ' ' : ''}${spoken}`);\n      }\n      settle(selected, '', false, snapshot.disposed ? selected.labels.unavailable : selected.labels.sendFailed);\n      return;\n    }\n    if (selected.abort.signal.aborted || session.current !== selected) return;\n    if (!submission) { settle(selected, '', false, selected.labels.unconfirmed); return; }\n    selected.stage = 'observing';\n    setShown({ element: selected.element, stage: 'observing', reply: '' });\n    observe(selected, submission, reply => {\n      if (session.current === selected && !selected.abort.signal.aborted) setShown({ element: selected.element, stage: 'observing', reply });\n    }, (reply, ok, problem) => settle(selected, reply, ok, problem));\n  } });\n  const { start, cancel: cancelDictation } = dictation;\n  const cancel = useCallback(() => {\n    const old = session.current;\n    session.current = null;\n    if (old) { old.stage = 'cancelled'; old.abort.abort(); }\n    cancelDictation();\n    picker.current?.suspend(true);\n    setShown(null);\n  }, [cancelDictation]);\n\n  useEffect(() => {\n    if (!enabled || !active || !agent) return;\n    if (!/^data-[a-z][a-z0-9-]*$/.test(attribute)) throw new TypeError('Agent target attribute must be a data-* attribute name');\n    const selector = `[${attribute}]`;\n    let pickedGesture: Element | null = null;\n    const marked = (element: Element | null) => element && !isExcluded(element) ? element.closest(selector) : null;\n    const gate = (event: Event) => {\n      const element = event.target instanceof Element ? event.target : null;\n      if (event.type === 'pointerdown') pickedGesture = null;\n      if (element && box.current?.contains(element)) return;\n      if (session.current || box.current) { if (event.type === 'pointerdown') cancel(); return; }\n      if (element && isExcluded(element)) { picker.current?.suspend(true); return; }\n      picker.current?.suspend(!marked(element));\n    };\n    const key = (event: KeyboardEvent) => {\n      if (event.key === 'Escape' && (session.current || box.current || picker.current?.state().suspended === false)) { event.preventDefault(); event.stopImmediatePropagation(); cancel(); }\n    };\n    const click = (event: MouseEvent) => {\n      // Suspending the picker on touch pointerup removes its touchend listener. Consume only that tap's compatibility click.\n      if (pickedGesture && event.target instanceof Node && pickedGesture.contains(event.target)) { pickedGesture = null; event.preventDefault(); event.stopImmediatePropagation(); }\n    };\n    // Registered before the picker: unmarked actions remain ordinary app actions, not consumed empty picks.\n    window.addEventListener('pointerdown', gate, true);\n    window.addEventListener('pointermove', gate, true);\n    window.addEventListener('keydown', key, true);\n    window.addEventListener('click', click, true);\n    const created = createPicker({ root: document.body, policy: createPrivacyPolicy(), tap: 'pick', wheel: false, keys: 'outside-ignored',\n      hitTest: (x, y) => {\n        const top = document.elementsFromPoint(x, y).find(element => !isExcluded(element));\n        const target = marked(top ?? null);\n        return target ? [target] : [];\n      },\n      onPick: element => {\n        const target = marked(element);\n        if (!target || session.current) return;\n        pickedGesture = target;\n        created.suspend(true);\n        try {\n          const context = contextOf(target, attribute, latest.current.words);\n          session.current = { ...context, element: target, controller: agent, abort: new AbortController(), onSettled: latest.current.onSettled, labels: latest.current.words, stage: 'dictating' };\n          setShown({ element: target, stage: 'dictating', reply: '' });\n          start();\n        } catch (error) { setShown({ element: target, stage: 'settled', reply: '', problem: error instanceof Error ? error.message : latest.current.words.invalidContext }); }\n      },\n    });\n    picker.current = created;\n    void created.start();\n    created.suspend(true);\n    return () => {\n      window.removeEventListener('pointerdown', gate, true);\n      window.removeEventListener('pointermove', gate, true);\n      window.removeEventListener('keydown', key, true);\n      window.removeEventListener('click', click, true);\n      cancel();\n      created.dispose();\n      if (picker.current === created) picker.current = null;\n    };\n  }, [enabled, active, agent, attribute, start, cancel]);\n\n  useEffect(() => {\n    const selected = session.current;\n    if (dictation.problem && selected?.stage === 'dictating') settle(selected, '', false, dictation.problem);\n  }, [dictation.problem]);\n  useLayoutEffect(() => {\n    if (!shown || !box.current) return;\n    const node = box.current;\n    const measure = () => {\n      const rect = shown.element.getBoundingClientRect();\n      const topEdge = (viewport?.top ?? 0) + 8, bottom = (viewport ? viewport.top + viewport.height : window.innerHeight) - 8;\n      const height = Math.min(node.getBoundingClientRect().height, Math.max(0, bottom - topEdge));\n      const lowest = Math.max(topEdge, bottom - height);\n      const top = Math.max(topEdge, Math.min(rect.bottom + 8 + height <= bottom ? rect.bottom + 8 : rect.top - height - 8 >= topEdge ? rect.top - height - 8 : lowest, lowest));\n      const width = Math.min(Math.max(240, rect.width), window.innerWidth - 16);\n      const next = { position: 'fixed' as const, top, left: Math.min(Math.max(8, rect.left), Math.max(8, window.innerWidth - width - 8)), width, maxHeight: Math.max(0, bottom - top), overflowY: 'auto' as const };\n      setPlace(previous => JSON.stringify(previous) === JSON.stringify(next) ? previous : next);\n    };\n    measure();\n    window.addEventListener('resize', measure);\n    window.addEventListener('scroll', measure, true);\n    const observer = typeof ResizeObserver === 'undefined' ? undefined : new ResizeObserver(measure);\n    observer?.observe(node);\n    return () => { window.removeEventListener('resize', measure); window.removeEventListener('scroll', measure, true); observer?.disconnect(); };\n  }, [shown, viewport]);\n\n  if (!enabled || !active || !shown || typeof document === 'undefined') return null;\n  const phase = shown.stage === 'dictating' ? dictation.phase : shown.stage;\n  return createPortal(<Card ref={box} size=\"sm\" data-feedback-ignore=\"\" data-boring=\"agent-target\" data-testid=\"agent-target-bar\" data-phase={phase}\n    role=\"region\" aria-label={words.title} className=\"app-shell fixed z-50\" style={place}>\n    <CardHeader><CardTitle>{words.title}</CardTitle></CardHeader>\n    <CardContent>\n      {shown.problem ? <p role=\"alert\" data-testid=\"agent-target-problem\">{shown.problem}</p>\n        : shown.reply ? <Message align=\"start\"><MessageContent><Bubble variant=\"secondary\"><BubbleContent data-testid=\"agent-target-reply\" className=\"whitespace-pre-wrap\">{shown.reply}</BubbleContent></Bubble></MessageContent></Message>\n          : <p role=\"status\">{phase === 'starting' ? words.opening : phase === 'recording' ? words.listening(dictation.seconds) : phase === 'transcribing' ? words.transcribing : phase === 'settled' ? words.answered : words.waiting}</p>}\n    </CardContent>\n    <CardFooter className=\"flex gap-2\">\n      {shown.stage === 'dictating' && <Button data-testid=\"agent-target-stop\" className=\"min-h-11 min-w-11\" disabled={phase !== 'recording'} onClick={dictation.finish}>{words.stop}</Button>}\n      <Button variant=\"ghost\" data-testid=\"agent-target-close\" className=\"min-h-11 min-w-11\" onClick={cancel}>{shown.stage === 'settled' ? words.close : words.cancel}</Button>\n    </CardFooter>\n  </Card>, document.body);\n}\n",
+      "type": "registry:component",
+      "target": "components/agent-target/agent-target.tsx"
+    },
+    {
+      "path": "registry/agent-target/agent-target-labels.ts",
+      "content": "import { chatTextFor } from '../pi-chat/locale';\nimport type { DictationLabels } from '../app-shell/use-dictation';\n\nexport interface AgentTargetLabels extends DictationLabels {\n  readonly title: string;\n  readonly opening: string;\n  readonly listening: (seconds: number) => string;\n  readonly transcribing: string;\n  readonly waiting: string;\n  readonly answered: string;\n  readonly stop: string;\n  readonly cancel: string;\n  readonly close: string;\n  readonly invalidContext: string;\n  readonly contextTooLarge: string;\n  readonly observationFailed: string;\n  readonly unanswered: string;\n  readonly unavailable: string;\n  readonly sendFailed: string;\n  readonly unconfirmed: string;\n}\n\nexport const agentTargetLabels: AgentTargetLabels = {\n  ...chatTextFor(undefined).labels,\n  title: 'Talk about this item',\n  opening: 'Opening microphone…',\n  listening: seconds => `Listening… ${seconds}s`,\n  transcribing: 'Transcribing…',\n  waiting: 'Waiting for the agent…',\n  answered: 'Request answered.',\n  stop: 'Stop and send',\n  cancel: 'Cancel',\n  close: 'Close',\n  invalidContext: 'Target context must be a JSON object.',\n  contextTooLarge: 'Target context exceeds 1 KB.',\n  observationFailed: 'Could not confirm the reply. Open chat to check it.',\n  unanswered: 'The agent did not answer this request.',\n  unavailable: 'The chat is no longer available.',\n  sendFailed: 'The request could not be sent. Your words are in the chat draft.',\n  unconfirmed: 'The request was not confirmed. Check the chat before trying again.',\n};\n\nexport const agentTargetLabelsFr: AgentTargetLabels = {\n  ...agentTargetLabels,\n  ...chatTextFor('fr').labels,\n  title: 'Parler de cet élément',\n  opening: 'Ouverture du microphone…',\n  listening: seconds => `J’écoute… ${seconds} s`,\n  transcribing: 'Transcription…',\n  waiting: 'Réponse en cours…',\n  answered: 'Demande traitée.',\n  stop: 'Arrêter et envoyer',\n  cancel: 'Annuler',\n  close: 'Fermer',\n  invalidContext: 'Le contexte doit être un objet JSON.',\n  contextTooLarge: 'Le contexte dépasse 1 Ko.',\n  observationFailed: 'Réponse non confirmée. Ouvrez la discussion pour la vérifier.',\n  unanswered: 'L’assistant n’a pas répondu à cette demande.',\n  unavailable: 'La discussion n’est plus disponible.',\n  sendFailed: 'Envoi impossible. Vos mots sont conservés dans le brouillon de la discussion.',\n  unconfirmed: 'Envoi non confirmé. Vérifiez la discussion avant de réessayer.',\n};\n",
+      "type": "registry:lib",
+      "target": "components/agent-target/agent-target-labels.ts"
+    }
+  ],
+  "type": "registry:component"
+}