@hachej/boring-ui-kit 0.4.2 → 0.4.4

package/dist/shared-chat/fake.js

@@ -0,0 +1,90 @@
+import { ChannelRequestError } from './error.js';
+/** Fictional in-memory host. The controls exercise exactly the source events a real host delivers. */
+export function createFakeChannelSource(seed) {
+    const data = structuredClone(seed);
+    const listeners = new Set();
+    const sends = [], actions = [];
+    let online = true;
+    function emit(event) {
+        if (event.type === 'message') {
+            const index = data.messages.findIndex(message => message.id === event.message.id);
+            if (index < 0)
+                data.messages.push(structuredClone(event.message));
+            else
+                data.messages[index] = structuredClone(event.message);
+        }
+        else if (event.type === 'delta') {
+            const message = data.messages.find(message => message.id === event.messageId && message.conversationId === event.conversationId);
+            if (message) {
+                message.text = (message.text ?? '') + event.text;
+                message.streaming = true;
+            }
+        }
+        else if (event.type === 'step') {
+            const message = data.messages.find(message => message.id === event.messageId && message.conversationId === event.conversationId);
+            if (message && Number.isSafeInteger(event.index) && event.index >= 0) {
+                const steps = [...(message.steps ?? [])];
+                steps[event.index] = { ...event.step };
+                message.steps = steps;
+            }
+        }
+        else if (event.type === 'presence')
+            for (const update of event.members) {
+                const member = data.members.find(member => member.id === update.id);
+                if (member)
+                    member.presence = update.presence;
+            }
+        else if (event.type === 'members') {
+            for (const member of event.members) {
+                const index = data.members.findIndex(existing => existing.id === member.id);
+                if (index < 0)
+                    data.members.push(structuredClone(member));
+                else
+                    data.members[index] = structuredClone(member);
+            }
+            const conversation = data.conversations.find(conversation => conversation.id === event.conversationId);
+            if (conversation)
+                conversation.members = event.members.map(member => member.id);
+        }
+        if (online)
+            for (const listener of [...listeners]) {
+                const id = event.type === 'message' ? event.message.conversationId : event.type === 'presence' ? undefined : event.conversationId;
+                if (id === undefined || id === listener.id)
+                    listener.event(structuredClone(event));
+            }
+    }
+    return {
+        me: data.me,
+        conversations: async () => structuredClone(data.conversations),
+        members: async (id) => structuredClone(data.members.filter(member => data.conversations.find(conversation => conversation.id === id)?.members.includes(member.id))),
+        history: async (id, opts) => {
+            const all = data.messages.filter(message => message.conversationId === id);
+            const end = opts.before ? all.findIndex(message => message.id === opts.before) : all.length;
+            if (end < 0)
+                throw new Error('Unknown history cursor');
+            const start = Math.max(0, end - opts.limit);
+            return { messages: structuredClone(all.slice(start, end)), ...(start > 0 && all[start] ? { before: all[start].id } : {}) };
+        },
+        send: async (input) => {
+            sends.push({ ...input, mentions: [...input.mentions], ...(input.attachments ? { attachments: [...input.attachments] } : {}) });
+            if (!online)
+                throw new ChannelRequestError('offline', 'Offline', true);
+            const duplicate = data.messages.find(message => message.clientId === input.clientId && message.conversationId === input.conversationId);
+            if (duplicate)
+                return structuredClone(duplicate);
+            const message = { id: `sent-${input.clientId}`, conversationId: input.conversationId, author: data.me.id, at: new Date().toISOString(), text: input.text, mentions: [...input.mentions], clientId: input.clientId, ...(input.replyTo ? { replyTo: input.replyTo } : {}) };
+            emit({ type: 'message', message });
+            return structuredClone(message);
+        },
+        action: async (input) => { actions.push(structuredClone(input)); },
+        subscribe: (id, event, status) => {
+            const listener = { id, event, status };
+            listeners.add(listener);
+            status?.(online ? 'live' : 'offline');
+            return () => { listeners.delete(listener); };
+        },
+        emit, sends, actions,
+        setStatus: (status) => { online = status === 'live'; for (const listener of [...listeners])
+            listener.status?.(status); },
+    };
+}

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

@@ -0,0 +1,51 @@
+import type { ChatAttempt, ChatDraft, ChatSendInput, NativeChatSnapshot } from '../native-chat.js';
+export { ChannelRequestError } from './error.js';
+import type { Card, ChannelMessage, ChannelSource, Member, SharedChatState } from './source.js';
+export type * from './source.js';
+export { channelAvatarStates } from './source.js';
+export type SharedChatSnapshot = Omit<NativeChatSnapshot, 'conversationId' | 'send' | 'shared'> & {
+    readonly conversationId: string;
+    readonly shared: SharedChatState;
+    readonly send: {
+        readonly kind: 'idle' | 'submitting' | 'admitted';
+    } | {
+        readonly kind: 'unknown';
+        readonly reason: string;
+        readonly retryable: boolean;
+    } | {
+        readonly kind: 'blocked';
+        readonly reason: string;
+    };
+};
+export type { ChatController, ChatSnapshot } from '../native-chat.js';
+/** Host-owned multi-party log, not a Pi conversation or an agent runtime. One adapter per selected conversation. */
+export declare function createSharedChat(source: ChannelSource, options: {
+    readonly conversationId: string;
+    readonly limit?: number;
+}): {
+    getSnapshot: () => SharedChatSnapshot;
+    subscribe: (listener: () => void) => () => void;
+    setText: (text: string) => void;
+    setAttachments: (attachments: ChatDraft["attachments"]) => void;
+    setFiles: (files: readonly File[]) => void;
+    setReplyTo: (messageId: string | undefined) => void;
+    clearHistory: () => void;
+    loadEarlier: () => Promise<void>;
+    connect: () => Promise<void>;
+    send: (_whenBusy?: ChatAttempt["whenBusy"], input?: ChatSendInput) => Promise<ChannelMessage | undefined>;
+    reconcile: () => Promise<void>;
+    retrySameRequest: () => Promise<void>;
+    stop: () => Promise<never>;
+    dispose: () => Promise<undefined>;
+    action: (card: Card) => Promise<void>;
+    remove: ((message: ChannelMessage) => Promise<void>) | undefined;
+    canRemove: (message: ChannelMessage) => boolean;
+};
+export type SharedChatController = ReturnType<typeof createSharedChat>;
+/** The composer uses the existing quoted @ token grammar. Tokens carry stable member ids; picker labels show names. */
+export declare function memberMention(member: Member): string;
+export { createFakeChannelSource } from './fake.js';
+export type { FakeChannelSeed } from './fake.js';
+export { createChannelSocket } from './socket.js';
+export type { ChannelSocketOptions, ChannelSocketSource } from './socket.js';
+//# sourceMappingURL=index.d.ts.map

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