zigmini 1.0.0-beta.3 → 1.1.0-beta.2

package/web/attachments.d.ts

@@ -0,0 +1,91 @@
+export interface AttachmentSpan {
+	readonly start: number;
+	readonly end: number;
+	readonly query: string;
+	readonly raw: string;
+}
+export interface OwnerDocument {
+	readonly id: string;
+	readonly grantId: string;
+	readonly name: string;
+	readonly format: "html" | "md" | "txt" | "pdf";
+	readonly bytes: number;
+	readonly sha256: string;
+	readonly readMode: "text" | "pages" | "ocr" | "native-document";
+	/** Per-grant state the server adds to message frames (absent on older servers). */
+	readonly grantRevoked?: boolean;
+}
+export interface AttachmentItem {
+	key: string;
+	id?: string;
+	revision: number;
+	state: string;
+	removed?: boolean;
+	eventRevision?: number;
+	readonly [field: string]: unknown;
+}
+export interface AttachmentDraft {
+	readonly conv: string;
+	readonly id: string;
+	items: AttachmentItem[];
+	submission: null | { id: string; state: string };
+	notice: string;
+}
+export interface AttachmentDrafts {
+	get(conv: string): AttachmentDraft;
+	reset(conv: string): AttachmentDraft;
+	update(event: { readonly conv: string; readonly data: unknown }): boolean;
+	ready(draft: AttachmentDraft): boolean;
+}
+export function attachmentQuery(text: string, caret: number): AttachmentSpan | null;
+export function replaceAttachmentQuery(text: string, span: AttachmentSpan | null): string;
+export function hostFilesSupported(snapshot: unknown): boolean;
+export function validDocument(value: unknown): value is OwnerDocument;
+export function validAttachmentStatus(value: unknown): boolean;
+export function visibleOwnerText(value: unknown): string;
+export function createAttachmentDrafts(uuid?: () => string): AttachmentDrafts;
+export class HostFileError extends Error { readonly code: string; constructor(code: string); }
+export function hostFileRequest(path: string, body?: unknown): Promise<unknown>;
+/** Ports of the sent document block: the chat's confirm dialog and the authenticated request; tests inject both. */
+export interface DocumentActions {
+	readonly request: (path: string, body?: unknown) => Promise<unknown>;
+	readonly confirm: (text: string) => boolean;
+}
+export const documentActions: DocumentActions;
+export function sentDocumentBlock(documents: unknown, actions?: DocumentActions): HTMLUListElement;
+export interface HostFileUI {
+	readonly input: HTMLTextAreaElement;
+	readonly menu: HTMLElement;
+	readonly tray: HTMLElement;
+	readonly note: HTMLElement;
+	readonly button: HTMLButtonElement;
+}
+export interface HostFileContext {
+	readonly conv: () => string;
+	readonly conversations: () => readonly string[];
+	readonly request: (path: string, body?: unknown) => Promise<unknown>;
+	readonly closeSlash: () => void;
+	readonly selected: (draft: AttachmentDraft, span: AttachmentSpan | null) => void;
+	readonly retry: (draft: AttachmentDraft) => void;
+	readonly changed?: () => void;
+	readonly locked?: () => boolean;
+}
+export interface HostFileComposer {
+	readonly drafts: AttachmentDrafts;
+	readonly visible: boolean;
+	readonly composing: boolean;
+	current(): AttachmentDraft;
+	render(): void;
+	refuseSend(reason: "limit" | "pending"): void;
+	close(): void;
+	open(span?: AttachmentSpan | null): Promise<void>;
+	choose(index: number): Promise<void>;
+	composition(active: boolean): void;
+	input(): void;
+	key(event: Pick<KeyboardEvent, "key" | "keyCode" | "isComposing" | "shiftKey">): boolean;
+	snapshot(data: unknown, connected?: boolean): void;
+	disconnect(): void;
+	event(event: { readonly conv: string; readonly data: unknown }): void;
+	ready(draft?: AttachmentDraft): boolean;
+}
+export function mountHostFiles(ui: HostFileUI, context: HostFileContext): HostFileComposer;

package/web/attachments.js

@@ -0,0 +1,422 @@
+import { registerStrings, t } from "./i18n.js";
+import strings from "./i18n/attachments.js";
+registerStrings(strings);
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const SHA = /^[0-9a-f]{64}$/;
+const MODES = ["text", "pages", "ocr", "native-document"];
+const FORMATS = ["html", "md", "txt", "pdf"];
+const positive = n => Number.isSafeInteger(n) && n > 0;
+const LETTER = /^\p{L}$/u;
+const terminal = state => ["discarded", "revoked", "bound"].includes(state);
+const MAX_DOCUMENTS = 4;
+
+/** Only an explicit, unquoted query before this caret is a selector, never a pasted path. */
+export function attachmentQuery(text, caret) {
+	const prefix = text.slice(0, caret);
+	const match = /(?:^|\s)@([^@\n]*)$/.exec(prefix);
+	if (!match) return null;
+	const start = prefix.length - match[1].length - 1;
+	let quote = "";
+	for (let i = 0; i < start; i++) {
+		if (text[i] === "\\") { i++; continue; }
+		if (text[i] === "'" && !quote && /[\p{L}\p{N}]/u.test(text[i - 1] ?? "")) continue;
+		if ("\"'`".includes(text[i])) {
+			if (quote === text[i]) quote = "";
+			else if (!quote) quote = text[i];
+		}
+	}
+	if (quote || /["'`\\]/.test(match[1])) return null;
+	return { start, end: caret, query: match[1], raw: prefix.slice(start) };
+}
+export function replaceAttachmentQuery(text, span) {
+	if (!span || text.slice(span.start, span.end) !== span.raw) return text;
+	return text.slice(0, span.start) + text.slice(span.end);
+}
+export function hostFilesSupported(snapshot) {
+	return snapshot?.capabilities?.hostFileAttachments === 1 && snapshot.notifyOnly !== true;
+}
+export function validDocument(d) {
+	return !!d && UUID.test(d.id) && UUID.test(d.grantId) && typeof d.name === "string" && d.name.length > 0
+		&& FORMATS.includes(d.format) && positive(d.bytes) && d.bytes <= 10485760 && SHA.test(d.sha256) && MODES.includes(d.readMode);
+}
+export function visibleOwnerText(data) {
+	return data?.attachmentFallback === true && Array.isArray(data.attachments) && data.attachments.length > 0
+		&& data.attachments.every(validDocument) ? "" : data?.text ?? "";
+}
+export function validAttachmentStatus(d) {
+	if (!d || !UUID.test(d.id) || typeof d.name !== "string" || !FORMATS.includes(d.format)
+		|| !positive(d.bytes) || d.bytes > 10485760 || !positive(d.revision)) return false;
+	const p = d.preparation;
+	if (!p || !Number.isSafeInteger(p.revision) || p.revision < 0) return false;
+	switch (d.state) {
+		case "snapshotting": return d.sha256 === null && d.readMode === null && p.revision === 0 && p.state === "pending";
+		case "sealed": return SHA.test(d.sha256) && d.readMode === null && p.state === "pending";
+		case "preparing": return SHA.test(d.sha256) && d.readMode === null && positive(p.revision) && p.state === "pending";
+		case "ready": case "bound": case "revoked":
+			return SHA.test(d.sha256) && MODES.includes(d.readMode) && positive(p.revision) && p.state === "ready";
+		case "error": case "discarded":
+			if (d.state === "error" && typeof d.error !== "string") return false;
+			if (d.sha256 === null && p.revision !== 0) return false;
+			return (d.sha256 === null || SHA.test(d.sha256)) && (d.readMode === null
+				? ["pending", "error", "encoding_required"].includes(p.state) && (d.state !== "error" || p.state !== "pending")
+				: SHA.test(d.sha256) && MODES.includes(d.readMode) && positive(p.revision) && p.state === "ready");
+		default: return false;
+	}
+}
+/** Mutable state is deliberately owned by exact conversation + draft, not the visible input. */
+export function createAttachmentDrafts(uuid = () => crypto.randomUUID()) {
+	const drafts = new Map();
+	return {
+		get(conv) {
+			if (!drafts.has(conv)) drafts.set(conv, { conv, id: uuid(), items: [], submission: null, notice: "" });
+			return drafts.get(conv);
+		},
+		reset(conv) { drafts.delete(conv); return this.get(conv); },
+		update(event) {
+			const draft = drafts.get(event.conv);
+			const data = event.data;
+			if (!draft || draft.id !== data?.draftId) return false;
+			const item = draft.items.find(item => item.id === data.attachmentId);
+			if (!item || terminal(item.state) || !positive(data.revision) || data.revision <= item.revision) return false;
+			// Events have no original SHA: fetch authenticated status before readiness can enable Send.
+			item.eventRevision = data.revision;
+			return true;
+		},
+		ready(draft) { return draft.items.length > 0 && draft.items.every(item => !item.removed && item.state === "ready" && validAttachmentStatus(item)); },
+	};
+}
+export class HostFileError extends Error {
+	constructor(code) { super(code); this.code = code; }
+}
+export async function hostFileRequest(path, body) {
+	const res = await fetch(path, { method: body === undefined ? "GET" : "POST", credentials: "same-origin",
+		headers: { "X-Zigmini-Host-Files": "1", ...(body === undefined ? {} : { "content-type": "application/json" }) },
+		...(body === undefined ? {} : { body: JSON.stringify(body) }), signal: AbortSignal.timeout(30000) });
+	const data = await res.json();
+	if (!res.ok) throw new HostFileError(typeof data.error === "string" ? data.error : `HTTP ${res.status}`);
+	return data;
+}
+const node = (tag, text, cls = "") => {
+	const el = document.createElement(tag); el.className = cls; if (text !== undefined) el.textContent = text; return el;
+};
+function action(text, run, disabled = false) {
+	const button = node("button", text, "text-btn"); button.type = "button"; button.disabled = disabled;
+	button.onclick = run; return button;
+}
+/** Known codes translate; an unknown server or transport code shows generic bilingual text, never the raw code. */
+const reason = (code, fallback = "documents.unknownError") => {
+	const key = `documents.${code}`; return t(key) === key ? t(fallback) : t(key);
+};
+/** A refused row explains itself with its own entry reason; gateway-wide and chip states never leak into it. */
+const entryReason = code => {
+	const key = `documents.entry.${code}`; return t(key) === key ? t("documents.disabled") : t(key);
+};
+/** A grant's revision starts at 1 and moves only when the grant is revoked (store: attachment_grants revision). */
+const GRANT_INITIAL_REVISION = 1;
+const DELIVERIES = ["consumed", "uncertain", "already_dispatched", "cancelled"];
+/** Answers after which the file is gone for good: the chip settles as unavailable and offers nothing further. */
+const SETTLED = new Set(["attachment_tombstoned", "attachment_reference_unavailable", "attachment_revoked"]);
+/** The sent block's ports: the chat's own confirm dialog and the authenticated request; tests inject both. */
+export const documentActions = { request: (path, body) => hostFileRequest(path, body), confirm: text => globalThis.confirm(text) };
+const summary = (d, ...extra) => [d.format.toUpperCase(), `${d.bytes} B`, reason(d.readMode), ...extra].filter(Boolean).join(" · ");
+export function sentDocumentBlock(documents, actions = documentActions) {
+	const list = node("ul", undefined, "document-list");
+	for (const d of (Array.isArray(documents) ? documents : []).filter(validDocument)) list.append(sentDocumentRow(d, actions));
+	return list;
+}
+/**
+ * The preserved user message keeps its chip. Revoke is the owner's own action, separate from discard and cleanup (C5): it
+ * reads the current state, revokes the grant at its revision, then shows the precise outcome and what revocation cannot
+ * take back (Q16). A revision conflict is re-read as state, never guessed.
+ */
+function sentDocumentRow(d, actions) {
+	const row = node("li", undefined, "document-chip");
+	const link = node("a", d.name); link.href = `/api/attachments/${encodeURIComponent(d.id)}/download`; link.download = d.name;
+	const meta = node("span", summary(d));
+	const revoke = action(t("documents.revoke"), () => void run());
+	revoke.setAttribute("aria-label", t("documents.revokeLabel", { name: d.name })); revoke.title = revoke.getAttribute("aria-label");
+	row.append(link, meta, revoke);
+	const read = () => actions.request(`/api/attachments/${encodeURIComponent(d.id)}`);
+	const settle = (state, note) => {
+		meta.textContent = summary(d, state); row.className = "document-chip revoked";
+		row.replaceChildren(node("strong", d.name), meta, ...(note ? [node("span", note, "document-caveat")] : []));
+	};
+	const unavailable = receipt => settle(t("documents.revoked"), [receipt ? t(`documents.delivery.${receipt.pendingDelivery}`) : "", t("documents.revokeCaveat")].filter(Boolean).join(" "));
+	async function run() {
+		if (!actions.confirm(t("documents.revokeConfirm", { name: d.name }))) return;
+		revoke.disabled = true; meta.textContent = summary(d, t("documents.revoking"));
+		try {
+			const status = await read();
+			if (!validAttachmentStatus(status) || status.id !== d.id) throw new HostFileError("invalid_attachment_status");
+			if (status.state === "revoked") { unavailable(null); return; }
+			const receipt = await actions.request(`/api/attachments/${encodeURIComponent(d.id)}/revoke`, { grantId: d.grantId, expectedRevision: GRANT_INITIAL_REVISION });
+			if (receipt?.grantId !== d.grantId || !positive(receipt.revision) || !DELIVERIES.includes(receipt.pendingDelivery) || !Array.isArray(receipt.limits)) throw new HostFileError("invalid_revoke_receipt");
+			unavailable(receipt);
+		} catch (e) {
+			if (!(e instanceof Error)) throw e;
+			const code = e.code ?? e.message;
+			if (code === "attachment_cas_conflict") {
+				const latest = await read().catch(() => null);
+				if (latest?.state === "revoked") { unavailable(null); return; }
+			}
+			if (SETTLED.has(code)) { settle(reason(code), ""); return; }
+			meta.textContent = summary(d, reason(code)); revoke.disabled = false;
+		}
+	}
+	// The server reports each message's own grant (B1-R); a same-file grant of another message is judged by its own field.
+	// An older server sends no field, and the chip then behaves as before.
+	if (d.grantRevoked === true) unavailable(null);
+	return row;
+}
+
+// allow: SIZE_OK - the scoped picker state machine and its DOM adapter are kept in the single authorized browser module.
+export function mountHostFiles(ui, context) {
+	const drafts = createAttachmentDrafts();
+	let supported = false, online = false, composing = false, queryComposing = false, committed = false, serial = 0, picker = null, painting = false;
+	const current = () => drafts.get(context.conv());
+	const notify = () => { render(); context.changed?.(); };
+	const error = (draft, e) => { if (!(e instanceof Error)) throw e; draft.notice = reason(e.code ?? e.message); notify(); };
+	/** A closed menu leaves no combobox popup and no textbox reference to it; the textarea stays a plain textbox. */
+	function close() {
+		serial++; picker = null; queryComposing = false; ui.menu.hidden = true; ui.menu.replaceChildren();
+		ui.button.setAttribute("aria-expanded", "false"); ui.input.removeAttribute("aria-controls"); ui.input.removeAttribute("aria-activedescendant");
+	}
+	async function refresh(draft, item) {
+		const result = await context.request(`/api/attachments/${encodeURIComponent(item.id)}`);
+		if (!draft.items.includes(item) || item.removed || !validAttachmentStatus(result) || result.id !== item.id
+			|| result.revision < item.revision || result.revision < (item.eventRevision ?? 0)) return;
+		if (result.state === "ready" && draft.notice === reason(item.error)) draft.notice = "";
+		delete item.error;
+		Object.assign(item, result); notify();
+	}
+	function forget(draft, item) {
+		if (draft.notice === reason(item.error)) draft.notice = "";
+		draft.items = draft.items.filter(i => i !== item);
+		// The limit notice describes the count, so it ends with it. This is the only place a draft's count falls.
+		if (draft.notice === t("documents.limit") && draft.items.length < MAX_DOCUMENTS) draft.notice = "";
+		notify();
+	}
+	async function discard(draft, item) {
+		item.removed = true;
+		// No server record yet: a settled chip leaves at once; a busy one waits for its receipt (then discards) or its failure.
+		if (!item.id) { if (!item.busy) forget(draft, item); else notify(); return; }
+		// The owner's remove always takes the chip out of the draft, so it can neither block Send nor be bound. The server
+		// record is released best-effort and never deleted here (C8): on failure it stays unbound against the staging quota.
+		forget(draft, item);
+		try {
+			const latest = await context.request(`/api/attachments/${encodeURIComponent(item.id)}`);
+			if (!validAttachmentStatus(latest) || latest.id !== item.id) throw new HostFileError("invalid_attachment_status");
+			if (latest.state === "discarded") return;
+			await context.request(`/api/attachments/${encodeURIComponent(item.id)}/discard`, { expectedRevision: latest.revision });
+		} catch (e) {
+			if ((e?.code ?? e?.message) === "attachment_not_found") return;
+			draft.notice = t("documents.discardFailed"); notify();
+		}
+	}
+	async function select(draft, item) {
+		if (item.busy) return;
+		item.busy = true; item.state = "selecting"; notify();
+		try {
+			const receipt = await context.request(`/api/host-file-pickers/${encodeURIComponent(item.pickerId)}/select`,
+				{ entryToken: item.entryToken, operationId: item.key });
+			if (!UUID.test(receipt.attachmentId) || !positive(receipt.revision)) throw new HostFileError("invalid_selection_receipt");
+			Object.assign(item, { id: receipt.attachmentId, revision: receipt.revision, state: receipt.state });
+			if (item.removed || !draft.items.includes(item)) { await discard(draft, item); return; }
+			await refresh(draft, item);
+		} catch (e) { item.state = "error"; item.error = e instanceof Error ? e.message : "selection_failed"; error(draft, e); }
+		finally { item.busy = false; notify(); }
+	}
+	function refuseSend(reason) {
+		current().notice = t(reason === "limit" ? "documents.limit" : "documents.pending");
+		notify();
+	}
+	async function choose(index) {
+		const p = picker, row = p?.entries[index], draft = current();
+		if (!p || !row?.selectable || draft.submission || composing || queryComposing || context.locked?.()) return;
+		if (row.kind === "directory") { await enter(row.entryToken); return; }
+		if (draft.items.length >= MAX_DOCUMENTS) { draft.notice = t("documents.limit"); notify(); return; }
+		const item = { key: crypto.randomUUID(), pickerId: p.id, entryToken: row.entryToken,
+			name: row.name, bytes: row.size, state: "selecting", revision: 0, removed: false };
+		draft.items.push(item); close(); ui.input.focus();
+		// The selector text is consumed now, so a receipt arriving later never touches what the owner types meanwhile.
+		context.selected(draft, p.span);
+		await select(draft, item);
+	}
+	/**
+	 * Entering a folder consumes the query: the folder lists unfiltered, the search box empties, and a typed selector keeps
+	 * only its "@" (what is typed next searches this folder). The span takes that shape first, so the composer's input
+	 * event for the rewrite finds nothing changed and lists nothing itself.
+	 */
+	async function enter(directory) {
+		const p = picker, span = p?.span; if (!p) return;
+		p.query = "";
+		if (span?.query) { p.span = { ...span, end: span.start + 1, query: "", raw: "@" }; context.selected(current(), { ...span, start: span.start + 1, raw: span.raw.slice(1) }); }
+		await list(directory);
+	}
+	async function list(directory, cursor) {
+		const p = picker; if (!p) return;
+		const ticket = ++serial; p.loading = true; p.notice = ""; renderMenu();
+		try {
+			const result = await context.request(`/api/host-file-pickers/${encodeURIComponent(p.id)}/list`,
+				{ directoryToken: directory, query: p.query, showHidden: p.hidden, ...(cursor ? { cursor } : {}) });
+			if (picker !== p || ticket !== serial) return;
+			if (!Array.isArray(result.entries) || result.entries.length > 50 || !result.entries.every(e =>
+				typeof e.entryToken === "string" && typeof e.name === "string" && typeof e.selectable === "boolean"
+				&& ["file", "directory", "disabled"].includes(e.kind))) throw new HostFileError("invalid_picker_page");
+			p.entries = result.entries;
+			p.directory = directory; p.parent = result.parentToken; p.next = result.nextCursor; p.index = p.entries.findIndex(e => e.selectable);
+		} catch (e) { if (picker === p && ticket === serial) { if (!(e instanceof Error)) throw e; p.notice = reason(e.code ?? e.message); } }
+		finally { if (picker === p && ticket === serial) { p.loading = false; renderMenu(); } }
+	}
+	async function open(span = attachmentQuery(ui.input.value, ui.input.selectionStart)) {
+		if (!supported || !online || composing || current().submission || context.locked?.()) return;
+		if (span && [...span.query].length > 200) { current().notice = t("documents.queryLong"); notify(); return; }
+		if (picker?.conv === context.conv()) {
+			// Only a changed query lists again; the composer's input event for a consumed selector finds nothing to do.
+			const query = span?.query ?? "", changed = query !== picker.query;
+			picker.span = span; picker.query = query;
+			if (picker.id && changed) await list(picker.directory);
+			return;
+		}
+		const draft = current(), ticket = ++serial;
+		picker = { conv: draft.conv, span, query: span?.query ?? "", hidden: false, entries: [], index: -1, loading: true }; renderMenu();
+		try {
+			const result = await context.request("/api/host-file-pickers", { convId: draft.conv, draftId: draft.id });
+			if (ticket !== serial || context.conv() !== draft.conv) return;
+			if (typeof result.pickerId !== "string" || typeof result.currentDirectoryToken !== "string" || !Array.isArray(result.rootEntries)) throw new HostFileError("invalid_picker");
+			Object.assign(picker, { id: result.pickerId, roots: result.rootEntries, directory: result.currentDirectoryToken });
+			await list(picker.directory);
+		} catch (e) { if (ticket === serial) { close(); error(draft, e); } }
+	}
+	function renderMenu() {
+		const p = picker; if (!p) return;
+		lift();
+		const focus = ui.menu.contains(document.activeElement) ? document.activeElement : null;
+		if (focus) p.focusTarget = { id: focus.id, tag: focus.tagName, text: focus.textContent, caret: focus.selectionStart };
+		else if (document.activeElement === ui.input) p.focusTarget = null;
+		ui.menu.hidden = false; ui.button.setAttribute("aria-expanded", "true");
+		const nav = node("div", undefined, "host-file-nav");
+		nav.append(node("strong", t("documents.title")), action(t("documents.close"), () => { close(); ui.input.focus(); }));
+		const queryLabel = node("label", t("documents.query"), "host-file-query-label");
+		const query = node("input"); query.id = "host-file-query"; query.type = "text"; query.value = p.query;
+		query.setAttribute("role", "combobox"); query.setAttribute("aria-autocomplete", "list"); query.setAttribute("aria-expanded", "true"); query.setAttribute("aria-controls", "host-file-list");
+		queryLabel.append(query); nav.append(queryLabel);
+		query.oninput = ev => {
+			if (picker !== p || ev.isComposing || queryComposing) return;
+			if ([...query.value].length > 200) { p.notice = t("documents.queryLong"); renderMenu(); return; }
+			p.query = query.value; void list(p.directory);
+		};
+		query.oncompositionstart = () => { if (picker === p) queryComposing = true; };
+		query.oncompositionend = () => { if (picker === p) { queryComposing = false; committed = true; query.dispatchEvent(new Event("input")); } };
+		query.onkeydown = ev => { if (api.key(ev)) { ev.preventDefault(); ev.stopPropagation(); if (ev.key === "Escape") ui.input.focus(); } };
+		query.onkeyup = ev => { if (!LETTER.test(ev.key ?? "")) committed = false; };
+		for (const root of (p.roots ?? [])) nav.append(action(root.name === "Home" ? t("documents.home") : root.name === "Computer" ? t("documents.computer") : root.name, () => void enter(root.entryToken), p.loading));
+		if (p.parent) nav.append(action(t("documents.parent"), () => void enter(p.parent), p.loading));
+		const hidden = node("label", t("documents.hidden")); const toggle = node("input"); toggle.id = "host-file-hidden"; toggle.type = "checkbox"; toggle.checked = p.hidden;
+		toggle.onchange = () => { p.hidden = toggle.checked; void list(p.directory); }; toggle.disabled = !p.id; hidden.prepend(toggle); nav.append(hidden);
+		const rows = node("div"); rows.id = "host-file-list"; rows.setAttribute("role", "listbox"); rows.setAttribute("aria-label", t("documents.title"));
+		p.entries.forEach((entry, i) => {
+			const row = node("div", undefined, "host-file-option"); row.id = `host-file-option-${i}`;
+			row.setAttribute("role", "option"); row.setAttribute("aria-selected", String(i === p.index)); row.setAttribute("aria-disabled", String(!entry.selectable || p.loading));
+			const name = node("span", `${entry.kind === "directory" ? "▸ " : ""}${entry.name}`); name.title = entry.name; row.append(name);
+			if (!entry.selectable) row.append(node("small", entryReason(entry.reason)));
+			row.onpointerdown = ev => { ev.preventDefault(); if (!p.loading) void choose(i); }; rows.append(row);
+		});
+		const status = node("div", p.loading ? t("documents.loading") : p.notice || (p.entries.length ? "" : t("documents.empty")), "host-file-status"); status.setAttribute("role", "status");
+		if (p.next) nav.append(action(t("documents.next"), () => void list(p.directory, p.next), p.loading));
+		if (p.notice) nav.append(action(t("documents.retry"), () => void list(p.directory)));
+		painting = true; ui.menu.replaceChildren(nav, rows, status);
+		if (p.focusTarget && (!p.loading || p.focusTarget.id)) {
+			const target = [...nav.querySelectorAll("button,input")].find(el => p.focusTarget.id ? el.id === p.focusTarget.id : el.tagName === p.focusTarget.tag && el.textContent === p.focusTarget.text);
+			target?.focus({ preventScroll: true });
+			if (target?.id === "host-file-query" && p.focusTarget.caret !== null) target.setSelectionRange(p.focusTarget.caret, p.focusTarget.caret);
+		}
+		painting = false;
+		ui.input.setAttribute("aria-controls", rows.id);
+		if (!p.loading && p.index >= 0) { ui.input.setAttribute("aria-activedescendant", `host-file-option-${p.index}`); query.setAttribute("aria-activedescendant", `host-file-option-${p.index}`); rows.children[p.index]?.scrollIntoView({ block: "nearest" }); }
+		else ui.input.removeAttribute("aria-activedescendant");
+	}
+	async function prepare(draft, item, encoding) {
+		item.prepareOperation ??= { encoding, key: crypto.randomUUID(), revision: item.revision };
+		if (item.prepareOperation.encoding !== encoding) item.prepareOperation = { encoding, key: crypto.randomUUID(), revision: item.revision };
+		const op = item.prepareOperation; item.busy = true; notify();
+		try { await context.request(`/api/attachments/${encodeURIComponent(item.id)}/prepare`, { encoding, operationId: op.key, expectedRevision: op.revision }); await refresh(draft, item); }
+		catch (e) { error(draft, e); } finally { item.busy = false; notify(); }
+	}
+	/**
+	 * Both menus float above whatever stands between the composer and the log (tray chips, the limit notice), never over
+	 * it, and never past the top of the screen: their room is what is left above that edge (less the 6px gap and an 8px
+	 * margin), so a long list scrolls inside the menu instead of pushing its header out of view.
+	 */
+	function lift() {
+		const host = ui.menu.parentElement;
+		if (!host?.getBoundingClientRect) return;
+		const top = host.getBoundingClientRect().top;
+		const above = [ui.tray, ui.note].filter(el => el.offsetParent !== null).map(el => el.getBoundingClientRect().top);
+		const edge = Math.min(top, ...above);
+		host.style.setProperty("--menu-lift", `${top - edge}px`);
+		host.style.setProperty("--menu-room", `${Math.max(0, edge - 6 - 8)}px`);
+	}
+	function render() {
+		const draft = current(); ui.button.disabled = !supported || !online || !!draft.submission || !!context.locked?.();
+		ui.button.textContent = t("documents.button"); ui.button.title = !online ? t("documents.offline") : !supported ? t("documents.unsupported") : t("documents.title");
+		ui.note.textContent = !online ? t("documents.offline") : !supported ? t("documents.unsupported") : draft.notice;
+		ui.tray.replaceChildren();
+		for (const item of draft.items) {
+			const chip = node("li", undefined, "document-chip"); chip.dataset.attachmentKey = item.key;
+			chip.append(node("strong", item.name), node("span", [item.format?.toUpperCase(), item.bytes === undefined ? "" : `${item.bytes} B`, reason(item.state), item.readMode ? reason(item.readMode) : "", item.error ? reason(item.error) : ""].filter(Boolean).join(" · ")));
+			const locked = !!draft.submission || item.busy;
+			if (item.state === "error") chip.append(action(t("documents.retry"), () => void (item.id ? refresh(draft, item).catch(e => error(draft, e)) : select(draft, item)), locked));
+			if (item.id && item.format && item.format !== "pdf" && !terminal(item.state)) {
+				const encoding = node("select"); encoding.setAttribute("aria-label", t("documents.encoding", { name: item.name })); encoding.disabled = locked;
+				encoding.append(new Option(t("documents.chooseEncoding"), ""));
+				for (const e of ["utf-8", "utf-16le", "utf-16be", "euc-kr", "cp949"]) encoding.append(new Option(e, e));
+				encoding.onchange = () => { if (encoding.value) void prepare(draft, item, encoding.value); }; chip.append(encoding);
+			}
+			const remove = action("×", () => void discard(draft, item), !!draft.submission || !!(item.removed && item.busy)); remove.setAttribute("aria-label", t("documents.remove", { name: item.name })); remove.title = remove.getAttribute("aria-label"); chip.append(remove); ui.tray.append(chip);
+		}
+		if (draft.submission) ui.tray.append(action(t("documents.retrySubmission"), () => context.retry(draft), !supported || !online || draft.submission.state !== "uncertain"));
+		lift();
+	}
+	ui.input.setAttribute("aria-autocomplete", "list"); ui.button.setAttribute("aria-expanded", "false"); ui.button.setAttribute("aria-controls", "host-file-menu");
+	ui.button.onclick = () => { context.closeSlash(); ui.input.focus(); void open(null); };
+	ui.menu.addEventListener("pointerdown", ev => { if (ev.target.closest("[role=option]")) ev.preventDefault(); });
+	ui.menu.addEventListener("keydown", ev => { if (ev.key === "Escape") { ev.preventDefault(); close(); ui.input.focus(); } });
+	ui.menu.addEventListener("focusout", ev => { if (!painting && ev.relatedTarget !== ui.input && !ui.menu.contains(ev.relatedTarget)) close(); });
+	ui.input.addEventListener("keyup", ev => { if (!LETTER.test(ev.key ?? "")) committed = false; });
+	ui.input.addEventListener("blur", () => { committed = false; });
+	if (typeof ResizeObserver === "function") { const sizes = new ResizeObserver(lift); sizes.observe(ui.tray); sizes.observe(ui.note); }
+	if (typeof window === "object" && typeof window.addEventListener === "function") window.addEventListener("resize", lift);
+	const api = {
+		drafts, current, render: notify, refuseSend, close, open, choose,
+		get visible() { return !!picker; },
+		get composing() { return composing || queryComposing; },
+		composition(active) { composing = active; committed = !active; if (active) close(); else this.input(); },
+		input() { if (composing) return; const span = attachmentQuery(ui.input.value, ui.input.selectionStart); if (span) { context.closeSlash(); void open(span); } else close(); },
+		key(ev) {
+			if (composing || queryComposing || ev.isComposing || ev.keyCode === 229 || ev.shiftKey) return false;
+			// The key that ends an IME composition can arrive after compositionend with isComposing false (Safari, WebKit 165004;
+			// Chrome on macOS with Korean input sends a second keydown). Only while this menu owns the keys (open, or an @ listing
+			// pending) does that key merely finish the composition; otherwise it is left to the composer. The flag set at
+			// compositionend is cleared by a non-letter keyup (a rolled-over letter keyup is not the committing key), by blur, or
+			// by the next distinct keydown; no timer is involved.
+			if (committed) { committed = false; if (picker) { if (ev.key === "Enter") return true; if (ev.key === "Tab") { close(); return false; } } }
+			if (!picker) return false;
+			if (ev.key === "Escape") { close(); return true; }
+			if (ev.key === "ArrowDown" || ev.key === "ArrowUp") {
+				const indices = picker.entries.flatMap((e, i) => e.selectable ? [i] : []);
+				if (indices.length) picker.index = indices[(indices.indexOf(picker.index) + (ev.key === "ArrowDown" ? 1 : -1) + indices.length) % indices.length];
+				renderMenu(); return true;
+			}
+			if (ev.key === "Tab" && (picker.loading || picker.index < 0)) { close(); return false; }
+			if (ev.key === "Enter" || ev.key === "Tab") { if (!picker.loading) void choose(picker.index); return true; }
+			return false;
+		},
+		snapshot(data, connected = true) { supported = hostFilesSupported(data); online = connected; close(); notify(); },
+		disconnect() { online = false; supported = false; close(); for (const conv of context.conversations()) { const s = drafts.get(conv).submission; if (s) s.state = "uncertain"; } notify(); },
+		event(event) { if (drafts.update(event)) { const draft = drafts.get(event.conv), item = draft.items.find(i => i.id === event.data.attachmentId); void refresh(draft, item).catch(e => error(draft, e)); } },
+		ready(draft = current()) { return supported && online && (draft.items.length === 0 || drafts.ready(draft)); },
+	};
+	return api;
+}

package/web/collaboration.d.ts

@@ -0,0 +1,87 @@
+export const REQUESTS_PATH: string;
+export const ARTIFACTS_PATH: string;
+export const REQUEST_STATES: readonly RequestState[];
+export const TERMINAL_STATES: readonly RequestState[];
+
+export type RequestState = "queued" | "running" | "waiting_peer" | "waiting_owner" | "result_preparing" | "completed" | "failed" | "interrupted" | "cancel_requested" | "cancelled" | "unresolved_delivery" | "version_conflict";
+export type RequestKind = "task" | "question";
+export type StateTone = "ok" | "busy" | "warn" | "danger";
+
+export interface CardActor { readonly kind: "main" | "agent"; readonly id: string | null }
+export interface ResultFile { readonly artifactId: string; readonly name: string; readonly bytes: number | null; readonly sha256: string | null; readonly mediaType: string | null }
+export interface CardResult { readonly resultId: string | null; readonly text: string; readonly files: ResultFile[] }
+/** One request as the open conversation knows it from its events and the owner listing. */
+export interface Card {
+	readonly requestId: string;
+	readonly rootId: string | null;
+	readonly kind: RequestKind | null;
+	readonly text: string | null;
+	readonly files: string[];
+	readonly actor: CardActor | null;
+	/** The recipient agent of a sent request, from the owner listing; null until listed (F3 D5). */
+	readonly targetAgent: string | null;
+	readonly outgoing: boolean | null;
+	readonly seq: number | null;
+	readonly ts: string | null;
+	readonly state: string | null;
+	readonly revision: number | null;
+	readonly resultId: string | null;
+	readonly result: CardResult | null;
+	readonly replied: boolean;
+	readonly blocked: string | null;
+	readonly deliveryUnknown: boolean;
+	readonly listed: boolean;
+}
+export type Cards = Map<string, Card>;
+
+export interface StoredEventLike { readonly type: string; readonly seq?: number; readonly ts?: string; readonly conv?: string; readonly data?: unknown }
+export interface EventOutcome { readonly cards: Cards; readonly requestId: string | null; readonly change: "created" | "updated" | null; readonly notice: string | null }
+
+/** True for the gateway's C-4 `notice {kind:"collaboration",requestId,direction}`, which the card already shows. */
+export function isCollaborationFallback(event: StoredEventLike | null | undefined): boolean;
+
+export interface CardNote { readonly text: string; readonly error: boolean }
+export interface CardView {
+	readonly requestId: string;
+	readonly outgoing: boolean;
+	readonly from: string;
+	readonly to: string;
+	readonly ts: string | null;
+	readonly title: string;
+	readonly kind: RequestKind | null;
+	readonly kindLabel: string | null;
+	readonly state: string | null;
+	readonly stateLabel: string;
+	readonly tone: StateTone;
+	readonly uncertain: boolean;
+	readonly text: string;
+	readonly inputs: { readonly artifactId: string; readonly name: string; readonly bytes: null; readonly sha256: null }[];
+	readonly result: { readonly text: string; readonly files: (ResultFile & { readonly size: string })[] } | null;
+	readonly replied: boolean;
+	readonly cancellable: boolean;
+	readonly notes: CardNote[];
+}
+export interface CardContext { readonly agents: readonly { readonly id: string; readonly name: string }[] | null; readonly agentId: string | null; readonly mainName: string }
+
+export interface ApiRequest { readonly method: string; readonly path: string; readonly headers?: Record<string, string>; readonly body?: string }
+export interface CancelOutcome { readonly ok: boolean; readonly state: string | null; readonly revision: number | null; readonly line: string }
+export interface Outcome { readonly ok: boolean; readonly line: string }
+export interface TargetOption { readonly id: string; readonly name: string; readonly checked: boolean; readonly missing: boolean | null }
+export interface FileOriginTag { readonly origin: "user-upload" | "collaboration-copy"; readonly text: string; readonly tip: string }
+
+export function isTerminal(state: unknown): boolean;
+export function emptyCards(): Cards;
+export function applyCollaborationEvent(cards: Cards, event: StoredEventLike): EventOutcome;
+export function mergeRequestListing(cards: Cards, listing: unknown): { readonly cards: Cards; readonly changed: string[] };
+export function stateTone(state: string | null): StateTone;
+export function stateLabel(state: string | null): string;
+export function cardView(card: Card, ctx: CardContext): CardView;
+export function cancelRequest(card: Card | null | undefined): ApiRequest | null;
+export function listingRequest(conv: string): ApiRequest;
+export function artifactPath(artifactId: string): string;
+export function cancelOutcome(status: number, body: unknown): CancelOutcome;
+export function downloadOutcome(name: string, status: number, body: unknown, digests: { readonly expected: string | null; readonly header: string | null; readonly computed: string | null }): Outcome;
+export function listingOutcome(status: number, body: unknown): Outcome;
+export function targetOptions(agents: unknown, selfId: string | null, saved: unknown): { readonly loaded: boolean; readonly options: TargetOption[] };
+export function fileOriginLabel(row: { readonly origin?: string | null } | null | undefined): FileOriginTag | null;
+export function fileDeleteText(row: { readonly origin?: string | null } | null | undefined): string;