feat(diagnostics): the debug recorder — start, the pill, steps, screenshots, stop (E16 S2)

- the start dialog is the consent: level (Részletes/Teljes), what is recorded, retention and the cap (now served as diagnostics.session_minutes) - the pill docks under the toasts: elapsed time, Step (an optional label, its own Escape layer), Screenshot (tab capture where the browser has it), Stop; compact on a phone - while recording, lib/log tags every event and every request path (req, beacon, uploadReq via one identityHeaders) names the session; applyDiagnostics raises the level for the session's run and never lowers a raised one, and lapses at whichever ends first - Stop sends what is waiting before the server closes the session; the cap says so and opens the composer - Settings → Diagnosztika and the command palette start/step/stop it - the evidence leaves the log upload's own request lines out - the step shortcut is deliberately palette-only: the keymap's D1 rule bars a new modifier chord, and a bare letter collides with the players'
2026-09-19 22:08:10 +02:00
parent 2d9595b0e5
commit 46fce4a767
26 changed files with 1347 additions and 89 deletions
@@ -10,7 +10,9 @@ import { QueryClient, QueryClientProvider } from "@tanstack/react-query";

 import type { CommandGroup } from "./ui/CommandPalette";

-vi.mock("react-i18next", () => ({
+vi.mock("react-i18next", async (importOriginal) => ({
+  // The rest of the module too: the recorder's actions reach `i18n/index`, which needs it.
+  ...(await importOriginal<typeof import("react-i18next")>()),
  useTranslation: () => ({ t: (k: string) => k, i18n: { language: "en" } }),
 }));

@@ -140,4 +142,21 @@ describe("AppCommandPalette", () => {
    then?.();
    expect(requestSurprise).toHaveBeenCalledTimes(1);
  });
+
+  it("offers the debug recorder by its state, and not to the demo account", () => {
+    const recorder = () => ids("actions").filter((id) => id.startsWith("action:recorder:"));
+    mount();
+    expect(recorder()).toEqual(["action:recorder:start"]);
+
+    cleanup();
+    const until = new Date(Date.now() + 60_000).toISOString();
+    me = user({ debug_session: { id: "0123456789abcdef", until, ended_at: null } });
+    mount();
+    expect(recorder()).toEqual(["action:recorder:step", "action:recorder:stop"]);
+
+    cleanup();
+    me = user({ is_demo: true });
+    mount();
+    expect(recorder()).toEqual([]);
+  });
 });
@@ -1,7 +1,7 @@
 import { useMemo } from "react";
 import { useTranslation } from "react-i18next";
 import { useQuery } from "@tanstack/react-query";
-import { Keyboard, ListVideo, Palette, Sparkles, Tv } from "lucide-react";
+import { Bug, Flag, Keyboard, ListVideo, Palette, Sparkles, Square, Tv } from "lucide-react";
 import CommandPalette, { type CommandGroup } from "./ui/CommandPalette";
 import { api } from "../lib/api";
 import { qk } from "../lib/queryKeys";
@@ -10,6 +10,8 @@ import { moduleDef, moduleOrder } from "../lib/modules";
 import { SCHEMES, type Scheme } from "../lib/theme";
 import { closePalette, toggleKeyboardHelp, usePaletteOpen } from "../lib/keymap";
 import { requestSurprise } from "../lib/homeIntent";
+import { openRecorderStart } from "../lib/debugRecorder";
+import { useDebugRecording } from "./useDebugRecording";
 import { useNavigationActions } from "./navigationContext";
 import { usePlaylistsActions } from "./playlistsContext";
 import { usePrefs } from "./prefsContext";
@@ -34,6 +36,7 @@ export default function AppCommandPalette() {
  const { setSelectedId } = usePlaylistsActions();
  const { theme, setTheme } = usePrefs();
  const savedViews = useSavedViews();
+  const recording = useDebugRecording();

  // Only fetch the lists while the palette is actually open — it is a rarely-opened surface and
  // these are otherwise the feed's and the playlist rail's own queries, shared through the cache.
@@ -147,6 +150,34 @@ export default function AppCommandPalette() {
          icon: <Keyboard className="w-4 h-4" />,
          run: toggleKeyboardHelp,
        },
+        // The debug recorder (E16) — not for the shared demo account, which cannot record. While
+        // it runs, Stop and a step marker take Start's place: the palette is reachable inside a
+        // player or a dialog where the pill's buttons are a long Tab away.
+        ...(me?.is_demo
+          ? []
+          : recording.session
+            ? [
+                {
+                  id: "action:recorder:step",
+                  label: t("recorder.palette.step"),
+                  icon: <Flag className="w-4 h-4" />,
+                  run: () => recording.markStep(""),
+                },
+                {
+                  id: "action:recorder:stop",
+                  label: t("recorder.palette.stop"),
+                  icon: <Square className="w-4 h-4" />,
+                  run: () => recording.stop.mutate(recording.session!.id),
+                },
+              ]
+            : [
+                {
+                  id: "action:recorder:start",
+                  label: t("recorder.palette.start"),
+                  icon: <Bug className="w-4 h-4" />,
+                  run: openRecorderStart,
+                },
+              ]),
        ...SCHEMES.map((s) => ({
          id: `action:theme:${s.id}`,
          label: t("palette.theme", { name: s.name }),
@@ -166,6 +197,7 @@ export default function AppCommandPalette() {
    savedViews,
    theme,
    setTheme,
+    recording,
    setPage,
    openChannel,
    setSelectedId,
@@ -0,0 +1,203 @@
+// @vitest-environment jsdom
+//
+// E16 S2: the debug recorder. Its pill rides the toast hosts (lib/toastDock) and stays out of their
+// live region; Start is consent-first; Stop sends what is waiting BEFORE the server closes the
+// session; a step is one tagged event; Escape in the step prompt closes only the prompt, never the
+// dialog the pill sits in. i18n is a key-passthrough with its params; the API is stubbed and `me`
+// lives in a real query cache, as in the app.
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { act, cleanup, fireEvent, render, screen, waitFor, within } from "@testing-library/react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+
+import type { DebugSession, Me } from "../lib/api";
+import { qk } from "../lib/queryKeys";
+
+vi.mock("react-i18next", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("react-i18next")>();
+  return {
+    ...actual,
+    useTranslation: () => ({
+      t: (key: string, opts?: Record<string, unknown>) =>
+        opts && Object.keys(opts).length ? `${key}:${Object.values(opts).join(",")}` : key,
+      i18n: { language: "en" },
+    }),
+  };
+});
+
+const { order, session, startDebugSession, stopDebugSession } = vi.hoisted(() => {
+  const order: string[] = [];
+  const session = (over: Partial<DebugSession> = {}): DebugSession => ({
+    id: "0123456789abcdef",
+    level: "DEBUG",
+    started_at: new Date().toISOString(),
+    until: new Date(Date.now() + 3_600_000).toISOString(),
+    ended_at: null,
+    ended_reason: null,
+    issue_url: null,
+    screenshots: 0,
+    ...over,
+  });
+  const startDebugSession = vi.fn((level: "DEBUG" | "TRACE") =>
+    Promise.resolve({ ok: true as const, session: session({ level }) }),
+  );
+  const stopDebugSession = vi.fn((id: string) => {
+    order.push("stop");
+    return Promise.resolve({
+      ok: true as const,
+      session: session({ id, ended_at: new Date().toISOString(), ended_reason: "stopped" }),
+    });
+  });
+  return { order, session, startDebugSession, stopDebugSession };
+});
+vi.mock("../lib/api", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("../lib/api")>();
+  return { ...actual, api: { ...actual.api, startDebugSession, stopDebugSession } };
+});
+vi.mock("../lib/diagnostics", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("../lib/diagnostics")>();
+  return {
+    ...actual,
+    flushNow: () => {
+      order.push("flush");
+      return Promise.resolve();
+    },
+  };
+});
+
+import DebugRecorder from "./DebugRecorder";
+import Modal from "./ui/Modal";
+import Toaster from "./ui/Toaster";
+import { closeComposer, openRecorderStart, useComposerSession } from "../lib/debugRecorder";
+import { events } from "../lib/log";
+
+beforeEach(() => {
+  order.length = 0;
+  sessionStorage.clear();
+});
+afterEach(() => {
+  cleanup();
+  closeComposer();
+  vi.clearAllMocks();
+  vi.useRealTimers();
+});
+
+let composing: string | null = null;
+function ComposerProbe() {
+  composing = useComposerSession();
+  return null;
+}
+
+function mount(me: Partial<Me>, extra: React.ReactNode = null) {
+  const qc = new QueryClient({ defaultOptions: { mutations: { retry: false } } });
+  qc.setQueryData(qk.me(), {
+    id: 1,
+    is_demo: false,
+    preferences: {},
+    diagnostics: { level: "INFO", until: null, retention_days: 7, session_minutes: 60 },
+    debug_session: null,
+    ...me,
+  });
+  render(
+    <QueryClientProvider client={qc}>
+      <Toaster />
+      <DebugRecorder />
+      <ComposerProbe />
+      {extra}
+    </QueryClientProvider>,
+  );
+  return qc;
+}
+
+const pill = () => screen.queryByRole("group", { name: "recorder.pill.label" });
+
+describe("the recorder pill", () => {
+  it("shows while a session records, under the toasts and outside their live region", () => {
+    mount({ debug_session: session() });
+    const p = pill()!;
+    expect(p).not.toBeNull();
+    expect(p.closest("[data-toast-region]")).not.toBeNull();
+    expect(p.closest("[aria-live]")).toBeNull();
+  });
+
+  it("is not there for a session that ended or ran past its cap", () => {
+    mount({ debug_session: session({ until: new Date(Date.now() - 1000).toISOString() }) });
+    expect(pill()).toBeNull();
+    cleanup();
+    mount({ debug_session: session({ ended_at: new Date().toISOString() }) });
+    expect(pill()).toBeNull();
+  });
+
+  it("Stop sends what is waiting first, then stops, then opens the composer", async () => {
+    const qc = mount({ debug_session: session() });
+    fireEvent.click(within(pill()!).getByRole("button", { name: "recorder.pill.stop" }));
+    await waitFor(() => expect(stopDebugSession).toHaveBeenCalledWith("0123456789abcdef"));
+    expect(order).toEqual(["flush", "stop"]);
+    await waitFor(() => expect(pill()).toBeNull());
+    expect(qc.getQueryData<Me>(qk.me())?.debug_session).toBeNull();
+    expect(composing).toBe("0123456789abcdef");
+  });
+
+  it("a step is one tagged event, numbered, and the focus comes back to Step", () => {
+    mount({ debug_session: session() });
+    const step = within(pill()!).getByRole("button", { name: "recorder.pill.step" });
+    fireEvent.click(step);
+    const input = screen.getByLabelText("recorder.pill.stepPrompt:1");
+    expect(document.activeElement).toBe(input);
+    fireEvent.change(input, { target: { value: "opened the player" } });
+    fireEvent.keyDown(input, { key: "Enter" });
+    const marked = events().filter((e) => e.event === "debug.step");
+    expect(marked.slice(-1)[0]?.attrs).toMatchObject({ n: 1, label: "opened the player" });
+    expect(screen.queryByLabelText(/recorder.pill.stepPrompt/)).toBeNull();
+    expect(document.activeElement).toBe(step);
+    expect(step.textContent).toContain("· 1");
+  });
+
+  it("Escape in the step prompt closes the prompt, not the dialog the pill sits in", () => {
+    const onClose = vi.fn();
+    mount(
+      { debug_session: session() },
+      <Modal title="dialog" onClose={onClose}>
+        <p>inside</p>
+      </Modal>,
+    );
+    // The pill moved into the dialog's own toast host.
+    expect(pill()!.closest('[role="dialog"]')).not.toBeNull();
+    const marked = () => events().filter((e) => e.event === "debug.step").length;
+    const before = marked();
+    fireEvent.click(within(pill()!).getByRole("button", { name: "recorder.pill.step" }));
+    fireEvent.keyDown(screen.getByLabelText(/recorder.pill.stepPrompt/), { key: "Escape" });
+    expect(screen.queryByLabelText(/recorder.pill.stepPrompt/)).toBeNull();
+    expect(onClose).not.toHaveBeenCalled();
+    expect(marked()).toBe(before);
+  });
+
+  it("offers a screenshot only where the browser can capture a tab", () => {
+    mount({ debug_session: session() });
+    // jsdom has no Screen Capture API — like iOS Safari.
+    expect(within(pill()!).queryByRole("button", { name: "recorder.pill.screenshot" })).toBeNull();
+  });
+
+  it("at its cap it says so and opens the composer", () => {
+    vi.useFakeTimers();
+    mount({ debug_session: session({ until: new Date(Date.now() + 5_000).toISOString() }) });
+    act(() => void vi.advanceTimersByTime(5_000));
+    expect(screen.getByText("recorder.pill.expired:60")).not.toBeNull();
+    expect(composing).toBe("0123456789abcdef");
+  });
+});
+
+describe("the start dialog", () => {
+  it("states the retention and the cap, and starts at the level chosen", async () => {
+    const qc = mount({});
+    act(() => openRecorderStart());
+    expect(screen.getByText(/recorder.start.kept:7/)).not.toBeNull();
+    expect(screen.getByText(/recorder.start.cap:60/)).not.toBeNull();
+    fireEvent.click(screen.getByRole("button", { name: "settings.diagnostics.levels.TRACE" }));
+    expect(screen.getByText("recorder.start.what.TRACE")).not.toBeNull();
+    fireEvent.click(screen.getByRole("button", { name: /recorder.start.confirm/ }));
+    await waitFor(() => expect(startDebugSession).toHaveBeenCalledWith("TRACE"));
+    await waitFor(() => expect(pill()).not.toBeNull());
+    expect(qc.getQueryData<Me>(qk.me())?.debug_session?.level).toBe("TRACE");
+    expect(screen.queryByText("recorder.start.title")).toBeNull();
+  });
+});
@@ -0,0 +1,296 @@
+import { useEffect, useRef, useState, type KeyboardEvent as ReactKeyboardEvent } from "react";
+import { useTranslation } from "react-i18next";
+import { useQueryClient } from "@tanstack/react-query";
+import { Camera, Flag, Square } from "lucide-react";
+
+import type { DebugSessionLevel } from "../lib/api";
+import { canCaptureTab } from "../lib/captureTab";
+import {
+  closeRecorderStart,
+  openComposer,
+  openRecorderStart,
+  useRecorderStartOpen,
+  useStepCount,
+} from "../lib/debugRecorder";
+import { useLayer } from "../lib/layerStack";
+import { notify } from "../lib/notifications";
+import { qk } from "../lib/queryKeys";
+import { dockUnderToasts } from "../lib/toastDock";
+import { useMe } from "../lib/useMe";
+import { Button } from "./ui/Button";
+import Modal from "./ui/Modal";
+import SegmentedToggle from "./ui/SegmentedToggle";
+import { inputCls } from "./ui/form";
+import { useDebugRecording } from "./useDebugRecording";
+
+// The debug recorder (E16): Start → reproduce → Stop.
+//
+// While a session records, its pill sits under the toasts (lib/toastDock), so it rides every toast
+// host — the page, each dialog, both players, the fullscreen player — and is reachable wherever the
+// bug is being reproduced, above a player's control band rather than on it. Mounted once, in the
+// app shell, for a signed-in account other than the demo.
+
+/** `m:ss` since `since`, re-rendered every second. */
+function useElapsed(since: string): string {
+  const [, tick] = useState(0);
+  useEffect(() => {
+    const id = window.setInterval(() => tick((n) => n + 1), 1000);
+    return () => window.clearInterval(id);
+  }, []);
+  const s = Math.max(0, Math.floor((Date.now() - Date.parse(since)) / 1000));
+  return `${Math.floor(s / 60)}:${String(s % 60).padStart(2, "0")}`;
+}
+
+export default function DebugRecorder() {
+  const { t } = useTranslation();
+  const qc = useQueryClient();
+  const me = useMe();
+  const { session } = useDebugRecording();
+  const startOpen = useRecorderStartOpen();
+  const id = session?.id;
+
+  useEffect(() => (id ? dockUnderToasts(RecorderPill) : undefined), [id]);
+
+  // The cap: the server ends the session at `until` whether or not anyone stops it. This tab says
+  // so, and opens the composer for it — the recording is as useful as one stopped by hand.
+  const until = session?.until;
+  const minutes = me?.diagnostics?.session_minutes;
+  useEffect(() => {
+    if (!id || !until) return;
+    const wait = Math.min(Date.parse(until) - Date.now(), 2 ** 31 - 1);
+    const timer = window.setTimeout(() => {
+      notify({ level: "warning", message: t("recorder.pill.expired", { count: minutes ?? 0 }) });
+      openComposer(id);
+      void qc.invalidateQueries({ queryKey: qk.me() });
+    }, wait);
+    return () => window.clearTimeout(timer);
+  }, [id, until, minutes, qc, t]);
+
+  return startOpen ? <StartDialog /> : null;
+}
+
+function StartDialog() {
+  const { t } = useTranslation();
+  const me = useMe();
+  const { start } = useDebugRecording();
+  const [level, setLevel] = useState<DebugSessionLevel>("DEBUG");
+  const days = me.diagnostics.retention_days;
+  const minutes = me.diagnostics.session_minutes;
+  const levels: readonly DebugSessionLevel[] = ["DEBUG", "TRACE"];
+  return (
+    <Modal title={t("recorder.start.title")} onClose={closeRecorderStart}>
+      <div className="flex flex-col gap-4">
+        <p className="text-sm text-muted leading-relaxed">{t("recorder.start.intro")}</p>
+        <div className="flex flex-col items-start gap-1.5">
+          <span className="text-sm text-muted">{t("recorder.start.level")}</span>
+          <SegmentedToggle
+            size="md"
+            ariaLabel={t("recorder.start.level")}
+            options={levels.map((l) => ({
+              value: l,
+              label: t(`settings.diagnostics.levels.${l}`),
+            }))}
+            value={level}
+            onChange={setLevel}
+          />
+        </div>
+        <div className="rounded-lg border border-border bg-surface/60 px-4 py-3 flex flex-col gap-2 text-sm leading-relaxed">
+          <div className="font-semibold">{t("recorder.start.whatTitle")}</div>
+          <p>{t(`recorder.start.what.${level}`)}</p>
+          <p className="text-muted">{t("settings.diagnostics.consent.never")}</p>
+          <p className="text-muted">
+            {t("recorder.start.kept", { count: days })}{" "}
+            {t("recorder.start.cap", { count: minutes })}
+          </p>
+        </div>
+        <div className="flex justify-end gap-2">
+          <Button variant="ghost" onClick={closeRecorderStart}>
+            {t("common.cancel")}
+          </Button>
+          <Button
+            variant="primary"
+            loading={start.isPending}
+            icon={<span className="w-2.5 h-2.5 rounded-full bg-danger" aria-hidden />}
+            onClick={() => start.mutate(level)}
+          >
+            {t("recorder.start.confirm")}
+          </Button>
+        </div>
+      </div>
+    </Modal>
+  );
+}
+
+/** The pill: how long it has been recording, and the three things to do while it does. */
+function RecorderPill() {
+  const { t } = useTranslation();
+  const { session, stop, shoot, markStep, screenshot } = useDebugRecording();
+  const [hidden, setHidden] = useState(false);
+  const [stepOpen, setStepOpen] = useState(false);
+  const stepButton = useRef<HTMLButtonElement>(null);
+  const steps = useStepCount(session?.id ?? "");
+  if (!session) return null;
+  return (
+    <div
+      role="group"
+      aria-label={t("recorder.pill.label")}
+      className={`relative glass rounded-full h-12 pl-3 sm:pl-4 pr-1.5 flex items-center gap-1.5 sm:gap-2 shadow-lg ${
+        hidden ? "invisible" : ""
+      }`}
+    >
+      <span
+        aria-hidden
+        className="w-2.5 h-2.5 shrink-0 rounded-full bg-danger ring-4 ring-danger/20 motion-safe:animate-pulse"
+      />
+      <Elapsed since={session.started_at} />
+      <span className="chip hidden sm:inline-flex px-2 py-0.5 text-2xs">
+        {t(`settings.diagnostics.levels.${session.level}`)}
+      </span>
+      <span aria-hidden className="hidden sm:block w-px h-6 bg-border" />
+      <Button
+        ref={stepButton}
+        variant="outline-accent"
+        size="sm"
+        className="rounded-full"
+        icon={<Flag className="w-4 h-4" />}
+        label={t("recorder.pill.step")}
+        aria-expanded={stepOpen}
+        onClick={() => setStepOpen((v) => !v)}
+      >
+        <span className="hidden sm:inline tabular-nums">
+          {t("recorder.pill.step")}
+          {steps ? ` · ${steps}` : ""}
+        </span>
+      </Button>
+      {canCaptureTab() && (
+        <Button
+          variant="outline"
+          size="sm"
+          className="rounded-full"
+          icon={<Camera className="w-4 h-4" />}
+          label={t("recorder.pill.screenshot")}
+          loading={shoot.isPending}
+          onClick={() => void screenshot(setHidden)}
+        >
+          <span className="hidden sm:inline tabular-nums">
+            {t("recorder.pill.screenshot")}
+            {session.screenshots ? ` · ${session.screenshots}` : ""}
+          </span>
+        </Button>
+      )}
+      <Button
+        variant="danger"
+        size="sm"
+        className="rounded-full"
+        icon={<Square className="w-3.5 h-3.5 fill-current" />}
+        label={t("recorder.pill.stop")}
+        loading={stop.isPending}
+        onClick={() => stop.mutate(session.id)}
+      >
+        <span className="hidden sm:inline">{t("recorder.pill.stop")}</span>
+      </Button>
+      {stepOpen && (
+        <StepPrompt
+          id={session.id}
+          onDone={(label) => {
+            if (label !== null) markStep(label);
+            setStepOpen(false);
+            stepButton.current?.focus();
+          }}
+        />
+      )}
+    </div>
+  );
+}
+
+function Elapsed({ since }: { since: string }) {
+  const { t } = useTranslation();
+  const time = useElapsed(since);
+  return (
+    // On a phone only the clock: the pill has to fit the content column beside the rail, and the
+    // red dot already says what it is.
+    <span className="text-sm font-semibold tabular-nums whitespace-nowrap">
+      <span className="hidden sm:inline">{t("recorder.pill.recording", { time })}</span>
+      <span className="sm:hidden">{time}</span>
+    </span>
+  );
+}
+
+/** Settings → Diagnosztika: start a recording, or see the one running and stop it. */
+export function RecorderSettings() {
+  const { t } = useTranslation();
+  const { session, stop } = useDebugRecording();
+  if (!session)
+    return (
+      <div className="flex flex-wrap items-center justify-between gap-3">
+        <p className="text-sm text-muted max-w-prose">{t("recorder.settings.hint")}</p>
+        <Button
+          variant="outline"
+          icon={<span className="w-2.5 h-2.5 rounded-full bg-danger" aria-hidden />}
+          onClick={openRecorderStart}
+        >
+          {t("recorder.settings.start")}
+        </Button>
+      </div>
+    );
+  return (
+    <div className="flex flex-wrap items-center justify-between gap-2 rounded-xl border border-danger/40 bg-danger/10 px-3 py-2 text-sm">
+      <span className="inline-flex items-center gap-2">
+        <span className="h-2 w-2 shrink-0 rounded-full bg-danger" aria-hidden />
+        <SettingsElapsed since={session.started_at} />
+      </span>
+      <Button
+        variant="danger-soft"
+        size="sm"
+        loading={stop.isPending}
+        onClick={() => stop.mutate(session.id)}
+      >
+        {t("recorder.settings.stop")}
+      </Button>
+    </div>
+  );
+}
+
+function SettingsElapsed({ since }: { since: string }) {
+  const { t } = useTranslation();
+  const time = useElapsed(since);
+  return <span className="tabular-nums">{t("recorder.settings.recording", { time })}</span>;
+}
+
+/** "What did you just do?" — optional; Enter marks the step, Escape leaves it unmarked. */
+function StepPrompt({ id, onDone }: { id: string; onDone: (label: string | null) => void }) {
+  const { t } = useTranslation();
+  const n = useStepCount(id) + 1;
+  const [label, setLabel] = useState("");
+  // A layer of its own, so Escape closes only the prompt — not the dialog or the player the pill may
+  // be sitting in: the topmost layer takes Escape (lib/layerStack), and this one opened last.
+  useLayer(true, () => onDone(null));
+  const onKeyDown = (e: ReactKeyboardEvent<HTMLInputElement>) => {
+    if (e.key === "Enter") {
+      e.preventDefault();
+      onDone(label);
+    }
+  };
+  return (
+    <div className="absolute bottom-full left-0 mb-2 w-80 max-w-[calc(100vw-2rem)] glass rounded-xl p-3 flex flex-col gap-2 shadow-lg">
+      <label htmlFor="debug-step-label" className="text-sm text-muted">
+        {t("recorder.pill.stepPrompt", { n })}
+      </label>
+      <input
+        id="debug-step-label"
+        autoFocus
+        value={label}
+        onChange={(e) => setLabel(e.target.value)}
+        onKeyDown={onKeyDown}
+        maxLength={200}
+        className={`${inputCls} w-full`}
+      />
+      <div className="flex items-center justify-between gap-2 text-xs text-muted">
+        <span>{t("recorder.pill.stepHint")}</span>
+        <Button variant="primary" size="sm" onClick={() => onDone(label)}>
+          {t("recorder.pill.mark")}
+        </Button>
+      </div>
+    </div>
+  );
+}
@@ -37,6 +37,7 @@ const setLevel = vi.fn(
        level,
        until: level === "INFO" ? null : new Date(Date.now() + 86_400_000).toISOString(),
        retention_days: 7,
+        session_minutes: 60,
      },
    }),
 );
@@ -61,7 +62,7 @@ function mount(me: Partial<Me>) {
    id: 1,
    is_demo: false,
    preferences: {},
-    diagnostics: { level: "INFO", until: null, retention_days: 7 },
+    diagnostics: { level: "INFO", until: null, retention_days: 7, session_minutes: 60 },
    ...me,
  });
  render(
@@ -131,7 +132,7 @@ describe("DiagnosticsSettings", () => {

  it("going back to the base level needs no consent", async () => {
    const until = new Date(Date.now() + 3_600_000).toISOString();
-    mount({ diagnostics: { level: "DEBUG", until, retention_days: 7 } });
+    mount({ diagnostics: { level: "DEBUG", until, retention_days: 7, session_minutes: 60 } });
    fireEvent.click(levelButton("settings.diagnostics.levels.INFO"));
    expect(screen.queryByTestId("diagnostics-consent")).toBeNull();
    await waitFor(() => expect(setLevel).toHaveBeenCalledWith("INFO"));
@@ -169,7 +170,7 @@ describe("DiagnosticsSettings", () => {
    try {
      // Raised, so the status line's countdown is mounted and its 30 s tick keeps re-rendering.
      const until = new Date(Date.now() + 3_600_000).toISOString();
-      mount({ diagnostics: { level: "DEBUG", until, retention_days: 7 } });
+      mount({ diagnostics: { level: "DEBUG", until, retention_days: 7, session_minutes: 60 } });
      fireEvent.click(levelButton("settings.diagnostics.levels.TRACE"));
      const elsewhere = document.createElement("button");
      document.body.append(elsewhere);
@@ -194,7 +195,7 @@ describe("DiagnosticsSettings", () => {

  it("the ticking status line is not a live region", async () => {
    const until = new Date(Date.now() + 3_600_000).toISOString();
-    mount({ diagnostics: { level: "DEBUG", until, retention_days: 7 } });
+    mount({ diagnostics: { level: "DEBUG", until, retention_days: 7, session_minutes: 60 } });
    const status = screen.getByTestId("diagnostics-status");
    expect(status.closest('[role="status"], [aria-live]')).toBeNull();
  });
@@ -215,7 +216,7 @@ describe("DiagnosticsSettings", () => {
      id: 1,
      is_demo: false,
      preferences: {},
-      diagnostics: { level: "INFO", until: null, retention_days: 7 },
+      diagnostics: { level: "INFO", until: null, retention_days: 7, session_minutes: 60 },
    });
    await stale;
    expect(qc.getQueryData<Me>(qk.me())?.diagnostics.level).toBe("TRACE");
@@ -224,7 +225,7 @@ describe("DiagnosticsSettings", () => {

  it("a lapsed level shows as the base level", () => {
    const until = new Date(Date.now() - 60_000).toISOString();
-    mount({ diagnostics: { level: "TRACE", until, retention_days: 7 } });
+    mount({ diagnostics: { level: "TRACE", until, retention_days: 7, session_minutes: 60 } });
    expect(levelButton("settings.diagnostics.levels.INFO").getAttribute("aria-pressed")).toBe(
      "true",
    );
@@ -10,6 +10,7 @@ import InlineNotice from "./ui/InlineNotice";
 import SegmentedToggle from "./ui/SegmentedToggle";
 import { Section, SettingRow } from "./ui/form";
 import MyLogViewer from "./MyLogViewer";
+import { RecorderSettings } from "./DebugRecorder";

 const LEVELS: readonly DiagnosticsLevel[] = ["INFO", "DEBUG", "TRACE"];

@@ -181,6 +182,12 @@ export default function DiagnosticsSettings() {
        )}
      </Section>

+      {!me.is_demo && (
+        <Section title={t("recorder.settings.title")}>
+          <RecorderSettings />
+        </Section>
+      )}
+
      <Section title={t("settings.myLog.title")}>
        <MyLogViewer />
      </Section>
@@ -0,0 +1,99 @@
+import { useMutation, useQueryClient } from "@tanstack/react-query";
+import { useTranslation } from "react-i18next";
+
+import { api, type DebugSession, type DebugSessionLevel } from "../lib/api";
+import { notifyActionError } from "../lib/actionErrors";
+import { captureTab } from "../lib/captureTab";
+import { closeRecorderStart, nextStep, openComposer } from "../lib/debugRecorder";
+import { flushNow, liveSession } from "../lib/diagnostics";
+import { log } from "../lib/log";
+import { notify } from "../lib/notifications";
+import { updateMeCache, useMe } from "../lib/useMe";
+
+/** The debug recording's actions (E16), shared by everything that drives it: the pill, Settings →
+ *  Diagnosztika and the command palette. The session itself is `me.debug_session` — the server's
+ *  answer, so a reload, another tab or the cap all show the same thing. */
+export function useDebugRecording() {
+  const { t } = useTranslation();
+  const qc = useQueryClient();
+  const me = useMe();
+  const session = liveSession(me?.debug_session);
+  const setSession = (next: DebugSession | null) =>
+    updateMeCache(qc, (prev) => ({ ...prev, debug_session: next }));
+
+  const start = useMutation({
+    mutationFn: (level: DebugSessionLevel) => api.startDebugSession(level),
+    meta: { failTitle: "recorder.start.failed" },
+    onSuccess: (r) => {
+      setSession(r.session);
+      closeRecorderStart();
+    },
+  });
+
+  const stop = useMutation({
+    mutationFn: async (id: string) => {
+      log.info("debug.stop", "recording stopped by the user");
+      // The events of the last seconds before Stop are the ones closest to what went wrong. Sent
+      // while the session still tags them: once it is closed the server no longer does.
+      await flushNow();
+      return api.stopDebugSession(id);
+    },
+    meta: { failTitle: "recorder.pill.stopFailed" },
+    onSuccess: (r) => {
+      setSession(null);
+      notify({ level: "success", message: t("recorder.pill.stopped") });
+      openComposer(r.session.id);
+    },
+  });
+
+  const shoot = useMutation({
+    mutationFn: async ({ id, image }: { id: string; image: Blob }) =>
+      api.addDebugScreenshot(id, image),
+    meta: { failTitle: "recorder.pill.shotFailed" },
+    onSuccess: (r) => {
+      updateMeCache(qc, (prev) =>
+        prev.debug_session
+          ? {
+              ...prev,
+              debug_session: {
+                ...prev.debug_session,
+                screenshots: prev.debug_session.screenshots + 1,
+              },
+            }
+          : prev,
+      );
+      // In the evidence too, where the step list is drafted from: which step it belongs to.
+      log.info("debug.screenshot", "screenshot taken", { screenshot: r.screenshot.id });
+      notify({ level: "success", message: t("recorder.pill.shotSaved") });
+    },
+  });
+
+  /** Mark the next step; `label` is what the user says they just did (may be empty). */
+  const markStep = (label: string) => {
+    if (!session) return;
+    const n = nextStep(session.id);
+    const text = label.trim();
+    log.info("debug.step", text || `step ${n}`, { n, ...(text ? { label: text } : {}) });
+    notify({ level: "info", message: t("recorder.pill.stepMarked", { n }) });
+  };
+
+  /** Capture this tab and attach it. `hide` runs around the capture so the pill is not in the
+   *  frame. Nothing happens when the user cancels the browser's picker. */
+  const screenshot = async (hide: (hidden: boolean) => void) => {
+    if (!session) return;
+    hide(true);
+    let image: Blob | null = null;
+    try {
+      // Two frames: the pill's `invisible` must be painted before the capture reads the tab.
+      await new Promise((r) => requestAnimationFrame(() => requestAnimationFrame(r)));
+      image = await captureTab();
+    } catch (err) {
+      notifyActionError(err, t("recorder.pill.shotFailed"));
+    } finally {
+      hide(false);
+    }
+    if (image) shoot.mutate({ id: session.id, image });
+  };
+
+  return { session, start, stop, shoot, markStep, screenshot };
+}