Merge branch 'feature/cancel-queued-message' into predev

# Conflicts:
#	backend-handoff.md

3 files changed, 231 insertions, 10 deletions

diff --git a/src/features/surface-host/ui/MessageQueueList.svelte b/src/features/surface-host/ui/MessageQueueList.svelte
index 554fa02..b260de2 100644
--- a/src/features/surface-host/ui/MessageQueueList.svelte
+++ b/src/features/surface-host/ui/MessageQueueList.svelte
@@ -1,21 +1,92 @@
 <script lang="ts">
-  import { parseMessageQueuePayload } from "../logic/message-queue";
+  import {
+    parseMessageQueuePayload,
+    reconcileCancelledIds,
+    selectVisibleMessages,
+  } from "../logic/message-queue";
 
-  let { payload }: { readonly payload: unknown } = $props();
+  let {
+    payload,
+    onCancel,
+  }: {
+    readonly payload: unknown;
+    /**
+     * Cancel (remove) a single queued message by id (`chat.queue.cancel`).
+     * Required-but-nullable (not optional) so a parent can thread a
+     * `| undefined` callback through under `exactOptionalPropertyTypes`:
+     * `undefined` → a read-only list (no × affordance), e.g. a generic surface
+     * context with no conversation scope. The list still reconciles from the
+     * surface either way.
+     */
+    readonly onCancel: ((messageId: string) => void) | undefined;
+  } = $props();
 
   // Parse defensively; an unparseable payload yields null → render nothing
   // (graceful skip, per the custom-field contract).
   const data = $derived(parseMessageQueuePayload(payload));
+
+  // Optimistic-removal: a cancelled id is hidden the instant the user clicks,
+  // ahead of the surface's post-cancel snapshot. Reconcile on every payload
+  // change so a confirmed-removed id (no longer in the snapshot) is dropped
+  // from the set — keeping it bounded (pure helpers in logic/message-queue).
+  let cancelledIds = $state<ReadonlySet<string>>(new Set());
+
+  $effect(() => {
+    const parsed = data;
+    if (parsed === null) return;
+    const next = reconcileCancelledIds(parsed.messages, cancelledIds);
+    if (next !== cancelledIds) cancelledIds = next;
+  });
+
+  const visible = $derived(
+    data === null ? [] : selectVisibleMessages(data.messages, cancelledIds),
+  );
+
+  function handleCancel(messageId: string): void {
+    // Optimistically hide the row + fire the cancel (fire-and-forget; the
+    // surface update reconciles). Idempotent server-side, so a double-click or
+    // a cancel of an already-drained message is a silent no-op — no rollback.
+    if (cancelledIds.has(messageId)) return;
+    const next = new Set(cancelledIds);
+    next.add(messageId);
+    cancelledIds = next;
+    onCancel?.(messageId);
+  }
 </script>
 
 {#if data !== null && data.messages.length > 0}
   <ul class="flex flex-col gap-1 text-sm">
-    {#each data.messages as msg (msg.id)}
-      <li class="rounded-box bg-base-200 px-3 py-2">
-        <p class="whitespace-pre-wrap">{msg.text}</p>
-        <time class="text-xs opacity-50" datetime={new Date(msg.queuedAt).toISOString()}>
-          {new Date(msg.queuedAt).toLocaleTimeString()}
-        </time>
+    {#each visible as msg (msg.id)}
+      <li class="flex items-start gap-2 rounded-box bg-base-200 px-3 py-2">
+        <div class="min-w-0 flex-1">
+          <p class="whitespace-pre-wrap break-words">{msg.text}</p>
+          <time class="text-xs opacity-50" datetime={new Date(msg.queuedAt).toISOString()}>
+            {new Date(msg.queuedAt).toLocaleTimeString()}
+          </time>
+        </div>
+        {#if onCancel !== undefined}
+          <button
+            type="button"
+            class="btn btn-ghost btn-xs btn-square shrink-0 opacity-60 hover:opacity-100"
+            title="Cancel this queued message"
+            aria-label="Cancel this queued message"
+            onclick={() => handleCancel(msg.id)}
+          >
+            <svg
+              xmlns="http://www.w3.org/2000/svg"
+              viewBox="0 0 24 24"
+              fill="none"
+              stroke="currentColor"
+              stroke-width="2.5"
+              stroke-linecap="round"
+              stroke-linejoin="round"
+              class="h-3.5 w-3.5"
+            >
+              <line x1="18" y1="6" x2="6" y2="18"></line>
+              <line x1="6" y1="6" x2="18" y2="18"></line>
+            </svg>
+          </button>
+        {/if}
       </li>
     {/each}
   </ul>
diff --git a/src/features/surface-host/ui/MessageQueueList.test.ts b/src/features/surface-host/ui/MessageQueueList.test.ts
new file mode 100644
index 0000000..53044b3
--- /dev/null
+++ b/src/features/surface-host/ui/MessageQueueList.test.ts
@@ -0,0 +1,135 @@
+import type { QueuedMessage } from "@dispatch/wire";
+import { render, screen } from "@testing-library/svelte";
+import userEvent from "@testing-library/user-event";
+import { describe, expect, it, vi } from "vitest";
+import MessageQueueList from "./MessageQueueList.svelte";
+
+function msg(id: string, text: string, queuedAt = 1_700_000_000_000): QueuedMessage {
+  return { id, text, queuedAt };
+}
+
+/** Build the message-queue surface field payload. */
+function payload(messages: readonly QueuedMessage[]): { messages: readonly QueuedMessage[] } {
+  return { messages };
+}
+
+describe("MessageQueueList", () => {
+  it("renders each queued message's text", () => {
+    render(MessageQueueList, {
+      props: {
+        payload: payload([msg("m1", "steer left"), msg("m2", "go right")]),
+        onCancel: undefined,
+      },
+    });
+    expect(screen.getByText("steer left")).toBeInTheDocument();
+    expect(screen.getByText("go right")).toBeInTheDocument();
+  });
+
+  it("renders nothing when the queue is empty", () => {
+    const { container } = render(MessageQueueList, {
+      props: { payload: payload([]), onCancel: undefined },
+    });
+    expect(container.querySelector("ul")).toBeNull();
+  });
+
+  it("renders nothing for a malformed payload (graceful skip)", () => {
+    const { container } = render(MessageQueueList, {
+      props: { payload: { nope: true }, onCancel: undefined },
+    });
+    expect(container.querySelector("ul")).toBeNull();
+  });
+
+  it("omits the cancel button when no onCancel is wired (read-only)", () => {
+    render(MessageQueueList, {
+      props: { payload: payload([msg("m1", "steer")]), onCancel: undefined },
+    });
+    expect(screen.queryByRole("button", { name: /cancel/i })).toBeNull();
+  });
+
+  it("renders a cancel button per row when onCancel is wired", () => {
+    render(MessageQueueList, {
+      props: { payload: payload([msg("m1", "a"), msg("m2", "b")]), onCancel: vi.fn() },
+    });
+    expect(screen.getAllByRole("button", { name: /cancel/i })).toHaveLength(2);
+  });
+
+  it("clicking cancel fires onCancel with the row's message id and optimistically hides the row", async () => {
+    const user = userEvent.setup();
+    const onCancel = vi.fn();
+    render(MessageQueueList, {
+      props: { payload: payload([msg("m1", "keep me"), msg("m2", "cancel me")]), onCancel },
+    });
+
+    // Both rows visible before click.
+    expect(screen.getByText("keep me")).toBeInTheDocument();
+    expect(screen.getByText("cancel me")).toBeInTheDocument();
+
+    const buttons = screen.getAllByRole("button", { name: /cancel/i });
+    // Cancel the SECOND row (m2). Buttons mirror row order.
+    const cancelM2 = buttons[1];
+    if (cancelM2 === undefined) throw new Error("expected two cancel buttons");
+    await user.click(cancelM2);
+
+    expect(onCancel).toHaveBeenCalledTimes(1);
+    expect(onCancel).toHaveBeenCalledWith("m2");
+    // m2 is optimistically hidden immediately; m1 remains.
+    expect(screen.getByText("keep me")).toBeInTheDocument();
+    expect(screen.queryByText("cancel me")).toBeNull();
+  });
+
+  it("does not fire onCancel twice for a double-click on the same row (idempotent client-side)", async () => {
+    const user = userEvent.setup();
+    const onCancel = vi.fn();
+    render(MessageQueueList, {
+      props: { payload: payload([msg("m1", "x")]), onCancel },
+    });
+
+    const button = screen.getByRole("button", { name: /cancel/i });
+    await user.click(button);
+    // The row is gone after the first click; the button left the DOM, so a
+    // second click on the stale element is a no-op — onCancel fires once.
+    await user.click(button).catch(() => {});
+    expect(onCancel).toHaveBeenCalledTimes(1);
+  });
+
+  it("reconciles from the surface: a cancelled id gone from the snapshot clears the optimistic hide", async () => {
+    const user = userEvent.setup();
+    const onCancel = vi.fn();
+    const { rerender } = render(MessageQueueList, {
+      props: { payload: payload([msg("m1", "a"), msg("m2", "b")]), onCancel },
+    });
+
+    // Cancel m1 — it hides optimistically.
+    const cancelButtons = screen.getAllByRole("button", { name: /cancel/i });
+    const cancelM1 = cancelButtons[0];
+    if (cancelM1 === undefined) throw new Error("expected a cancel button");
+    await user.click(cancelM1);
+    expect(screen.queryByText("a")).toBeNull();
+    expect(screen.getByText("b")).toBeInTheDocument();
+
+    // The surface pushes the post-cancel snapshot: m1 is gone (server confirmed).
+    // A NEW message m3 arrives in the same snapshot. The list renders m2 + m3.
+    rerender({ payload: payload([msg("m2", "b"), msg("m3", "c")]), onCancel });
+    expect(screen.queryByText("a")).toBeNull();
+    expect(screen.getByText("b")).toBeInTheDocument();
+    expect(screen.getByText("c")).toBeInTheDocument();
+  });
+
+  it("re-shows a row if the surface snapshot still contains a cancelled id (cancel not yet confirmed)", async () => {
+    // Edge case: the cancel is in flight and the surface hasn't updated yet, but
+    // a re-render with the SAME snapshot must keep the row hidden (optimistic).
+    const user = userEvent.setup();
+    const onCancel = vi.fn();
+    const samePayload = payload([msg("m1", "a")]);
+    const { rerender } = render(MessageQueueList, {
+      props: { payload: samePayload, onCancel },
+    });
+
+    await user.click(screen.getByRole("button", { name: /cancel/i }));
+    expect(screen.queryByText("a")).toBeNull();
+
+    // Re-render with the same (stale) snapshot — the row stays hidden.
+    rerender({ payload: payload([msg("m1", "a")]), onCancel });
+    expect(screen.queryByText("a")).toBeNull();
+  });
+});
diff --git a/src/features/surface-host/ui/SurfaceView.svelte b/src/features/surface-host/ui/SurfaceView.svelte
index aed8d03..8ce8ade 100644
--- a/src/features/surface-host/ui/SurfaceView.svelte
+++ b/src/features/surface-host/ui/SurfaceView.svelte
@@ -11,7 +11,22 @@
   import TodoList from "./TodoList.svelte";
   import Toggle from "./Toggle.svelte";
 
-  let { spec, onInvoke }: { spec: SurfaceSpec; onInvoke: (msg: InvokeMessage) => void } = $props();
+  let {
+    spec,
+    onInvoke,
+    onCancelQueuedMessage,
+  }: {
+    spec: SurfaceSpec;
+    onInvoke: (msg: InvokeMessage) => void;
+    /**
+     * Cancel a queued message by id — threaded ONLY to the `message-queue`
+     * renderer. Optional + scoped: generic surfaces (which pass nothing) keep
+     * rendering a read-only queue list. Kept as a typed callback (never a
+     * stringly-typed bus); the renderer dispatch is on `rendererId` (a renderer
+     * KIND), never the surface id.
+     */
+    onCancelQueuedMessage?: (messageId: string) => void;
+  } = $props();
 
   const plan = $derived(planSurface(spec));
   // Consecutive stats render together as one aligned table; everything else is
@@ -40,7 +55,7 @@
       {#if group.field.rendererId === "table"}
         <SurfaceTable payload={group.field.payload} />
       {:else if group.field.rendererId === "message-queue"}
-        <MessageQueueList payload={group.field.payload} />
+        <MessageQueueList payload={group.field.payload} onCancel={onCancelQueuedMessage} />
       {:else if group.field.rendererId === "todo"}
         <TodoList payload={group.field.payload} />
       {/if}