@joewinke/jatui 0.37.0 → 0.38.0

package/dist/artifact-blocks/blocks/checklist/ChecklistBlock.svelte

@@ -0,0 +1,1048 @@
+<script lang="ts">
+  /**
+   * checklist block — the Runbook archetype of the one review experience
+   * (docs/review-ux/proposal.md, mos-lsmve.7): rows with a title, an optional
+   * test URL, an owner, a verdict and a note. Viewers decide each row; that
+   * per-viewer state persists via ctx.saveState (keyed per row id). With
+   * teamMode:true the AUTHORED status in params renders as the shared "Team"
+   * status — the agents' view, updated by republishing the spec — beside the
+   * viewer's own private verdict ("You").
+   *
+   * Built from the shared jatui review primitives so what a reviewer learns
+   * here carries to every other review page:
+   *   - Rows are focusable cards walked by reviewKeys (j/k, ↓/↑, gg/G). On the
+   *     focused card: a pass, x fail, b blocked, u undo (back to Untested),
+   *     n note, Enter opens the row's test link, [ / ] walk earlier rounds,
+   *     f next row that needs you (retest, then undecided), ? shortcuts. The
+   *     old p letter still works for one release; the shortcuts modal says so.
+   *   - VerdictControl: Pass / Fail / Blocked, labels always visible, a second
+   *     press never clears, Undo is explicit.
+   *   - ReviewNote: the note of the CURRENT round, opening itself on Fail or
+   *     Blocked, with its own Saving / Saved ✓ / Not saved state.
+   *   - RoundHistory: earlier rounds, locked (Joe D1 = A).
+   *   - ReviewFilterBar (chips with counts + one Sort/Group menu) and
+   *     ReviewProgress (one tone bar + a sentence) on top.
+   *
+   * Rounds (Joe D2 = A): a row's round is its `retestSince`. When the team
+   * marks a row ready with a new retestSince, the viewer's previous verdict
+   * and note show as a locked history line and the current round starts
+   * blank; the first save in the round writes that move (retest.ts
+   * CHECKLIST_ROUNDS, on the viewer's own save — never a migration).
+   *
+   * Team progress (mos-mssz0): in teamMode the Team column also speaks two
+   * team-only states — "In progress" and "Ready to retest". A ready row the
+   * viewer has not re-verdicted in its round carries a "Retest" chip and
+   * counts in the progress line; the same rule (retest.ts) is what puts the
+   * page under Needs you on /admin/artifacts.
+   *
+   * Read-only surfaces (public share, print, tests without saveState) render
+   * verdicts as badges with no controls, plus the locked history — they must
+   * look correct without ever calling saveState.
+   *
+   * Sort + group (mos-iwmjz) live in the filter bar's menu. They are
+   * viewer-LOCAL layout choices — persisted in the viewer's browser
+   * (localStorage, try/catch), never in block state — and render server-side
+   * with the defaults so hydration never disagrees with a saved row order.
+   * The DOM order always equals the visual order, so j/k and Tab follow what
+   * the viewer sees.
+   */
+  import Icon from "./Icon.svelte"
+  import { tick } from "svelte"
+  import ReviewFilterBar from "../../../components/review/ReviewFilterBar.svelte"
+  import ReviewNote from "../../../components/review/ReviewNote.svelte"
+  import ReviewProgress from "../../../components/review/ReviewProgress.svelte"
+  import ReviewShortcuts from "../../../components/review/ReviewShortcuts.svelte"
+  import RoundHistory from "../../../components/review/RoundHistory.svelte"
+  import VerdictControl from "../../../components/review/VerdictControl.svelte"
+  import {
+    buildReviewFilters,
+    orderRounds,
+    type ReviewRound,
+  } from "../../../components/review/reviewSummary.js"
+  import {
+    createReviewKeys,
+    type NeedsYou,
+    type ReviewKeysOptions,
+  } from "../../../actions/reviewKeys.js"
+  import { isTypingTarget } from "../../../utils/keyboardShortcutRegistry.js"
+  import type { BlockProps } from "../../types.js"
+  import {
+    CHECKLIST_STATUSES,
+    type ChecklistParams,
+    type ChecklistRow,
+    type ChecklistRowState,
+    type ChecklistState,
+    type ChecklistStatus,
+  } from "./schema.js"
+  import {
+    CHECKLIST_ROUNDS,
+    rowAwaitsViewer,
+    rowRound,
+    seedStatus,
+  } from "./retest.js"
+  import {
+    CHECKLIST_GROUPS,
+    CHECKLIST_SORTS,
+    GROUP_OPTIONS,
+    ICON_TONE,
+    LABEL,
+    LEGACY_KEYS,
+    SORT_OPTIONS,
+    STATUS_BADGE,
+    STATUS_RANK,
+    TEAM_ICON_TONE,
+    TEAM_LABEL,
+    TITLE_LINK,
+    VERDICT_OPTIONS,
+    type ChecklistGroup,
+    type ChecklistSort,
+  } from "./labels.js"
+  import SectionTools from "../../SectionTools.svelte"
+
+  let { params, ctx }: BlockProps<ChecklistParams> = $props()
+
+  const rows = $derived(params?.rows ?? [])
+  const teamMode = $derived(params?.teamMode === true)
+  /** Interactive = the viewer can set verdicts here (private to them). */
+  const interactive = $derived(Boolean(ctx?.saveState) && !ctx?.readonly)
+  /** This viewer's saved state for this block (null = none yet). */
+  const saved = $derived((ctx?.state ?? null) as ChecklistState | null)
+  const groupName = $derived(`chk-${ctx?.blockId ?? "checklist"}`)
+
+  // ---- viewer view prefs: sort + group (mos-iwmjz) ------------------------
+  // Layout choices are UI preference, not verdict data: they persist in THIS
+  // BROWSER under a per-(artifact, block) key and never through ctx.saveState
+  // (state is shared per-viewer verdict data keyed per artifact version — a
+  // sort must not write it). Every access is try/catch'd and guarded, so a
+  // missing/full/blocked storage renders the defaults and works fine.
+  const VIEW_KEY = `jat-checklist-view:${ctx?.artifactId ?? "artifact"}:${ctx?.blockId ?? "checklist"}`
+
+  // Raw (string) values are what the filter bar's menu binds; the typed
+  // views below coerce, so corrupted storage can never produce an unknown
+  // mode.
+  let sortByRaw = $state<string>("authored")
+  let groupByRaw = $state<string>("none")
+  const sortBy = $derived(isSort(sortByRaw) ? sortByRaw : "authored")
+  const groupBy = $derived(isGroup(groupByRaw) ? groupByRaw : "none")
+
+  function isSort(v: unknown): v is ChecklistSort {
+    return (
+      typeof v === "string" &&
+      (CHECKLIST_SORTS as readonly string[]).includes(v)
+    )
+  }
+  function isGroup(v: unknown): v is ChecklistGroup {
+    return (
+      typeof v === "string" &&
+      (CHECKLIST_GROUPS as readonly string[]).includes(v)
+    )
+  }
+
+  function loadViewPrefs(): {
+    sortBy?: ChecklistSort
+    groupBy?: ChecklistGroup
+  } {
+    try {
+      if (typeof localStorage === "undefined") return {}
+      const raw = localStorage.getItem(VIEW_KEY)
+      if (!raw) return {}
+      const parsed: unknown = JSON.parse(raw)
+      if (!parsed || typeof parsed !== "object") return {}
+      const o = parsed as Record<string, unknown>
+      return {
+        ...(isSort(o.sortBy) ? { sortBy: o.sortBy } : {}),
+        ...(isGroup(o.groupBy) ? { groupBy: o.groupBy } : {}),
+      }
+    } catch {
+      return {}
+    }
+  }
+
+  function saveViewPrefs(next: { sortBy: string; groupBy: string }) {
+    try {
+      if (typeof localStorage === "undefined") return
+      localStorage.setItem(VIEW_KEY, JSON.stringify(next))
+    } catch {
+      /* storage unavailable or full — prefs just stay session-local */
+    }
+  }
+
+  /** Set once the saved prefs (or their absence) landed on mount. */
+  let viewHydrated = $state(false)
+
+  // Restore once on mount. Effects never run on SSR, so the server render
+  // always paints the defaults and hydration never disagrees with a
+  // saved-prefs row order; the restore is a post-hydration update.
+  $effect(() => {
+    const prefs = loadViewPrefs()
+    if (prefs.sortBy) sortByRaw = prefs.sortBy
+    if (prefs.groupBy) groupByRaw = prefs.groupBy
+    viewHydrated = true
+  })
+
+  // Persist on change — only after the restore above ran, so a default can
+  // never overwrite what the viewer saved.
+  $effect(() => {
+    if (!viewHydrated) return
+    saveViewPrefs({ sortBy: sortByRaw, groupBy: groupByRaw })
+  })
+
+  const STATUS_ICON = {
+    pass: "circle-check",
+    fail: "circle-x",
+    blocked: "circle-pause",
+    untested: "circle-dashed",
+  } as const
+  const TEAM_ICON = {
+    ...STATUS_ICON,
+    ready: "rotate-ccw",
+    in_progress: "circle-dot-dashed",
+  } as const
+
+  // ---- the viewer's stored entries, one per row ---------------------------
+  // State is keyed per (artifact, version, user, blockId) and does not change
+  // while mounted — one mount-time read, like the callout block. Each entry
+  // is the row's saved shape: the CURRENT round flat ({status, note, at,
+  // statusAt, round}) plus the locked `history[]`. Stored JSON is untrusted,
+  // so only known fields of the right type survive the read.
+  let entries = $state<Record<string, Record<string, unknown>>>({})
+  {
+    const s = (ctx?.state as ChecklistState | null)?.rows ?? {}
+    for (const [id, r] of Object.entries(s)) {
+      if (!r || typeof r !== "object") continue
+      const raw = r as Record<string, unknown>
+      const e: Record<string, unknown> = {}
+      if (isStatus(raw.status)) e.status = raw.status
+      for (const k of ["note", "at", "statusAt", "round"] as const)
+        if (typeof raw[k] === "string") e[k] = raw[k]
+      const history = CHECKLIST_ROUNDS.parseHistory(raw.history)
+      if (history.length > 0) e.history = history
+      entries[id] = e
+    }
+  }
+
+  function isStatus(v: unknown): v is ChecklistStatus {
+    return (
+      typeof v === "string" &&
+      (CHECKLIST_STATUSES as readonly string[]).includes(v)
+    )
+  }
+
+  /** Each row's current round + locked history, as the viewer sees it now. */
+  const views = $derived.by(() => {
+    const out: Record<string, ReturnType<typeof CHECKLIST_ROUNDS.view>> = {}
+    for (const row of rows)
+      out[row.id] = CHECKLIST_ROUNDS.view(entries[row.id], rowRound(row))
+    return out
+  })
+
+  /**
+   * The viewer's verdict for a row in its current round. Their save wins;
+   * a stale round starts blank. What fills a row with NO save differs by
+   * mode (mos-lsmve.16 F8): in teamMode the viewer starts UNTETED — the
+   * Team column already shows the team's verdict, and seeding "You" from
+   * it double-counted the team's answer as the viewer's (untouched rows
+   * carried an Undo, a Blocked row's note sat open, they counted as
+   * decided). Outside teamMode the authored status still seeds: a solo
+   * checklist's statuses ARE the statuses being confirmed.
+   */
+  function viewerStatus(row: ChecklistRow): ChecklistStatus {
+    const v = views[row.id]
+    const st = v?.current.status
+    if (isStatus(st)) return st
+    if (v?.stale) return "untested"
+    if (teamMode) return "untested"
+    return seedStatus(row)
+  }
+
+  /** The current round's note ("" when none). */
+  function currentNote(row: ChecklistRow): string {
+    const n = views[row.id]?.current.note
+    return typeof n === "string" ? n : ""
+  }
+
+  /** A `ready` row the viewer has not re-verdicted in its round. */
+  function awaitsRetest(row: ChecklistRow): boolean {
+    return rowAwaitsViewer(row, entries[row.id])
+  }
+
+  /** Earlier rounds, oldest first (how RoundHistory numbers them). Keys are
+   * made unique per line, so two lines of one round never collide. */
+  function historyOf(row: ChecklistRow): ReviewRound[] {
+    const lines = views[row.id]?.history ?? []
+    return [...lines].reverse().map((l, i) => ({
+      round: `${i}:${l.round ?? "legacy"}`,
+      verdict: l.verdict ?? null,
+      note: l.note ?? null,
+      at: l.at ?? null,
+    }))
+  }
+
+  // ---- saving (coalesced locally; the host may debounce further) ----------
+  let saving = $state(false)
+  let saveError = $state<string | null>(null)
+  let justSavedAt = $state<string | null>(null)
+  let saveTimer: ReturnType<typeof setTimeout> | null = null
+
+  function queueSave() {
+    if (!interactive || !ctx?.saveState) return
+    if (saveTimer) clearTimeout(saveTimer)
+    saving = true
+    saveTimer = setTimeout(() => void flushSave(), 350)
+  }
+
+  /**
+   * The payload carries every row the viewer touched, each in its saved
+   * shape — status even when it equals the authored seed (a note-only save
+   * must not drop a saved status — the state replaces as a whole), an
+   * empty-string note to persist an intentional clear, and the row's own
+   * `round` + `history`. Each row keeps its own `at` / `statusAt` — stamped
+   * when THAT row changed, never by a save elsewhere on the page.
+   */
+  function statePayload(): ChecklistState {
+    const out: NonNullable<ChecklistState["rows"]> = {}
+    for (const row of rows) {
+      const e = entries[row.id]
+      if (e && Object.keys(e).length > 0)
+        out[row.id] = { ...e } as ChecklistRowState
+    }
+    return { rows: out, at: new Date().toISOString() }
+  }
+
+  /** Save now. Resolves false (and shows the error) when the host refused. */
+  async function flushSave(): Promise<boolean> {
+    if (saveTimer) clearTimeout(saveTimer)
+    saveTimer = null
+    if (!ctx?.saveState) return false
+    saveError = null
+    saving = true
+    try {
+      await ctx.saveState(statePayload())
+      justSavedAt = new Date().toISOString()
+      return true
+    } catch (e) {
+      saveError = e instanceof Error ? e.message : "Saving failed"
+      return false
+    } finally {
+      saving = false
+    }
+  }
+
+  /** Apply one change to a row through the round model (the first save in
+   * a new round locks the old verdict + note into history first). */
+  function patchRow(row: ChecklistRow, patch: Record<string, unknown>) {
+    entries[row.id] = CHECKLIST_ROUNDS.save(
+      entries[row.id],
+      patch,
+      rowRound(row),
+    )
+  }
+
+  function setStatus(row: ChecklistRow, status: string) {
+    if (!interactive || !isStatus(status)) return
+    const now = new Date().toISOString()
+    const opensNote = VERDICT_OPTIONS.some(
+      (o) => o.id === status && o.opensNote,
+    )
+    patchRow(row, { status, at: now, statusAt: now })
+    queueSave()
+    // ReviewNote opens itself on a verdict CHANGE only while it is mounted
+    // open; a closed note is not, so open + focus it here.
+    if (opensNote && !openNotes[row.id]) void toggleNote(row)
+  }
+
+  /** Undo: the current round back to Untested. The note stays. */
+  function undo(row: ChecklistRow) {
+    if (viewerStatus(row) === "untested") return
+    setStatus(row, "untested")
+  }
+
+  /** Every keystroke lands in the round (locally); ReviewNote's debounced
+   * onSave is what sends it. */
+  function noteInput(row: ChecklistRow, text: string) {
+    if (!interactive) return
+    patchRow(row, { note: text, at: new Date().toISOString() })
+  }
+
+  async function noteSave(row: ChecklistRow, text: string) {
+    noteInput(row, text)
+    if (!(await flushSave())) throw new Error(saveError ?? "Saving failed")
+  }
+
+  /** Rows whose note field is open. Seeded open where a note matters: the
+   * viewer's own note exists on the row, or their verdict stands at Fail /
+   * Blocked. In teamMode an UNDECIDED row never seeds its note open — a
+   * Team-blocked row is the team's problem statement, not this viewer's
+   * open field, and a seeded-open field IS a note-only save waiting to
+   * happen (mos-lsmve.16 F8). A row the viewer HAS saved keeps the old
+   * rule (their own fail/blocked opens the field). */
+  let openNotes = $state<Record<string, boolean>>({})
+  for (const row of params?.rows ?? []) {
+    if (teamMode && !entries[row.id]) continue
+    const st = viewerStatus(row)
+    if (currentNote(row) !== "" || st === "fail" || st === "blocked")
+      openNotes[row.id] = true
+  }
+
+  function noteInputId(row: ChecklistRow): string {
+    return `${groupName}-note-${row.id}`
+  }
+
+  async function toggleNote(row: ChecklistRow) {
+    if (!interactive) return
+    const open = !openNotes[row.id]
+    openNotes[row.id] = open
+    if (!open) return
+    await tick()
+    document.getElementById(noteInputId(row))?.focus()
+  }
+
+  // ---- earlier rounds -----------------------------------------------------
+  let historyOpen = $state<Record<string, boolean>>({})
+  let historySelected = $state<Record<string, string | null>>({})
+
+  /** `[` older / `]` newer: walk the locked lines; past the newest is back
+   * to the current round (nothing selected). */
+  function stepRound(row: ChecklistRow, delta: -1 | 1) {
+    const order = orderRounds(historyOf(row)).map((r) => r.entry.round)
+    if (order.length === 0) return
+    const cur = historySelected[row.id] ?? null
+    const at = cur === null ? -1 : order.indexOf(cur)
+    const next = delta === -1 ? Math.min(at + 1, order.length - 1) : at - 1
+    historySelected[row.id] = next < 0 ? null : order[next]
+    historyOpen[row.id] = next >= 0 || Boolean(historyOpen[row.id])
+  }
+
+  // ---- summary ------------------------------------------------------------
+  const counts = $derived.by(() => {
+    const c: Record<ChecklistStatus, number> = {
+      pass: 0,
+      fail: 0,
+      blocked: 0,
+      untested: 0,
+    }
+    for (const row of rows) c[viewerStatus(row)]++
+    return c
+  })
+  const total = $derived(rows.length)
+  /** Ready rows awaiting this viewer's retest (teamMode only). */
+  const retestCount = $derived(
+    teamMode ? rows.filter((r) => awaitsRetest(r)).length : 0,
+  )
+
+  // ---- filter (session-local) ---------------------------------------------
+  /** Does this row wait on the viewer — a retest, or no verdict yet? */
+  function needsViewer(row: ChecklistRow): boolean {
+    return (teamMode && awaitsRetest(row)) || viewerStatus(row) === "untested"
+  }
+  /** `f` asks this: retest wins over undecided, like the Needs-you chip. */
+  function needsYou(id: string): NeedsYou {
+    const row = rowById(id)
+    if (!row) return false
+    if (teamMode && awaitsRetest(row)) return "retest"
+    return viewerStatus(row) === "untested" ? "undecided" : false
+  }
+
+  const filters = $derived(
+    buildReviewFilters({
+      verdicts: VERDICT_OPTIONS,
+      counts,
+      total,
+      needsYou: teamMode ? rows.filter(needsViewer).length : undefined,
+      retest: teamMode ? retestCount : undefined,
+    }),
+  )
+  let filterRaw = $state("all")
+  /** A filter whose chip emptied out falls back to All, never a blank list. */
+  const filter = $derived(
+    filters.some((f) => f.id === filterRaw) ? filterRaw : "all",
+  )
+
+  function passesFilter(row: ChecklistRow): boolean {
+    switch (filter) {
+      case "all":
+        return true
+      case "needs-you":
+        return needsViewer(row)
+      case "undecided":
+        return viewerStatus(row) === "untested"
+      case "retest":
+        return awaitsRetest(row)
+      default:
+        return viewerStatus(row) === filter
+    }
+  }
+
+  // ---- sort + group (viewer-local choices, persisted in the browser) ------
+  /** One group of rows: stable key, DOM-safe slug, label, order, rows. */
+  interface ChecklistBucket {
+    key: string
+    slug: string
+    label: string
+    order: number
+    rows: ChecklistRow[]
+  }
+
+  /** Bucket keys are data (owner names etc.); ids must be DOM-safe. */
+  function slugify(key: string): string {
+    return key.toLowerCase().replace(/[^a-z0-9_-]+/g, "-")
+  }
+
+  /**
+   * Sorted rows. `sort` is stable, so equal keys keep the authored order —
+   * the status sort is a re-prioritisation (fail → blocked → untested →
+   * pass), never a reshuffle of peers. Status sorts the VIEWER's status
+   * (what they are working through), owner/title are alphabetical with
+   * ownerless rows last.
+   */
+  const sortedRows = $derived.by(() => {
+    const shown = rows.filter(passesFilter)
+    if (sortBy === "authored") return shown
+    const copy = [...shown]
+    if (sortBy === "status")
+      copy.sort(
+        (a, b) => STATUS_RANK[viewerStatus(a)] - STATUS_RANK[viewerStatus(b)],
+      )
+    else if (sortBy === "owner")
+      copy.sort((a, b) => {
+        if (a.owner && b.owner) return a.owner.localeCompare(b.owner)
+        if (a.owner) return -1
+        if (b.owner) return 1
+        return 0
+      })
+    else copy.sort((a, b) => a.title.localeCompare(b.title))
+    return copy
+  })
+
+  /** Which bucket a row belongs to under the current grouping. */
+  function bucketOf(row: ChecklistRow): {
+    key: string
+    label: string
+    order: number
+  } {
+    if (groupBy === "status") {
+      const st = viewerStatus(row)
+      return { key: `status-${st}`, label: LABEL[st], order: STATUS_RANK[st] }
+    }
+    if (groupBy === "owner") {
+      if (!row.owner) return { key: "owner-none", label: "No owner", order: 1 }
+      return { key: `owner-${row.owner}`, label: row.owner, order: 0 }
+    }
+    // mismatch — teamMode: an UNdecided row is neither a match nor a
+    // divergence (the viewer has not answered it — F8), so only decided
+    // rows group by divergence; undecided rows bucket under their own
+    // group. Solo mode: the viewer's verdict vs the authored seed.
+    if (teamMode && viewerStatus(row) === "untested")
+      return { key: "mismatch-undecided", label: "Not decided yet", order: 1 }
+    const diverged =
+      viewerStatus(row) !==
+      (teamMode ? (row.status ?? "untested") : seedStatus(row))
+    if (teamMode)
+      return diverged
+        ? { key: "mismatch-yes", label: "Mismatch", order: 0 }
+        : { key: "mismatch-no", label: "Match", order: 2 }
+    return diverged
+      ? { key: "mismatch-yes", label: "Changed", order: 0 }
+      : { key: "mismatch-no", label: "Unchanged", order: 1 }
+  }
+
+  /**
+   * Contiguous groups in display order (empty ones never appear). With
+   * grouping off this is one headerless bucket carrying the sorted rows.
+   */
+  const groupedRows = $derived.by(() => {
+    if (groupBy === "none")
+      return [
+        { key: "all", slug: "all", label: "", order: 0, rows: sortedRows },
+      ] satisfies ChecklistBucket[]
+    const map = new Map<string, ChecklistBucket>()
+    for (const row of sortedRows) {
+      const meta = bucketOf(row)
+      let bucket = map.get(meta.key)
+      if (!bucket) {
+        bucket = { ...meta, slug: slugify(meta.key), rows: [] }
+        map.set(meta.key, bucket)
+      }
+      bucket.rows.push(row)
+    }
+    return [...map.values()].sort(
+      (a, b) => a.order - b.order || a.label.localeCompare(b.label),
+    )
+  })
+
+  /** Collapsed groups are session-local UI state, not persisted. */
+  let collapsedGroups = $state<Record<string, boolean>>({})
+
+  function toggleGroup(key: string) {
+    collapsedGroups[key] = !collapsedGroups[key]
+  }
+
+  // ---- keyboard: the shared review map ------------------------------------
+  let listEl: HTMLUListElement | undefined = $state()
+  let helpOpen = $state(false)
+
+  function rowById(id: string): ChecklistRow | undefined {
+    return rows.find((r) => r.id === id)
+  }
+
+  /** Enter on a card follows its test link (the same anchor a click hits). */
+  function openRow(el: HTMLElement | null) {
+    el?.querySelector<HTMLAnchorElement>("a[data-row-link]")?.click()
+  }
+
+  const keyConfig: ReviewKeysOptions = $derived({
+    // Collapsed groups hide their cards; j/k skips what is not on screen.
+    getItems: () =>
+      listEl
+        ? [...listEl.querySelectorAll<HTMLElement>("[data-item-id]")].filter(
+            (el) => !el.closest("[hidden]"),
+          )
+        : [],
+    onOpen: (_id, el) => openRow(el),
+    onRound: (id, delta) => {
+      const row = rowById(id)
+      if (row) stepRound(row, delta)
+    },
+    onHelp: () => (helpOpen = true),
+    ...(interactive
+      ? {
+          verdicts: VERDICT_OPTIONS,
+          onVerdict: (id: string, v: string) => {
+            const row = rowById(id)
+            if (row) setStatus(row, v)
+          },
+          onUndo: (id: string) => {
+            const row = rowById(id)
+            if (row) undo(row)
+          },
+          onNote: (id: string) => {
+            const row = rowById(id)
+            if (row) void toggleNote(row)
+          },
+          needsYou,
+        }
+      : {}),
+  })
+
+  const keys = createReviewKeys({})
+  $effect(() => {
+    keys.update(keyConfig)
+  })
+
+  /**
+   * Listens on the block, not the window: a page can carry several review
+   * blocks, and each one's keys act on its own focused card. The old p letter
+   * is honoured after the shared map passes on a key (f is the shared
+   * "next item that needs you", so it never reaches this fallback).
+   */
+  function onKeydown(e: KeyboardEvent) {
+    if (keys.handleKeydown(e)) return
+    if (!interactive || e.defaultPrevented || e.isComposing) return
+    if (e.ctrlKey || e.metaKey || e.altKey || isTypingTarget(e.target)) return
+    const legacy = LEGACY_KEYS[e.key.toLowerCase()]
+    const id = legacy ? keys.currentId() : null
+    const row = id ? rowById(id) : undefined
+    if (!legacy || !row) return
+    e.preventDefault()
+    setStatus(row, legacy)
+  }
+
+  const SHORTCUTS_FOOTNOTE =
+    "The old P still passes for one more release (now A). F no longer fails (that is X): it jumps to the next item that needs you, as on every review page. U is Undo now, not Untested."
+
+  const timeFmt = new Intl.DateTimeFormat("en-US", {
+    hour: "numeric",
+    minute: "2-digit",
+  })
+  const dateTimeFmt = new Intl.DateTimeFormat("en-US", {
+    month: "short",
+    day: "numeric",
+    hour: "numeric",
+    minute: "2-digit",
+  })
+
+  const savedLine = $derived.by(() => {
+    if (saveError) return saveError
+    if (saving) return "Saving…"
+    if (justSavedAt) return `Saved ${timeFmt.format(new Date(justSavedAt))}`
+    return ""
+  })
+
+  function notePlaceholder(st: ChecklistStatus): string {
+    if (st === "fail") return "What failed?"
+    if (st === "blocked") return "What is it waiting on?"
+    return "Add a note"
+  }
+
+  /**
+   * The external-link marker rides with the title's LAST word (nowrap), so a
+   * wrapping title can never strand the icon alone on its own line.
+   */
+  function titleHead(title: string): string {
+    const i = title.trimEnd().lastIndexOf(" ")
+    return i < 0 ? "" : title.slice(0, i + 1)
+  }
+  function titleTail(title: string): string {
+    const i = title.trimEnd().lastIndexOf(" ")
+    return i < 0 ? title : title.slice(i + 1)
+  }
+
+  /** https:// links leave the app (new tab + marker); root-relative stay. */
+  function isExternal(url: string): boolean {
+    return /^https:\/\//i.test(url.trim())
+  }
+</script>
+
+<!-- The cards are the interactive elements; the section only hosts the
+     review keys (they bail unless a card or its controls has focus). -->
+<!-- svelte-ignore a11y_no_static_element_interactions -->
+<section
+  class="artifact-checklist @container w-full rounded-box border border-base-content/10 bg-base-100"
+  onkeydown={onKeydown}
+>
+  <header class="flex flex-col gap-2 px-4 pt-3.5 pb-3">
+    {#if params?.title}
+      <div class="flex items-center gap-2">
+        <h2 class="min-w-0 text-sm font-semibold text-base-content">
+          {params.title}
+        </h2>
+        <SectionTools {ctx} inline />
+      </div>
+    {/if}
+    <ReviewProgress
+      verdicts={VERDICT_OPTIONS}
+      {counts}
+      {total}
+      retest={retestCount}
+      label="{params?.title ?? 'Checklist'} progress"
+      size="sm"
+    />
+    <ReviewFilterBar
+      {filters}
+      bind:active={filterRaw}
+      sortOptions={rows.length > 1 ? SORT_OPTIONS : undefined}
+      bind:sort={sortByRaw}
+      groupOptions={rows.length > 1 ? GROUP_OPTIONS : undefined}
+      bind:group={groupByRaw}
+      onHelp={() => (helpOpen = true)}
+      label="Filter {params?.title ?? 'checklist'}"
+    />
+  </header>
+
+  <ul
+    bind:this={listEl}
+    class="divide-y divide-base-content/10 border-t border-base-content/10"
+    aria-label={params?.title ?? "Checklist"}
+  >
+    {#snippet rowItem(row: ChecklistRow)}
+      {@const vStatus = viewerStatus(row)}
+      {@const iconName = STATUS_ICON[vStatus]}
+      {@const team = row.status ?? "untested"}
+      {@const teamIconName = TEAM_ICON[team]}
+      {@const retest = teamMode && awaitsRetest(row)}
+      {@const history = historyOf(row)}
+      {@const roundN = history.length + 1}
+      {@const verdict = vStatus === "untested" ? null : vStatus}
+      <!-- svelte-ignore a11y_no_noninteractive_tabindex -->
+      <li
+        class="grid grid-cols-[auto_minmax(0,1fr)] gap-x-2.5 gap-y-2 px-4 py-3 focus-visible:outline-2 focus-visible:-outline-offset-2 focus-visible:outline-primary"
+        data-row-id={row.id}
+        data-item-id={row.id}
+        tabindex="0"
+        aria-labelledby="{groupName}-title-{row.id}"
+        data-status={vStatus}
+        data-awaits-retest={retest ? "" : undefined}
+      >
+        <span class="mt-0.5 {ICON_TONE[vStatus]}" aria-hidden="true">
+          <Icon name={iconName} size={18} strokeWidth={2} />
+        </span>
+
+        <div class="min-w-0">
+          {#if row.url}
+            {#if isExternal(row.url)}
+              <a
+                id="{groupName}-title-{row.id}"
+                href={row.url}
+                target="_blank"
+                rel="noopener noreferrer"
+                data-row-link
+                class="{TITLE_LINK} font-medium text-base-content"
+                >{titleHead(row.title)}<span class="whitespace-nowrap"
+                  >{titleTail(row.title)}<Icon
+                    name="external-link"
+                    size={12}
+                    class="ml-1 inline align-baseline text-base-content/50"
+                    aria-hidden="true"
+                  /></span
+                ><span class="sr-only"> (opens in a new tab)</span></a
+              >
+            {:else}
+              <a
+                id="{groupName}-title-{row.id}"
+                href={row.url}
+                data-row-link
+                class="{TITLE_LINK} font-medium text-base-content"
+                >{row.title}</a
+              >
+            {/if}
+          {:else}
+            <span
+              id="{groupName}-title-{row.id}"
+              class="font-medium text-base-content">{row.title}</span
+            >
+          {/if}
+          {#if row.note}
+            <p
+              class="mt-0.5 max-w-[75ch] text-sm leading-snug whitespace-pre-wrap text-base-content/75"
+            >
+              {row.note}
+            </p>
+          {/if}
+        </div>
+
+        <!-- Meta line: owner, then the Team status + Retest chip. -->
+        {#if row.owner || teamMode}
+          <div
+            class="col-start-2 flex flex-wrap items-center gap-x-3 gap-y-1.5"
+          >
+            {#if row.owner}
+              <p class="text-xs text-base-content/70">
+                <span class="sr-only">{"Owner: "}</span><span
+                  class="rounded-full bg-base-content/10 px-2 py-0.5"
+                  >{row.owner}</span
+                >
+              </p>
+            {/if}
+            {#if teamMode}
+              <span
+                class="inline-flex items-center gap-1 text-xs"
+                data-team-status={team}
+                title="Team status: what the last publish recorded (update by republishing)"
+              >
+                <span class="text-base-content/70"
+                  >Team<span class="sr-only">{": "}</span></span
+                >
+                <Icon
+                  name={teamIconName}
+                  size={16}
+                  strokeWidth={2.25}
+                  class={TEAM_ICON_TONE[team]}
+                  aria-hidden="true"
+                />
+                <span class="font-medium text-base-content"
+                  >{TEAM_LABEL[team]}</span
+                >
+              </span>
+              {#if retest}
+                <span
+                  class="badge badge-sm badge-info"
+                  data-retest-chip={row.id}
+                  title={row.retestSince
+                    ? `Fixed since your last verdict (${dateTimeFmt.format(new Date(row.retestSince))}) — test it again`
+                    : "The team marked this ready — test it again"}>Retest</span
+                >
+              {/if}
+            {/if}
+          </div>
+        {/if}
+
+        <!-- Decision line: the current round's verdict (+ note toggle). -->
+        <div
+          class="col-start-2 flex flex-wrap items-center gap-x-3 gap-y-2"
+          data-decision={row.id}
+        >
+          {#if history.length > 0}
+            <span
+              class="text-xs font-medium text-base-content/70"
+              data-current-round={row.id}
+              title={row.retestSince
+                ? `Opened when the team marked it ready (${dateTimeFmt.format(new Date(row.retestSince))})`
+                : undefined}>Round {roundN}</span
+            >
+          {/if}
+          {#if interactive}
+            {#if teamMode}
+              <span class="text-xs text-base-content/70" aria-hidden="true"
+                >You</span
+              >
+            {/if}
+            <VerdictControl
+              options={VERDICT_OPTIONS}
+              value={verdict}
+              onVerdict={(v) => setStatus(row, v)}
+              onUndo={() => undo(row)}
+              label="{teamMode ? 'Your verdict' : 'Verdict'} for {row.title}"
+            />
+            {#if !openNotes[row.id]}
+              <button
+                type="button"
+                class="btn btn-ghost btn-xs gap-1 font-normal text-base-content/70 hover:text-base-content"
+                aria-label="Add a note to {row.title}"
+                aria-keyshortcuts="n"
+                data-add-note={row.id}
+                onclick={() => void toggleNote(row)}
+              >
+                <Icon name="message-square-plus" size={13} aria-hidden="true" />
+                Add note
+              </button>
+            {/if}
+          {:else}
+            <span class="flex items-center gap-1.5">
+              {#if teamMode}
+                <span class="text-xs text-base-content/70" aria-hidden="true"
+                  >You</span
+                >
+              {/if}
+              <span
+                class="badge badge-sm {STATUS_BADGE[vStatus]}"
+                title={teamMode ? "Your saved status" : "Status"}
+              >
+                {#if teamMode}<span class="sr-only">{"Your status: "}</span
+                  >{/if}{LABEL[vStatus]}
+              </span>
+            </span>
+          {/if}
+        </div>
+
+        {#if interactive}
+          <ReviewNote
+            class="checklist-note col-start-2"
+            id={noteInputId(row)}
+            label={history.length > 0 ? `Round ${roundN} note` : "Note"}
+            placeholder={notePlaceholder(vStatus)}
+            bind:open={() => openNotes[row.id] ?? false,
+            (v) => (openNotes[row.id] = v)}
+            value={currentNote(row)}
+            {verdict}
+            options={VERDICT_OPTIONS}
+            round={rowRound(row)}
+            rows={1}
+            onInput={(t) => noteInput(row, t)}
+            onSave={(t) => noteSave(row, t)}
+          />
+        {:else if currentNote(row)}
+          <p
+            class="col-start-2 text-sm whitespace-pre-wrap text-base-content/75"
+          >
+            Note: {currentNote(row)}
+          </p>
+        {/if}
+
+        {#if history.length > 0}
+          <div class="col-start-2" data-round-history={row.id}>
+            <RoundHistory
+              rounds={history}
+              verdicts={VERDICT_OPTIONS}
+              bind:open={() => historyOpen[row.id] ?? false,
+              (v) => (historyOpen[row.id] = v)}
+              bind:selected={() => historySelected[row.id] ?? null,
+              (v) => (historySelected[row.id] = v)}
+              toggleLabel={(n) =>
+                `${n} earlier ${n === 1 ? "round" : "rounds"}`}
+            />
+          </div>
+        {/if}
+      </li>
+    {/snippet}
+    {#each groupedRows as g (g.key)}
+      {#if groupBy === "none"}
+        {#each g.rows as row (row.id)}
+          {@render rowItem(row)}
+        {/each}
+      {:else}
+        <!-- Grouped: one header per non-empty group, count included,
+             collapsible via `hidden` so hidden rows also leave the tab
+             order — keyboard order always matches the visual order. -->
+        <li data-group={g.slug}>
+          <h3 class="m-0">
+            <button
+              type="button"
+              class="flex w-full items-center gap-2 px-4 py-2 text-xs font-semibold text-base-content/70 hover:bg-base-content/5 hover:text-base-content"
+              aria-expanded={!collapsedGroups[g.key]}
+              aria-controls="{groupName}-group-{g.slug}"
+              data-group-toggle={g.slug}
+              onclick={() => toggleGroup(g.key)}
+            >
+              <Icon
+                name="chevron-down"
+                size={14}
+                class="transition-transform {collapsedGroups[g.key]
+                  ? '-rotate-90'
+                  : ''}"
+                aria-hidden="true"
+              />
+              <span>{g.label}</span>
+              <span
+                class="rounded-full bg-base-content/10 px-1.5 py-0.5 text-2xs font-medium tabular-nums"
+                data-group-count={g.slug}
+              >
+                {g.rows.length}
+              </span>
+            </button>
+          </h3>
+          <ul
+            class="divide-y divide-base-content/10"
+            id="{groupName}-group-{g.slug}"
+            hidden={collapsedGroups[g.key]}
+          >
+            {#each g.rows as row (row.id)}
+              {@render rowItem(row)}
+            {/each}
+          </ul>
+        </li>
+      {/if}
+    {/each}
+  </ul>
+
+  {#if interactive}
+    <footer
+      class="flex flex-wrap items-center justify-between gap-2 border-t border-base-content/10 px-4 py-2.5"
+    >
+      <p class="text-xs text-base-content/70">
+        {teamMode
+          ? "Your verdicts are private to you. Team is what the last publish recorded."
+          : "Verdicts and notes save privately for you on this page."}
+        <!-- Keyboard hint hidden on touch-first (coarse pointer) devices. -->
+        <span class="whitespace-nowrap [@media(pointer:coarse)]:hidden"
+          >Keys: <kbd class="kbd kbd-xs">a</kbd> pass,
+          <kbd class="kbd kbd-xs">x</kbd> fail,
+          <kbd class="kbd kbd-xs">b</kbd> blocked,
+          <kbd class="kbd kbd-xs">?</kbd> all shortcuts.</span
+        >
+      </p>
+      <p
+        aria-live="polite"
+        class="text-xs tabular-nums {saveError
+          ? 'text-error'
+          : 'text-base-content/70'}"
+      >
+        {savedLine}
+      </p>
+    </footer>
+  {:else if saved?.at}
+    <footer
+      class="border-t border-base-content/10 px-4 py-2.5 text-xs tabular-nums text-base-content/70"
+    >
+      Last updated {dateTimeFmt.format(new Date(saved.at))}
+    </footer>
+  {/if}
+</section>
+
+{#if helpOpen}
+  <ReviewShortcuts
+    bind:open={helpOpen}
+    config={keyConfig}
+    title="Checklist shortcuts"
+    footnote={interactive ? SHORTCUTS_FOOTNOTE : undefined}
+  />
+{/if}
+
+<style>
+  /* ReviewNote's textarea is DaisyUI .textarea (min-height 5rem): a resting
+     note is ONE line here, grows with its content and scrolls past ~6. */
+  .artifact-checklist :global(.checklist-note textarea) {
+    min-height: 0;
+    max-height: 7.5rem;
+    overflow-y: auto;
+  }
+</style>