@hienlh/ppm 0.23.14 → 0.23.16

package/src/web/design-share-page/share-threads-panel.tsx

@@ -0,0 +1,103 @@
+import { useState } from "react";
+import { ChevronDown, ChevronRight, MessageSquare, X } from "@/lib/icons";
+import type { PinStatus } from "../components/design/comments/use-comment-pins";
+import { pinStatusText, type GuestThread } from "./share-thread-model";
+import { Byline } from "./share-entry";
+import { buttonQuiet, cx } from "./share-ui";
+
+/**
+ * The list of a link's threads: open ones numbered like their pins, resolved ones folded
+ * under "Resolved (n)". Who the reviewer is, and the way to change it, sits at the top.
+ */
+
+function ThreadRow({ thread, number, status, active, onOpen }: {
+  thread: GuestThread;
+  number: number | null;
+  status: PinStatus;
+  active: boolean;
+  onOpen: () => void;
+}) {
+  const note = pinStatusText(status, number, !!thread.resolvedAt);
+  return (
+    <li>
+      <button type="button" onClick={onOpen} aria-current={active ? "true" : undefined}
+        className={cx("flex min-h-11 w-full items-start gap-3 px-4 py-3 text-left active:bg-panel-2 can-hover:hover:bg-panel-2",
+          active && "bg-panel-2")}>
+        <span className={cx("mt-0.5 flex size-6 shrink-0 items-center justify-center rounded-full text-xs font-semibold",
+          number === null ? "bg-panel-2 text-text-3" : "bg-primary text-primary-fg")} aria-hidden="true">
+          {number ?? "✓"}
+        </span>
+        <span className="flex min-w-0 flex-1 flex-col gap-0.5">
+          <span className="flex min-w-0 items-center gap-2"><Byline author={thread.author} /></span>
+          <span className="line-clamp-2 whitespace-pre-wrap break-words text-sm text-text-2">{thread.body}</span>
+          <span className="text-xs text-text-3">
+            {thread.replies.length === 1 ? "1 reply" : `${thread.replies.length} replies`}
+            {note && note !== `Pin ${number}` ? ` · ${note}` : ""}
+          </span>
+        </span>
+      </button>
+    </li>
+  );
+}
+
+export function ShareThreadsPanel({ open, resolved, numbers, statusOf, activeId, name, expiryText, onOpen, onChangeName, onClose }: {
+  open: GuestThread[];
+  resolved: GuestThread[];
+  numbers: ReadonlyMap<string, number>;
+  statusOf: (id: string) => PinStatus;
+  activeId: string | null;
+  name: string | null;
+  expiryText: string | null;
+  onOpen: (id: string) => void;
+  onChangeName: () => void;
+  onClose?: () => void;
+}) {
+  const [showResolved, setShowResolved] = useState(false);
+  return (
+    <div className="flex min-h-0 flex-1 flex-col">
+      <div className="flex shrink-0 items-center gap-2 border-b border-border py-1 pl-4 pr-2">
+        <h2 className="flex-1 text-sm font-semibold">Comments ({open.length})</h2>
+        {onClose && (
+          <button type="button" className={buttonQuiet} onClick={onClose} aria-label="Close comments">
+            <X className="size-5" />
+          </button>
+        )}
+      </div>
+      <div className="flex shrink-0 items-center gap-2 px-4 py-2 text-xs text-text-2">
+        <span className="min-w-0 flex-1 truncate">{name ? `Commenting as ${name}` : "You will be asked for a name when you first write"}</span>
+        {name && <button type="button" className={cx(buttonQuiet, "text-xs")} onClick={onChangeName}>Change name</button>}
+      </div>
+      {expiryText && <p className="shrink-0 px-4 pb-2 text-xs text-text-3">{expiryText}</p>}
+      <div className="min-h-0 flex-1 overflow-y-auto overscroll-contain border-t border-border">
+        {open.length === 0 && resolved.length === 0 && (
+          <div className="flex flex-col items-center gap-2 px-6 py-10 text-center text-sm text-text-2">
+            <MessageSquare className="size-6 text-text-3" />
+            No comments yet. Choose Comment, then the part of the design you want to talk about.
+          </div>
+        )}
+        <ul aria-label="Open comments">
+          {open.map((t) => (
+            <ThreadRow key={t.id} thread={t} number={numbers.get(t.id) ?? null} status={statusOf(t.id)}
+              active={activeId === t.id} onOpen={() => onOpen(t.id)} />
+          ))}
+        </ul>
+        {resolved.length > 0 && (
+          <div className="border-t border-border">
+            <button type="button" className={cx(buttonQuiet, "w-full justify-start rounded-none px-4")}
+              aria-expanded={showResolved} onClick={() => setShowResolved((v) => !v)}>
+              {showResolved ? <ChevronDown className="size-4" /> : <ChevronRight className="size-4" />} Resolved ({resolved.length})
+            </button>
+            {showResolved && (
+              <ul aria-label="Resolved comments">
+                {resolved.map((t) => (
+                  <ThreadRow key={t.id} thread={t} number={null} status={statusOf(t.id)}
+                    active={activeId === t.id} onOpen={() => onOpen(t.id)} />
+                ))}
+              </ul>
+            )}
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}

package/src/web/design-share-page/share-toolbar.tsx

@@ -0,0 +1,105 @@
+import type { ElementType } from "react";
+import { Layers, MessageSquare, MessageSquarePlus, Monitor, PanelRight, Presentation, Smartphone, Tablet, X } from "@/lib/icons";
+import type { DesignVariant } from "../../shared/design-variants";
+import { DEVICE_FRAMES, type DeviceFrameId } from "../components/design/canvas/device-frame-presets";
+import { buttonQuiet, buttonToggleOn, cx } from "./share-ui";
+
+/**
+ * The reviewer's controls. From `md` a toolbar above the design: variants, device frames,
+ * Comment and the comments panel. On a phone the same actions sit in a bar at the bottom,
+ * in the thumb zone; there is no device frame there, the phone is the frame.
+ */
+
+const FRAME_ICONS: Record<DeviceFrameId, ElementType> = { desktop: Monitor, tablet: Tablet, phone: Smartphone, slide: Presentation };
+
+export const variantLabel = (v: DesignVariant, i: number): string => v.label || `Variant ${i + 1}`;
+
+/** A native select: the platform's own picker on a phone, no custom dropdown to get wrong. */
+export function VariantPicker({ variants, file, onChange, compact }: {
+  variants: DesignVariant[];
+  file: string;
+  onChange: (file: string) => void;
+  compact?: boolean;
+}) {
+  if (variants.length < 2) return null;
+  return (
+    <label className={cx("relative flex min-h-11 items-center gap-2 rounded-lg px-3 text-sm font-medium text-text-2 active:bg-panel-2 can-hover:hover:bg-panel-2",
+      compact && "flex-col justify-center gap-0.5 px-2 text-xs")}>
+      <Layers className={compact ? "size-5" : "size-4"} aria-hidden="true" />
+      <span className={compact ? undefined : "sr-only"}>Variants</span>
+      <select value={file} onChange={(e) => onChange(e.target.value)} aria-label="Variant"
+        className={cx("bg-transparent text-sm text-text", compact && "absolute inset-0 opacity-0")}>
+        {variants.map((v, i) => <option key={v.file} value={v.file}>{variantLabel(v, i)}</option>)}
+      </select>
+    </label>
+  );
+}
+
+export function ShareToolbar({ title, subtitle, variants, file, onVariant, frame, onFrame, picking, onPicking, panelOpen, onPanel, count }: {
+  title: string;
+  subtitle: string;
+  variants: DesignVariant[];
+  file: string;
+  onVariant: (file: string) => void;
+  frame: DeviceFrameId;
+  onFrame: (frame: DeviceFrameId) => void;
+  picking: boolean;
+  onPicking: (on: boolean) => void;
+  panelOpen: boolean;
+  onPanel: (open: boolean) => void;
+  count: number;
+}) {
+  return (
+    <header className="flex shrink-0 items-center gap-2 border-b border-border bg-panel px-3 py-1">
+      <div className="min-w-0 flex-1">
+        <h1 className="truncate text-sm font-semibold">{title}</h1>
+        <p className="truncate text-xs text-text-3">{subtitle}</p>
+      </div>
+      <VariantPicker variants={variants} file={file} onChange={onVariant} />
+      <div className="flex items-center gap-0.5 rounded-lg border border-border p-0.5" role="group" aria-label="Device frame">
+        {DEVICE_FRAMES.map((f) => {
+          const Icon = FRAME_ICONS[f.id];
+          return (
+            <button key={f.id} type="button" title={f.label} aria-label={f.label} aria-pressed={frame === f.id}
+              className={cx(buttonQuiet, "px-2", frame === f.id && buttonToggleOn)} onClick={() => onFrame(f.id)}>
+              <Icon className="size-4" />
+            </button>
+          );
+        })}
+      </div>
+      <button type="button" aria-pressed={picking} onClick={() => onPicking(!picking)}
+        className={cx(buttonQuiet, picking && buttonToggleOn)}>
+        <MessageSquarePlus className="size-4" /> {picking ? "Choosing…" : "Comment"}
+      </button>
+      <button type="button" aria-pressed={panelOpen} onClick={() => onPanel(!panelOpen)}
+        className={cx(buttonQuiet, panelOpen && buttonToggleOn)} aria-label={`Comments (${count})`}>
+        <PanelRight className="size-4" /> {count}
+      </button>
+    </header>
+  );
+}
+
+export function ShareBottomBar({ variants, file, onVariant, picking, onPicking, onComments, count }: {
+  variants: DesignVariant[];
+  file: string;
+  onVariant: (file: string) => void;
+  picking: boolean;
+  onPicking: (on: boolean) => void;
+  onComments: () => void;
+  count: number;
+}) {
+  const cell = "flex min-h-12 min-w-16 flex-1 flex-col items-center justify-center gap-0.5 rounded-lg text-xs font-medium text-text-2 active:bg-panel-2";
+  return (
+    <nav className="flex shrink-0 items-stretch gap-2 border-t border-border bg-panel px-2 pt-1 pb-[max(0.25rem,env(safe-area-inset-bottom))]" aria-label="Review">
+      <button type="button" aria-pressed={picking} onClick={() => onPicking(!picking)} className={cx(cell, picking && "text-primary")}>
+        {picking ? <X className="size-5" /> : <MessageSquarePlus className="size-5" />} {picking ? "Done" : "Comment"}
+      </button>
+      <button type="button" onClick={onComments} className={cell}>
+        <MessageSquare className="size-5" /> Comments ({count})
+      </button>
+      {variants.length > 1 && (
+        <div className="flex flex-1"><VariantPicker variants={variants} file={file} onChange={onVariant} compact /></div>
+      )}
+    </nav>
+  );
+}

package/src/web/design-share-page/share-ui.ts

@@ -0,0 +1,30 @@
+/**
+ * Small shared pieces of the reviewer page's markup: class joining and the button looks.
+ * Every target is at least 44px on every side, on a phone and on a desktop alike.
+ */
+
+export function cx(...parts: Array<string | false | null | undefined>): string {
+  return parts.filter(Boolean).join(" ");
+}
+
+const BUTTON = "inline-flex min-h-11 min-w-11 items-center justify-center gap-2 rounded-lg px-3 text-sm font-medium select-none disabled:opacity-50";
+
+export const buttonPrimary = `${BUTTON} bg-primary text-primary-fg active:opacity-80 can-hover:hover:opacity-90`;
+export const buttonQuiet = `${BUTTON} text-text-2 active:bg-panel-2 can-hover:hover:bg-panel-2`;
+export const buttonOutline = `${BUTTON} border border-border bg-panel text-text active:bg-panel-2 can-hover:hover:bg-panel-2`;
+export const buttonToggleOn = "bg-panel-2 text-text ring-1 ring-border";
+
+export const fieldClass = "w-full rounded-lg border border-border bg-panel px-3 py-2 text-base text-text placeholder:text-text-3 md:text-sm";
+
+/** A date as the reviewer's own locale writes it. */
+export function formatDate(value: number | string): string {
+  const d = new Date(value);
+  if (Number.isNaN(d.getTime())) return "";
+  return d.toLocaleDateString(undefined, { year: "numeric", month: "short", day: "numeric" });
+}
+
+export function formatDateTime(value: string): string {
+  const d = new Date(value);
+  if (Number.isNaN(d.getTime())) return "";
+  return d.toLocaleString(undefined, { month: "short", day: "numeric", hour: "2-digit", minute: "2-digit" });
+}

package/src/web/design-share-page/share.css

@@ -0,0 +1,63 @@
+/*
+ * The reviewer page's styles. Tailwind scans this folder only (`source(none)` + `@source`),
+ * so nothing of the app's class list lands here. The page has no theme engine: its colours
+ * follow the reviewer's own light or dark setting.
+ */
+@import "tailwindcss" source(none);
+@source ".";
+
+@custom-variant can-hover (@media (hover: hover) and (pointer: fine));
+
+@theme {
+  --color-bg: #f6f7f9;
+  --color-panel: #ffffff;
+  --color-panel-2: #eef0f3;
+  --color-border: #d9dde3;
+  --color-text: #15181d;
+  --color-text-2: #4a525e;
+  --color-text-3: #6b7380;
+  --color-primary: #2563eb;
+  --color-primary-fg: #ffffff;
+  --color-owner: #7c3aed;
+  --color-owner-fg: #ffffff;
+  --color-error: #c62828;
+  --color-warning: #9a6200;
+  --color-stage: #e6e9ee;
+  --font-sans: system-ui, -apple-system, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
+}
+
+@media (prefers-color-scheme: dark) {
+  :root {
+    --color-bg: #111418;
+    --color-panel: #181c22;
+    --color-panel-2: #222831;
+    --color-border: #313844;
+    --color-text: #e8ebef;
+    --color-text-2: #b4bcc7;
+    --color-text-3: #8d96a3;
+    --color-primary: #5b8def;
+    --color-primary-fg: #0b1220;
+    --color-owner: #a78bfa;
+    --color-owner-fg: #140b2b;
+    --color-error: #ff7b72;
+    --color-warning: #e3b341;
+    --color-stage: #0b0d10;
+  }
+}
+
+@layer base {
+  html, body, #root {
+    height: 100%;
+  }
+  body {
+    margin: 0;
+    background: var(--color-bg);
+    color: var(--color-text);
+    font-family: var(--font-sans);
+    -webkit-tap-highlight-color: transparent;
+  }
+  :focus-visible {
+    outline: 2px solid var(--color-primary);
+    outline-offset: 2px;
+  }
+}

package/src/web/design-share-page/use-share-canvas.ts

@@ -0,0 +1,51 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+import { newBridgeNonce, useDesignBridge } from "../components/design/canvas/use-design-bridge";
+import { shareBase } from "./share-api";
+
+/**
+ * The design frame of a share link: which page it shows and the bridge to it.
+ *
+ * Every load gets a fresh nonce on its URL (`?n=`), and reloading means setting a new `src`:
+ * the frame's origin is opaque, so `location.reload()` is not the parent's to call. A load
+ * that never says `ready` is retried once with a new nonce; failing again, the page says the
+ * design stopped responding rather than reloading forever.
+ */
+
+/** `/s/<code>/f/<slug>/<file>`, each segment encoded, `file` keeping its own slashes. */
+export function frameUrl(code: string, slug: string, file: string): string {
+  return `${shareBase(code)}/f/${encodeURIComponent(slug)}/${file.split("/").map(encodeURIComponent).join("/")}`;
+}
+
+export function useShareCanvas(code: string, slug: string, file: string) {
+  const iframeRef = useRef<HTMLIFrameElement | null>(null);
+  const [nonce, setNonce] = useState(() => newBridgeNonce());
+  const [dead, setDead] = useState(false);
+  const recovering = useRef(false);
+
+  const recover = useCallback(() => {
+    if (recovering.current) { setDead(true); return; }
+    recovering.current = true;
+    setNonce(newBridgeNonce());
+  }, []);
+  const bridge = useDesignBridge(iframeRef, nonce, recover);
+
+  // Another page of the design is another document: a new nonce goes with it.
+  const shown = useRef(file);
+  useEffect(() => {
+    if (shown.current === file) return;
+    shown.current = file;
+    setNonce(newBridgeNonce());
+  }, [file]);
+
+  useEffect(() => bridge.on("ready", () => { recovering.current = false; setDead(false); }), [bridge.on]);
+
+  const reload = useCallback(() => {
+    recovering.current = false;
+    setDead(false);
+    setNonce(newBridgeNonce());
+  }, []);
+
+  return { iframeRef, src: `${frameUrl(code, slug, file)}?n=${encodeURIComponent(nonce)}`, bridge, dead, reload };
+}
+
+export type ShareCanvasState = ReturnType<typeof useShareCanvas>;

package/src/web/design-share-page/use-share-info.ts

@@ -0,0 +1,34 @@
+import { useCallback, useEffect, useState } from "react";
+import type { DesignShareGuestInfo } from "../../shared/design-share-guest-types";
+import { fetchShareInfo, ShareApiError, failureMessage } from "./share-api";
+
+/** What `/s/<code>/info` said: still loading, the shared version, a dead link, or a failure to retry. */
+export type ShareInfoState =
+  | { status: "loading" }
+  | { status: "ready"; info: DesignShareGuestInfo }
+  | { status: "invalid" }
+  | { status: "error"; message: string };
+
+export function useShareInfo(code: string | null): { state: ShareInfoState; retry: () => void } {
+  const [state, setState] = useState<ShareInfoState>(code ? { status: "loading" } : { status: "invalid" });
+  const [attempt, setAttempt] = useState(0);
+
+  useEffect(() => {
+    if (!code) return;
+    let cancelled = false;
+    setState({ status: "loading" });
+    fetchShareInfo(code).then(
+      (info) => { if (!cancelled) setState({ status: "ready", info }); },
+      (e: unknown) => {
+        if (cancelled) return;
+        const failure = e instanceof ShareApiError ? e.failure : null;
+        if (failure?.kind === "invalid") setState({ status: "invalid" });
+        else setState({ status: "error", message: failure ? failureMessage(failure) : "Could not open the design." });
+      },
+    );
+    return () => { cancelled = true; };
+  }, [code, attempt]);
+
+  const retry = useCallback(() => setAttempt((n) => n + 1), []);
+  return { state, retry };
+}

package/src/web/design-share-page/use-share-session.ts

@@ -0,0 +1,75 @@
+import { useCallback, useMemo, useRef, useState } from "react";
+import type { DesignShareGuestInfo } from "../../shared/design-share-guest-types";
+import { failureMessage, isVersionChanged, ShareApiError, shareWrites, type ShareFailure } from "./share-api";
+import { browserStore, loadGuestKey, loadGuestName, saveGuestName } from "./share-identity";
+import { useShareThreads } from "./use-share-threads";
+import type { GuestThread } from "./share-thread-model";
+
+/**
+ * One reviewer on one link: their key and name, the threads, and every write, each of
+ * which reports its own failure in the page's notice line and answers whether it went
+ * through. A write refused because the link stopped opening turns the whole page into the
+ * "no longer valid" state, the same as a poll that finds it so.
+ */
+
+export interface ShareNotice { id: number; message: string }
+
+export function useShareSession(info: DesignShareGuestInfo, code: string) {
+  const store = useMemo(() => browserStore(), []);
+  const key = useMemo(() => loadGuestKey(store, info.linkId), [store, info.linkId]);
+  const [name, setNameState] = useState(() => loadGuestName(store, info.linkId));
+  const [notice, setNotice] = useState<ShareNotice | null>(null);
+  const [writeInvalid, setWriteInvalid] = useState(false);
+  const noticeId = useRef(0);
+
+  const notify = useCallback((message: string) => setNotice({ id: ++noticeId.current, message }), []);
+  const dismissNotice = useCallback(() => setNotice(null), []);
+  const onPollFailure = useCallback((f: ShareFailure) => notify(failureMessage(f)), [notify]);
+  const threads = useShareThreads(code, key, info.versionId, onPollFailure);
+  const [writeVersionChanged, setWriteVersionChanged] = useState(false);
+  const { applyThread, applyDeleted, refresh } = threads;
+  const writes = useMemo(() => shareWrites(code, key), [code, key]);
+
+  /** Validates and remembers a name; an error is for the field that asked. */
+  const setName = useCallback((raw: string) => {
+    const saved = saveGuestName(store, info.linkId, raw);
+    if (saved.ok) setNameState(saved.name);
+    return saved;
+  }, [store, info.linkId]);
+
+  const run = useCallback(async <T,>(op: () => Promise<T>, done: (result: T) => void): Promise<boolean> => {
+    try {
+      done(await op());
+      return true;
+    } catch (e) {
+      const failure: ShareFailure = e instanceof ShareApiError ? e.failure : { kind: "network" };
+      if (failure.kind === "invalid") setWriteInvalid(true);
+      // The page's own bar says this, with the button that fixes it.
+      else if (isVersionChanged(failure)) setWriteVersionChanged(true);
+      else notify(failureMessage(failure));
+      // The thread may be gone or changed under the reviewer; show what is there now.
+      if (failure.kind === "error" && (failure.status === 404 || failure.status === 409)) refresh();
+      return false;
+    }
+  }, [notify, refresh]);
+
+  const actions = useMemo(() => ({
+    addThread: (anchor: unknown, body: string, as: string, onDone: (t: GuestThread) => void) =>
+      run(() => writes.addThread(anchor, body, as, info.versionId), (t) => { applyThread(t); onDone(t); }),
+    reply: (id: string, body: string, as: string) => run(() => writes.reply(id, body, as), applyThread),
+    editThread: (id: string, body: string) => run(() => writes.editThread(id, body), applyThread),
+    deleteThread: (id: string) => run(() => writes.deleteThread(id), () => applyDeleted(id)),
+    editReply: (id: string, replyId: string, body: string) => run(() => writes.editReply(id, replyId, body), applyThread),
+    deleteReply: (id: string, replyId: string) => run(() => writes.deleteReply(id, replyId), applyThread),
+  }), [run, writes, applyThread, applyDeleted, info.versionId]);
+
+  return {
+    name, setName, notice, dismissNotice,
+    threads: threads.threads, loaded: threads.loaded, invalid: threads.invalid || writeInvalid,
+    versionChanged: threads.versionChanged || writeVersionChanged,
+    actions,
+  };
+}
+
+export type ShareSession = ReturnType<typeof useShareSession>;
+export type ShareActions = ShareSession["actions"];

package/src/web/design-share-page/use-share-threads.ts

@@ -0,0 +1,139 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+import { fetchThreads, ShareApiError, type ShareFailure } from "./share-api";
+import { removeThread, upsertThread, type GuestThread } from "./share-thread-model";
+
+/**
+ * The link's threads, kept current by polling.
+ *
+ * Polling rather than a stream: a Cloudflare tunnel does not pass a closed connection on to
+ * the origin, so a stream per reviewer would never be let go. A poll goes out every
+ * {@link POLL_MS} while the page is visible, at once when it becomes visible again, and right
+ * after the reviewer's own write; `If-None-Match` makes an unchanged answer a bodiless 304.
+ * A 404 means the link stopped opening, and polling stops for good. An answer naming another
+ * version than the page's means the owner re-pinned the link: the page says so and keeps
+ * polling, since the threads are the link's and not the version's.
+ */
+
+export const POLL_MS = 10_000;
+export const MAX_BACKOFF_MS = 60_000;
+
+/**
+ * How long until the next poll, or null for none while the page is hidden. A server that
+ * asked for a wait gets at least that; failures in a row back off, doubling up to a minute.
+ */
+export function nextPollDelay(s: { visible: boolean; failures: number; retryAfterMs?: number }): number | null {
+  if (!s.visible) return null;
+  const backoff = Math.min(POLL_MS * 2 ** Math.max(0, s.failures), MAX_BACKOFF_MS);
+  return Math.max(backoff, s.retryAfterMs ?? 0);
+}
+
+export interface ShareThreadsState {
+  threads: GuestThread[];
+  loaded: boolean;
+  invalid: boolean;
+  /** The owner re-pinned the link since this page loaded, so it shows an old version. */
+  versionChanged: boolean;
+  /** Fold a write's answer in at once, then poll so everyone else's changes follow. */
+  applyThread: (thread: GuestThread) => void;
+  applyDeleted: (id: string) => void;
+  refresh: () => void;
+}
+
+/** Whether a poll's answer names another version than the one the page loaded. */
+export function repinnedSince(shown: string, reported: string | null): boolean {
+  return reported !== null && reported !== shown;
+}
+
+export function useShareThreads(
+  code: string, key: string, versionId: string, onFailure: (f: ShareFailure) => void,
+): ShareThreadsState {
+  const [threads, setThreads] = useState<GuestThread[]>([]);
+  const [loaded, setLoaded] = useState(false);
+  const [invalid, setInvalid] = useState(false);
+  const [versionChanged, setVersionChanged] = useState(false);
+  const etag = useRef<string | null>(null);
+  const timer = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const inFlight = useRef(false);
+  const again = useRef(false);
+  const failures = useRef(0);
+  const stopped = useRef(false);
+  const onFailureRef = useRef(onFailure);
+  onFailureRef.current = onFailure;
+  // The timer calls the current poll through this, so the two callbacks need not name each other.
+  const pollRef = useRef<() => Promise<void>>(async () => {});
+
+  const schedule = useCallback((retryAfterMs?: number) => {
+    if (timer.current) clearTimeout(timer.current);
+    timer.current = null;
+    if (stopped.current) return;
+    const delay = nextPollDelay({ visible: document.visibilityState === "visible", failures: failures.current, retryAfterMs });
+    if (delay !== null) timer.current = setTimeout(() => { void pollRef.current(); }, delay);
+  }, []);
+
+  const poll = useCallback(async () => {
+    if (stopped.current) return;
+    if (inFlight.current) { again.current = true; return; }
+    inFlight.current = true;
+    let retryAfterMs: number | undefined;
+    try {
+      const answer = await fetchThreads(code, key, etag.current);
+      failures.current = 0;
+      if (!answer.unchanged) {
+        etag.current = answer.etag;
+        setThreads(answer.threads);
+        if (repinnedSince(versionId, answer.versionId)) setVersionChanged(true);
+      }
+      setLoaded(true);
+    } catch (e) {
+      const failure: ShareFailure = e instanceof ShareApiError ? e.failure : { kind: "network" };
+      if (failure.kind === "invalid") {
+        stopped.current = true;
+        setInvalid(true);
+      } else {
+        failures.current++;
+        // A poll failing quietly is normal on a phone; only a wait the server asked for is news.
+        if (failure.kind === "rate-limited") {
+          retryAfterMs = failure.retryAfterMs;
+          onFailureRef.current(failure);
+        }
+      }
+    } finally {
+      inFlight.current = false;
+    }
+    if (again.current) {
+      again.current = false;
+      void poll();
+      return;
+    }
+    schedule(retryAfterMs);
+  }, [code, key, versionId, schedule]);
+  pollRef.current = poll;
+
+  useEffect(() => {
+    stopped.current = false;
+    void poll();
+    const onVisibility = () => {
+      if (document.visibilityState === "visible") void poll();
+      else schedule();
+    };
+    document.addEventListener("visibilitychange", onVisibility);
+    return () => {
+      stopped.current = true;
+      document.removeEventListener("visibilitychange", onVisibility);
+      if (timer.current) clearTimeout(timer.current);
+    };
+  }, [poll, schedule]);
+
+  const applyThread = useCallback((thread: GuestThread) => {
+    setThreads((list) => upsertThread(list, thread));
+    void poll();
+  }, [poll]);
+  const applyDeleted = useCallback((id: string) => {
+    setThreads((list) => removeThread(list, id));
+    void poll();
+  }, [poll]);
+
+  const refresh = useCallback(() => { void poll(); }, [poll]);
+
+  return { threads, loaded, invalid, versionChanged, applyThread, applyDeleted, refresh };
+}

package/src/web/hooks/use-chat.ts

@@ -15,6 +15,7 @@ import type { PromptCacheState } from "../../shared/prompt-cache-idle";
 import type { TurnStop } from "../../shared/turn-stop";
 import { decodeReply, encodeReply, type ReplyReference } from "../../shared/chat-reply";
 import { prefixTokens } from "../../shared/turn-usage";
+import { dbExecuteApprovalInput } from "../../shared/db-ai-tools";
 import type { ChatWsServerMessage, SessionPhase, BackgroundShell, VersionGroup } from "../../types/api";
 import { useBackgroundOutputStore } from "../stores/background-output-store";
 import { useSessionListStore } from "@/stores/session-list-store";
@@ -664,7 +665,9 @@ export function useChat(
       }
 
       case "approval_request": {
-        upsertStreamingEvent((e) => e.type === "approval_request" && (e as any).requestId === ev.requestId);
+        const dbApproval = dbExecuteApprovalInput(ev.tool, ev.input);
+        // A database change already has its db_execute card in the turn; its approval is only the prompt.
+        if (!dbApproval) upsertStreamingEvent((e) => e.type === "approval_request" && (e as any).requestId === ev.requestId);
         // During turn_events replay, session_state already set the correct
         // pendingApproval — skip re-setting it for historical (already-answered) events
         if (isReplayingRef.current) break;
@@ -681,7 +684,7 @@ export function useChat(
           const sid = sessionIdRef.current;
           const isQuestion = ev.tool === "AskUserQuestion";
           approvalToastRef.current = toast[isQuestion ? "info" : "warning"](
-            isQuestion ? "AI has a question" : `${ev.tool} needs permission`,
+            isQuestion ? "AI has a question" : dbApproval ? `AI wants to change ${dbApproval.connectionName}` : `${ev.tool} needs permission`,
             {
               description: projectNameRef.current || `Session ${sid.slice(0, 8)}`,
               duration: Infinity,