@fabriktor/fx 0.0.100 → 0.0.102

package/dist/src/chat/chat.d.ts

@@ -1,14 +1,17 @@
 import type { ChatOperator, UsersOperator, WSCloseHandler, WSConnection, WSErrorHandler, WSMessageHandler } from "@fabriktor/client";
 import { type Chat, type ChatRoom, type ChatRoomMember, type User } from "@fabriktor/schema";
 import { type RequiredSearchOptions, type SearchOptions, type SearchPage, type SearchPaginationOptions } from "../core/search.js";
+import { ChatSendQueue, type ChatSendQueueOptions } from "./send-queue.js";
 type ChatInsertOptions = Parameters<ChatOperator["insertOneChat"]>[0];
 type ChatReplaceOptions = Parameters<ChatOperator["replaceOneChat"]>[0];
 export type CreateChatOptions = ChatInsertOptions;
 export type EnsureChatRoomOptions = Parameters<ChatOperator["ensureChatRoom"]>[0];
 export type MarkChatObjectsUploadedOptions = {
+    signal?: AbortSignal;
     id: ChatReplaceOptions["id"];
 };
 export type ClearChatObjectsOptions = {
+    signal?: AbortSignal;
     id: ChatReplaceOptions["id"];
 };
 export type ReactChatOptions = Parameters<ChatOperator["reactChat"]>[0];
@@ -102,6 +105,7 @@ export type GlobalChatRoomsSession = {
     closeLeavingPage(reason?: string): void;
 };
 export interface ChatFXOperator {
+    newSendQueue(opts: Omit<ChatSendQueueOptions, "chat">): ChatSendQueue;
     createChat(opts: CreateChatOptions): Promise<Chat>;
     ensureChatRoom(opts: EnsureChatRoomOptions): Promise<string>;
     markChatObjectsUploaded(opts: MarkChatObjectsUploadedOptions): Promise<Chat>;
@@ -123,6 +127,7 @@ export declare class ChatFX implements ChatFXOperator {
     private chat;
     private users;
     constructor(opts: ChatFXOptions);
+    newSendQueue(opts: Omit<ChatSendQueueOptions, "chat">): ChatSendQueue;
     createChat(opts: CreateChatOptions): Promise<Chat>;
     ensureChatRoom(opts: EnsureChatRoomOptions): Promise<string>;
     markChatObjectsUploaded(opts: MarkChatObjectsUploadedOptions): Promise<Chat>;

package/dist/src/chat/chat.js

@@ -7,6 +7,7 @@ import { IDKey, } from "@fabriktor/schema";
 import { errRequired, errResolveFailed, errValidation } from "../core/err.js";
 import { requiredOperationID } from "../core/id.js";
 import { normalizeSearchPage, normalizeSearchPerPage, normalizeSearchQuery, runSearch, } from "../core/search.js";
+import { ChatSendQueue } from "./send-queue.js";
 const closeCodeNormal = 1000;
 const wsRefreshMilliseconds = 40 * 60 * 1000;
 const wsRefreshRetryMilliseconds = 30 * 1000;
@@ -25,6 +26,9 @@ export class ChatFX {
         this.chat = opts.chat;
         this.users = opts.users;
     }
+    newSendQueue(opts) {
+        return new ChatSendQueue({ ...opts, chat: this.chat });
+    }
     async createChat(opts) {
         const out = await this.chat.insertOneChat(opts);
         const id = requiredOperationID(out, msgCreatedChatIDMissing);
@@ -37,21 +41,23 @@ export class ChatFX {
     async markChatObjectsUploaded(opts) {
         await this.chat.replaceOneChat({
             id: opts.id,
+            signal: opts.signal,
             in: {
                 objects_uploaded: true,
             },
         });
-        return await this.findChat(opts.id);
+        return await this.findChat(opts.id, opts.signal);
     }
     async clearChatObjects(opts) {
         await this.chat.replaceOneChat({
             id: opts.id,
+            signal: opts.signal,
             in: {
                 has_objects: false,
                 objects_uploaded: false,
             },
         });
-        return await this.findChat(opts.id);
+        return await this.findChat(opts.id, opts.signal);
     }
     async searchChats(opts) {
         const q = normalizeSearchQuery(opts.q);
@@ -459,9 +465,10 @@ export class ChatFX {
             username: user.username,
         };
     }
-    async findChat(id) {
+    async findChat(id, signal) {
         const out = await this.chat.findOneChat({
             id,
+            signal,
         });
         const chat = out.value;
         if (chat === undefined) {

package/dist/src/chat/optimistic.d.ts

@@ -0,0 +1,17 @@
+import { type Chat, type InChat } from "@fabriktor/schema";
+export declare function newChatInput(opts: {
+    chat_room_id: string;
+    text: string;
+    quoted_message_id?: string;
+    has_objects?: boolean;
+}): InChat;
+export declare function newOptimisticChat(opts: {
+    owner_id: string;
+    in: InChat;
+}): Chat;
+export declare function isOptimisticChat(chat: Pick<Chat, "id">): boolean;
+export declare function matchesOptimisticChat(chat: Chat, optimistic: Chat): boolean;
+/** Reconcile only the local outgoing bubbles. Server timestamps/IDs stay authoritative. */
+export declare function projectQueuedChats(chats: Chat[], snapshot: import("./send-queue.js").ChatSendSnapshot, ownerID: string, roomID: string): Chat[];
+export declare function activeQueuedChat(snapshot: import("./send-queue.js").ChatSendSnapshot, ownerID: string, roomID: string): Chat | null;
+export declare function queuedChatsByID(snapshot: import("./send-queue.js").ChatSendSnapshot): Readonly<Record<string, import("./send-queue.js").QueuedChat>>;

package/dist/src/chat/optimistic.js

@@ -0,0 +1,78 @@
+// Copyright (C) Fabriktor, Inc. 2025-present.
+//
+// Licensed under the Apache License, Version 2.0 (the "License"); you may
+// not use this file except in compliance with the License. You may obtain
+// a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
+import { ChatSendStatus } from "./send-queue.js";
+import { ZeroID } from "@fabriktor/schema";
+const optimisticChatIDPrefix = "optimistic-chat:";
+export function newChatInput(opts) {
+    return {
+        chat_room_id: opts.chat_room_id,
+        text: opts.text,
+        quoted_message_id: opts.quoted_message_id ?? ZeroID,
+        mentions: [],
+        has_objects: opts.has_objects ?? false,
+        objects_uploaded: false,
+    };
+}
+export function newOptimisticChat(opts) {
+    const created_at = new Date().toISOString();
+    return {
+        ...opts.in,
+        id: `${optimisticChatIDPrefix}${crypto.randomUUID()}`,
+        updated_at: created_at,
+        created_at,
+        owner_id: opts.owner_id,
+        reactions: {},
+    };
+}
+export function isOptimisticChat(chat) {
+    return chat.id.startsWith(optimisticChatIDPrefix);
+}
+export function matchesOptimisticChat(chat, optimistic) {
+    return (chat.owner_id === optimistic.owner_id &&
+        chat.chat_room_id === optimistic.chat_room_id &&
+        chat.text === optimistic.text &&
+        chat.quoted_message_id === optimistic.quoted_message_id &&
+        chat.has_objects === optimistic.has_objects);
+}
+/** Reconcile only the local outgoing bubbles. Server timestamps/IDs stay authoritative. */
+export function projectQueuedChats(chats, snapshot, ownerID, roomID) {
+    const entries = snapshot.entries.filter((entry) => entry.owner_id === ownerID && entry.input.chat_room_id === roomID);
+    const confirmed = new Map(chats
+        .filter((chat) => !isOptimisticChat(chat))
+        .map((chat) => [chat.id, chat]));
+    for (const chat of snapshot.confirmed) {
+        if (chat.owner_id !== ownerID || chat.chat_room_id !== roomID) {
+            continue;
+        }
+        const previous = confirmed.get(chat.id);
+        if (!previous ||
+            Date.parse(previous.updated_at) < Date.parse(chat.updated_at)) {
+            confirmed.set(chat.id, chat);
+        }
+    }
+    const result = [...confirmed.values()].sort((a, b) => Date.parse(a.created_at) - Date.parse(b.created_at) ||
+        a.id.localeCompare(b.id));
+    for (const entry of entries) {
+        if (!entry.chat) {
+            result.push(entry.optimistic);
+        }
+    }
+    return result.length === chats.length &&
+        result.every((chat, index) => chat === chats[index])
+        ? chats
+        : result;
+}
+export function activeQueuedChat(snapshot, ownerID, roomID) {
+    return (snapshot.entries.find((entry) => entry.owner_id === ownerID &&
+        entry.input.chat_room_id === roomID &&
+        entry.status === ChatSendStatus.Sending)?.optimistic ?? null);
+}
+export function queuedChatsByID(snapshot) {
+    return Object.fromEntries(snapshot.entries.map((entry) => [
+        entry.chat?.id ?? entry.optimistic.id,
+        entry,
+    ]));
+}

package/dist/src/chat/send-queue.d.ts

@@ -0,0 +1,87 @@
+import type { ChatOperator } from "@fabriktor/client";
+import type { Chat, InChat } from "@fabriktor/schema";
+import { type QueueStore, type QueueLock } from "../core/queue.js";
+export declare const ChatSendStatus: {
+    readonly Saving: "saving";
+    readonly Queued: "queued";
+    readonly Sending: "sending";
+    readonly Failed: "failed";
+    readonly Interrupted: "interrupted";
+    readonly Uploading: "uploading";
+    readonly UploadInterrupted: "upload_interrupted";
+};
+export type ChatSendStatus = (typeof ChatSendStatus)[keyof typeof ChatSendStatus];
+export type ChatSendAttachments = {
+    files: File[];
+    save_to_personal_box: boolean;
+    full_quality: boolean;
+};
+export type QueuedChat = {
+    id: string;
+    sequence?: number;
+    owner_id: string;
+    input: InChat;
+    optimistic: Chat;
+    status: ChatSendStatus;
+    server_id?: string;
+    chat?: Chat;
+    attachments: ChatSendAttachments;
+    attempted: boolean;
+    upload_key: string;
+    personal_box_key: string;
+};
+export type ChatSendStore = QueueStore<QueuedChat>;
+export type ChatSendLock = QueueLock;
+export type ChatSendSnapshot = {
+    entries: readonly QueuedChat[];
+    confirmed: readonly Chat[];
+    error?: unknown;
+};
+export type ChatSendQueueOptions = {
+    chat: ChatOperator;
+    store: ChatSendStore;
+    lock: ChatSendLock;
+    upload: (entry: QueuedChat, signal: AbortSignal) => Promise<boolean>;
+    changed?: (chat?: Chat) => void;
+};
+export declare class ChatSendQueue {
+    private readonly opts;
+    private owner;
+    private controller;
+    private entries;
+    private confirmed;
+    private listeners;
+    private readonly queue;
+    private uploads;
+    private sends;
+    private cancellations;
+    private writes;
+    private pendingSaves;
+    private error?;
+    private enabled;
+    private revision;
+    constructor(opts: ChatSendQueueOptions);
+    get hasUnsavedMessages(): boolean;
+    get snapshot(): ChatSendSnapshot;
+    subscribe(listener: (snapshot: ChatSendSnapshot) => void): () => void;
+    start(ownerID: string): Promise<void>;
+    pause(): void;
+    enqueue(input: InChat, attachments: ChatSendAttachments): string;
+    private persist;
+    confirm(chat: Chat): void;
+    refresh(): Promise<void>;
+    retry(id: string): Promise<void>;
+    remove(id: string): Promise<void>;
+    private work;
+    private startUpload;
+    private recoverUpload;
+    private uploadLock;
+    private roomLock;
+    private current;
+    private save;
+    private replace;
+    private remember;
+    private publish;
+}
+export declare function chatSendNeedsRetry(entry: QueuedChat): boolean;
+export declare function chatSendCanRemove(entry: QueuedChat): boolean;

package/dist/src/chat/send-queue.js

@@ -0,0 +1,554 @@
+// Copyright (C) Fabriktor, Inc. 2025-present.
+//
+// Licensed under the Apache License, Version 2.0 (the "License"); you may
+// not use this file except in compliance with the License. You may obtain
+// a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
+import { requiredOperationID } from "../core/id.js";
+import { PersistentQueue, } from "../core/queue.js";
+import { newOptimisticChat } from "./optimistic.js";
+export const ChatSendStatus = {
+    Saving: "saving",
+    Queued: "queued",
+    Sending: "sending",
+    Failed: "failed",
+    Interrupted: "interrupted",
+    Uploading: "uploading",
+    UploadInterrupted: "upload_interrupted",
+};
+// Persistent FIFO per account and room. The transport never advances beyond a
+// failed/uncertain head. Other rooms and other users remain independent.
+export class ChatSendQueue {
+    opts;
+    owner = "";
+    controller = new AbortController();
+    entries = [];
+    confirmed = new Map();
+    listeners = new Set();
+    queue;
+    uploads = new Set();
+    sends = new Map();
+    cancellations = new Set();
+    writes = Promise.resolve();
+    pendingSaves = new Map();
+    error;
+    enabled = false;
+    revision = 0;
+    constructor(opts) {
+        this.opts = opts;
+        this.queue = new PersistentQueue(opts.store, opts.lock);
+    }
+    get hasUnsavedMessages() {
+        return this.pendingSaves.size > 0;
+    }
+    get snapshot() {
+        return {
+            entries: this.entries,
+            confirmed: [...this.confirmed.values()],
+            error: this.error,
+        };
+    }
+    subscribe(listener) {
+        this.listeners.add(listener);
+        listener(this.snapshot);
+        return () => this.listeners.delete(listener);
+    }
+    async start(ownerID) {
+        if (this.enabled && this.owner === ownerID) {
+            await this.refresh();
+            return;
+        }
+        this.pause();
+        if (this.owner !== ownerID) {
+            this.entries = [...this.pendingSaves.values()].filter((entry) => entry.owner_id === ownerID);
+            this.confirmed.clear();
+            this.error = undefined;
+        }
+        this.owner = ownerID;
+        this.enabled = ownerID !== "";
+        this.controller = new AbortController();
+        this.publish();
+        await this.refresh();
+    }
+    pause() {
+        this.enabled = false;
+        this.controller.abort();
+    }
+    enqueue(input, attachments) {
+        if (!this.enabled || !this.owner) {
+            throw new Error("Chat send queue is not ready.");
+        }
+        const optimistic = newOptimisticChat({ owner_id: this.owner, in: input });
+        const entry = {
+            id: crypto.randomUUID(),
+            owner_id: this.owner,
+            input: structuredClone(input),
+            optimistic,
+            status: ChatSendStatus.Saving,
+            attachments: { ...attachments, files: [...attachments.files] },
+            attempted: false,
+            upload_key: crypto.randomUUID(),
+            personal_box_key: crypto.randomUUID(),
+        };
+        this.pendingSaves.set(entry.id, entry);
+        this.entries = [...this.entries, entry];
+        this.publish();
+        this.persist();
+        return entry.id;
+    }
+    // A failed storage transaction holds later local submissions in memory in
+    // order. They are visible, but no network request may precede durable intent.
+    persist() {
+        this.writes = this.writes.then(async () => {
+            const blocked = new Set();
+            for (const entry of this.pendingSaves.values()) {
+                if (entry.status !== ChatSendStatus.Saving) {
+                    blocked.add(entry.owner_id);
+                }
+                if (blocked.has(entry.owner_id)) {
+                    continue;
+                }
+                try {
+                    const saved = await this.queue.enqueue({
+                        ...entry,
+                        status: ChatSendStatus.Queued,
+                    });
+                    this.pendingSaves.delete(entry.id);
+                    this.replace(saved);
+                    this.opts.changed?.();
+                }
+                catch (err) {
+                    const failed = { ...entry, status: ChatSendStatus.Failed };
+                    this.pendingSaves.set(entry.id, failed);
+                    this.replace(failed);
+                    if (entry.owner_id === this.owner) {
+                        this.error = err;
+                        this.publish();
+                    }
+                    blocked.add(entry.owner_id);
+                }
+            }
+            await this.refresh();
+        });
+    }
+    // Queue confirmations from another tab or the existing upload coordinator.
+    // This does not subscribe to, acknowledge, or alter any server event stream.
+    confirm(chat) {
+        if (chat.owner_id !== this.owner) {
+            return;
+        }
+        this.remember(chat);
+        this.publish();
+    }
+    async refresh() {
+        if (!this.enabled) {
+            return;
+        }
+        const owner = this.owner, signal = this.controller.signal, revision = ++this.revision;
+        try {
+            const stored = await this.opts.store.list(owner);
+            if (!this.current(owner, signal) || revision !== this.revision) {
+                return;
+            }
+            const local = this.entries.filter((entry) => entry.sequence === undefined);
+            const ids = new Set(stored.map((entry) => entry.id));
+            this.entries = [
+                ...stored,
+                ...local.filter((entry) => !ids.has(entry.id)),
+            ];
+            for (const entry of stored) {
+                if (entry.chat) {
+                    this.remember(entry.chat);
+                }
+            }
+            this.error = undefined;
+            this.publish();
+            for (const room of new Set(stored
+                .filter((entry) => !entry.chat)
+                .map((entry) => entry.input.chat_room_id))) {
+                this.work(room, owner, signal);
+            }
+            for (const entry of stored) {
+                if (entry.chat && entry.status === ChatSendStatus.Uploading) {
+                    this.recoverUpload(entry, owner, signal);
+                }
+            }
+        }
+        catch (err) {
+            if (this.current(owner, signal)) {
+                this.error = err;
+                this.publish();
+            }
+        }
+    }
+    async retry(id) {
+        const entry = this.entries.find((value) => value.id === id);
+        if (!entry || !this.enabled) {
+            return;
+        }
+        if (entry.sequence === undefined) {
+            if (entry.status !== ChatSendStatus.Failed) {
+                return;
+            }
+            const saving = { ...entry, status: ChatSendStatus.Saving };
+            this.pendingSaves.set(id, saving);
+            this.replace(saving);
+            this.persist();
+            await this.writes;
+            return;
+        }
+        const signal = this.controller.signal, owner = this.owner;
+        await this.opts.lock(this.roomLock(entry), signal, async () => {
+            if (!this.current(owner, signal)) {
+                return;
+            }
+            const current = (await this.opts.store.list(owner)).find((value) => value.id === id);
+            if (!current || !chatSendNeedsRetry(current)) {
+                return;
+            }
+            if (current.chat) {
+                this.startUpload(current, owner, signal, true);
+            }
+            else {
+                await this.save({ ...current, status: ChatSendStatus.Queued });
+            }
+        });
+        await this.refresh();
+    }
+    async remove(id) {
+        const owner = this.owner, signal = this.controller.signal;
+        let entry = this.entries.find((value) => value.id === id);
+        if (!entry ||
+            !this.current(owner, signal) ||
+            !chatSendCanRemove(entry) ||
+            this.cancellations.has(id)) {
+            return;
+        }
+        this.cancellations.add(id);
+        try {
+            // Finish a pending local save before removing its durable record. The
+            // cancellation flag prevents this tab from starting that message meanwhile.
+            if (entry.status === ChatSendStatus.Saving) {
+                await this.writes;
+                entry = this.entries.find((value) => value.id === id);
+            }
+            if (!entry || !this.current(owner, signal) || !chatSendCanRemove(entry)) {
+                return;
+            }
+            // Cancel only this request. A server response that already arrived wins;
+            // the shared room lock still protects removal from another tab's sender.
+            this.sends.get(id)?.abort();
+            if (entry.sequence === undefined) {
+                this.pendingSaves.delete(id);
+                this.entries = this.entries.filter((value) => value.id !== id);
+                this.publish();
+                this.persist();
+                return;
+            }
+            const removeStored = async () => {
+                if (!this.current(owner, signal))
+                    return;
+                const stored = (await this.opts.store.list(owner)).find((value) => value.id === id);
+                if (stored && !chatSendCanRemove(stored))
+                    return;
+                await this.opts.store.remove(id);
+                this.entries = this.entries.filter((value) => value.id !== id);
+                this.publish();
+                this.opts.changed?.();
+            };
+            // Upload retries use their own lock so a slow multipart never holds the
+            // message lane. Discard must coordinate with that same lock.
+            await this.opts.lock(entry.chat ? this.uploadLock(entry) : this.roomLock(entry), signal, removeStored);
+        }
+        finally {
+            this.cancellations.delete(id);
+            this.persist();
+            await this.refresh();
+        }
+    }
+    work(room, owner, signal) {
+        this.queue.process({
+            owner_id: owner,
+            scope: `chat-send:${room}`,
+            signal,
+            select: (entry) => entry.input.chat_room_id === room && !entry.chat,
+            on_error: (err) => {
+                if (this.current(owner, signal)) {
+                    this.error = err;
+                    this.publish();
+                }
+            },
+            on_idle: () => {
+                if (this.enabled && signal.aborted) {
+                    void this.refresh();
+                }
+            },
+            run: async (entry) => {
+                if (!this.current(owner, signal) || this.cancellations.has(entry.id)) {
+                    return false;
+                }
+                if (entry.status === ChatSendStatus.Sending ||
+                    (entry.status === ChatSendStatus.Interrupted && entry.server_id)) {
+                    if (!entry.server_id) {
+                        await this.save({ ...entry, status: ChatSendStatus.Interrupted });
+                        return false;
+                    }
+                }
+                else if (entry.status !== ChatSendStatus.Queued) {
+                    return false;
+                }
+                let current = entry;
+                const request = new AbortController();
+                const requestSignal = AbortSignal.any([signal, request.signal]);
+                this.sends.set(entry.id, request);
+                try {
+                    current = {
+                        ...entry,
+                        status: ChatSendStatus.Sending,
+                        attempted: true,
+                    };
+                    await this.save(current);
+                    if (!this.current(owner, signal)) {
+                        return false;
+                    }
+                    if (!current.server_id) {
+                        requestSignal.throwIfAborted();
+                        const out = await this.opts.chat.insertOneChat({
+                            in: current.input,
+                            signal: requestSignal,
+                            idempotency_key: current.id,
+                        });
+                        current = {
+                            ...current,
+                            server_id: requiredOperationID(out, "Created chat response did not contain an ID."),
+                        };
+                        // Retain the returned ID even if the page/account changed meanwhile.
+                        await this.save(current);
+                    }
+                    if (!this.current(owner, signal)) {
+                        return false;
+                    }
+                    const out = await this.opts.chat.findOneChat({
+                        id: current.server_id,
+                        signal,
+                    });
+                    const chat = out.value;
+                    if (!chat ||
+                        chat.id !== current.server_id ||
+                        chat.owner_id !== owner ||
+                        chat.chat_room_id !== room) {
+                        throw new Error("Chat confirmation could not be resolved.");
+                    }
+                    if (!this.current(owner, signal)) {
+                        return false;
+                    }
+                    this.remember(chat);
+                    if (current.attachments.files.length) {
+                        current = {
+                            ...current,
+                            chat,
+                            status: ChatSendStatus.UploadInterrupted,
+                        };
+                        await this.save(current);
+                        this.startUpload(current, owner, signal);
+                    }
+                    else {
+                        await this.opts.store.remove(current.id);
+                        this.entries = this.entries.filter((value) => value.id !== current.id);
+                        this.publish();
+                        this.opts.changed?.(chat);
+                    }
+                }
+                catch (err) {
+                    try {
+                        await this.save({
+                            ...current,
+                            status: requestSignal.aborted
+                                ? ChatSendStatus.Interrupted
+                                : ChatSendStatus.Failed,
+                        });
+                    }
+                    catch (storageError) {
+                        this.error = storageError;
+                    }
+                    if (this.current(owner, signal) && !request.signal.aborted) {
+                        this.error = err;
+                        this.publish();
+                    }
+                    return false;
+                }
+                finally {
+                    this.sends.delete(entry.id);
+                }
+                return true;
+            },
+        });
+    }
+    startUpload(entry, owner, signal, reconcile = false) {
+        if (this.uploads.has(entry.id)) {
+            return;
+        }
+        this.uploads.add(entry.id);
+        void this.opts
+            .lock(this.uploadLock(entry), signal, async () => {
+            if (!this.current(owner, signal)) {
+                return;
+            }
+            const stored = (await this.opts.store.list(owner)).find((value) => value.id === entry.id);
+            if (!stored || !chatSendNeedsRetry(stored)) {
+                return;
+            }
+            try {
+                if (reconcile && stored.server_id) {
+                    const out = await this.opts.chat.findOneChat({
+                        id: stored.server_id,
+                        signal,
+                    });
+                    if (!this.current(owner, signal)) {
+                        return;
+                    }
+                    if (out.value?.owner_id !== owner ||
+                        out.value.chat_room_id !== stored.input.chat_room_id) {
+                        throw new Error("Chat confirmation could not be resolved.");
+                    }
+                    if (out.value.objects_uploaded || !out.value.has_objects) {
+                        this.remember(out.value);
+                        await this.opts.store.remove(stored.id);
+                        this.entries = this.entries.filter((value) => value.id !== stored.id);
+                        this.publish();
+                        this.opts.changed?.(out.value);
+                        return;
+                    }
+                }
+                await this.save({ ...stored, status: ChatSendStatus.Uploading });
+                const success = await this.opts.upload(stored, signal);
+                if (!this.current(owner, signal)) {
+                    return;
+                }
+                if (!success) {
+                    throw new Error("Chat attachment upload is incomplete.");
+                }
+                await this.opts.store.remove(entry.id);
+                this.entries = this.entries.filter((value) => value.id !== entry.id);
+                this.publish();
+                this.opts.changed?.(this.confirmed.get(entry.server_id));
+            }
+            catch {
+                await this.save({
+                    ...entry,
+                    status: ChatSendStatus.UploadInterrupted,
+                });
+            }
+        })
+            .catch((err) => {
+            if (this.current(owner, signal)) {
+                this.error = err;
+                this.publish();
+            }
+        })
+            .finally(() => this.uploads.delete(entry.id));
+    }
+    recoverUpload(entry, owner, signal) {
+        if (this.uploads.has(entry.id)) {
+            return;
+        }
+        this.uploads.add(entry.id);
+        void this.opts
+            .lock(this.uploadLock(entry), signal, async () => {
+            if (!this.current(owner, signal)) {
+                return;
+            }
+            const stored = (await this.opts.store.list(owner)).find((value) => value.id === entry.id);
+            if (!stored || stored.status !== ChatSendStatus.Uploading) {
+                return;
+            }
+            // Never repeat a multipart batch or paid personal copy automatically.
+            try {
+                const out = stored.server_id
+                    ? await this.opts.chat.findOneChat({ id: stored.server_id, signal })
+                    : undefined;
+                if (!this.current(owner, signal)) {
+                    return;
+                }
+                if (out?.value &&
+                    out.value.owner_id === owner &&
+                    out.value.chat_room_id === stored.input.chat_room_id &&
+                    (out.value.objects_uploaded || !out.value.has_objects)) {
+                    this.remember(out.value);
+                    await this.opts.store.remove(stored.id);
+                    this.entries = this.entries.filter((value) => value.id !== stored.id);
+                    this.publish();
+                    this.opts.changed?.(out.value);
+                    return;
+                }
+            }
+            catch (err) {
+                if (!this.current(owner, signal)) {
+                    return;
+                }
+                this.error = err;
+            }
+            await this.save({
+                ...stored,
+                status: ChatSendStatus.UploadInterrupted,
+            });
+        })
+            .catch((err) => {
+            if (this.current(owner, signal)) {
+                this.error = err;
+                this.publish();
+            }
+        })
+            .finally(() => this.uploads.delete(entry.id));
+    }
+    uploadLock(entry) {
+        return `chat-upload:${entry.owner_id}:${entry.id}`;
+    }
+    roomLock(entry) {
+        return `${entry.owner_id}:chat-send:${entry.input.chat_room_id}`;
+    }
+    current(owner, signal) {
+        return this.enabled && this.owner === owner && !signal.aborted;
+    }
+    async save(entry) {
+        await this.opts.store.put(entry);
+        this.replace(entry);
+        this.opts.changed?.();
+    }
+    replace(entry) {
+        if (entry.owner_id !== this.owner) {
+            return;
+        }
+        const index = this.entries.findIndex((value) => value.id === entry.id);
+        this.entries =
+            index < 0
+                ? [...this.entries, entry]
+                : this.entries.map((value) => (value.id === entry.id ? entry : value));
+        this.publish();
+    }
+    remember(chat) {
+        const old = this.confirmed.get(chat.id);
+        if (!old || old.updated_at <= chat.updated_at) {
+            this.confirmed.set(chat.id, chat);
+        }
+    }
+    publish() {
+        this.revision++;
+        for (const listener of this.listeners) {
+            listener(this.snapshot);
+        }
+    }
+}
+export function chatSendNeedsRetry(entry) {
+    return (entry.status === ChatSendStatus.Failed ||
+        entry.status === ChatSendStatus.Interrupted ||
+        entry.status === ChatSendStatus.UploadInterrupted);
+}
+export function chatSendCanRemove(entry) {
+    if (!entry.chat && entry.server_id) {
+        return false;
+    }
+    return (entry.status === ChatSendStatus.Saving ||
+        entry.status === ChatSendStatus.Queued ||
+        entry.status === ChatSendStatus.Sending ||
+        chatSendNeedsRetry(entry));
+}

package/dist/src/core/queue-store.d.ts

@@ -0,0 +1,13 @@
+import type { QueueLock, QueueRecord, QueueStore } from "./queue.js";
+export declare class IndexedDBQueueStore<T extends QueueRecord> implements QueueStore<T> {
+    private readonly name;
+    private database?;
+    constructor(name: string);
+    private open;
+    add(entry: T): Promise<T>;
+    put(entry: T): Promise<void>;
+    remove(id: string): Promise<void>;
+    list(ownerID: string): Promise<T[]>;
+    private transaction;
+}
+export declare const browserQueueLock: QueueLock;

package/dist/src/core/queue-store.js

@@ -0,0 +1,112 @@
+// Copyright (C) Fabriktor, Inc. 2025-present.
+//
+// Licensed under the Apache License, Version 2.0 (the "License"); you may
+// not use this file except in compliance with the License. You may obtain
+// a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
+const version = 1;
+const entriesStore = "entries";
+const ownerIndex = "owner_id";
+// IndexedDB preserves structured-clone payloads (including Files). No network
+// operation may begin until the transaction's completion event has fired.
+export class IndexedDBQueueStore {
+    name;
+    database;
+    constructor(name) {
+        this.name = name;
+    }
+    open() {
+        if (this.database) {
+            return this.database;
+        }
+        this.database = new Promise((resolve, reject) => {
+            let blocked = false;
+            const request = indexedDB.open(this.name, version);
+            request.onupgradeneeded = () => {
+                const store = request.result.createObjectStore(entriesStore, {
+                    keyPath: "sequence",
+                    autoIncrement: true,
+                });
+                store.createIndex(ownerIndex, ownerIndex);
+                store.createIndex("id", "id", { unique: true });
+            };
+            request.onsuccess = () => {
+                const db = request.result;
+                if (blocked) {
+                    db.close();
+                    return;
+                }
+                db.onversionchange = () => {
+                    db.close();
+                    this.database = undefined;
+                };
+                resolve(db);
+            };
+            request.onerror = () => {
+                this.database = undefined;
+                reject(request.error);
+            };
+            request.onblocked = () => {
+                blocked = true;
+                this.database = undefined;
+                reject(new Error("Local queue storage upgrade is blocked by another tab."));
+            };
+        });
+        return this.database;
+    }
+    async add(entry) {
+        return this.transaction("readwrite", (store) => {
+            const request = store.add(entry);
+            return () => ({ ...entry, sequence: Number(request.result) });
+        });
+    }
+    async put(entry) {
+        if (entry.sequence === undefined) {
+            throw new Error("Cannot update a queue entry before it is saved.");
+        }
+        await this.transaction("readwrite", (store) => {
+            store.put(entry);
+            return () => undefined;
+        });
+    }
+    async remove(id) {
+        await this.transaction("readwrite", (store) => {
+            const request = store.index("id").getKey(id);
+            request.onsuccess = () => {
+                if (request.result !== undefined) {
+                    store.delete(request.result);
+                }
+            };
+            return () => undefined;
+        });
+    }
+    async list(ownerID) {
+        return this.transaction("readonly", (store) => {
+            const request = store.index(ownerIndex).getAll(ownerID);
+            return () => request.result.sort((a, b) => a.sequence - b.sequence);
+        });
+    }
+    async transaction(mode, run) {
+        const db = await this.open();
+        return new Promise((resolve, reject) => {
+            const tx = db.transaction(entriesStore, mode, mode === "readwrite" ? { durability: "strict" } : undefined);
+            let result;
+            try {
+                result = run(tx.objectStore(entriesStore));
+            }
+            catch (err) {
+                tx.abort();
+                reject(err);
+                return;
+            }
+            tx.oncomplete = () => resolve(result());
+            tx.onabort = () => reject(tx.error ?? new Error("Local queue transaction was aborted."));
+            tx.onerror = () => reject(tx.error);
+        });
+    }
+}
+export const browserQueueLock = async (name, signal, run) => {
+    if (!navigator.locks) {
+        throw new Error("This browser cannot coordinate the local send queue safely.");
+    }
+    await navigator.locks.request(name, { signal }, run);
+};

package/dist/src/core/queue.d.ts

@@ -0,0 +1,31 @@
+export type QueueRecord = {
+    id: string;
+    owner_id: string;
+    sequence?: number;
+};
+export interface QueueStore<T extends QueueRecord> {
+    add(entry: T): Promise<T>;
+    put(entry: T): Promise<void>;
+    remove(id: string): Promise<void>;
+    list(ownerID: string): Promise<T[]>;
+}
+export type QueueLock = (name: string, signal: AbortSignal, run: () => Promise<void>) => Promise<void>;
+export type ProcessQueueOptions<T> = {
+    owner_id: string;
+    scope: string;
+    signal: AbortSignal;
+    select: (entry: T) => boolean;
+    run: (entry: T, signal: AbortSignal) => Promise<boolean>;
+    on_error: (err: unknown) => void;
+    on_idle: () => void;
+};
+export declare class PersistentQueue<T extends QueueRecord> {
+    readonly store: QueueStore<T>;
+    readonly lock: QueueLock;
+    private workers;
+    private pending;
+    private writes;
+    constructor(store: QueueStore<T>, lock: QueueLock);
+    enqueue(entry: T): Promise<T>;
+    process(opts: ProcessQueueOptions<T>): void;
+}

package/dist/src/core/queue.js

@@ -0,0 +1,64 @@
+// Copyright (C) Fabriktor, Inc. 2025-present.
+//
+// Licensed under the Apache License, Version 2.0 (the "License"); you may
+// not use this file except in compliance with the License. You may obtain
+// a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
+// Store order is authoritative across views/tabs. Each scope has one worker;
+// run must durably retire the head before returning true. False pauses the
+// lane without blocking other scopes. Storage/transport failures never skip it.
+export class PersistentQueue {
+    store;
+    lock;
+    workers = new Set();
+    pending = new Map();
+    writes = Promise.resolve();
+    constructor(store, lock) {
+        this.store = store;
+        this.lock = lock;
+    }
+    enqueue(entry) {
+        const saved = this.writes.then(() => this.store.add(entry));
+        this.writes = saved.catch(() => undefined);
+        return saved;
+    }
+    process(opts) {
+        const key = `${opts.owner_id}:${opts.scope}`;
+        if (opts.signal.aborted) {
+            return;
+        }
+        if (this.workers.has(key)) {
+            this.pending.set(key, opts);
+            return;
+        }
+        this.workers.add(key);
+        const drain = async () => {
+            while (!opts.signal.aborted) {
+                let advance = false;
+                await this.lock(key, opts.signal, async () => {
+                    const head = (await this.store.list(opts.owner_id)).find(opts.select);
+                    if (head && !opts.signal.aborted) {
+                        advance = await opts.run(head, opts.signal);
+                    }
+                });
+                if (!advance) {
+                    return;
+                }
+            }
+        };
+        void drain()
+            .catch((err) => {
+            if (!opts.signal.aborted) {
+                opts.on_error(err);
+            }
+        })
+            .finally(() => {
+            this.workers.delete(key);
+            const pending = this.pending.get(key);
+            this.pending.delete(key);
+            opts.on_idle();
+            if (pending) {
+                this.process(pending);
+            }
+        });
+    }
+}

package/dist/src/index.d.ts

@@ -2,12 +2,16 @@ export * from "./auth/auth.js";
 export * from "./billable/billable.js";
 export * from "./calls/calls.js";
 export * from "./chat/chat.js";
+export * from "./chat/optimistic.js";
+export * from "./chat/send-queue.js";
 export * from "./contacts/contacts.js";
 export * from "./core/date.js";
 export * from "./core/err.js";
 export * from "./core/id.js";
 export * from "./core/pre-action.js";
 export * from "./core/pull.js";
+export * from "./core/queue-store.js";
+export * from "./core/queue.js";
 export * from "./core/search.js";
 export * from "./feed/feed.js";
 export * from "./fulfillments/fulfillments.js";

package/dist/src/index.js

@@ -2,12 +2,16 @@ export * from "./auth/auth.js";
 export * from "./billable/billable.js";
 export * from "./calls/calls.js";
 export * from "./chat/chat.js";
+export * from "./chat/optimistic.js";
+export * from "./chat/send-queue.js";
 export * from "./contacts/contacts.js";
 export * from "./core/date.js";
 export * from "./core/err.js";
 export * from "./core/id.js";
 export * from "./core/pre-action.js";
 export * from "./core/pull.js";
+export * from "./core/queue-store.js";
+export * from "./core/queue.js";
 export * from "./core/search.js";
 export * from "./feed/feed.js";
 export * from "./fulfillments/fulfillments.js";

package/dist/src/storage/storage.d.ts

@@ -1,5 +1,5 @@
 import { type Object as StorageObject, type RPStorageUpload } from "@fabriktor/schema";
-import type { OperationResultOf, OptionalField, StorageCollection, StorageOperator, StorageUploadFile, UploadStorageOptions } from "@fabriktor/client";
+import type { OperationResultOf, RequestOptions, OptionalField, StorageCollection, StorageOperator, StorageUploadFile, UploadStorageOptions } from "@fabriktor/client";
 type StorageDownloadOptions = Parameters<StorageOperator["download"]>[1];
 export declare const StorageUploadModeration: {
     readonly Clean: "clean";
@@ -20,19 +20,21 @@ export type UploadObjectsOptions = UploadStorageOptions & {
     col: StorageCollection;
 };
 export type UploadObjectsWithPersonalBoxOptions = UploadObjectsOptions & {
+    personal_box_idempotency_key?: string;
     user_id?: string;
     save_to_personal_box?: boolean;
 };
 export type DownloadObjectsOptions = OptionalField<StorageDownloadOptions, "mime_prefix"> & {
     col: StorageCollection;
 };
-export type UploadUserObjectsOptions = {
+export type UploadUserObjectsOptions = RequestOptions & {
     user_id: string;
     uploader_id?: string;
     full_quality?: boolean;
     files: StorageUploadFile[];
 };
-export type UploadChatObjectsOptions = {
+export type UploadChatObjectsOptions = RequestOptions & {
+    personal_box_idempotency_key?: string;
     chat_id: string;
     user_id?: string;
     uploader_id?: string;

package/dist/src/storage/storage.js

@@ -37,6 +37,7 @@ export class StorageFX {
         this.storage = opts.storage;
     }
     async uploadObjects(opts) {
+        opts.signal?.throwIfAborted();
         validateUpload(opts);
         const owner_id = opts.owner_id.trim();
         const out = await this.storage.upload(opts.col, {
@@ -45,6 +46,8 @@ export class StorageFX {
             full_quality: opts.full_quality,
             public_url: opts.public_url,
             files: opts.files,
+            signal: opts.signal,
+            idempotency_key: opts.idempotency_key,
         });
         return uploadResult(out);
     }
@@ -57,6 +60,8 @@ export class StorageFX {
             full_quality: opts.full_quality,
             public_url: opts.public_url,
             files: opts.files,
+            signal: opts.signal,
+            idempotency_key: opts.idempotency_key,
         });
         if (personal_box_user_id === undefined) {
             return {
@@ -64,12 +69,15 @@ export class StorageFX {
                 primary,
             };
         }
+        opts.signal?.throwIfAborted();
         try {
             const personal_box = await this.uploadUserObjects({
                 user_id: personal_box_user_id,
                 uploader_id: opts.uploader_id,
                 full_quality: opts.full_quality,
                 files: opts.files,
+                signal: opts.signal,
+                idempotency_key: opts.personal_box_idempotency_key,
             });
             return {
                 status: StoragePersonalBoxUploadStatus.Complete,
@@ -114,6 +122,8 @@ export class StorageFX {
             uploader_id: opts.uploader_id,
             full_quality: opts.full_quality,
             files: opts.files,
+            signal: opts.signal,
+            idempotency_key: opts.idempotency_key,
         });
     }
     async uploadChatObjects(opts) {
@@ -131,7 +141,10 @@ export class StorageFX {
             uploader_id: opts.uploader_id,
             full_quality: opts.full_quality,
             files: opts.files,
+            signal: opts.signal,
+            idempotency_key: opts.idempotency_key,
             save_to_personal_box: opts.save_to_personal_box,
+            personal_box_idempotency_key: opts.personal_box_idempotency_key,
         });
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fabriktor/fx",
-  "version": "0.0.100",
+  "version": "0.0.102",
   "description": "![Fabriktor Logo](./img/fabriktor-character.gif)",
   "type": "module",
   "exports": {
@@ -17,7 +17,7 @@
     "typescript": "^6.0.3"
   },
   "dependencies": {
-    "@fabriktor/client": "0.0.80",
+    "@fabriktor/client": "0.0.81",
     "@fabriktor/fx": "0.0.94",
     "@fabriktor/schema": "0.0.62"
   }