@crvouga/atlas 1.20.0 → 1.22.0

package/packages/visualizer/src/critiques/CritiquesPage.tsx

@@ -0,0 +1,402 @@
+/**
+ * @module Needs-polish page
+ *
+ * The opinions of automated reviewers (critics) about the product's captured UI states, ranked so people review the likeliest
+ * problems first. It reads the report the viewer already holds, so a critique appears the moment its layer arrives. A critique is
+ * an opinion and is shown as one: never with a passed or failed mark, never in a test count, and never changing whether anything
+ * passes. A critique that judged an earlier picture is shown as that and is not ranked; a critic that could not judge says why.
+ *
+ * Three readings sit on the same evidence: the findings drawn where they were found on the picture (`FindingOverlay`), whether the
+ * critics agree about the pictures several of them judged (the Agreement view), and what reviewers decided about an opinion (marks:
+ * accepted or dismissed, per finding or for the whole opinion). Marks are made with `atlas critic review`, because a browser's sign-in
+ * box may only look; the viewer reads them and says how to make one.
+ */
+import { markStanding, type AgreementOutcome, type MarkStanding, type Stance } from '@crvouga/atlas/reports/critique-review';
+import type { EntryCritique } from '@crvouga/atlas/reports/ui-catalog-entries';
+import { Accordion, Alert, Anchor, Badge, Button, Code, Container, Drawer, Group, Image, NativeSelect, Stack, Switch, Table, Tabs, Text, Title } from '@mantine/core';
+import { Link } from '@tanstack/react-router';
+import { useMemo, useState } from 'react';
+
+import { reportAssetUrl } from '../evidence/api';
+import { useEvidence } from '../evidence/evidence-context';
+import { ago, exactTime, plural, useNow } from '../evidence/format';
+import { EvidenceIncomplete, EvidenceWaiting } from '../evidence/load-state';
+import { FindingOverlay, SEVERITY_COLOR } from './FindingOverlay';
+import { polishList, type PolishList, type RankedEntry } from './ranking';
+import { useCritiqueNavigate, useCritiqueSearch } from './search';
+
+type Critique = EntryCritique['critique'];
+
+const severityRank = (severity: string | undefined) => (severity === 'major' ? 3 : severity === 'minor' ? 2 : severity === 'info' ? 1 : 0);
+
+function worst(critique: Critique): string | undefined {
+  return [...(critique.findings ?? [])].sort((a, b) => severityRank(b.severity) - severityRank(a.severity))[0]?.severity;
+}
+
+function score(critique: Critique): string {
+  const value = critique.verdict?.score;
+  return value === undefined ? 'No score' : String(Math.round(value * 1000) / 1000);
+}
+
+function standing(critique: Critique): string {
+  const relative = critique.verdict?.relative;
+  if (!relative || relative.percentile === undefined) return 'Not compared';
+  return `${Math.round(relative.percentile)}th percentile among ${plural(relative.sampleSize ?? 0, 'score', 'scores')} of ${relative.stateKind}`;
+}
+
+/** What reviewers decided, as a short word and who. Never a pass or a failure: accepting an opinion says the UI needs polish. */
+const MARK_WORD: Readonly<Record<MarkStanding['state'], string>> = { accepted: 'Accepted', dismissed: 'Dismissed', disputed: 'Reviewers disagree', unmarked: 'Not reviewed' };
+const MARK_COLOR: Readonly<Record<MarkStanding['state'], string>> = { accepted: 'orange', dismissed: 'gray', disputed: 'yellow', unmarked: 'gray' };
+
+/** Who decided what, one line each. */
+function markWho(standing: MarkStanding): string[] {
+  const lines = [];
+  if (standing.accepted.length) lines.push(`Accepted by ${standing.accepted.join(', ')}`);
+  if (standing.dismissed.length) lines.push(`Dismissed by ${standing.dismissed.join(', ')}`);
+  if (standing.earlier) lines.push(`Marks at an earlier picture (${standing.earlier}) count for nothing now`);
+  return lines;
+}
+
+function MarkBadge({ standing }: { standing: MarkStanding }) {
+  const who = markWho(standing);
+  return (
+    <Stack gap={2} align="flex-start">
+      <Badge variant={standing.state === 'unmarked' ? 'outline' : 'light'} color={MARK_COLOR[standing.state]}>{MARK_WORD[standing.state]}</Badge>
+      {who.map((line) => <Text key={line} fz="xs" c="dimmed">{line}</Text>)}
+      {standing.notes.map((note, index) => <Text key={index} fz="xs" c="dimmed">“{note}”</Text>)}
+    </Stack>
+  );
+}
+
+function Label({ critique }: { critique: Critique }) {
+  const label = critique.verdict?.label;
+  return label ? <Badge variant="light" color={label === 'needs-polish' ? 'orange' : 'gray'}>{label}</Badge> : <Text span c="dimmed" fz="sm">No label</Text>;
+}
+
+function Thumb({ item }: { item: RankedEntry }) {
+  return <Image src={reportAssetUrl(item.entry.image.path)} alt={`${item.entry.title}, ${item.entry.profile.label}`} loading="lazy" fit="contain" h={56} w={56} />;
+}
+
+function EntryLink({ item }: { item: RankedEntry }) {
+  return (
+    <Anchor fw={700} aria-label={`Open ${item.entry.title}, ${item.entry.profile.label}`} renderRoot={(props) => <Link {...props} to="/critiques" search={((prev: Record<string, unknown>) => ({ ...prev, entry: item.entry.key })) as never} resetScroll={false} />}>
+      {item.entry.title}
+    </Anchor>
+  );
+}
+
+function regionText(region: NonNullable<Critique['findings']>[number]['region']): string {
+  return region ? `${region.x}, ${region.y} · ${region.w}×${region.h} ${region.unit}` : '';
+}
+
+function Detail({ item, onClose }: { item: RankedEntry; onClose: () => void }) {
+  const now = useNow();
+  const { critique } = item.found;
+  const findings = critique.findings ?? [];
+  const [showFindings, setShowFindings] = useState(true);
+  const [selected, setSelected] = useState<number | null>(null);
+  const placed = findings.some((finding) => finding.region);
+  const whole = markStanding(item.entry.marks, { critic: critique.critic.name });
+  return (
+    <Drawer opened onClose={onClose} position="right" size="xl" title={item.entry.title} closeButtonProps={{ 'aria-label': 'Close the critique' }}>
+      <Stack gap="md">
+        <Text c="dimmed" fz="sm">{item.entry.key} · {item.entry.state}</Text>
+        <FindingOverlay src={reportAssetUrl(item.entry.image.path)} alt={`${item.entry.title}, ${item.entry.profile.label}`} size={item.entry.image} findings={findings} selected={selected} show={showFindings && item.found.currency === 'current'} />
+        {placed && (
+          <Switch checked={showFindings} onChange={(event) => setShowFindings(event.currentTarget.checked)} label="Show findings on the picture" description={item.found.currency === 'current' ? 'Numbered boxes match the findings below. A finding without a region is listed but not drawn.' : 'Not drawn: the picture changed since these findings were made, so their places no longer apply.'} disabled={item.found.currency !== 'current'} />
+        )}
+        {item.found.currency === 'earlier-image' && (
+          <Alert role="status" color="orange" title="This critique judged an earlier picture">
+            The picture of this state has changed since {critique.critic.name} looked at it. Its opinion is shown for reference and does not count as a judgement of what is shown now.
+          </Alert>
+        )}
+        {critique.failure ? (
+          <Alert role="status" color="gray" title="The critic could not judge this picture">
+            Reason: <Code>{critique.failure.reason}</Code>{critique.failure.message ? ` — ${critique.failure.message}` : ''}. The next run tries again. This says nothing about the picture.
+          </Alert>
+        ) : (
+          <Group gap="sm" aria-label="Verdict">
+            <Title order={3}>Opinion</Title>
+            <Badge variant="outline">Score {score(critique)}</Badge>
+            <Label critique={critique} />
+            {critique.verdict?.confidence !== undefined && <Badge variant="outline">Confidence {Math.round(critique.verdict.confidence * 100)}%</Badge>}
+            <Text fz="sm">{standing(critique)}</Text>
+            {critique.verdict?.relative?.delta !== undefined && <Text fz="sm">Change against the previous picture: {critique.verdict.relative.delta > 0 ? '+' : ''}{critique.verdict.relative.delta}</Text>}
+          </Group>
+        )}
+        {!critique.failure && (
+          <Stack gap={4} aria-label="Review of the opinion">
+            <Title order={3}>Review</Title>
+            <MarkBadge standing={whole} />
+            <Text c="dimmed" fz="sm">
+              Accepting says the opinion is right and the UI needs polish; dismissing says it does not. Marks are made on the command line (a browser sign-in only reads):{' '}
+              <Code>atlas critic review --entry {item.entry.key} --critic {critique.critic.name} --accept</Code> or <Code>--dismiss</Code>, with <Code>--finding &lt;id&gt;</Code> for one finding. A mark never changes a result or the gate.
+            </Text>
+          </Stack>
+        )}
+        {findings.length > 0 ? (
+          <Table.ScrollContainer minWidth={420}>
+            <Table aria-label="Findings">
+              <Table.Thead>
+                <Table.Tr>
+                  <Table.Th scope="col">#</Table.Th>
+                  <Table.Th scope="col">Category</Table.Th>
+                  <Table.Th scope="col">Severity</Table.Th>
+                  <Table.Th scope="col">Where</Table.Th>
+                  <Table.Th scope="col">Why</Table.Th>
+                  <Table.Th scope="col">Suggestion</Table.Th>
+                  <Table.Th scope="col">Review</Table.Th>
+                </Table.Tr>
+              </Table.Thead>
+              <Table.Tbody>
+                {findings.map((finding, index) => (
+                  <Table.Tr key={finding.id ?? index} data-finding={finding.id ?? String(index + 1)}>
+                    <Table.Td>
+                      {finding.region && item.found.currency === 'current' && showFindings
+                        ? <Button size="compact-xs" variant={selected === index ? 'filled' : 'subtle'} aria-pressed={selected === index} aria-label={`Locate finding ${index + 1} on the picture`} onClick={() => setSelected(selected === index ? null : index)}>{index + 1}</Button>
+                        : index + 1}
+                    </Table.Td>
+                    <Table.Td>{finding.category ?? 'Uncategorized'}</Table.Td>
+                    <Table.Td><Badge variant="light" color={SEVERITY_COLOR[finding.severity ?? ''] ?? 'gray'}>{finding.severity ?? 'No severity'}</Badge></Table.Td>
+                    <Table.Td>{regionText(finding.region) || <Text span c="dimmed">Whole picture</Text>}</Table.Td>
+                    <Table.Td>{finding.rationale ?? ''}</Table.Td>
+                    <Table.Td>{finding.suggestion ?? ''}</Table.Td>
+                    <Table.Td>{finding.id ? <MarkBadge standing={markStanding(item.entry.marks, { critic: critique.critic.name, finding: finding.id })} /> : <Text span c="dimmed" fz="sm">Cannot be marked alone: it has no id</Text>}</Table.Td>
+                  </Table.Tr>
+                ))}
+              </Table.Tbody>
+            </Table>
+          </Table.ScrollContainer>
+        ) : (
+          !critique.failure && <Text c="dimmed">This critic gives a score and no findings, so it cannot say what to fix.</Text>
+        )}
+        <Accordion variant="contained">
+          <Accordion.Item value="provenance">
+            <Accordion.Control>Where this opinion came from</Accordion.Control>
+            <Accordion.Panel>
+              <Table aria-label="Provenance" withRowBorders>
+                <Table.Tbody>
+                  {([
+                    ['Critic', `${critique.critic.name} ${critique.critic.version}${critique.critic.kind ? ` (${critique.critic.kind})` : ''}`],
+                    ['Model', critique.model ? `${critique.model.id}${critique.model.provider ? `, ${critique.model.provider}` : ''}` : 'None declared'],
+                    ['Parameters', critique.parameters ? JSON.stringify(critique.parameters) : 'None declared'],
+                    ['Picture judged', critique.subject.imageSha256],
+                    ['Layer', `${item.found.layer.slice(0, 12)} (${item.found.producer})`],
+                    ['Recorded', `${ago(item.found.recordedAtMs, now)} (${exactTime(item.found.recordedAtMs)})`],
+                    ['Cost', critique.usage ? [critique.usage.inputTokens === undefined ? '' : `${critique.usage.inputTokens} tokens in`, critique.usage.outputTokens === undefined ? '' : `${critique.usage.outputTokens} out`, critique.usage.latencyMs === undefined ? '' : `${critique.usage.latencyMs} ms`].filter(Boolean).join(', ') || 'Not reported' : 'Not reported']
+                  ] as const).map(([name, value]) => (
+                    <Table.Tr key={name}>
+                      <Table.Th scope="row" w="30%">{name}</Table.Th>
+                      <Table.Td>{value}</Table.Td>
+                    </Table.Tr>
+                  ))}
+                </Table.Tbody>
+              </Table>
+            </Accordion.Panel>
+          </Accordion.Item>
+        </Accordion>
+      </Stack>
+    </Drawer>
+  );
+}
+
+const STANCE_WORDS: Readonly<Record<Stance, string>> = { flags: 'Flags it', clear: 'Does not flag it', 'no-view': 'No view' };
+const STANCE_COLOR: Readonly<Record<Stance, string>> = { flags: 'orange', clear: 'gray', 'no-view': 'gray' };
+const OUTCOME_WORDS: Readonly<Record<AgreementOutcome, string>> = { 'agree-flag': 'All flag it', 'agree-clear': 'None flag it', disagree: 'Critics disagree', unclear: 'Not enough views' };
+
+/** Whether the critics agree about the pictures several of them judged. A reading for people: not a verdict, a status or a gate. */
+function AgreementPanel({ list }: { list: PolishList }) {
+  const { agreement } = list;
+  if (agreement.critics.length < 2 || agreement.rows.length === 0) {
+    return (
+      <Text c="dimmed" role="status" component="div" data-empty>
+        {agreement.critics.length < 2
+          ? 'Agreement needs two critics to have judged the same picture. Run another critic against this server (atlas critic run --critic <name> --all) and compare them here.'
+          : `No picture has been judged by more than one critic yet${list.kinds.length > 1 ? ' in this state kind' : ''}.`}
+      </Text>
+    );
+  }
+  return (
+    <Stack gap="md">
+      <Text c="dimmed" fz="sm">
+        Only each critic’s opinion of the picture an entry has now is compared. A critic flags a UI when its label says needs-polish, when it has findings, or, with neither, when its score is in the lowest quarter of its state kind; a bare score with no standing, or a critic that failed, gives no view and never makes critics agree. Entries every critic flags come first, then those they disagree about.
+        {agreement.single > 0 ? ` ${plural(agreement.single, 'state has', 'states have')} been judged by only one critic and ${agreement.single === 1 ? 'is' : 'are'} not shown.` : ''}
+      </Text>
+      <Table.ScrollContainer minWidth={560}>
+        <Table aria-label="Critics compared, those that all flag a state first" striped>
+          <Table.Thead>
+            <Table.Tr>
+              <Table.Th scope="col">State</Table.Th>
+              <Table.Th scope="col">Kind</Table.Th>
+              {agreement.critics.map((critic) => <Table.Th key={critic} scope="col">{critic}</Table.Th>)}
+              <Table.Th scope="col">Agreement</Table.Th>
+            </Table.Tr>
+          </Table.Thead>
+          <Table.Tbody>
+            {agreement.rows.map((row) => (
+              <Table.Tr key={row.entry.key} data-entry={row.entry.key} data-outcome={row.outcome}>
+                <Table.Td><Stack gap={2}><Text fw={700}>{row.entry.title}</Text><Text c="dimmed" fz="xs">{row.entry.profile.label}</Text></Stack></Table.Td>
+                <Table.Td>{row.entry.state}</Table.Td>
+                {agreement.critics.map((critic) => {
+                  const view = row.views.find((candidate) => candidate.critic === critic);
+                  if (!view) return <Table.Td key={critic}><Text c="dimmed" fz="sm">Not judged at this picture</Text></Table.Td>;
+                  return (
+                    <Table.Td key={critic}>
+                      <Stack gap={2} align="flex-start">
+                        <Badge variant="light" color={STANCE_COLOR[view.stance]}>{STANCE_WORDS[view.stance]}</Badge>
+                        <Anchor fz="sm" aria-label={`Open ${critic}’s critique of ${row.entry.title}, ${row.entry.profile.label}`} renderRoot={(props) => <Link {...props} to="/critiques" search={((prev: Record<string, unknown>) => ({ ...prev, critic, entry: row.entry.key })) as never} resetScroll={false} />}>
+                          {view.score === undefined ? 'No score' : `Score ${Math.round(view.score * 1000) / 1000}`}{view.percentile === undefined ? '' : `, ${Math.round(view.percentile)}th percentile`}
+                        </Anchor>
+                      </Stack>
+                    </Table.Td>
+                  );
+                })}
+                <Table.Td><Badge variant={row.outcome === 'agree-flag' ? 'filled' : 'outline'} color={row.outcome === 'disagree' ? 'yellow' : row.outcome === 'agree-flag' ? 'orange' : 'gray'}>{OUTCOME_WORDS[row.outcome]}</Badge></Table.Td>
+              </Table.Tr>
+            ))}
+          </Table.Tbody>
+        </Table>
+      </Table.ScrollContainer>
+    </Stack>
+  );
+}
+
+/** The `/critiques` route. */
+export function CritiquesPage() {
+  const evidence = useEvidence();
+  const search = useCritiqueSearch();
+  const go = useCritiqueNavigate();
+  const list = useMemo(() => polishList(evidence.evidence, search), [evidence.evidence, search]);
+  const unavailable = evidence.backends.filter((backend) => !backend.available);
+  const all = [...list.ranked, ...list.unranked];
+  const view = search.view === 'agreement' ? 'agreement' : 'ranked';
+  const open = search.entry ? all.find((item) => item.entry.key === search.entry) ?? null : null;
+  return (
+    <Container size="xl" w="100%" py="xl" component="article" aria-label="Needs polish">
+      <Stack gap="md">
+        <Stack gap={4}>
+          <Title order={1}>Needs polish</Title>
+          <Text c="dimmed">
+            What automated reviewers think of the captured UI states, lowest first, so the likeliest problems are reviewed first. These are opinions: they are not test results, are never counted with them, and never change whether a report passes.
+          </Text>
+        </Stack>
+        {evidence.unavailable && <Alert role="alert" color="red" title="Recorded results cannot be read">{evidence.unavailable}</Alert>}
+        {unavailable.length > 0 && (
+          <Alert role="status" color="orange" title={`${plural(unavailable.length, 'backend is', 'backends are')} not available`}>
+            {unavailable.map((backend) => backend.label).join(', ')}: critiques held there are not shown. This list may be incomplete.
+          </Alert>
+        )}
+        <EvidenceIncomplete />
+        {!evidence.ready && !evidence.unavailable && <EvidenceWaiting label="Reading the recorded critiques…" />}
+        {evidence.ready && list.critics.length === 0 && (
+          <Text c="dimmed" role="status" component="div" data-empty>
+            No critic has judged a captured UI state yet. Run <Code>atlas critic run --critic &lt;name&gt; --all</Code> against this server; critiques appear here the moment they arrive.
+            {list.unjudgeable > 0 ? ` ${plural(list.unjudgeable, 'captured state has', 'captured states have')} no stored picture, so a critic cannot see ${list.unjudgeable === 1 ? 'it' : 'them'}.` : ''}
+          </Text>
+        )}
+        {list.critic && (
+          <>
+            <Group align="flex-end" gap="md">
+              {view === 'ranked' && <NativeSelect label="Critic" description="Scores are ranked within one critic" value={list.critic} data={list.critics.map((critic) => ({ value: critic.name, label: `${critic.name} (${critic.critiques})` }))} onChange={(event) => go({ critic: event.currentTarget.value })} />}
+              <NativeSelect label="State kind" value={search.kind ?? ''} data={[{ value: '', label: 'All kinds' }, ...list.kinds.map((kind) => ({ value: kind, label: kind }))]} onChange={(event) => go({ kind: event.currentTarget.value || undefined })} />
+            </Group>
+            <Tabs value={view} onChange={(next) => go({ view: next === 'agreement' ? 'agreement' : undefined })} keepMounted={false}>
+              <Tabs.List>
+                <Tabs.Tab value="ranked">Ranked</Tabs.Tab>
+                <Tabs.Tab value="agreement">Agreement across critics</Tabs.Tab>
+              </Tabs.List>
+              <Tabs.Panel value="agreement" pt="md"><AgreementPanel list={list} /></Tabs.Panel>
+              <Tabs.Panel value="ranked" pt="md">
+            <Stack gap="md">
+            <Group gap="xs" role="status" aria-label="Critique summary">
+              <Badge variant="light">{plural(list.ranked.length, 'state judged', 'states judged')}</Badge>
+              {list.unranked.length > 0 && <Badge variant="outline">{list.unranked.length} not judged at the current picture</Badge>}
+              {list.unjudged > 0 && <Badge variant="outline">{list.unjudged} not judged yet</Badge>}
+            </Group>
+            {list.ranked.length > 0 ? (
+              <Table.ScrollContainer minWidth={640}>
+                <Table aria-label="States ranked by score, lowest first" striped>
+                  <Table.Thead>
+                    <Table.Tr>
+                      <Table.Th scope="col">Rank</Table.Th>
+                      <Table.Th scope="col">Picture</Table.Th>
+                      <Table.Th scope="col">State</Table.Th>
+                      <Table.Th scope="col">Kind</Table.Th>
+                      <Table.Th scope="col">Score</Table.Th>
+                      <Table.Th scope="col">Within its kind</Table.Th>
+                      <Table.Th scope="col">Findings</Table.Th>
+                      <Table.Th scope="col">Review</Table.Th>
+                    </Table.Tr>
+                  </Table.Thead>
+                  <Table.Tbody>
+                    {list.ranked.map((item, index) => {
+                      const severity = worst(item.found.critique);
+                      return (
+                        <Table.Tr key={item.entry.key} data-entry={item.entry.key}>
+                          <Table.Td>{index + 1}</Table.Td>
+                          <Table.Td><Thumb item={item} /></Table.Td>
+                          <Table.Td><Stack gap={2}><EntryLink item={item} /><Text c="dimmed" fz="xs">{item.entry.profile.label}</Text></Stack></Table.Td>
+                          <Table.Td>{item.entry.state}</Table.Td>
+                          <Table.Td><Group gap="xs" wrap="nowrap"><Text span>{score(item.found.critique)}</Text><Label critique={item.found.critique} /></Group></Table.Td>
+                          <Table.Td>{standing(item.found.critique)}</Table.Td>
+                          <Table.Td>
+                            {(item.found.critique.findings ?? []).length > 0 ? (
+                              <Group gap="xs" wrap="nowrap">
+                                <Text span>{plural((item.found.critique.findings ?? []).length, 'finding', 'findings')}</Text>
+                                {severity && <Badge variant="light" color={SEVERITY_COLOR[severity] ?? 'gray'}>{severity}</Badge>}
+                              </Group>
+                            ) : <Text span c="dimmed">None given</Text>}
+                          </Table.Td>
+                          <Table.Td><MarkBadge standing={markStanding(item.entry.marks, { critic: item.found.critique.critic.name })} /></Table.Td>
+                        </Table.Tr>
+                      );
+                    })}
+                  </Table.Tbody>
+                </Table>
+              </Table.ScrollContainer>
+            ) : (
+              <Text c="dimmed" role="status" component="div">{list.critic} has not produced a score for any state in view.</Text>
+            )}
+            {list.unranked.length > 0 && (
+              <Stack gap="xs">
+                <Title order={2}>Not judged at the current picture</Title>
+                <Table.ScrollContainer minWidth={420}>
+                  <Table aria-label="States not judged at the current picture">
+                    <Table.Thead>
+                      <Table.Tr>
+                        <Table.Th scope="col">State</Table.Th>
+                        <Table.Th scope="col">Why</Table.Th>
+                      </Table.Tr>
+                    </Table.Thead>
+                    <Table.Tbody>
+                      {list.unranked.map((item) => (
+                        <Table.Tr key={item.entry.key} data-entry={item.entry.key}>
+                          <Table.Td><Stack gap={2}><EntryLink item={item} /><Text c="dimmed" fz="xs">{item.entry.profile.label}</Text></Stack></Table.Td>
+                          <Table.Td>
+                            {item.found.critique.failure
+                              ? `The critic could not judge it (${item.found.critique.failure.reason}); the next run tries again`
+                              : 'The picture changed since it was judged; the older opinion is kept for reference'}
+                          </Table.Td>
+                        </Table.Tr>
+                      ))}
+                    </Table.Tbody>
+                  </Table>
+                </Table.ScrollContainer>
+              </Stack>
+            )}
+            </Stack>
+              </Tabs.Panel>
+            </Tabs>
+          </>
+        )}
+        {search.entry && !open && evidence.ready && evidence.pending === 0 && (
+          <Alert role="status" color="gray" title="That entry has no critique in this view">
+            <Text span inherit>{search.entry}</Text> is not among the states this critic has judged or tried to judge.{' '}
+            <Anchor renderRoot={(props) => <Link {...props} to="/critiques" search={((prev: Record<string, unknown>) => ({ ...prev, entry: undefined })) as never} />}>Back to the list</Anchor>
+          </Alert>
+        )}
+      </Stack>
+      {open && <Detail item={open} onClose={() => go({ entry: undefined })} />}
+    </Container>
+  );
+}

package/packages/visualizer/src/critiques/FindingOverlay.tsx

@@ -0,0 +1,50 @@
+/**
+ * @module Finding overlays
+ *
+ * A critic's findings drawn where they were found, on the picture they are about. A finding's region is in the unit the critic stated:
+ * `normalized` (0..1 of the picture) or `px` (pixels of the stored picture, which needs the picture's size, taken from the catalog
+ * or from the loaded image). A region in any other unit cannot be placed and is not drawn; the findings table still says where in
+ * words. Every box carries the finding's number, so it is never told apart by color alone, and the picture keeps its own alternative text.
+ * An overlay is an opinion drawn over evidence: it changes nothing about the picture and is never a result.
+ */
+import type { EntryCritique } from '@crvouga/atlas/reports/ui-catalog-entries';
+import { Badge, Box, Image } from '@mantine/core';
+import { useState } from 'react';
+
+type CritiqueFinding = NonNullable<EntryCritique['critique']['findings']>[number];
+
+/** The color of a severity, as the table shows it. Unknown severities are gray. */
+export const SEVERITY_COLOR: Readonly<Record<string, string>> = { major: 'red', minor: 'yellow', info: 'blue' };
+
+/** A region as percentages of the picture, or `null` when it cannot be placed (an unknown unit, no known size for pixels, or not finite numbers). */
+export function regionBox(region: NonNullable<CritiqueFinding['region']>, size: { readonly width: number; readonly height: number } | null): { left: number; top: number; width: number; height: number } | null {
+  const [fx, fy] = region.unit === 'normalized' ? [1, 1] : region.unit === 'px' && size ? [size.width, size.height] : [0, 0];
+  if (!fx || !fy || ![region.x, region.y, region.w, region.h].every(Number.isFinite)) return null;
+  const clamp = (value: number) => Math.min(100, Math.max(0, value));
+  const left = clamp((region.x / fx) * 100), top = clamp((region.y / fy) * 100);
+  return { left, top, width: Math.min(100 - left, clamp((region.w / fx) * 100)), height: Math.min(100 - top, clamp((region.h / fy) * 100)) };
+}
+
+/** The picture with a numbered box for each finding that has a region. `selected` (an index into `findings`) is drawn thicker. */
+export function FindingOverlay({ src, alt, size, findings, selected, show }: {
+  src: string; alt: string; size?: { width?: number | undefined; height?: number | undefined };
+  findings: readonly CritiqueFinding[]; selected: number | null; show: boolean;
+}) {
+  const [natural, setNatural] = useState<{ width: number; height: number } | null>(null);
+  const known = size?.width && size.height ? { width: size.width, height: size.height } : natural;
+  return (
+    <Box pos="relative" w="fit-content" maw="100%">
+      <Image src={src} alt={alt} loading="lazy" fit="contain" onLoad={(event) => { const img = event.currentTarget; if (img.naturalWidth && img.naturalHeight) setNatural({ width: img.naturalWidth, height: img.naturalHeight }); }} />
+      {show && findings.map((finding, index) => {
+        const box = finding.region ? regionBox(finding.region, known) : null;
+        if (!box) return null;
+        const color = SEVERITY_COLOR[finding.severity ?? ''] ?? 'gray';
+        return (
+          <Box key={finding.id ?? index} data-finding={finding.id ?? String(index + 1)} aria-hidden pos="absolute" left={`${box.left}%`} top={`${box.top}%`} w={`${box.width}%`} h={`${box.height}%`} data-selected={selected === index} bd={`${selected === index ? 4 : 2}px solid ${color}.7`}>
+            <Badge circle size="sm" color={color} variant="filled">{index + 1}</Badge>
+          </Box>
+        );
+      })}
+    </Box>
+  );
+}

package/packages/visualizer/src/critiques/ranking.ts

@@ -0,0 +1,54 @@
+/**
+ * @module Needs-polish ranking
+ *
+ * Reads the critiques the viewer holds into a ranked list for one critic. A critique is an opinion, never a result: nothing
+ * here counts toward a test total or changes a status. The list ranks the entries a critic judged at their current picture, lowest
+ * first (a score is read as higher-is-better, which is the convention of the critique format); when every ranked score also
+ * carries its standing among the scores of the same state kind (`relative.percentile`), that standing ranks them instead, because a
+ * loading overlay is not compared with a full screen. An entry whose picture changed since it was judged, or whose critic
+ * could not judge it, is listed apart and is never ranked, and an entry the critic never saw is only counted.
+ */
+import { critiqueAgreement, rankCritiques, type CritiqueAgreement, type RankedEntry } from '@crvouga/atlas/reports/critique-review';
+import { catalogEntries, type CatalogEntry } from '@crvouga/atlas/reports/ui-catalog-entries';
+import type { LayerEvidence } from '@crvouga/atlas/reports/evidence-types';
+
+export type { RankedEntry } from '@crvouga/atlas/reports/critique-review';
+
+/** What the page shows for one critic and (optionally) one kind of UI state. */
+export type PolishList = {
+  /** Critics that have a critique of any entry, most critiques first. */
+  readonly critics: readonly { readonly name: string; readonly critiques: number }[];
+  /** The critic whose scores rank the list; null when no critic has judged anything. */
+  readonly critic: string | null;
+  /** The state kinds of the entries that are in scope, for the filter. */
+  readonly kinds: readonly string[];
+  /** Entries judged at their current picture with a verdict, lowest first. */
+  readonly ranked: readonly RankedEntry[];
+  /** How the list was ranked: by standing within the state kind, or by raw score. */
+  readonly rankedBy: 'standing-within-kind' | 'score';
+  /** Entries whose newest critique judged an earlier picture, or could not judge: not ranked. */
+  readonly unranked: readonly RankedEntry[];
+  /** Entries in scope the critic has not judged at all. */
+  readonly unjudged: number;
+  /** Captured states that are not entries because no stored picture backs them. */
+  readonly unjudgeable: number;
+  /** Every captured state with a stored picture, for the readings that look across critics. */
+  readonly entries: readonly CatalogEntry[];
+  /** Whether the critics agree on the pictures two or more of them judged (state kind applied). */
+  readonly agreement: CritiqueAgreement;
+};
+
+/**
+ * The list for a critic and state kind over the layers the viewer holds. With no `critic` the one with most critiques is used.
+ */
+export function polishList(layers: readonly LayerEvidence[], choice: { readonly critic?: string | undefined; readonly kind?: string | undefined } = {}): PolishList {
+  const { entries, unjudgeable } = catalogEntries(layers);
+  const tally = new Map<string, number>();
+  for (const entry of entries) for (const found of entry.critiques) tally.set(found.critique.critic.name, (tally.get(found.critique.critic.name) ?? 0) + 1);
+  const critics = [...tally].map(([name, critiques]) => ({ name, critiques })).sort((a, b) => b.critiques - a.critiques || (a.name < b.name ? -1 : 1));
+  const critic = choice.critic && tally.has(choice.critic) ? choice.critic : critics[0]?.name ?? null;
+  const kinds = [...new Set(entries.map((entry) => entry.state))].sort();
+  const { ranked, rankedBy, unranked, unjudged } = rankCritiques(entries, critic, choice.kind);
+  const agreement = critiqueAgreement(entries, choice.kind);
+  return { critics, critic, kinds, ranked, rankedBy, unranked, unjudged, unjudgeable, entries, agreement };
+}

package/packages/visualizer/src/critiques/search.ts

@@ -0,0 +1,41 @@
+/**
+ * @module Needs-polish address
+ *
+ * What the needs-polish page shows is in the address of the `/critiques` route, so a link reproduces the view: the critic whose
+ * scores rank the list, the kind of UI state, and the entry opened. Anything unreadable is dropped, never an error.
+ */
+import { useNavigate, useSearch } from '@tanstack/react-router';
+import { useMemo } from 'react';
+import { z } from 'zod/v4';
+
+const text = z
+  .preprocess((value) => (typeof value === 'number' || typeof value === 'boolean' ? String(value) : value), z.string().min(1))
+  .optional()
+  .catch(undefined);
+
+/** The `/critiques` route's search: the critic, the state kind, the open entry (an entry key) and the view (`ranked` or `agreement`). */
+export const CritiqueSearchFields = { critic: text, kind: text, entry: text, view: text };
+
+/** The address's parts, as the router holds them. */
+export type CritiqueSearch = { readonly [K in keyof typeof CritiqueSearchFields]?: string | undefined };
+
+/** The needs-polish parameters, read from the address. */
+export function useCritiqueSearch(): CritiqueSearch {
+  const raw = useSearch({ strict: false }) as Record<string, unknown>;
+  return useMemo(() => {
+    const search: Record<string, string> = {};
+    for (const name of Object.keys(CritiqueSearchFields)) {
+      const value = raw[name];
+      if (typeof value === 'string' && value) search[name] = value;
+      else if (typeof value === 'number') search[name] = String(value);
+    }
+    return search;
+  }, [raw]);
+}
+
+/** Returns `go(patch)`, which moves the page to the address with `patch` applied (fields set to undefined are removed). */
+export function useCritiqueNavigate() {
+  const navigate = useNavigate();
+  return (patch: CritiqueSearch, options: { replace?: boolean } = {}) =>
+    void navigate({ to: '/critiques', search: ((prev: Record<string, unknown>) => ({ ...prev, ...patch })) as never, replace: options.replace ?? false, resetScroll: false });
+}

package/packages/visualizer/src/evidence/applicability-view.tsx

@@ -21,13 +21,16 @@ export type ApplicabilityState = {
   readonly setOnlyStale: (on: boolean) => void;
 };
 
+/** The address fields the release and the evidence filter are held in, shared by the spec route and the behaviors route. */
+type ReleaseAddress = { release?: string; releaseSha?: string; releasePlatform?: string; evidence?: 'stale' };
+
 /**
- * The release (`release` build, `releaseSha`, `releasePlatform`) and evidence filter (`evidence=stale`) of the spec
- * address. They are held in the address, so a shared link shows the same reading. Must be used under the spec route.
+ * The release (`release` build, `releaseSha`, `releasePlatform`) and evidence filter (`evidence=stale`) of the address of a
+ * spec page or of the behaviors page. They are held in the address, so a shared link shows the same reading.
  */
 export function useApplicabilityState(): ApplicabilityState {
-  const search = useSearch({ from: '/specs/$kind' });
-  const navigate = useNavigate({ from: '/specs/$kind' });
+  const search = useSearch({ strict: false }) as ReleaseAddress;
+  const navigate = useNavigate();
   const release = useMemo<ReleaseIdentity>(
     () => ({
       ...(search.release ? { build: search.release } : {}),
@@ -39,18 +42,19 @@ export function useApplicabilityState(): ApplicabilityState {
   const setRelease = useCallback(
     (next: ReleaseIdentity) =>
       void navigate({
-        search: (prev) => ({
+        to: '.',
+        search: ((prev: Record<string, unknown>) => ({
           ...prev,
           release: next.build || undefined,
           releaseSha: next.sha || undefined,
           releasePlatform: next.platform || undefined
-        }),
+        })) as never,
         replace: true
       }),
     [navigate]
   );
   const setOnlyStale = useCallback(
-    (on: boolean) => void navigate({ search: (prev) => ({ ...prev, evidence: on ? ('stale' as const) : undefined }), replace: true }),
+    (on: boolean) => void navigate({ to: '.', search: ((prev: Record<string, unknown>) => ({ ...prev, evidence: on ? 'stale' : undefined })) as never, replace: true }),
     [navigate]
   );
   return { release, onlyStale: search.evidence === 'stale', setRelease, setOnlyStale };