@marktiderman/genesis-chat 0.1.1 → 0.2.0

package/src/__tests__/review-fixes-web.test.tsx

@@ -0,0 +1,402 @@
+/**
+ * @vitest-environment happy-dom
+ * @feat:chat
+ * Fixes from the review of the phases 2–4 client, as people see them: a thread that one bad
+ * message can't crash, catch-up after a long time away, read places in topics, link previews,
+ * the emoji picker, broadcast and schedule retries, and the camera.
+ */
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { act, cleanup, configure, fireEvent, render, renderHook, screen, waitFor } from "@testing-library/react";
+import type { ReactNode } from "react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { ChatError } from "../core/client";
+import type { ChatAttachment } from "../core/types";
+import { CATCH_UP_MAX_PAGES, CATCH_UP_PAGE, ChatProvider, chatKeys, useConversation, useLinkPreviews, type ChatProviderProps } from "../react";
+import {
+  ChatBroadcast,
+  ChatEmojiPicker,
+  ChatErrorBoundary,
+  ChatLinkPreview,
+  ChatThread,
+  createMemoryChatClient,
+  useVideoRecorder,
+  type MemoryChatClient,
+  type MemoryChatOptions,
+  type MemoryConversationSeed,
+} from "../web";
+
+afterEach(() => {
+  cleanup();
+  vi.restoreAllMocks();
+  vi.unstubAllGlobals();
+  vi.useRealTimers();
+});
+configure({ asyncUtilTimeout: 5000 });
+
+const ME = "00000000-0000-4000-8000-0000000000a1";
+const SAM = "00000000-0000-4000-8000-0000000000b2";
+const LEE = "00000000-0000-4000-8000-0000000000c3";
+const names: Record<string, string> = { [ME]: "Me", [SAM]: "Sam", [LEE]: "Lee" };
+const resolveUser = (id: string) => ({ name: names[id] ?? "Someone" });
+const at = (min: number) => new Date(Date.now() - (600 - min) * 60_000).toISOString();
+
+function providers(client: MemoryChatClient, extra: Partial<ChatProviderProps> = {}, queryClient = new QueryClient({ defaultOptions: { queries: { retry: false } } })) {
+  const wrapper = ({ children }: { children: ReactNode }) => (
+    <QueryClientProvider client={queryClient}>
+      <ChatProvider client={client} userId={ME} {...extra}>
+        {children}
+      </ChatProvider>
+    </QueryClientProvider>
+  );
+  return { wrapper, queryClient };
+}
+const mount = (client: MemoryChatClient, ui: ReactNode, extra: Partial<ChatProviderProps> = {}) => render(<>{ui}</>, { wrapper: providers(client, extra).wrapper });
+
+const dm = (over: Partial<MemoryConversationSeed> = {}): MemoryConversationSeed => ({
+  id: "c1",
+  members: [{ userId: ME }, { userId: SAM }],
+  messages: [{ id: "m1", senderId: SAM, body: "Hello", createdAt: at(1) }],
+  ...over,
+});
+const make = (seed: MemoryConversationSeed, over: Partial<MemoryChatOptions> = {}) => createMemoryChatClient({ me: ME, conversations: [seed], ...over });
+const openMenu = (el: HTMLElement) => fireEvent.keyDown(el, { key: "Enter" });
+
+describe("one bad message can't take the thread down", () => {
+  it("draws a conversation whose other member stored malformed hours", async () => {
+    const client = make(dm(), { availability: { [SAM]: { timeZone: "UTC", hours: { mon: [[9, 17]], tue: 5 } as never } } });
+    mount(client, <ChatThread conversationId="c1" resolveUser={resolveUser} />);
+    await screen.findByText("Hello");
+    await waitFor(() => expect(client.calls.some((c) => c.method === "availabilityFor")).toBe(true));
+    expect(screen.getByText("Hello")).toBeTruthy();
+  });
+
+  it("an attachment kind named after a prototype key (constructor) gets the generic card", async () => {
+    const client = make(dm({ messages: [{ id: "a", senderId: SAM, body: "see this", createdAt: at(1), attachments: [{ kind: "constructor", ref: {} }] }] }));
+    mount(client, <ChatThread conversationId="c1" resolveUser={resolveUser} />, { attachmentKinds: { form: { title: () => "A form" } } });
+    await screen.findByText("see this");
+    expect(screen.getByText("Constructor")).toBeTruthy();
+  });
+
+  it("an app card whose functions throw or return junk falls back to the generic card", async () => {
+    const error = vi.spyOn(console, "error").mockImplementation(() => undefined);
+    const client = make(
+      dm({
+        messages: [
+          { id: "a", senderId: SAM, body: "first", createdAt: at(1), attachments: [{ kind: "form", ref: {} }] },
+          { id: "b", senderId: SAM, body: "second", createdAt: at(2), attachments: [{ kind: "lesson", ref: {} }] },
+        ],
+      }),
+    );
+    mount(client, <ChatThread conversationId="c1" resolveUser={resolveUser} />, {
+      attachmentKinds: {
+        form: {
+          title: (a: ChatAttachment) => {
+            throw new Error(`bad ref ${String(a.kind)}`);
+          },
+        },
+        lesson: { title: () => 42 as unknown as string },
+      },
+    });
+    await screen.findByText("second");
+    expect(screen.getByText("Form")).toBeTruthy();
+    expect(screen.getByText("Lesson")).toBeTruthy();
+    expect(error).toHaveBeenCalled();
+  });
+
+  it("an attachment slot that throws shows the generic card instead", async () => {
+    vi.spyOn(console, "error").mockImplementation(() => undefined);
+    const client = make(dm({ messages: [{ id: "a", senderId: SAM, body: "with a form", createdAt: at(1), attachments: [{ kind: "form", name: "Check-in", ref: {} }] }] }));
+    const Boom = () => {
+      throw new Error("the app's renderer broke");
+    };
+    mount(client, <ChatThread conversationId="c1" resolveUser={resolveUser} slots={{ attachment: Boom }} />);
+    await screen.findByText("with a form");
+    expect(screen.getByText("Check-in")).toBeTruthy();
+  });
+
+  it("ChatErrorBoundary shows its fallback and reports the error", () => {
+    const onError = vi.fn();
+    vi.spyOn(console, "error").mockImplementation(() => undefined);
+    const Boom = () => {
+      throw new Error("row broke");
+    };
+    render(
+      <ChatErrorBoundary fallback={<span>could not draw</span>} onError={onError}>
+        <Boom />
+      </ChatErrorBoundary>,
+    );
+    expect(screen.getByText("could not draw")).toBeTruthy();
+    expect(onError).toHaveBeenCalled();
+  });
+});
+
+describe("catch-up after a long time away", () => {
+  const seedMessages = (n: number) => Array.from({ length: n }, (_, i) => ({ id: `m${i + 1}`, senderId: SAM, body: `message ${i + 1}`, createdAt: new Date(Date.UTC(2026, 0, 1, 0, 0, i)).toISOString() }));
+  const key = [...chatKeys.conversation("c1"), "messages", null, null] as const;
+
+  it("pages until it has everything", async () => {
+    const client = make(dm({ messages: seedMessages(450) }));
+    const first = (await client.messages("c1", { beforeSeq: 2, limit: 1 })).messages;
+    const { wrapper, queryClient } = providers(client);
+    queryClient.setQueryData(key, { messages: first, hasEarlier: false });
+    const { result } = renderHook(() => useConversation("c1", { markRead: false }), { wrapper });
+    await waitFor(() => expect(result.current.messages).toHaveLength(450));
+    expect(client.calls.filter((c) => c.method === "messages" && (c.args[1] as { afterSeq?: number })?.afterSeq != null)).toHaveLength(3);
+  });
+
+  it(`after ${CATCH_UP_MAX_PAGES} full pages it shows the newest page, with the rest behind "load earlier"`, async () => {
+    const total = CATCH_UP_PAGE * CATCH_UP_MAX_PAGES + 300;
+    const client = make(dm({ messages: seedMessages(total) }));
+    const first = (await client.messages("c1", { beforeSeq: 2, limit: 1 })).messages;
+    const { wrapper, queryClient } = providers(client);
+    queryClient.setQueryData(key, { messages: first, hasEarlier: false });
+    const { result } = renderHook(() => useConversation("c1", { markRead: false }), { wrapper });
+    await waitFor(() => expect(result.current.messages.at(-1)?.body).toBe(`message ${total}`));
+    await waitFor(() => expect(result.current.messages).toHaveLength(50));
+    expect(result.current.hasEarlier).toBe(true);
+  });
+});
+
+describe("read places", () => {
+  const cohort = make({
+    id: "c1",
+    members: [{ userId: ME }, { userId: SAM }, { userId: LEE }],
+    topics: [{ topic: "w1", title: "Week 1" }],
+    messages: [
+      { id: "t1", senderId: SAM, body: "in week 1", topic: "w1", createdAt: at(1) },
+      { id: "g1", senderId: LEE, body: "general, unseen", createdAt: at(2) },
+      { id: "t2", senderId: SAM, body: "more week 1", topic: "w1", createdAt: at(3) },
+    ],
+  });
+
+  it("a topic view doesn't move your read place (it would pass unseen messages in other topics)", async () => {
+    const { wrapper } = providers(cohort);
+    const { result } = renderHook(() => useConversation("c1", { topic: "w1" }), { wrapper });
+    await waitFor(() => expect(result.current.messages).toHaveLength(2));
+    await act(() => new Promise((r) => setTimeout(r, 50)));
+    const mine = async () => (await cohort.members("c1")).find((m) => m.userId === ME)!.lastReadSeq;
+    expect(await mine()).toBe(0);
+    // The whole timeline does.
+    renderHook(() => useConversation("c1"), { wrapper });
+    await waitFor(async () => expect(await mine()).toBe(3));
+  });
+});
+
+describe("link previews", () => {
+  const preview = { url: "https://example.test/a", status: "ok" as const, title: "A post", description: null, imageUrl: "https://tracker.test/pixel.png", siteName: "Example", fetchedAt: "" };
+
+  it("show no image by default: the linked site never learns who read it", () => {
+    render(<ChatLinkPreview preview={preview} />);
+    expect(screen.getByTestId("genesis-chat-link-preview")).toBeTruthy();
+    expect(screen.queryByTestId("genesis-chat-link-preview-image")).toBeNull();
+  });
+
+  it("load the image through the app's proxy when asked, and never without one", () => {
+    const { rerender } = render(<ChatLinkPreview preview={preview} images="proxy" proxyUrl={(u) => `/img-proxy?u=${encodeURIComponent(u)}`} />);
+    expect(screen.getByTestId("genesis-chat-link-preview-image").getAttribute("src")).toBe("/img-proxy?u=https%3A%2F%2Ftracker.test%2Fpixel.png");
+    rerender(<ChatLinkPreview preview={preview} images="proxy" />);
+    expect(screen.queryByTestId("genesis-chat-link-preview-image")).toBeNull();
+    rerender(<ChatLinkPreview preview={preview} images="direct" />);
+    expect(screen.getByTestId("genesis-chat-link-preview-image").getAttribute("src")).toBe(preview.imageUrl);
+  });
+
+  it("ask once per message: a new message with a link doesn't refetch the others", async () => {
+    const client = make(dm({ messages: [{ id: "m1", senderId: SAM, body: "https://example.test/a", createdAt: at(1) }, { id: "m2", senderId: SAM, body: "https://example.test/b", createdAt: at(2) }] }), { linkPreviews: [preview] });
+    const { wrapper } = providers(client);
+    const { result, rerender } = renderHook(({ ids }) => useLinkPreviews(ids), { wrapper, initialProps: { ids: ["m1"] } });
+    await waitFor(() => expect(result.current.m1?.[0]?.title).toBe("A post"));
+    rerender({ ids: ["m1", "m2"] });
+    await waitFor(() => expect(result.current.m2).toBeDefined());
+    const asked = client.calls.filter((c) => c.method === "linkPreviewsFor").flatMap((c) => c.args[0] as string[]);
+    expect(asked.filter((id) => id === "m1")).toHaveLength(1);
+  });
+});
+
+describe("the emoji picker", () => {
+  it("fetches nothing from a CDN: without emojibaseUrl it isn't offered", async () => {
+    const fetchMock = vi.fn();
+    vi.stubGlobal("fetch", fetchMock);
+    vi.spyOn(console, "warn").mockImplementation(() => undefined);
+    render(<ChatEmojiPicker onSelect={() => undefined} />);
+    expect(screen.getByTestId("genesis-chat-emoji-picker-unset")).toBeTruthy();
+    const client = make(dm());
+    mount(client, <ChatThread conversationId="c1" resolveUser={resolveUser} />);
+    await screen.findByTestId("genesis-chat-input");
+    expect(screen.queryByTestId("genesis-chat-emoji-button")).toBeNull();
+    expect(screen.queryByTestId("genesis-chat-more-reactions")).toBeNull();
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+
+  it("is offered once the app hosts the data", async () => {
+    const client = make(dm());
+    mount(client, <ChatThread conversationId="c1" resolveUser={resolveUser} emojibaseUrl="/emojibase" />);
+    expect(await screen.findByTestId("genesis-chat-emoji-button")).toBeTruthy();
+  });
+});
+
+describe("retrying a broadcast or a schedule", () => {
+  it("a broadcast sent again after a timeout keeps its clientId, and a double click sends once", async () => {
+    const client = createMemoryChatClient({ me: ME, conversations: [dm(), { id: "c2", members: [{ userId: ME }, { userId: LEE }] }] });
+    const real = client.broadcast.bind(client);
+    const ids: string[] = [];
+    let fail = true;
+    client.broadcast = vi.fn(async (convs: string[], clientId: string, body: string) => {
+      ids.push(clientId);
+      await new Promise((r) => setTimeout(r, 20));
+      if (fail) {
+        fail = false;
+        throw new ChatError("timeout", undefined, "broadcast_message");
+      }
+      return real(convs, clientId, body);
+    });
+    mount(client, <ChatBroadcast resolveUser={resolveUser} />);
+    fireEvent.change(screen.getByLabelText("Message"), { target: { value: "Session moved" } });
+    await screen.findByText("Lee");
+    fireEvent.click(screen.getByRole("button", { name: "Select all" }));
+    const send = screen.getByTestId("genesis-chat-broadcast-send");
+    fireEvent.click(send);
+    fireEvent.click(send);
+    await waitFor(() => expect(ids).toHaveLength(1));
+    await act(() => new Promise((r) => setTimeout(r, 40)));
+    expect(ids).toHaveLength(1);
+    fireEvent.click(screen.getByTestId("genesis-chat-broadcast-send"));
+    await waitFor(() => expect(ids).toHaveLength(2));
+    expect(ids[1]).toBe(ids[0]);
+  });
+
+  it("a schedule tried again after a failure keeps its clientId", async () => {
+    const client = make(dm());
+    const real = client.schedule.bind(client);
+    const ids: string[] = [];
+    let fail = true;
+    client.schedule = vi.fn(async (input) => {
+      ids.push(input.clientId);
+      if (fail) throw new ChatError("timeout", undefined, "schedule_message");
+      return real(input);
+    });
+    mount(client, <ChatThread conversationId="c1" resolveUser={resolveUser} />);
+    const box = (await screen.findByTestId("genesis-chat-input")) as HTMLTextAreaElement;
+    fireEvent.change(box, { target: { value: "Later" } });
+    openMenu(await screen.findByTestId("genesis-chat-send-menu"));
+    fireEvent.click((await screen.findAllByTestId("genesis-chat-schedule-pick"))[0]!);
+    await waitFor(() => expect(ids.length).toBeGreaterThan(0));
+    await waitFor(() => expect((screen.getByTestId("genesis-chat-send-menu") as HTMLButtonElement).disabled).toBe(false));
+    expect(box.value).toBe("Later");
+    fail = false;
+    const before = ids.length;
+    openMenu(screen.getByTestId("genesis-chat-send-menu"));
+    fireEvent.click((await screen.findAllByTestId("genesis-chat-schedule-pick"))[0]!);
+    await waitFor(() => expect(box.value).toBe(""));
+    expect(ids.length).toBeGreaterThan(before);
+    expect(new Set(ids).size).toBe(1);
+  });
+
+  it("the custom time defaults to an hour from when the dialog opens", async () => {
+    vi.useFakeTimers({ toFake: ["Date"] });
+    const t0 = new Date(2026, 9, 26, 8, 0, 0);
+    vi.setSystemTime(t0);
+    const client = make(dm());
+    mount(client, <ChatThread conversationId="c1" resolveUser={resolveUser} />);
+    fireEvent.change(await screen.findByTestId("genesis-chat-input"), { target: { value: "Later" } });
+    // The menu (and its dialog) are drawn now, three hours before the dialog opens.
+    const menu = await screen.findByTestId("genesis-chat-send-menu");
+    vi.setSystemTime(new Date(2026, 9, 26, 11, 0, 0));
+    openMenu(menu);
+    fireEvent.click(await screen.findByTestId("genesis-chat-schedule-custom"));
+    const input = (await screen.findByTestId("genesis-chat-schedule-input")) as HTMLInputElement;
+    await waitFor(() => expect(input.value).toBe("2026-10-26T12:00"));
+  });
+});
+
+describe("the camera", () => {
+  const realMedia = Object.getOwnPropertyDescriptor(navigator, "mediaDevices");
+  afterEach(() => {
+    if (realMedia) Object.defineProperty(navigator, "mediaDevices", realMedia);
+    else delete (navigator as { mediaDevices?: unknown }).mediaDevices;
+  });
+
+  class FakeRecorder {
+    static isTypeSupported = (t: string) => t === "video/webm";
+    state: "inactive" | "recording" = "inactive";
+    mimeType = "video/webm";
+    ondataavailable: ((e: { data: Blob }) => void) | null = null;
+    onstop: (() => void) | null = null;
+    start() {
+      this.state = "recording";
+    }
+    stop() {
+      this.state = "inactive";
+      this.ondataavailable?.({ data: new Blob(["frames"], { type: "video/webm" }) });
+      this.onstop?.();
+    }
+  }
+  async function recordTake() {
+    vi.stubGlobal("MediaRecorder", FakeRecorder);
+    Object.defineProperty(navigator, "mediaDevices", { configurable: true, value: { getUserMedia: async () => ({ getTracks: () => [{ stop: () => undefined }] }) } });
+    fireEvent.click(await screen.findByTestId("genesis-chat-video-button"));
+    const record = await screen.findByTestId("genesis-chat-video-record");
+    await waitFor(() => expect((record as HTMLButtonElement).disabled).toBe(false));
+    await act(async () => {
+      fireEvent.click(record);
+    });
+    fireEvent.click(await screen.findByTestId("genesis-chat-video-stop"));
+    await screen.findByTestId("genesis-chat-video-retake");
+  }
+
+  it("cancels a hosted video upload, sending nothing", async () => {
+    let signal: AbortSignal | undefined;
+    vi.stubGlobal("fetch", vi.fn((_url: string, init: RequestInit) => new Promise((_r, reject) => {
+      signal = init.signal ?? undefined;
+      signal?.addEventListener("abort", () => reject(new DOMException("aborted", "AbortError")));
+    })));
+    const client = make(dm());
+    mount(client, <ChatThread conversationId="c1" resolveUser={resolveUser} />, { videoUpload: { create: async () => ({ url: "https://up.test/1", providerId: "u1", provider: "mux" }) } });
+    await recordTake();
+    await act(async () => {
+      fireEvent.click(screen.getByTestId("genesis-chat-video-send"));
+    });
+    fireEvent.click(await screen.findByTestId("genesis-chat-video-cancel-upload"));
+    await waitFor(() => expect(signal?.aborted).toBe(true));
+    await screen.findByTestId("genesis-chat-video-send");
+    expect(client.calls.some((c) => c.method === "send")).toBe(false);
+  });
+
+  it("keeps the take's preview while it uploads, and frees it once the message lands", async () => {
+    const revoke = vi.fn();
+    vi.stubGlobal("URL", Object.assign(class extends URL {}, { createObjectURL: () => "blob:take", revokeObjectURL: revoke, canParse: URL.canParse }));
+    const client = make(dm());
+    let land!: () => void;
+    const upload = client.upload.bind(client);
+    client.upload = vi.fn(async (...args: Parameters<typeof upload>) => {
+      await new Promise<void>((r) => (land = r));
+      return upload(...args);
+    });
+    mount(client, <ChatThread conversationId="c1" resolveUser={resolveUser} />);
+    await recordTake();
+    await act(async () => {
+      fireEvent.click(screen.getByTestId("genesis-chat-video-send"));
+    });
+    await waitFor(() => expect(screen.queryByTestId("genesis-chat-video-recorder")).toBeNull());
+    expect(revoke).not.toHaveBeenCalledWith("blob:take");
+    await waitFor(() => expect(client.upload).toHaveBeenCalled());
+    land();
+    await waitFor(() => expect(client.calls.some((c) => c.method === "send")).toBe(true));
+    await waitFor(() => expect(revoke).toHaveBeenCalledWith("blob:take"));
+  });
+
+  it("turns off a camera that answers after the recorder closed", async () => {
+    vi.stubGlobal("MediaRecorder", class { static isTypeSupported = () => true; });
+    let answer!: (s: unknown) => void;
+    const stop = vi.fn();
+    Object.defineProperty(navigator, "mediaDevices", { configurable: true, value: { getUserMedia: () => new Promise((r) => (answer = r)) } });
+    const { result, unmount } = renderHook(() => useVideoRecorder({ maxMs: 60_000 }));
+    let opened!: Promise<boolean>;
+    act(() => {
+      opened = result.current.open();
+    });
+    unmount();
+    answer({ getTracks: () => [{ stop }, { stop }] });
+    expect(await opened).toBe(false);
+    expect(stop).toHaveBeenCalledTimes(2);
+  });
+});

package/src/__tests__/server-effects.test.ts

@@ -0,0 +1,158 @@
+/** @feat:chat The runner's phase 2–4 work: moderation and unfurl effects, scheduled posting, retention. */
+import { describe, expect, it, vi } from "vitest";
+import { createChatRunner, type ChatEffect, type LinkUnfurler, type Moderator } from "../server";
+import { fakeSupabase } from "./server-fakes";
+
+const effect = (id: number, kind: string, payload: Record<string, unknown>, attempts = 1): ChatEffect => ({ id, kind, key: `${kind}:${id}`, payload, attempts });
+const deliver = async () => {};
+
+describe("createChatRunner: moderate", () => {
+  const message = { id: "m1", body: "you are useless", deleted_at: null };
+  const photo = { id: "a1", message_id: "m1", kind: "image", provider: "storage", path: "c/u/p.jpg", mime: "image/jpeg" };
+  const voice = { id: "a2", message_id: "m1", kind: "voice", provider: "storage", path: "c/u/v.m4a", mime: "audio/mp4" };
+
+  it("claims moderate only with a moderator, sends text and signed photo URLs, and stores the verdict", async () => {
+    const moderate = vi.fn(async () => ({ result: "hidden" as const, reason: "Automatic moderation: harassment 0.95" }));
+    const moderator: Moderator = { name: "fake", moderate };
+    const sb = fakeSupabase({
+      rpc: { claim_effects: () => [effect(1, "moderate", { message_id: "m1" })] },
+      tables: { messages: [message], attachments: [photo, voice] },
+    });
+    expect(await createChatRunner({ supabase: sb.client, deliver, moderator }).run()).toMatchObject({ claimed: 1, done: 1, failed: 0 });
+    expect(sb.rpcCalls[0]!.args.p_kinds).toEqual(["push", "transcribe", "storage.remove", "video.remove", "moderate"]);
+    expect(sb.signed).toEqual(["c/u/p.jpg@600"]);
+    expect(moderate).toHaveBeenCalledWith({ text: "you are useless", imageUrls: ["https://files.test/c/u/p.jpg?token=x"] });
+    expect(sb.rpcCalls).toContainEqual({
+      fn: "moderate_message",
+      args: { p_message_id: "m1", p_result: "hidden", p_reason: "Automatic moderation: harassment 0.95" },
+    });
+  });
+
+  it("sends every photo, in position order, so none past the first few escapes the verdict", async () => {
+    const moderate = vi.fn(async () => ({ result: "clean" as const }));
+    const photos = [5, 0, 3, 1, 4, 2].map((position) => ({ ...photo, id: `p${position}`, position, path: `c/u/${position}.jpg` }));
+    const sb = fakeSupabase({
+      rpc: { claim_effects: () => [effect(1, "moderate", { message_id: "m1" })] },
+      tables: { messages: [message], attachments: photos },
+    });
+    await createChatRunner({ supabase: sb.client, deliver, moderator: { name: "fake", moderate } }).run();
+    expect(moderate).toHaveBeenCalledWith({ text: "you are useless", imageUrls: [0, 1, 2, 3, 4, 5].map((n) => `https://files.test/c/u/${n}.jpg?token=x`) });
+  });
+
+  it("does not claim moderate without a moderator", async () => {
+    const sb = fakeSupabase({ rpc: { claim_effects: () => [] } });
+    await createChatRunner({ supabase: sb.client, deliver }).run();
+    expect(sb.rpcCalls[0]!.args.p_kinds).not.toContain("moderate");
+  });
+
+  it("calls a deleted message clean (releasing its held push) without judging it, and retries a provider failure", async () => {
+    const moderate = vi.fn(async () => ({ result: "clean" as const }));
+    const gone = fakeSupabase({
+      rpc: { claim_effects: () => [effect(1, "moderate", { message_id: "m1" })] },
+      tables: { messages: [{ ...message, deleted_at: "2026-10-25T00:00:00Z" }] },
+    });
+    expect(await createChatRunner({ supabase: gone.client, deliver, moderator: { name: "fake", moderate } }).run()).toMatchObject({ done: 1 });
+    expect(moderate).not.toHaveBeenCalled();
+    expect(gone.rpcCalls).toContainEqual({ fn: "moderate_message", args: { p_message_id: "m1", p_result: "clean", p_reason: null } });
+
+    const down = fakeSupabase({ rpc: { claim_effects: () => [effect(1, "moderate", { message_id: "m1" })] }, tables: { messages: [message] } });
+    const failing: Moderator = { name: "fake", moderate: () => Promise.reject(new Error("OpenAI moderation answered HTTP 503")) };
+    expect(await createChatRunner({ supabase: down.client, deliver, moderator: failing }).run()).toMatchObject({ failed: 1 });
+    expect(down.rpcCalls).toContainEqual({ fn: "complete_effect", args: { p_id: 1, p_error: "OpenAI moderation answered HTTP 503" } });
+    expect(down.rpcCalls.some((c) => c.fn === "moderate_message")).toBe(false);
+  });
+
+  it("never fails open silently: on the last attempt it files flagged, moderation unavailable", async () => {
+    const sb = fakeSupabase({ rpc: { claim_effects: () => [effect(1, "moderate", { message_id: "m1" }, 8)] }, tables: { messages: [message] } });
+    const failing: Moderator = { name: "fake", moderate: () => Promise.reject(new Error("OpenAI moderation answered HTTP 503")) };
+    expect(await createChatRunner({ supabase: sb.client, deliver, moderator: failing }).run()).toMatchObject({ failed: 1 });
+    expect(sb.rpcCalls).toContainEqual({
+      fn: "moderate_message",
+      args: { p_message_id: "m1", p_result: "flagged", p_reason: "moderation unavailable" },
+    });
+  });
+});
+
+describe("createChatRunner: unfurl", () => {
+  it("saves an ok preview with its fields", async () => {
+    const unfurler: LinkUnfurler = {
+      unfurl: vi.fn(async (url: string) => ({ url, status: "ok" as const, title: "Plan", description: "Week 3", imageUrl: "https://x.test/i.png", siteName: "X" })),
+    };
+    const sb = fakeSupabase({ rpc: { claim_effects: () => [effect(1, "unfurl", { url: "https://x.test/plan" })] } });
+    expect(await createChatRunner({ supabase: sb.client, deliver, unfurler }).run()).toMatchObject({ done: 1 });
+    expect(sb.rpcCalls[0]!.args.p_kinds).toContain("unfurl");
+    expect(sb.rpcCalls).toContainEqual({
+      fn: "save_link_preview",
+      args: { p_url: "https://x.test/plan", p_status: "ok", p_title: "Plan", p_description: "Week 3", p_image_url: "https://x.test/i.png", p_site_name: "X" },
+    });
+  });
+
+  it("saves blocked and failed statuses without fields", async () => {
+    const unfurler: LinkUnfurler = { unfurl: async (url) => ({ url, status: "blocked", title: "should not be kept" }) };
+    const sb = fakeSupabase({ rpc: { claim_effects: () => [effect(1, "unfurl", { url: "https://10.0.0.1/" })] } });
+    await createChatRunner({ supabase: sb.client, deliver, unfurler }).run();
+    expect(sb.rpcCalls).toContainEqual({
+      fn: "save_link_preview",
+      args: { p_url: "https://10.0.0.1/", p_status: "blocked", p_title: null, p_description: null, p_image_url: null, p_site_name: null },
+    });
+  });
+});
+
+describe("createChatRunner: scheduled messages", () => {
+  it("posts each due message and counts posted and refused", async () => {
+    const sb = fakeSupabase({
+      rpc: {
+        claim_effects: () => [],
+        due_scheduled: () => ["s1", "s2", "s3"],
+        post_scheduled: (a) => (a.p_id === "s2" ? null : `msg-${String(a.p_id)}`),
+      },
+    });
+    const report = await createChatRunner({ supabase: sb.client, deliver }).run();
+    expect(report.scheduled).toEqual({ due: 3, posted: 2, skipped: 1, failed: 0 });
+    expect(sb.rpcCalls).toContainEqual({ fn: "due_scheduled", args: { p_limit: 50 } });
+    expect(sb.rpcCalls.filter((c) => c.fn === "post_scheduled").map((c) => c.args.p_id)).toEqual(["s1", "s2", "s3"]);
+  });
+
+  it("reports a failing due_scheduled without failing the run, and can be turned off", async () => {
+    const sb = fakeSupabase({
+      rpc: {
+        claim_effects: () => [],
+        due_scheduled: () => {
+          throw new Error("42501");
+        },
+      },
+    });
+    const report = await createChatRunner({ supabase: sb.client, deliver }).run();
+    expect(report).toMatchObject({ claimed: 0, scheduled: { due: 0, posted: 0, skipped: 0, failed: 0 }, errors: ["due_scheduled: 42501"] });
+
+    const off = fakeSupabase({ rpc: { claim_effects: () => [] } });
+    const quiet = await createChatRunner({ supabase: off.client, deliver, scheduled: false }).run();
+    expect(quiet.scheduled).toBeUndefined();
+    expect(off.rpcCalls.some((c) => c.fn === "due_scheduled")).toBe(false);
+  });
+});
+
+describe("createChatRunner: retention", () => {
+  it("purges only when asked, in batches until a short one", async () => {
+    const answers = [1000, 1000, 12];
+    const sb = fakeSupabase({ rpc: { claim_effects: () => [], purge_expired: () => answers.shift() ?? 0 } });
+    expect((await createChatRunner({ supabase: sb.client, deliver }).run()).purged).toBeUndefined();
+    expect(sb.rpcCalls.some((c) => c.fn === "purge_expired")).toBe(false);
+
+    const report = await createChatRunner({ supabase: sb.client, deliver, retention: true }).run();
+    expect(report.purged).toBe(2012);
+    expect(sb.rpcCalls.filter((c) => c.fn === "purge_expired").map((c) => c.args)).toEqual([{ p_limit: 1000 }, { p_limit: 1000 }, { p_limit: 1000 }]);
+  });
+
+  it("reports a purge failure", async () => {
+    const sb = fakeSupabase({
+      rpc: {
+        claim_effects: () => [],
+        purge_expired: () => {
+          throw new Error("57014");
+        },
+      },
+    });
+    expect(await createChatRunner({ supabase: sb.client, deliver, retention: true, scheduled: false }).run()).toMatchObject({ purged: 0, errors: ["purge_expired: 57014"] });
+  });
+});

package/src/__tests__/server-fakes.ts

@@ -0,0 +1,90 @@
+/** @feat:chat Fakes for the server tests: a supabase-js shaped object and a fetch. */
+import type { ChatSupabase } from "../core/client";
+
+export type Row = Record<string, unknown>;
+type RpcHandler = (args: Record<string, unknown>) => unknown;
+type Err = { message?: string; code?: string; statusCode?: string } | null;
+
+export interface FakeSupabase {
+  client: ChatSupabase;
+  rpcCalls: { fn: string; args: Record<string, unknown> }[];
+  removed: { bucket: string; paths: string[] }[];
+  signed: string[];
+}
+
+/** rpc results by function name; tables as arrays of rows, filtered by eq(). */
+export function fakeSupabase(opts: {
+  rpc?: Record<string, RpcHandler>;
+  tables?: Record<string, Row[]>;
+  removeError?: Err;
+  signedUrlError?: Err;
+}): FakeSupabase {
+  const rpcCalls: FakeSupabase["rpcCalls"] = [];
+  const removed: FakeSupabase["removed"] = [];
+  const signed: string[] = [];
+  const builder = (table: string) => {
+    const filters: [string, unknown][] = [];
+    let orderBy: string | null = null;
+    const sorted = (list: Row[]) => (orderBy ? [...list].sort((x, y) => Number(x[orderBy!]) - Number(y[orderBy!])) : list);
+    const rows = () => sorted((opts.tables?.[table] ?? []).filter((r) => filters.every(([k, v]) => r[k] === v)));
+    const b = {
+      select: () => b,
+      eq: (k: string, v: unknown) => (filters.push([k, v]), b),
+      order: (k: string) => ((orderBy = k), b),
+      limit: () => b,
+      maybeSingle: async () => ({ data: rows()[0] ?? null, error: null }),
+      // Awaiting the builder itself lists every matching row.
+      then: (resolve: (v: { data: Row[]; error: null }) => unknown, reject?: (e: unknown) => unknown) =>
+        Promise.resolve({ data: rows(), error: null }).then(resolve, reject),
+    };
+    return b;
+  };
+  const client = {
+    schema: () => ({
+      rpc: async (fn: string, args: Record<string, unknown>) => {
+        rpcCalls.push({ fn, args });
+        const h = opts.rpc?.[fn];
+        try {
+          return { data: h ? h(args) : null, error: null };
+        } catch (e) {
+          return { data: null, error: { code: (e as Error).message } };
+        }
+      },
+      from: builder,
+    }),
+    storage: {
+      from: (bucket: string) => ({
+        remove: async (paths: string[]) => {
+          removed.push({ bucket, paths });
+          return { data: opts.removeError ? null : paths.map((name) => ({ name })), error: opts.removeError ?? null };
+        },
+        createSignedUrl: async (path: string, seconds: number) => {
+          signed.push(`${path}@${seconds}`);
+          return opts.signedUrlError
+            ? { data: null, error: opts.signedUrlError }
+            : { data: { signedUrl: `https://files.test/${path}?token=x` }, error: null };
+        },
+      }),
+    },
+  };
+  return { client: client as unknown as ChatSupabase, rpcCalls, removed, signed };
+}
+
+export interface FakeFetch {
+  fetch: typeof fetch;
+  calls: { url: string; init: RequestInit | undefined }[];
+}
+
+/** A fetch answering with `respond(url, init)`. */
+export function fakeFetch(respond: (url: string, init: RequestInit | undefined) => Response | Promise<Response>): FakeFetch {
+  const calls: FakeFetch["calls"] = [];
+  const f = (async (input: RequestInfo | URL, init?: RequestInit) => {
+    const url = typeof input === "string" ? input : input instanceof URL ? input.href : input.url;
+    calls.push({ url, init });
+    return respond(url, init);
+  }) as typeof fetch;
+  return { fetch: f, calls };
+}
+
+export const jsonResponse = (body: unknown, status = 200) =>
+  new Response(JSON.stringify(body), { status, headers: { "content-type": "application/json" } });