@oddkin/ai 0.0.0-stage → 1.0.0-beta.1

package/dist/controllers/composer.js

@@ -0,0 +1,291 @@
+/**
+ * `ComposerController` — draft, attachments, and submission state for a prompt composer.
+ * Tracks draft revisions so acknowledging an older submission never clears newer input, keeps
+ * the draft through failures, and owns only the object URLs it created. DOM-free (File and
+ * URL APIs are used only when called). Contract: docs/architecture/ai-interaction.md §8.1.
+ */
+import { signal } from '@oddkin/core/reactive';
+import { createId } from '../internal/ids.js';
+const BUSY = new Set(['uploading', 'processing']);
+export function matchesAccept(file, accept) {
+    if (!accept.length)
+        return true;
+    const name = file.name.toLowerCase();
+    const type = file.type.toLowerCase();
+    return accept.some((raw) => {
+        const pattern = raw.trim().toLowerCase();
+        if (!pattern)
+            return false;
+        if (pattern.startsWith('.'))
+            return name.endsWith(pattern);
+        if (pattern.endsWith('/*'))
+            return type.startsWith(pattern.slice(0, -1));
+        return type === pattern;
+    });
+}
+export class ComposerController {
+    #state;
+    state;
+    #files = new Map();
+    #ownedUrls = new Set();
+    #options;
+    #disposed = false;
+    constructor(options = {}) {
+        this.#options = options;
+        this.#state = signal({ text: '', revision: 0, attachments: [], issues: [] });
+        this.state = this.#state;
+    }
+    getSnapshot() {
+        return this.#state.peek();
+    }
+    configure(options) {
+        this.#options = { ...this.#options, ...options };
+    }
+    /** Replace the draft text (user edit or host restore). Increments the draft revision. */
+    setText(text) {
+        const now = this.#state.peek();
+        if (now.text === text)
+            return;
+        this.#set({ ...now, text, revision: now.revision + 1 });
+    }
+    /** Validate and add files. Rejected files are reported in `issues` and never added. */
+    addFiles(files) {
+        const now = this.#state.peek();
+        const issues = [];
+        const added = [];
+        if (this.#options.attachments === false) {
+            for (const file of files)
+                issues.push({ code: 'ai.attachment.unavailable', name: file.name });
+            this.#set({ ...now, issues });
+            return added;
+        }
+        const max = this.#options.maxFiles ?? Infinity;
+        let count = now.attachments.length;
+        for (const file of files) {
+            if (!matchesAccept(file, this.#options.accept ?? [])) {
+                issues.push({
+                    code: 'ai.attachment.type',
+                    name: file.name,
+                    limit: (this.#options.accept ?? []).join(', '),
+                });
+                continue;
+            }
+            if (this.#options.maxFileSize !== undefined && file.size > this.#options.maxFileSize) {
+                issues.push({
+                    code: 'ai.attachment.size',
+                    name: file.name,
+                    limit: this.#options.maxFileSize,
+                });
+                continue;
+            }
+            if (count >= max) {
+                issues.push({ code: 'ai.attachment.count', name: file.name, limit: max });
+                continue;
+            }
+            count++;
+            const id = (this.#options.createId ?? createId)('attachment');
+            this.#files.set(id, file);
+            const previewUrl = this.#preview(file);
+            added.push({
+                id,
+                name: file.name,
+                size: file.size,
+                mediaType: file.type || 'application/octet-stream',
+                status: 'selected',
+                ...(previewUrl ? { previewUrl } : {}),
+            });
+        }
+        this.#set({
+            ...now,
+            attachments: [...now.attachments, ...added],
+            revision: added.length ? now.revision + 1 : now.revision,
+            issues,
+        });
+        return added;
+    }
+    /** The runtime File for an attachment (never part of serializable state). */
+    file(id) {
+        return this.#files.get(id);
+    }
+    /** Host-reported upload or processing progress. Ignored for removed attachments. */
+    updateAttachment(id, update) {
+        const now = this.#state.peek();
+        if (!now.attachments.some((a) => a.id === id))
+            return;
+        this.#set({
+            ...now,
+            attachments: now.attachments.map((a) => a.id === id ? { ...a, ...update } : a),
+        });
+    }
+    removeAttachment(id) {
+        const now = this.#state.peek();
+        const attachment = now.attachments.find((a) => a.id === id);
+        if (!attachment)
+            return;
+        this.#release(attachment);
+        this.#set({
+            ...now,
+            attachments: now.attachments.filter((a) => a.id !== id),
+            revision: now.revision + 1,
+            issues: [],
+        });
+    }
+    clearIssues() {
+        const now = this.#state.peek();
+        if (now.issues.length)
+            this.#set({ ...now, issues: [] });
+    }
+    /** Why the draft cannot be submitted now, or undefined when it can. */
+    blocker() {
+        const now = this.#state.peek();
+        if (now.submission?.status === 'submitting')
+            return 'submitting';
+        if (now.attachments.some((a) => BUSY.has(a.status)))
+            return 'attachments-busy';
+        if (now.attachments.some((a) => a.status === 'failed'))
+            return 'attachments-failed';
+        if (!now.text.trim() && !now.attachments.length)
+            return 'empty';
+        return undefined;
+    }
+    /**
+     * Capture the draft as a submission. The draft stays in place (and editable) until the host
+     * acknowledges acceptance; a failure leaves it untouched.
+     */
+    beginSubmit() {
+        if (this.blocker())
+            return undefined;
+        const now = this.#state.peek();
+        const submission = {
+            submissionId: (this.#options.createId ?? createId)('submission'),
+            revision: now.revision,
+            text: now.text,
+            attachments: now.attachments,
+        };
+        this.#set({
+            ...now,
+            submission: {
+                submissionId: submission.submissionId,
+                revision: now.revision,
+                status: 'submitting',
+            },
+        });
+        return submission;
+    }
+    /**
+     * The host accepted `submissionId`. Clears the submitted text only if the draft was not
+     * edited since; attachments added after submission stay. Stale ids are ignored.
+     */
+    acknowledge(submissionId) {
+        const now = this.#state.peek();
+        if (now.submission?.submissionId !== submissionId)
+            return false;
+        const submittedRevision = now.submission.revision;
+        const edited = now.revision !== submittedRevision;
+        const submittedIds = this.#submittedIds.get(submissionId);
+        const remaining = edited ? now.attachments.filter((a) => !submittedIds?.has(a.id)) : [];
+        for (const attachment of now.attachments)
+            if (!remaining.includes(attachment))
+                this.#release(attachment);
+        this.#submittedIds.delete(submissionId);
+        this.#set({
+            text: edited ? now.text : '',
+            revision: now.revision + 1,
+            attachments: remaining,
+            submission: undefined,
+            issues: [],
+        });
+        return true;
+    }
+    #submittedIds = new Map();
+    /** The host rejected `submissionId`. The draft and attachments are preserved. */
+    fail(submissionId, error) {
+        const now = this.#state.peek();
+        if (now.submission?.submissionId !== submissionId)
+            return false;
+        this.#set({
+            ...now,
+            submission: { submissionId, revision: now.submission.revision, status: 'failed', error },
+        });
+        return true;
+    }
+    /** Abandon the pending submission locally (e.g. the host cancelled it before acceptance). */
+    cancel(submissionId) {
+        const now = this.#state.peek();
+        if (now.submission?.submissionId !== submissionId)
+            return false;
+        this.#set({ ...now, submission: undefined });
+        return true;
+    }
+    /** Revoke owned preview URLs and drop File references. */
+    dispose() {
+        if (this.#disposed)
+            return;
+        this.#disposed = true;
+        for (const url of this.#ownedUrls)
+            URL.revokeObjectURL(url);
+        this.#ownedUrls.clear();
+        this.#files.clear();
+    }
+    /** Number of object URLs this controller currently owns (for leak tests). */
+    get ownedUrlCount() {
+        return this.#ownedUrls.size;
+    }
+    /** Revoke owned preview URLs (e.g. while a view is disconnected); the files are kept. */
+    releasePreviews() {
+        const now = this.#state.peek();
+        if (!now.attachments.some((a) => a.previewUrl && this.#ownedUrls.has(a.previewUrl)))
+            return;
+        this.#set({
+            ...now,
+            attachments: now.attachments.map((a) => {
+                if (!a.previewUrl || !this.#ownedUrls.delete(a.previewUrl))
+                    return a;
+                URL.revokeObjectURL(a.previewUrl);
+                const { previewUrl: _released, ...rest } = a;
+                return rest;
+            }),
+        });
+    }
+    /** Recreate previews released by `releasePreviews`. */
+    restorePreviews() {
+        if (this.#disposed)
+            return;
+        const now = this.#state.peek();
+        let changed = false;
+        const attachments = now.attachments.map((a) => {
+            const file = this.#files.get(a.id);
+            if (a.previewUrl || !file)
+                return a;
+            const previewUrl = this.#preview(file);
+            if (!previewUrl)
+                return a;
+            changed = true;
+            return { ...a, previewUrl };
+        });
+        if (changed)
+            this.#set({ ...now, attachments });
+    }
+    #preview(file) {
+        if (this.#options.previews === false || !file.type.startsWith('image/'))
+            return undefined;
+        if (typeof URL === 'undefined' || typeof URL.createObjectURL !== 'function')
+            return undefined;
+        const url = URL.createObjectURL(file);
+        this.#ownedUrls.add(url);
+        return url;
+    }
+    #release(attachment) {
+        this.#files.delete(attachment.id);
+        // Only URLs this controller created; host-provided URLs are never revoked.
+        if (attachment.previewUrl && this.#ownedUrls.delete(attachment.previewUrl))
+            URL.revokeObjectURL(attachment.previewUrl);
+    }
+    #set(next) {
+        if (next.submission?.status === 'submitting' &&
+            !this.#submittedIds.has(next.submission.submissionId))
+            this.#submittedIds.set(next.submission.submissionId, new Set(next.attachments.map((a) => a.id)));
+        this.#state.value = next;
+    }
+}
+//# sourceMappingURL=composer.js.map

package/dist/controllers/composer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"composer.js","sourceRoot":"","sources":["../../src/controllers/composer.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,MAAM,EAA8B,MAAM,uBAAuB,CAAC;AAE3E,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAoE9C,MAAM,IAAI,GAAkC,IAAI,GAAG,CAAC,CAAC,WAAW,EAAE,YAAY,CAAC,CAAC,CAAC;AAEjF,MAAM,UAAU,aAAa,CAC3B,IAAoC,EACpC,MAAyB;IAEzB,IAAI,CAAC,MAAM,CAAC,MAAM;QAAE,OAAO,IAAI,CAAC;IAChC,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC;IACrC,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC;IACrC,OAAO,MAAM,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE;QACzB,MAAM,OAAO,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;QACzC,IAAI,CAAC,OAAO;YAAE,OAAO,KAAK,CAAC;QAC3B,IAAI,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC;YAAE,OAAO,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;QAC3D,IAAI,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC;YAAE,OAAO,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;QACzE,OAAO,IAAI,KAAK,OAAO,CAAC;IAC1B,CAAC,CAAC,CAAC;AACL,CAAC;AAED,MAAM,OAAO,kBAAkB;IACpB,MAAM,CAAwB;IAC9B,KAAK,CAA0B;IAC/B,MAAM,GAAG,IAAI,GAAG,EAAgB,CAAC;IACjC,UAAU,GAAG,IAAI,GAAG,EAAU,CAAC;IACxC,QAAQ,CAAkB;IAC1B,SAAS,GAAG,KAAK,CAAC;IAElB,YAAY,OAAO,GAAoB,EAAE;QACvC,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC;QACxB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAgB,EAAE,IAAI,EAAE,EAAE,EAAE,QAAQ,EAAE,CAAC,EAAE,WAAW,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,CAAC;QAC5F,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC;IAC3B,CAAC;IAED,WAAW;QACT,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;IAC5B,CAAC;IAED,SAAS,CAAC,OAAwB;QAChC,IAAI,CAAC,QAAQ,GAAG,EAAE,GAAG,IAAI,CAAC,QAAQ,EAAE,GAAG,OAAO,EAAE,CAAC;IACnD,CAAC;IAED,yFAAyF;IACzF,OAAO,CAAC,IAAY;QAClB,MAAM,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;QAC/B,IAAI,GAAG,CAAC,IAAI,KAAK,IAAI;YAAE,OAAO;QAC9B,IAAI,CAAC,IAAI,CAAC,EAAE,GAAG,GAAG,EAAE,IAAI,EAAE,QAAQ,EAAE,GAAG,CAAC,QAAQ,GAAG,CAAC,EAAE,CAAC,CAAC;IAC1D,CAAC;IAED,uFAAuF;IACvF,QAAQ,CAAC,KAAqB;QAC5B,MAAM,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;QAC/B,MAAM,MAAM,GAAoB,EAAE,CAAC;QACnC,MAAM,KAAK,GAAsB,EAAE,CAAC;QACpC,IAAI,IAAI,CAAC,QAAQ,CAAC,WAAW,KAAK,KAAK,EAAE,CAAC;YACxC,KAAK,MAAM,IAAI,IAAI,KAAK;gBAAE,MAAM,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,2BAA2B,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;YAC9F,IAAI,CAAC,IAAI,CAAC,EAAE,GAAG,GAAG,EAAE,MAAM,EAAE,CAAC,CAAC;YAC9B,OAAO,KAAK,CAAC;QACf,CAAC;QACD,MAAM,GAAG,GAAG,IAAI,CAAC,QAAQ,CAAC,QAAQ,IAAI,QAAQ,CAAC;QAC/C,IAAI,KAAK,GAAG,GAAG,CAAC,WAAW,CAAC,MAAM,CAAC;QACnC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,IAAI,CAAC,aAAa,CAAC,IAAI,EAAE,IAAI,CAAC,QAAQ,CAAC,MAAM,IAAI,EAAE,CAAC,EAAE,CAAC;gBACrD,MAAM,CAAC,IAAI,CAAC;oBACV,IAAI,EAAE,oBAAoB;oBAC1B,IAAI,EAAE,IAAI,CAAC,IAAI;oBACf,KAAK,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC;iBAC/C,CAAC,CAAC;gBACH,SAAS;YACX,CAAC;YACD,IAAI,IAAI,CAAC,QAAQ,CAAC,WAAW,KAAK,SAAS,IAAI,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,QAAQ,CAAC,WAAW,EAAE,CAAC;gBACrF,MAAM,CAAC,IAAI,CAAC;oBACV,IAAI,EAAE,oBAAoB;oBAC1B,IAAI,EAAE,IAAI,CAAC,IAAI;oBACf,KAAK,EAAE,IAAI,CAAC,QAAQ,CAAC,WAAW;iBACjC,CAAC,CAAC;gBACH,SAAS;YACX,CAAC;YACD,IAAI,KAAK,IAAI,GAAG,EAAE,CAAC;gBACjB,MAAM,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,qBAAqB,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,CAAC;gBAC1E,SAAS;YACX,CAAC;YACD,KAAK,EAAE,CAAC;YACR,MAAM,EAAE,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,QAAQ,IAAI,QAAQ,CAAC,CAAC,YAAY,CAAC,CAAC;YAC9D,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;YAC1B,MAAM,UAAU,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;YACvC,KAAK,CAAC,IAAI,CAAC;gBACT,EAAE;gBACF,IAAI,EAAE,IAAI,CAAC,IAAI;gBACf,IAAI,EAAE,IAAI,CAAC,IAAI;gBACf,SAAS,EAAE,IAAI,CAAC,IAAI,IAAI,0BAA0B;gBAClD,MAAM,EAAE,UAAU;gBAClB,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aACtC,CAAC,CAAC;QACL,CAAC;QACD,IAAI,CAAC,IAAI,CAAC;YACR,GAAG,GAAG;YACN,WAAW,EAAE,CAAC,GAAG,GAAG,CAAC,WAAW,EAAE,GAAG,KAAK,CAAC;YAC3C,QAAQ,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,QAAQ,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,QAAQ;YACxD,MAAM;SACP,CAAC,CAAC;QACH,OAAO,KAAK,CAAC;IACf,CAAC;IAED,6EAA6E;IAC7E,IAAI,CAAC,EAAU;QACb,OAAO,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAC7B,CAAC;IAED,oFAAoF;IACpF,gBAAgB,CACd,EAAU,EACV,MAA+E;QAE/E,MAAM,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;QAC/B,IAAI,CAAC,GAAG,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC;YAAE,OAAO;QACtD,IAAI,CAAC,IAAI,CAAC;YACR,GAAG,GAAG;YACN,WAAW,EAAE,GAAG,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CACrC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAE,EAAE,GAAG,CAAC,EAAE,GAAG,MAAM,EAAsB,CAAC,CAAC,CAAC,CAAC,CAC3D;SACF,CAAC,CAAC;IACL,CAAC;IAED,gBAAgB,CAAC,EAAU;QACzB,MAAM,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;QAC/B,MAAM,UAAU,GAAG,GAAG,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC;QAC5D,IAAI,CAAC,UAAU;YAAE,OAAO;QACxB,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC;QAC1B,IAAI,CAAC,IAAI,CAAC;YACR,GAAG,GAAG;YACN,WAAW,EAAE,GAAG,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC;YACvD,QAAQ,EAAE,GAAG,CAAC,QAAQ,GAAG,CAAC;YAC1B,MAAM,EAAE,EAAE;SACX,CAAC,CAAC;IACL,CAAC;IAED,WAAW;QACT,MAAM,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;QAC/B,IAAI,GAAG,CAAC,MAAM,CAAC,MAAM;YAAE,IAAI,CAAC,IAAI,CAAC,EAAE,GAAG,GAAG,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,CAAC;IAC3D,CAAC;IAED,uEAAuE;IACvE,OAAO;QACL,MAAM,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;QAC/B,IAAI,GAAG,CAAC,UAAU,EAAE,MAAM,KAAK,YAAY;YAAE,OAAO,YAAY,CAAC;QACjE,IAAI,GAAG,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;YAAE,OAAO,kBAAkB,CAAC;QAC/E,IAAI,GAAG,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,QAAQ,CAAC;YAAE,OAAO,oBAAoB,CAAC;QACpF,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,GAAG,CAAC,WAAW,CAAC,MAAM;YAAE,OAAO,OAAO,CAAC;QAChE,OAAO,SAAS,CAAC;IACnB,CAAC;IAED;;;OAGG;IACH,WAAW;QACT,IAAI,IAAI,CAAC,OAAO,EAAE;YAAE,OAAO,SAAS,CAAC;QACrC,MAAM,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;QAC/B,MAAM,UAAU,GAAe;YAC7B,YAAY,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,QAAQ,IAAI,QAAQ,CAAC,CAAC,YAAY,CAAC;YAChE,QAAQ,EAAE,GAAG,CAAC,QAAQ;YACtB,IAAI,EAAE,GAAG,CAAC,IAAI;YACd,WAAW,EAAE,GAAG,CAAC,WAAW;SAC7B,CAAC;QACF,IAAI,CAAC,IAAI,CAAC;YACR,GAAG,GAAG;YACN,UAAU,EAAE;gBACV,YAAY,EAAE,UAAU,CAAC,YAAY;gBACrC,QAAQ,EAAE,GAAG,CAAC,QAAQ;gBACtB,MAAM,EAAE,YAAY;aACrB;SACF,CAAC,CAAC;QACH,OAAO,UAAU,CAAC;IACpB,CAAC;IAED;;;OAGG;IACH,WAAW,CAAC,YAAoB;QAC9B,MAAM,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;QAC/B,IAAI,GAAG,CAAC,UAAU,EAAE,YAAY,KAAK,YAAY;YAAE,OAAO,KAAK,CAAC;QAChE,MAAM,iBAAiB,GAAG,GAAG,CAAC,UAAU,CAAC,QAAQ,CAAC;QAClD,MAAM,MAAM,GAAG,GAAG,CAAC,QAAQ,KAAK,iBAAiB,CAAC;QAClD,MAAM,YAAY,GAAG,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;QAC1D,MAAM,SAAS,GAAG,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,YAAY,EAAE,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QACxF,KAAK,MAAM,UAAU,IAAI,GAAG,CAAC,WAAW;YACtC,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,UAAU,CAAC;gBAAE,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC;QACjE,IAAI,CAAC,aAAa,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC;QACxC,IAAI,CAAC,IAAI,CAAC;YACR,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE;YAC5B,QAAQ,EAAE,GAAG,CAAC,QAAQ,GAAG,CAAC;YAC1B,WAAW,EAAE,SAAS;YACtB,UAAU,EAAE,SAAS;YACrB,MAAM,EAAE,EAAE;SACX,CAAC,CAAC;QACH,OAAO,IAAI,CAAC;IACd,CAAC;IACQ,aAAa,GAAG,IAAI,GAAG,EAAuB,CAAC;IAExD,iFAAiF;IACjF,IAAI,CAAC,YAAoB,EAAE,KAAkB;QAC3C,MAAM,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;QAC/B,IAAI,GAAG,CAAC,UAAU,EAAE,YAAY,KAAK,YAAY;YAAE,OAAO,KAAK,CAAC;QAChE,IAAI,CAAC,IAAI,CAAC;YACR,GAAG,GAAG;YACN,UAAU,EAAE,EAAE,YAAY,EAAE,QAAQ,EAAE,GAAG,CAAC,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE;SACzF,CAAC,CAAC;QACH,OAAO,IAAI,CAAC;IACd,CAAC;IAED,6FAA6F;IAC7F,MAAM,CAAC,YAAoB;QACzB,MAAM,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;QAC/B,IAAI,GAAG,CAAC,UAAU,EAAE,YAAY,KAAK,YAAY;YAAE,OAAO,KAAK,CAAC;QAChE,IAAI,CAAC,IAAI,CAAC,EAAE,GAAG,GAAG,EAAE,UAAU,EAAE,SAAS,EAAE,CAAC,CAAC;QAC7C,OAAO,IAAI,CAAC;IACd,CAAC;IAED,0DAA0D;IAC1D,OAAO;QACL,IAAI,IAAI,CAAC,SAAS;YAAE,OAAO;QAC3B,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC;QACtB,KAAK,MAAM,GAAG,IAAI,IAAI,CAAC,UAAU;YAAE,GAAG,CAAC,eAAe,CAAC,GAAG,CAAC,CAAC;QAC5D,IAAI,CAAC,UAAU,CAAC,KAAK,EAAE,CAAC;QACxB,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;IACtB,CAAC;IAED,6EAA6E;IAC7E,IAAI,aAAa;QACf,OAAO,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;IAC9B,CAAC;IAED,yFAAyF;IACzF,eAAe;QACb,MAAM,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;QAC/B,IAAI,CAAC,GAAG,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC;YAAE,OAAO;QAC5F,IAAI,CAAC,IAAI,CAAC;YACR,GAAG,GAAG;YACN,WAAW,EAAE,GAAG,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;gBACrC,IAAI,CAAC,CAAC,CAAC,UAAU,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,UAAU,CAAC;oBAAE,OAAO,CAAC,CAAC;gBACrE,GAAG,CAAC,eAAe,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC;gBAClC,MAAM,EAAE,UAAU,EAAE,SAAS,EAAE,GAAG,IAAI,EAAE,GAAG,CAAC,CAAC;gBAC7C,OAAO,IAAI,CAAC;YACd,CAAC,CAAC;SACH,CAAC,CAAC;IACL,CAAC;IAED,uDAAuD;IACvD,eAAe;QACb,IAAI,IAAI,CAAC,SAAS;YAAE,OAAO;QAC3B,MAAM,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;QAC/B,IAAI,OAAO,GAAG,KAAK,CAAC;QACpB,MAAM,WAAW,GAAG,GAAG,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;YAC5C,MAAM,IAAI,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;YACnC,IAAI,CAAC,CAAC,UAAU,IAAI,CAAC,IAAI;gBAAE,OAAO,CAAC,CAAC;YACpC,MAAM,UAAU,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;YACvC,IAAI,CAAC,UAAU;gBAAE,OAAO,CAAC,CAAC;YAC1B,OAAO,GAAG,IAAI,CAAC;YACf,OAAO,EAAE,GAAG,CAAC,EAAE,UAAU,EAAE,CAAC;QAC9B,CAAC,CAAC,CAAC;QACH,IAAI,OAAO;YAAE,IAAI,CAAC,IAAI,CAAC,EAAE,GAAG,GAAG,EAAE,WAAW,EAAE,CAAC,CAAC;IAClD,CAAC;IAED,QAAQ,CAAC,IAAU;QACjB,IAAI,IAAI,CAAC,QAAQ,CAAC,QAAQ,KAAK,KAAK,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC;YAAE,OAAO,SAAS,CAAC;QAC1F,IAAI,OAAO,GAAG,KAAK,WAAW,IAAI,OAAO,GAAG,CAAC,eAAe,KAAK,UAAU;YAAE,OAAO,SAAS,CAAC;QAC9F,MAAM,GAAG,GAAG,GAAG,CAAC,eAAe,CAAC,IAAI,CAAC,CAAC;QACtC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACzB,OAAO,GAAG,CAAC;IACb,CAAC;IAED,QAAQ,CAAC,UAA2B;QAClC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC;QAClC,2EAA2E;QAC3E,IAAI,UAAU,CAAC,UAAU,IAAI,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,UAAU,CAAC,UAAU,CAAC;YACxE,GAAG,CAAC,eAAe,CAAC,UAAU,CAAC,UAAU,CAAC,CAAC;IAC/C,CAAC;IAED,IAAI,CAAC,IAAmB;QACtB,IACE,IAAI,CAAC,UAAU,EAAE,MAAM,KAAK,YAAY;YACxC,CAAC,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,IAAI,CAAC,UAAU,CAAC,YAAY,CAAC;YAErD,IAAI,CAAC,aAAa,CAAC,GAAG,CACpB,IAAI,CAAC,UAAU,CAAC,YAAY,EAC5B,IAAI,GAAG,CAAC,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAC3C,CAAC;QACJ,IAAI,CAAC,MAAM,CAAC,KAAK,GAAG,IAAI,CAAC;IAC3B,CAAC;CACF"}

package/dist/controllers/conversation.d.ts

@@ -0,0 +1,106 @@
+import { type Readable } from '@oddkin/core/reactive';
+import { type NormalizeDiagnostic, type Normalized } from '../contracts/normalize.js';
+import type { AiEvent, AttemptTarget, Capabilities, ConversationSnapshot, ConversationState, ConversationTransport, EventSink, ExternalSource, FeedbackRecord, MessagePart, PublicError } from '../contracts/types.js';
+export interface ConversationControllerOptions {
+    readonly transport: ConversationTransport;
+    readonly conversationId?: string;
+    /** Application policy; narrows (never widens) what the transport supports. */
+    readonly capabilities?: Capabilities;
+    readonly createId?: (prefix: string) => string;
+    /** Dropped, duplicate, invalid, and stale input. Never shown to users by default. */
+    readonly onDiagnostic?: (diagnostic: ControllerDiagnostic) => void;
+}
+export interface ControllerDiagnostic extends NormalizeDiagnostic {
+    readonly attemptId?: string | undefined;
+}
+export type ActionResult = {
+    readonly ok: true;
+    readonly attemptId?: string;
+} | {
+    readonly ok: false;
+    readonly reason: 'unavailable' | 'stale' | 'duplicate' | 'invalid' | 'rejected' | 'busy';
+    readonly error?: PublicError;
+};
+export interface SendInput {
+    readonly text: string;
+    readonly files?: readonly Extract<MessagePart, {
+        type: 'file';
+    }>[];
+}
+declare class Sink implements EventSink {
+    #private;
+    readonly target: AttemptTarget;
+    private readonly owner;
+    private readonly generation;
+    constructor(target: AttemptTarget, owner: ConversationController, generation: number);
+    get active(): boolean;
+    /** @internal */
+    get _generation(): number;
+    push(event: AiEvent): void;
+    close(): void;
+    /** @internal Called when the controller replaces or disconnects this sink. */
+    _invalidate(): void;
+}
+export declare class ConversationController implements ExternalSource<ConversationState> {
+    #private;
+    /** The current immutable snapshot as an Oddkin readable. */
+    readonly state: Readable<ConversationState>;
+    constructor(options: ConversationControllerOptions);
+    getSnapshot(): ConversationState;
+    subscribe(listener: () => void): () => void;
+    /**
+     * Replace the conversation with a validated snapshot. A different conversation id isolates
+     * every in-flight stream, stop, and decision of the previous one.
+     */
+    load(raw: unknown): Normalized<ConversationSnapshot>;
+    /** Start an empty conversation, isolating the previous one. */
+    reset(conversationId?: string): void;
+    /** Replace the application capability policy (narrowing only). */
+    setCapabilities(capabilities: Capabilities | undefined): void;
+    /**
+     * Send a user message and start a new attempt. Resolves when the backend accepted or rejected
+     * the request. A rejected (never accepted) request removes the optimistic messages so the
+     * composer's preserved draft stays the single copy of the content.
+     */
+    send(input: SendInput): Promise<ActionResult>;
+    /** Retry a failed, interrupted, or cancelled attempt as a new linked attempt. */
+    retry(attemptId: string): Promise<ActionResult>;
+    /** Generate an alternative answer; the previous one stays reachable as a branch. */
+    regenerate(messageId: string): Promise<ActionResult>;
+    /** Edit a user message: a new sibling branch and a new attempt; the original is preserved. */
+    edit(messageId: string, text: string): Promise<ActionResult>;
+    /**
+     * Request cancellation of the underlying work for one attempt. The attempt stays
+     * `stop: requested` until the backend answers; partial output is kept. A response for an
+     * older request (or another conversation) is ignored.
+     */
+    stop(attemptId?: string | undefined): Promise<ActionResult>;
+    /**
+     * Close the client stream for an attempt without cancelling the work (unmount, navigation).
+     * The attempt keeps its status; `resume()` can reattach when supported.
+     */
+    disconnect(attemptId?: string | undefined): ActionResult;
+    /** Reattach to an existing attempt. Never starts new work or a new attempt. */
+    resume(attemptId?: string | undefined): Promise<ActionResult>;
+    /**
+     * Submit a decision for one approval revision. Repeated activation, stale revisions, and
+     * expired proposals are refused without a request. The approval stays `decision-pending`
+     * until the backend acknowledges it; acknowledgment does not mean the action succeeded.
+     */
+    decide(approvalId: string, revision: number, decision: 'approve' | 'reject', reason?: string): Promise<ActionResult>;
+    /** Show the branch containing `messageId` (following its most recently selected leaf). */
+    switchBranch(messageId: string): ActionResult;
+    /** Load earlier messages. Prepended messages never move the active branch. */
+    loadHistory(): Promise<ActionResult>;
+    submitFeedback(feedback: Omit<FeedbackRecord, 'status' | 'error'>): Promise<ActionResult>;
+    /** Release client-side work: disconnect open streams (never cancels remote work). */
+    dispose(): void;
+    /** @internal */
+    _accepts(sink: Sink): boolean;
+    /** @internal */
+    _closed(sink: Sink): void;
+    /** @internal */
+    _ingest(sink: Sink, event: AiEvent): void;
+}
+export {};
+//# sourceMappingURL=conversation.d.ts.map

package/dist/controllers/conversation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conversation.d.ts","sourceRoot":"","sources":["../../src/controllers/conversation.ts"],"names":[],"mappings":"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"}