diff --git a/app/globals.css b/app/globals.css
index 560de628..d6c55847 100644
--- a/app/globals.css
+++ b/app/globals.css
@@ -1237,14 +1237,6 @@ details.cohortpick .gearmenu-items { min-width: 22rem; max-width: 30rem; gap: 0;
 
 /* a plot's axis controls: source, then whatever that source needs */
 .axispick { display: inline-flex; align-items: center; gap: var(--s1); }
-/* a plot's highlight cohorts: one chip each, in the figure's colour for it */
-.hlpick { display: inline-flex; align-items: center; gap: var(--s1); flex-wrap: wrap; min-width: 0; }
-.hlchip {
-  display: inline-flex; align-items: center; gap: 4px; height: var(--ctl-h); padding: 0 2px 0 var(--s1);
-  border: 1px solid var(--line); border-radius: var(--r-sm); background: var(--paper); font-size: var(--t-sm); color: var(--ink);
-}
-.hldot { width: 9px; height: 9px; border-radius: 50%; flex: none; }
-.hlname { max-width: 9rem; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
 
 /* a server-rendered figure inside a view card: it takes the card's width, and scrolls
    sideways only if it truly cannot fit */
diff --git a/app/lab/explore-charts.tsx b/app/lab/explore-charts.tsx
index 921f0094..f851efab 100644
--- a/app/lab/explore-charts.tsx
+++ b/app/lab/explore-charts.tsx
@@ -47,7 +47,7 @@ export function ExploreCharts({ studies, draft, attrs, endpoints, addClauses, km
     const cohort: CohortDef = { ...(studies.length > 1 ? { studies } : {}), all: (draft ? draft.all : []) as CohortDef["all"] };
     const views: View[] = [];
     if (ep) views.push({ kind: "survival", endpoint: ep });
-    if (hasScatter) views.push({ kind: "plot", unit: "sample", x: { source: "clinical", attribute: X_ATTR, log: true }, y: { source: "clinical", attribute: Y_ATTR }, bins: [48, 32] });
+    if (hasScatter) views.push({ kind: "plot", unit: "sample", x: { source: "clinical", attribute: X_ATTR, log: true }, y: { source: "clinical", attribute: Y_ATTR }, bins: [48, 32], allPoints: false, points: [] });
     // a superseded request is cancelled, so the server stops its queries instead of finishing them
     const ac = new AbortController();
     api.analysis({ study: studies[0], cohorts: { Selected: cohort }, views }, { signal: ac.signal })
diff --git a/app/lab/plot-controls.tsx b/app/lab/plot-controls.tsx
index 6843214f..ec47ec66 100644
--- a/app/lab/plot-controls.tsx
+++ b/app/lab/plot-controls.tsx
@@ -1,13 +1,19 @@
 "use client";
-// The plot view's settings bar, shared by the lab's plot card and the portal pages' Plots tab:
-// both axes (with a log scale for a numeric one), a box plot's colour and ring, the highlighted
-// cohorts, the unit and the axis swap. Every control is an edit to the view, handed to `update`.
-import { ArrowLeftRight } from "lucide-react";
-import { AxisPicker, HighlightPicker } from "./view-chrome.tsx";
+// The plot view laid out as cBioPortal's Plots tab is, shared by the lab's plot card and the portal
+// pages' Plots tab: each axis defined in its own block in a sidebar (horizontal above vertical, a swap
+// between them, the unit and the point layers below), and beside it a line saying how many cases are shown,
+// a box plot's colour and ring, and the figure. Under a narrow card the sidebar sits above the figure.
+// Every control is an edit to the view, handed to `update`.
+import { useEffect, useState } from "react";
+import { ArrowDown, ArrowUp, X } from "lucide-react";
+import { AxisPicker } from "./view-chrome.tsx";
 import { Button } from "../_ui/button";
 import { Checkbox } from "../_ui/checkbox";
-import { Choice } from "../_ui/choice.tsx";
-import { TB } from "../_ui/toolbar.ts";
+import { Choice, OptionSelect } from "../_ui/choice.tsx";
+import { Input } from "../_ui/input";
+import { cn } from "../../lib/cn";
+import { FIELD } from "../_ui/toolbar.ts";
+import { DEFAULT_POINT_LAYERS, POINTS_CAP, LAYER_COLORS, POINT_LAYER_CAP, POINT_RULE_N, POINT_RULE_N_MAX, layerLabel, type PointLayerSpec } from "../../lib/plot-layers.ts";
 
 type Update = (fn: (view: any) => any) => void;
 
@@ -15,68 +21,182 @@ function LogToggle({ spec, side, numeric, busy, update }: { spec: any; side: "x"
   const axis = spec[side];
   if (!numeric || !axis || !("source" in axis) || (axis.source !== "clinical" && axis.source !== "molecular")) return null;
   return (
-    <label className="chk" title={"draw " + side + " on a log scale — log10(value + 1), so zero stays on the axis and a negative value is left out"}>
+    <label className="chk text-md text-foreground" title="draw this axis on a log scale — log10(value + 1), so zero stays on the axis and a negative value is left out">
       <Checkbox checked={!!axis.log} disabled={busy}
         onCheckedChange={(c) => update((vv) => {
           const a = { ...vv[side] };
           if (c === true) a.log = true; else delete a.log;
           return { ...vv, [side]: a };
         })} />
-      log
+      Log scale
     </label>
   );
 }
 
-export function PlotControls({ spec, plot, attrs, profiles, loading, busy, highlightOptions, update }: {
+/** one axis's definition in the sidebar: its name down the side, its fields stacked beside it */
+function AxisBlock({ title, children }: { title: string; children: React.ReactNode }) {
+  return (
+    <section className="plot-axis flex gap-1.5 rounded-md bg-muted py-2.5 pr-2.5 pl-1" aria-label={title}>
+      <h3 className="m-0 rotate-180 text-center text-md font-normal text-primary [writing-mode:vertical-lr]">{title}</h3>
+      <div className="flex min-w-0 flex-1 flex-col gap-2.5">{children}</div>
+    </section>
+  );
+}
+
+/** a ranked layer's count, typed in its chip and handed on when the field is left or Enter pressed */
+function LayerCount({ n, busy, onCommit }: { n: number; busy: boolean; onCommit: (n: number) => void }) {
+  const [draft, setDraft] = useState(String(n));
+  useEffect(() => setDraft(String(n)), [n]);
+  const commit = () => {
+    const v = Math.round(Number(draft));
+    if (Number.isFinite(v) && v >= 1 && v <= POINT_RULE_N_MAX && v !== n) onCommit(v); else setDraft(String(n));
+  };
+  return <Input className={cn(FIELD, "h-6 w-12 px-1 text-sm")} value={draft} disabled={busy} inputMode="numeric"
+    aria-label="how many cases" title={"how many cases (1–" + POINT_RULE_N_MAX + ")"}
+    onChange={(e) => setDraft(e.target.value.replace(/[^0-9]/g, ""))} onBlur={commit} onKeyDown={(e) => { if (e.key === "Enter") commit(); }} />;
+}
+
+/**
+ * The view's point layers: subsets of the plotted cohort drawn in colour over it, one chip per
+ * layer in the figure's colour for it, in order (the first layer draws a case two layers share),
+ * and a menu offering the rules and cohorts not yet chosen, up to the cap.
+ */
+function PointLayers({ layers, plot, cohortOptions, axisName, busy, onChange }: {
+  layers: PointLayerSpec[];
+  plot?: { shape: string; x: { kind: string }; y: { kind: string } };
+  cohortOptions: { name: string; label: string; depth: number }[];
+  axisName: (side: "x" | "y") => string;
+  busy: boolean;
+  onChange: (next: PointLayerSpec[]) => void;
+}) {
+  const has = (f: (l: PointLayerSpec) => boolean) => layers.some(f);
+  const offers: [string, string, PointLayerSpec][] = [];
+  if (!has((l) => "rule" in l && l.rule === "outliers")) offers.push(["outliers", "outliers (past 5,000 cases)", { rule: "outliers" }]);
+  for (const side of ["x", "y"] as const)
+    if (plot?.[side].kind === "num" && !has((l) => "rule" in l && l.rule === "extremes" && l.axis === side))
+      offers.push(["extremes:" + side, "top and bottom " + POINT_RULE_N + " by " + axisName(side), { rule: "extremes", axis: side }]);
+  if (plot?.shape === "scatter" && !has((l) => "rule" in l && l.rule === "trend"))
+    offers.push(["trend", POINT_RULE_N + " furthest from the fit", { rule: "trend" }]);
+  for (const o of cohortOptions)
+    if (!has((l) => "cohort" in l && l.cohort === o.name)) offers.push(["cohort:" + o.name, "\u00a0".repeat(o.depth * 2) + o.label, { cohort: o.name }]);
+  const full = layers.length >= POINT_LAYER_CAP;
+  const move = (i: number) => { const next = [...layers]; [next[i - 1], next[i]] = [next[i], next[i - 1]]; onChange(next); };
+  return (
+    <div className="plot-layers flex flex-col gap-1">
+      {layers.map((l, i) => (
+        <div key={i} className="plot-layer flex min-h-ctl items-center gap-1 rounded-sm border bg-card py-0.5 pr-0.5 pl-1.5 text-sm"
+          title={i ? "drawn under the layers above it: a case they share is theirs" : "drawn first: a case it shares with a later layer is its own"}>
+          <span className="size-2.5 flex-none rounded-full" style={{ background: LAYER_COLORS[i] }} />
+          <span className="min-w-0 flex-1 truncate" title={"cohort" in l ? l.cohort : layerLabel(l, axisName)}>{"cohort" in l ? l.cohort : layerLabel(l, axisName)}</span>
+          {"rule" in l && l.rule !== "outliers" && (
+            <LayerCount n={l.n ?? POINT_RULE_N} busy={busy} onCommit={(n) => onChange(layers.map((x, j) => j === i ? { ...x, n } as PointLayerSpec : x))} />
+          )}
+          {i > 0 && <Button type="button" variant="ghost" size="icon-xs" className="size-5 text-muted-foreground" disabled={busy}
+            aria-label="draw this layer before the one above it" title="draw this layer before the one above it" onClick={() => move(i)}><ArrowUp /></Button>}
+          <Button type="button" variant="ghost" size="icon-xs" className="size-5 text-muted-foreground" disabled={busy}
+            aria-label={"remove the layer " + ("cohort" in l ? l.cohort : layerLabel(l, axisName))} title="remove this layer"
+            onClick={() => onChange(layers.filter((_, j) => j !== i))}><X /></Button>
+        </div>
+      ))}
+      {!layers.length && <p className="m-0 text-sm text-muted-foreground">none: the plotted cohort alone</p>}
+      <OptionSelect className="w-full max-w-none" value="" disabled={busy || full || !offers.length} ariaLabel="add a point layer"
+        title={full ? "a plot draws at most " + POINT_LAYER_CAP + " point layers; remove one to add another"
+          : !offers.length ? "every rule and cohort this plot can draw is already a layer" : "add a subset to draw in its own colour"}
+        onValueChange={(v) => { const o = offers.find((x) => x[0] === v); if (o) onChange([...layers, o[2]]); }}>
+        <option value="">+ add a layer</option>
+        {offers.map(([value, label]) => <option key={value} value={value}>{label}</option>)}
+      </OptionSelect>
+    </div>
+  );
+}
+
+export function PlotControls({ spec, plot, attrs, profiles, loading, busy, cohortOptions, update, children }: {
   /** the view as the document holds it */
   spec: any;
-  /** the last result's plot, for which shape is on screen */
-  plot?: { shape: string; x: { kind: string }; y: { kind: string } };
+  /** the last result's plot: which shape is on screen, each axis's name and kind, how many cases it shows */
+  plot?: { shape: string; n: number; x: { kind: string; label: string }; y: { kind: string; label: string }; coverage?: { total: number } };
   attrs: { attribute: string; kind: string }[]; profiles: string[]; loading?: boolean; busy: boolean;
-  /** the cohorts that may be highlighted: every one but the plotted one and a split */
-  highlightOptions: { name: string; label: string; depth: number }[];
+  /** the cohorts a point layer may be: every one but the plotted one and a split */
+  cohortOptions: { name: string; label: string; depth: number }[];
   update: Update;
+  /** the figure, and whatever the page covers it with while it waits */
+  children: React.ReactNode;
 }) {
-  const chosen: string[] = Array.isArray(spec.highlight) ? spec.highlight : [];
-  // Every control here changes what is DRAWN and costs a query, so there is one zone and it says
-  // so — the same toolbar the oncoprint uses.
+  const layers: PointLayerSpec[] = Array.isArray(spec.points) ? spec.points : DEFAULT_POINT_LAYERS;
+  const axisName = (side: "x" | "y") => plot?.[side].label || side;
+  const unit = spec.unit || "sample";
+  // A box is drawn with its categories across, whichever axis the document holds them on, so a
+  // box whose categories sit on y shows its "vertical" axis across. Swapping makes the two agree.
+  const boxTransposed = plot?.shape === "box" && plot.x.kind === "num";
+  const boxDrawn = plot?.shape === "box" && !boxTransposed;
+  const axisFields = (side: "x" | "y") => <>
+    <AxisPicker side={side} stacked axis={spec[side]} attrs={attrs} profiles={profiles} loading={loading} busy={busy}
+      onChange={(a) => update((vv) => ({ ...vv, [side]: a }))} />
+    <LogToggle spec={spec} side={side} numeric={plot?.[side].kind === "num"} busy={busy} update={update} />
+  </>;
+  const total = plot?.coverage?.total;
+  // past the cap every case is density already, so the every-case switch has nothing to change
+  const overCap = !!plot && plot.n > POINTS_CAP;
   return (
-    <div className="viewtb">
-      <div className="tbz">
-        <span className="tbl" title="these change what is drawn, and re-run the query">data</span>
-        <AxisPicker side="x" axis={spec.x} attrs={attrs} profiles={profiles} loading={loading} busy={busy}
-          onChange={(a) => update((vv) => ({ ...vv, x: a }))} />
-        <LogToggle spec={spec} side="x" numeric={plot?.x.kind === "num"} busy={busy} update={update} />
-      </div>
-      <div className="tbz">
-        <AxisPicker side="y" axis={spec.y} attrs={attrs} profiles={profiles} loading={loading} busy={busy}
-          onChange={(a) => update((vv) => ({ ...vv, y: a }))} />
-        <LogToggle spec={spec} side="y" numeric={plot?.y.kind === "num"} busy={busy} update={update} />
-      </div>
-      {/* colour/ring only affect a box plot's violin — a scatter's density and a contingency table
-          have no per-case colour to split, so they are offered only once a box is on screen */}
-      {plot?.shape === "box" && <div className="tbz">
-        <span className="tbl" title="colours each group's violin by a category">colour</span>
-        <AxisPicker side="fill" axis={spec.colorBy} allowNone categorical attrs={attrs} profiles={profiles} loading={loading} busy={busy}
-          onChange={(a) => update((vv) => { const n = { ...vv }; if (a) n.colorBy = a; else delete n.colorBy; return n; })} />
-        <AxisPicker side="ring" axis={spec.ringBy} allowNone categorical attrs={attrs} profiles={profiles} loading={loading} busy={busy}
-          onChange={(a) => update((vv) => { const n = { ...vv }; if (a) n.ringBy = a; else delete n.ringBy; return n; })} />
-      </div>}
-      {plot?.shape !== "table" && (highlightOptions.length > 0 || chosen.length > 0) && <div className="tbz">
-        <HighlightPicker chosen={chosen} options={highlightOptions} busy={busy}
-          onChange={(next) => update((vv) => { const n = { ...vv }; if (next.length) n.highlight = next; else delete n.highlight; return n; })} />
-      </div>}
-      <div className="tbz">
-        <label className="tbfield" title="what a point is; patient mode averages a patient's samples">unit <Choice size="ctl"
-          value={spec.unit || "patient"} disabled={busy}
-          onChange={(u) => update((vv) => ({ ...vv, unit: u }))}
-          options={[["patient", "patients"], ["sample", "samples"]]} /></label>
-        {/* a box plot is always drawn categories-on-x, values-on-y whichever axis is which in the
-            document, so swapping would change nothing a reader can see */}
-        <Button variant="outline" size="sm" className={TB} disabled={busy || plot?.shape === "box"}
-          title={plot?.shape === "box" ? "a box plot is always drawn by category, whichever axis holds it — nothing to swap"
-            : "put the x axis on y and the y axis on x"}
-          onClick={() => update((vv) => ({ ...vv, x: vv.y, y: vv.x }))}><ArrowLeftRight />swap</Button>
+    <div className="@container mt-2.5" data-tw>
+      <div className="grid grid-cols-1 gap-4 @3xl:grid-cols-[16.5rem_minmax(0,1fr)]">
+        <aside className="plot-side flex flex-col gap-1.5" aria-label="plot axes">
+          <AxisBlock title="Horizontal axis">
+            {axisFields("x")}
+            {boxTransposed && <p className="m-0 text-sm text-muted-foreground">A box plot draws its categories across, so this axis is drawn up the side. Swap to make them agree.</p>}
+          </AxisBlock>
+          {/* a box drawn as the document says has nothing to swap: its categories are already across */}
+          <Button variant="link" size="inline" className="plot-swap self-center text-md" disabled={busy || boxDrawn}
+            title={boxDrawn ? "a box plot is always drawn by category across, which this one already is — nothing to swap"
+              : "put the horizontal axis's definition on the vertical axis, and the vertical one's on the horizontal"}
+            onClick={() => update((vv) => ({ ...vv, x: vv.y, y: vv.x }))}><ArrowUp />Swap axes<ArrowDown /></Button>
+          <AxisBlock title="Vertical axis">
+            {axisFields("y")}
+          </AxisBlock>
+          <div className="mt-2.5 flex flex-col gap-2.5">
+            <div className="axfield flex flex-col gap-1">
+              <span className="axfield-name text-sm font-semibold text-foreground">Each point is a</span>
+              <Choice size="ctl" className="w-full" value={unit} disabled={busy}
+                title="what a point is: a sample, or a patient with its samples combined (a number's mean, a category's common value or Multiple)"
+                onChange={(u) => update((vv) => ({ ...vv, unit: u }))}
+                options={[["sample", "sample"], ["patient", "patient"]]} />
+            </div>
+            {plot?.shape !== "table" && (
+              <div className="axfield flex flex-col gap-1">
+                <span className="axfield-name text-sm font-semibold text-foreground"
+                  title="subsets of the plotted cases drawn in their own colour over it; the first layer draws a case two share">Points</span>
+                <label className="chk text-md text-foreground" title={overCap
+                  ? "this plot has " + plot!.n.toLocaleString() + " " + unit + "s, more than 5,000, so it is drawn as density whatever this says"
+                  : "every case as a point when there are at most 5,000 and the study may show cases; off draws the density alone"}>
+                  <Checkbox checked={spec.allPoints !== false} disabled={busy || overCap}
+                    onCheckedChange={(c) => update((vv) => { const n = { ...vv }; if (c === true) delete n.allPoints; else n.allPoints = false; return n; })} />
+                  every {unit} (up to 5,000)
+                </label>
+                <PointLayers layers={layers} plot={plot} cohortOptions={cohortOptions} axisName={axisName} busy={busy}
+                  onChange={(next) => update((vv) => ({ ...vv, points: next }))} />
+              </div>
+            )}
+          </div>
+        </aside>
+        <div className="min-w-0">
+          {plot && <p className="plot-showing m-0 mb-2.5 rounded-sm bg-muted px-2.5 py-1.5 text-md">
+            Showing {plot.n.toLocaleString()}{total != null && total > plot.n ? " of " + total.toLocaleString() : ""} {unit}{plot.n === 1 ? "" : "s"} with data on both axes
+          </p>}
+          {/* colour and ring split a box's violin and points; a scatter's density and a contingency
+              have no per-case colour, so the controls appear only with a box on screen */}
+          {plot?.shape === "box" && <div className="viewtb mt-0 mb-2.5">
+            <div className="tbz">
+              <span className="tbl" title="colours each group's violin and points by a category">colour samples by</span>
+              <AxisPicker side="fill" axis={spec.colorBy} allowNone categorical attrs={attrs} profiles={profiles} loading={loading} busy={busy}
+                onChange={(a) => update((vv) => { const n = { ...vv }; if (a) n.colorBy = a; else delete n.colorBy; return n; })} />
+            </div>
+            <div className="tbz">
+              <AxisPicker side="ring" axis={spec.ringBy} allowNone categorical attrs={attrs} profiles={profiles} loading={loading} busy={busy}
+                onChange={(a) => update((vv) => { const n = { ...vv }; if (a) n.ringBy = a; else delete n.ringBy; return n; })} />
+            </div>
+          </div>}
+          {children}
+        </div>
       </div>
     </div>
   );
diff --git a/app/lab/view-cards.tsx b/app/lab/view-cards.tsx
index 689273db..b5970254 100644
--- a/app/lab/view-cards.tsx
+++ b/app/lab/view-cards.tsx
@@ -653,15 +653,16 @@ function PlotCard({ ctx, v, vi }: CardProps) {
   const { attrsLoading, busy, catalogAttrs, cohortChoice, docView, menuOpenRef, profileOptions, updateView } = ctx;
   // every cohort the document evaluates, but the plotted one and a split (which stands for several groups, not one set of cases)
   const ch = cohortChoice(vi, docView(vi), 1);
-  const highlightOptions = ch.nodes.filter((nd) => nd.kind !== "split" && nd.name !== ch.drawn[0])
+  const cohortOptions = ch.nodes.filter((nd) => nd.kind !== "split" && nd.name !== ch.drawn[0])
     .map((nd) => ({ name: nd.name, label: nd.label, depth: nd.depth }));
   return <>
     {v.kind === "plot" && <>
       <ViewHead menuStore={menuOpenRef.current} v={v} title="Plot" cohorts={ch} {...placement(ctx, vi)}
-        sub={v.plot ? <>{v.plot.shape === "scatter" ? "density" : v.plot.shape === "box" ? "box" : "contingency"} · {v.plot.n.toLocaleString()} {(docView(vi).unit || "patient")}s</> : "two axes over the same cases"} />
+        sub={v.plot ? <>{v.plot.shape === "scatter" ? "density" : v.plot.shape === "box" ? "box" : "contingency"} · {v.plot.n.toLocaleString()} {(docView(vi).unit || "sample")}s</> : "two axes over the same cases"} />
       <PlotControls spec={docView(vi)} plot={v.plot} attrs={catalogAttrs()} profiles={profileOptions()} loading={attrsLoading()} busy={busy}
-        highlightOptions={highlightOptions} update={(fn) => updateView(vi, fn)} />
-      <ViewFigure v={v} empty={v.plot?.note || "nothing to draw"} />
+        cohortOptions={cohortOptions} update={(fn) => updateView(vi, fn)}>
+        <ViewFigure v={v} empty={v.plot?.note || "nothing to draw"} />
+      </PlotControls>
     </>}
   </>;
 }
diff --git a/app/lab/view-chrome.tsx b/app/lab/view-chrome.tsx
index 6a1ae1b7..f48a5af7 100644
--- a/app/lab/view-chrome.tsx
+++ b/app/lab/view-chrome.tsx
@@ -7,9 +7,8 @@ import { attributeLabel } from "../../lib/custom-data-names.ts";
 import type { AnalysisSource, ViewParticipation } from "../../lib/types.ts";
 import { VIEW_HELP } from "../../lib/view-help.ts";
 import { SERIES, seriesStyle } from "../../lib/chart/style.ts";
-import { HIGHLIGHT_CAP, HIGHLIGHT_COLORS } from "../../lib/plot-highlight.ts";
 import { Waiting } from "../_oncoprint/OncoprintCard.tsx";
-import { ArrowDown, ArrowUp, Ellipsis, ExternalLink, Lock, LockOpen, Pencil, Plus, Save, Split, StickyNote, Trash2, X } from "lucide-react";
+import { ArrowDown, ArrowUp, Ellipsis, ExternalLink, Lock, LockOpen, Pencil, Plus, Save, Split, StickyNote, Trash2 } from "lucide-react";
 import { Button } from "../_ui/button";
 import { Input } from "../_ui/input";
 import { cn } from "../../lib/cn";
@@ -73,7 +72,7 @@ export function Participation({ p }: { p?: ViewParticipation }) {
  * in a molecular profile, or a gene's alterations. It is the same vocabulary the engine uses,
  * so what the reader picks is what the document says.
  */
-export function AxisPicker({ side, axis, attrs, profiles, busy, loading, onChange, allowNone, categorical }: {
+export function AxisPicker({ side, axis, attrs, profiles, busy, loading, onChange, allowNone, categorical, stacked }: {
   side: string; axis: any; busy?: boolean;
   attrs: { attribute: string; kind: string }[]; profiles: string[];
   /** the attribute/profile catalog is still being fetched: its select waits with a loader */
@@ -83,14 +82,21 @@ export function AxisPicker({ side, axis, attrs, profiles, busy, loading, onChang
   allowNone?: boolean;
   /** colours come from categories, so a molecular value is not on offer */
   categorical?: boolean;
+  /** one labelled field per row at the box's full width (a plot's axis sidebar), not a toolbar run */
+  stacked?: boolean;
 }) {
   const a = axis || {};
   const src = axis ? (a.source || "clinical") : "none";
   const set = (next: any) => onChange(next);
+  const w = stacked ? "w-full max-w-none" : "max-w-44";
+  /** a control with its name above it when stacked; inline, the toolbar's side label names the run */
+  const field = (name: string, control: React.ReactNode) =>
+    stacked ? <div className="axfield flex flex-col gap-1"><span className="axfield-name text-sm font-semibold text-foreground">{name}</span>{control}</div> : control;
+  const srcName: Record<string, string> = { clinical: "Clinical attribute", molecular: "Molecular profile", alteration: "Genes" };
   return (
-    <span className="axispick">
-      <span className="tbl">{side}</span>
-      <OptionSelect className="max-w-44" value={src} disabled={busy} title="what this axis measures"
+    <span className={stacked ? "axispick-stack flex flex-col gap-2.5" : "axispick"}>
+      {!stacked && <span className="tbl">{side}</span>}
+      {field("Data type", <OptionSelect className={w} value={src} disabled={busy} title="what this axis measures" ariaLabel={side + " data type"}
         onValueChange={(v) => {
           const s = v;
           // Keep whatever this axis last held for each source (spreading `a` rather than
@@ -106,42 +112,30 @@ export function AxisPicker({ side, axis, attrs, profiles, busy, loading, onChang
         <option value="clinical">clinical</option>
         {!categorical && <option value="molecular">molecular</option>}
         <option value="alteration">alteration</option>
-      </OptionSelect>
-      {src === "clinical" && loading && !attrs.length && <Waiting what="attributes" />}
-      {src === "clinical" && !(loading && !attrs.length) && (
-        <OptionSelect className="max-w-44" value={a.attribute || ""} disabled={busy} title="which clinical attribute"
+      </OptionSelect>)}
+      {src === "clinical" && loading && !attrs.length && field(srcName.clinical, <Waiting what="attributes" />)}
+      {src === "clinical" && !(loading && !attrs.length) && field(srcName.clinical,
+        <OptionSelect className={w} value={a.attribute || ""} disabled={busy} title="which clinical attribute" ariaLabel={side + " clinical attribute"}
           onValueChange={(v) => set({ ...a, attribute: v })}>
           {!attrs.some((x) => x.attribute === a.attribute) && <option value={a.attribute || ""}>{a.attribute || "(none)"}</option>}
           {attrs.map((x) => <option key={x.attribute} value={x.attribute}>{attributeLabel(x.attribute)}{x.kind === "num" ? "" : " (categorical)"}</option>)}
         </OptionSelect>
       )}
       {src === "molecular" && <>
-        {loading && !profiles.length ? <Waiting what="profiles" /> :
-        <OptionSelect className="max-w-44" value={a.profileType || ""} disabled={busy} title="which molecular profile"
+        {field(srcName.molecular, loading && !profiles.length ? <Waiting what="profiles" /> :
+        <OptionSelect className={w} value={a.profileType || ""} disabled={busy} title="which molecular profile" ariaLabel={side + " molecular profile"}
           onValueChange={(v) => set({ ...a, profileType: v })}>
           {!profiles.includes(a.profileType || "") && <option value={a.profileType || ""}>{a.profileType || "(none)"}</option>}
           {profiles.map((pt) => <option key={pt} value={pt}>{pt}</option>)}
-        </OptionSelect>}
-        <GeneInput gene={a.gene || ""} busy={busy} onCommit={(gene) => set({ ...a, gene })} />
+        </OptionSelect>)}
+        {field("Gene", <GeneInput gene={a.gene || ""} busy={busy} className={stacked ? w : undefined} onCommit={(gene) => set({ ...a, gene })} />)}
       </>}
       {src === "alteration" && (() => {
         const isOql = a.oql != null;
         const genes: string[] = a.genes && a.genes.length ? a.genes : a.gene ? [a.gene] : [];
         const isSet = !isOql && genes.length > 1;
-        return <>
-          {isOql
-            ? <OqlInput query={a.oql} busy={busy} onCommit={(oql) => set({ source: "alteration", oql })} />
-            : <GeneSetInput genes={genes} busy={busy}
-                onCommit={(next) => {
-                  // A gene SET (2+) only supports "mutated vs not" — combining several genes'
-                  // mutation types or copy-number states into one category has no honest reading,
-                  // so switching to a set falls back to that rather than leaving an axis the
-                  // engine would refuse.
-                  const by = next.length > 1 && a.by && a.by !== "mutated" ? "mutated" : a.by;
-                  set(next.length > 1 ? { ...a, gene: undefined, genes: next, by }
-                    : { ...a, genes: undefined, gene: next[0] || "", by });
-                }} />}
-          <OptionSelect className="max-w-44" value={isOql ? "oql" : a.by || (isSet ? "mutated" : "mutationType")} disabled={busy}
+        const groupBy = <OptionSelect className={w} value={isOql ? "oql" : a.by || (isSet ? "mutated" : "mutationType")} disabled={busy}
+            ariaLabel={side + " alteration grouping"}
             title={isOql ? "Altered when a case matches any line of the query, Unaltered otherwise"
               : isSet ? "a gene set is \"mutated vs not\", or write it as an OQL query" : "how the gene's alterations are grouped"}
             onValueChange={(v) => {
@@ -156,48 +150,29 @@ export function AxisPicker({ side, axis, attrs, profiles, busy, loading, onChang
             <option value="mutated">mutated vs not</option>
             <option value="cna" disabled={isSet}>copy number</option>
             <option value="oql">matches OQL</option>
-          </OptionSelect>
+          </OptionSelect>;
+        // stacked, the grouping comes first: it decides whether the box below takes genes or a query
+        return <>
+          {stacked && field("Group cases by", groupBy)}
+          {field(isOql ? "OQL query" : "Gene(s)", isOql
+            ? <OqlInput query={a.oql} busy={busy} className={stacked ? w : undefined} onCommit={(oql) => set({ source: "alteration", oql })} />
+            : <GeneSetInput genes={genes} busy={busy} className={stacked ? w : undefined}
+                onCommit={(next) => {
+                  // A gene SET (2+) only supports "mutated vs not" — combining several genes'
+                  // mutation types or copy-number states into one category has no honest reading,
+                  // so switching to a set falls back to that rather than leaving an axis the
+                  // engine would refuse.
+                  const by = next.length > 1 && a.by && a.by !== "mutated" ? "mutated" : a.by;
+                  set(next.length > 1 ? { ...a, gene: undefined, genes: next, by }
+                    : { ...a, genes: undefined, gene: next[0] || "", by });
+                }} />)}
+          {!stacked && groupBy}
         </>;
       })()}
     </span>
   );
 }
 
-/**
- * A plot's highlight cohorts: one chip per cohort in the view's list, in its figure colour, and a
- * select offering the document's other cohorts until the cap is reached. Order is colour, so a
- * removed chip shifts the ones after it to the next colour, as the figure does.
- */
-export function HighlightPicker({ chosen, options, busy, onChange }: {
-  chosen: string[];
-  /** cohorts that may be highlighted: every cohort but the plotted one */
-  options: { name: string; label: string; depth: number }[];
-  busy?: boolean;
-  onChange: (next: string[]) => void;
-}) {
-  const left = options.filter((o) => !chosen.includes(o.name));
-  return (
-    <span className="hlpick">
-      <span className="tbl" title="other cohorts drawn over this one, each in its own colour">highlight</span>
-      {chosen.map((n, i) => (
-        <span key={n} className="hlchip" title={"“" + n + "” drawn over the plotted cohort"}>
-          <span className="hldot" style={{ background: HIGHLIGHT_COLORS[i] }} />
-          <span className="hlname">{n}</span>
-          <Button type="button" variant="ghost" size="icon-xs" className="size-4 text-muted-foreground [&_svg:not([class*='size-'])]:size-3" disabled={busy}
-            aria-label={"stop highlighting " + n} onClick={() => onChange(chosen.filter((x) => x !== n))}><X /></Button>
-        </span>
-      ))}
-      {chosen.length < HIGHLIGHT_CAP && left.length > 0 && (
-        <OptionSelect className="max-w-40" value="" disabled={busy} aria-label="add a cohort to highlight"
-          onValueChange={(v) => { if (v) onChange([...chosen, v]); }}>
-          <option value="">{chosen.length ? "+ another" : "+ cohort"}</option>
-          {left.map((o) => <option key={o.name} value={o.name}>{"\u00a0".repeat(o.depth * 2) + o.label}</option>)}
-        </OptionSelect>
-      )}
-    </span>
-  );
-}
-
 /**
  * A gene name typed into a plot axis, debounced before it reaches the document/URL. Committing
  * on every keystroke (as the rest of this axis picker does for selects) meant an in-progress
@@ -205,13 +180,13 @@ export function HighlightPicker({ chosen, options, busy, onChange }: {
  * briefly became the shareable link, which the compiler then rejects ("a molecular axis needs
  * one gene"). A short pause before committing keeps that mid-edit state local to the input.
  */
-export function GeneInput({ gene, busy, onCommit }: { gene: string; busy?: boolean; onCommit: (gene: string) => void }) {
+export function GeneInput({ gene, busy, onCommit, className }: { gene: string; busy?: boolean; onCommit: (gene: string) => void; className?: string }) {
   const [draft, setDraft] = useState(gene);
   const timer = useRef<ReturnType<typeof setTimeout> | null>(null);
   useEffect(() => setDraft(gene), [gene]);
   const commit = (v: string) => { if (timer.current) clearTimeout(timer.current); onCommit(v); };
   return (
-    <Input className={cn(FIELD, "w-22 px-1.5 uppercase")} value={draft} disabled={busy} placeholder="gene"
+    <Input className={cn(FIELD, "w-22 px-1.5 uppercase", className)} value={draft} disabled={busy} placeholder="gene" aria-label="gene"
       onChange={(e) => {
         const v = e.target.value.toUpperCase();
         setDraft(v);
@@ -228,7 +203,7 @@ export function GeneInput({ gene, busy, onCommit }: { gene: string; busy?: boole
  * the same reason: committing every keystroke would briefly make an empty or half-typed gene
  * list the shareable link, which the compiler then rejects.
  */
-export function GeneSetInput({ genes, busy, onCommit }: { genes: string[]; busy?: boolean; onCommit: (genes: string[]) => void }) {
+export function GeneSetInput({ genes, busy, onCommit, className }: { genes: string[]; busy?: boolean; onCommit: (genes: string[]) => void; className?: string }) {
   const joined = genes.join(",");
   const [draft, setDraft] = useState(joined);
   const timer = useRef<ReturnType<typeof setTimeout> | null>(null);
@@ -236,7 +211,7 @@ export function GeneSetInput({ genes, busy, onCommit }: { genes: string[]; busy?
   const parse = (v: string) => v.split(",").map((g) => g.trim().toUpperCase()).filter(Boolean);
   const commit = (v: string) => { if (timer.current) clearTimeout(timer.current); onCommit(parse(v)); };
   return (
-    <Input className={cn(FIELD, "w-auto max-w-56 min-w-22 px-1.5 uppercase")} value={draft} disabled={busy} placeholder="gene, or gene,gene,... for a set" size={Math.max(8, Math.min(30, draft.length + 2))}
+    <Input className={cn(FIELD, "w-auto max-w-56 min-w-22 px-1.5 uppercase", className)} value={draft} disabled={busy} placeholder="gene, or gene,gene,... for a set" size={Math.max(8, Math.min(30, draft.length + 2))}
       title={'one gene, or a comma-separated gene set ("is any of these altered")'}
       onChange={(e) => {
         const v = e.target.value.toUpperCase();
@@ -253,13 +228,13 @@ export function GeneSetInput({ genes, busy, onCommit }: { genes: string[]; busy?
  * on Enter or on leaving the box — like the gene inputs, so a half-typed query never becomes the
  * shareable link. The engine checks it and the view says what it refused.
  */
-export function OqlInput({ query, busy, onCommit }: { query: string; busy?: boolean; onCommit: (oql: string) => void }) {
+export function OqlInput({ query, busy, onCommit, className }: { query: string; busy?: boolean; onCommit: (oql: string) => void; className?: string }) {
   const [draft, setDraft] = useState(query);
   const timer = useRef<ReturnType<typeof setTimeout> | null>(null);
   useEffect(() => setDraft(query), [query]);
   const commit = (v: string) => { if (timer.current) clearTimeout(timer.current); if (v.trim() && v !== query) onCommit(v.trim()); };
   return (
-    <Input className={cn(FIELD, "w-auto max-w-88 px-1.5")} value={draft} disabled={busy} placeholder="KRAS: G12C; STK11: MUT" spellCheck={false}
+    <Input className={cn(FIELD, "w-auto max-w-88 px-1.5", className)} value={draft} disabled={busy} placeholder="KRAS: G12C; STK11: MUT" spellCheck={false}
       size={Math.max(16, Math.min(44, draft.length + 2))}
       title={"OQL, one gene per line or ';' — e.g. KRAS: G12C; STK11: MUT; EGFR: AMP; TP53: DRIVER; ERBB2: EXP>2. " +
         "A case is Altered when it matches any of them."}
diff --git a/app/portal/PortalTabs.tsx b/app/portal/PortalTabs.tsx
index 97ef8a19..0dab91f5 100644
--- a/app/portal/PortalTabs.tsx
+++ b/app/portal/PortalTabs.tsx
@@ -133,6 +133,16 @@ export function PortalTabs({ doc, tabs, titles, open, onOpen, onDoc, onCounts, c
               onView={(n) => edit(vi, n as unknown as View)} note={v.note} studies={v.studies} />
           : v && !v.error ? KindCardBody({ c: { ...mc, v } }) : null;
         const drawn = Array.isArray(spec.cohorts) ? (spec.cohorts as string[]) : Object.keys(doc.cohorts || {});
+        // the figure and what covers it while it waits; a plot holds it beside its axis sidebar
+        const figureArea = <>
+          {busy && !v && <div className="skeleton skeleton-view" />}
+          {busy && v && !(drawsOwnWaiting(v.kind) && !v.error) && <div className="view-updating"><span className="spinner" /> updating…</div>}
+          {!busy && st?.error && <p className="note">{st.error}</p>}
+          {v && v.error && <p className="note">{v.error}</p>}
+          {v && !v.error && (body
+            ? <>{body}{v.caveat && <p className="note vfoot">{v.caveat}</p>}</>
+            : <ViewFigure v={figureView(spec, v)} />)}
+        </>;
         return (
           <section key={key + vi} className={cn("card viewcard", busy && !v && "viewloading")} aria-busy={busy || undefined}>
             <ViewHead menuStore={menus.current} v={v && !v.error ? v : { kind: spec.kind }} title={titles[vi]}
@@ -140,14 +150,10 @@ export function PortalTabs({ doc, tabs, titles, open, onOpen, onDoc, onCounts, c
             {hasKindCard(spec.kind as string) && <KindCardControls c={mc} />}
             {spec.kind === "plot" && <PlotControls spec={spec} plot={v && !v.error ? v.plot : undefined} attrs={catalog.attrs} profiles={catalog.profiles}
               loading={catalog.loading} busy={busy} update={(fn) => edit(vi, fn(spec))}
-              highlightOptions={Object.keys(doc.cohorts || {}).filter((n) => n !== drawn[0]).map((n) => ({ name: n, label: n, depth: 0 }))} />}
-            {busy && !v && <div className="skeleton skeleton-view" />}
-            {busy && v && !(drawsOwnWaiting(v.kind) && !v.error) && <div className="view-updating"><span className="spinner" /> updating…</div>}
-            {!busy && st?.error && <p className="note">{st.error}</p>}
-            {v && v.error && <p className="note">{v.error}</p>}
-            {v && !v.error && (body
-              ? <>{body}{v.caveat && <p className="note vfoot">{v.caveat}</p>}</>
-              : <ViewFigure v={figureView(spec, v)} />)}
+              cohortOptions={Object.keys(doc.cohorts || {}).filter((n) => n !== drawn[0]).map((n) => ({ name: n, label: n, depth: 0 }))}>
+              {figureArea}
+            </PlotControls>}
+            {spec.kind !== "plot" && figureArea}
           </section>
         );
       })}
diff --git a/app/portal/results/page.tsx b/app/portal/results/page.tsx
index 50cfd397..0a23214a 100644
--- a/app/portal/results/page.tsx
+++ b/app/portal/results/page.tsx
@@ -58,7 +58,7 @@ function resultsLayout(study: string, entries: string[], genes: string[], known:
     { title: "Oncoprint", views: [v("Oncoprint", { kind: "oncoprint", genes, cohorts: both })] },
     { title: "Cancer Types Summary", views: [v("Cancer types summary", { kind: "cancertypes", genes, cohorts: ["Altered"] })] },
     ...(genes.length >= 2 ? [{ title: "Mutual Exclusivity", views: [v("Mutual exclusivity", { kind: "cooccurrence", genes, cohorts: both })] }] : []),
-    ...(expr ? [{ title: "Plots", views: [v("Plot", { kind: "plot", x: { source: "alteration", gene: genes[0], by: "cna" }, y: { source: "molecular", profileType: expr, gene: genes[0] }, cohorts: ["All patients"], highlight: ["Altered"] })] }] : []),
+    ...(expr ? [{ title: "Plots", views: [v("Plot", { kind: "plot", x: { source: "alteration", gene: genes[0], by: "cna" }, y: { source: "molecular", profileType: expr, gene: genes[0] }, cohorts: ["All patients"], points: [{ cohort: "Altered" }] })] }] : []),
     // the portal's Mutations tab: one gene at a time, its lollipop over its mutation table
     { title: "Mutations", views: [v("Mutation diagram", { kind: "hotspots", genes: [genes[0]], cohorts: ["Altered"] }),
         v("Mutation table", { kind: "mutations", gene: genes[0], cohorts: ["Altered"] })],
diff --git a/docs/DATA-BOUNDARY.md b/docs/DATA-BOUNDARY.md
index 403bba63..f05ddf88 100644
--- a/docs/DATA-BOUNDARY.md
+++ b/docs/DATA-BOUNDARY.md
@@ -86,7 +86,7 @@ of …"). One rule decides it, `lib/view-coverage.ts`: the engine refuses by it
 (`lib/analysis.ts`), and the page does not offer such a view (the add-view buttons, disabled with
 the reason) or such a cohort (its row in a view's cohort picker). Where every patient is counted
 and only a per-patient detail is withheld — the labs waterfall's bars, composition's per-case
-bars, a plot highlight drawn as density — the view is drawn and says what is withheld.
+bars, a plot's cohort layer drawn as density — the view is drawn and says what is withheld.
 
 ## Opt-in patient-level federation (per study and kind of data)
 
diff --git a/docs/dsl.md b/docs/dsl.md
index 1637396c..9f3efc2c 100644
--- a/docs/dsl.md
+++ b/docs/dsl.md
@@ -275,7 +275,7 @@ patient — so the arm counts summing to more than the base cohort is expected,
 | `logistic` | `outcome:axis, outcomeEvent?:"<level>", covariates:[axis, ...(max 8)], cohorts:[names]` | multivariate logistic regression: a BINARY outcome (not time-to-event — no endpoint/months convention here) regressed on several covariates at once, reported as odds ratios with Wald confidence intervals, drawn as a forest plot the same shape as `cox`'s. `outcome` is a plot axis, exactly like a covariate (clinical, molecular, or alteration status). A categorical outcome (a clinical attribute, or an alteration axis) needs `outcomeEvent` naming which observed value counts as the event (1) — every other observed value collapses into "not event" (0), and which values got collapsed is disclosed in the caveat; omitting it, or naming a value never observed, is refused with the actual observed values listed rather than guessed at. A numeric outcome must already be coded exactly 0/1 (refused otherwise) and must NOT be given `outcomeEvent`. Covariates use the exact same dummy-coding and reference-level rules as `cox` (see above): a mutated-vs-not axis defaults to `"Not mutated"`, others default to the most frequent level, `reference` overrides either. Same patient-level-only boundary as `cox` |
 | `course` | `eventTypes:[≤6], anchor?:{eventType,key?,value?,occurrence?}, binMonths?:3, fromMonths?:-12, toMonths?:60, cohorts:[names]` | the **clinical course**: per time bin, the share of the cohort in each event state. Two things it refuses to fake. (1) The denominator is the patients still under observation in that bin — first recorded event to last contact (the later of their last event and their OS follow-up) — never the whole cohort, which would make a curve fall merely because follow-up ran out. (2) `anchor` is optional for one study but **required across studies**: day 0 is birth in some studies and first sequencing in others, and nothing in the schema records which, so raw day 0 compares incomparable clocks. Event types that carry real durations are drawn as a state the patient is IN; the rest as an event that HAPPENED — read from the data, not from the name. Bins are half-open [t, t+w). Event-name spellings differing only in case are folded (`Treatment`/`TREATMENT`) and the fold is named in the caveat; nothing else is merged |
 | `sequence` | `labelKey?:"SUBTYPE", eventType?:"treatment", lineClasses?:"systemic"|"all"|[classes], exclude?:[values], lineGap?:90, maxSteps?:3, topN?:8, cohorts:[names]` | **what follows what**: therapy transitions as lines, drawn as a Sankey. Records are first grouped into LINES — therapies less than `lineGap` days apart are one line, labelled by their whole combination (sorted, so `A + B` and `B + A` are one regimen). That grouping is the point: a patient has a median of 6 treatment records and 4 distinct agents, and combination therapy is several records describing ONE decision. Paths that end flow into TWO explicit terminals, never one: **no further line** (the study watched for at least one `lineGap` and saw no further therapy) and **record ends here** (it did not, so nothing can be concluded). Measured on MSK-CHORD, 68% of patients have under three months of observation after their last therapy and the median is 15 days — so collapsing the two would turn record-keeping into an apparent clinical decision. Flows out of a node sum to it, so nobody vanishes. Up to two cohorts are drawn as panels sharing one scale and one colour per regimen. Lines are the shared definition (see "Treatment line (derived)" above): systemic-therapy records by default, `lineClasses` `"all"` for every treatment record or a list of class names for your own; `labelKey` only names a line’s therapies (e.g. AGENT), it never decides which records form lines. `exclude` drops records by label value, matched ignoring case. More than two cohorts is refused |
-| `plot` | `x:axis, y:axis, unit?:"patient"\|"sample", bins?:[240,160], points?:true, colorBy?:axis, ringBy?:axis, highlight?:[names(max 4)], cohorts:[names]` | two axes over the same cases, aggregated **inside the database**: a scatter comes back as counts per grid cell, a box as quartiles per group, two categoricals as a contingency table. The payload is a few kilobytes whatever the cohort's size |
+| `plot` | `x:axis, y:axis, unit?:"sample"\|"patient", bins?:[240,160], allPoints?:true, points?:[layer(max 4)], colorBy?:axis, ringBy?:axis, cohorts:[names]` | two axes over the same cases, aggregated **inside the database**: a scatter comes back as counts per grid cell, a box as quartiles per group, two categoricals as a contingency table. The payload is a few kilobytes whatever the cohort's size. A point is a sample, as on cBioPortal's Plots tab; `unit:"patient"` makes it a patient, combining a patient's samples: a numeric value is their mean, a category their common value or "Multiple" where they differ, an alteration counts if any sample has it, and the caption says how many patients had more than one sample. Every case is a point up to 5,000 (`allPoints: false` turns that off), from a participant that may show cases; `points` lists up to four subsets drawn in colour over it — `{rule:"outliers"}` (the default), `{rule:"extremes",axis,n}`, `{rule:"trend",n}`, `{cohort}` — see **Points** below |
 | `attrition` | `cohorts:[names] (≤6)` | **cohort attrition**, CONSORT-style: for each cohort, the study base and then the patients left after each clause of its `all`, in the order written, with how many that clause alone removed. Each step is evaluated as its own cohort (the first k clauses ANDed), with the same compiler and the same per-study counts, so the last step is the cohort's own count by construction — a mismatch is reported, never smoothed over. The order of clauses changes the path, never the final count. Counts only, so every participant (aggregate-only and remote included) can answer; across studies the counts are summed and overlap is not deduplicated |
 | `genome` | `binMb?:2, threshold?:0.2, includeX?:false, cohorts:[names] (≤4)` | **genome-wide copy-number frequency** from the copy-number SEGMENTS: the share of each cohort's segmented samples gained (log2 segment mean ≥ `threshold`) or lost (≤ −`threshold`) in every `binMb`-megabase bin (1–50) along chromosomes 1–22 (and X with `includeX` — its log ratio mostly records sex, so it is off by default), drawn as gains up and losses down, one panel per cohort. Each bin's denominator is the samples whose segmentation covers it — a bin nothing covers is drawn as unmeasured, never as copy-neutral. A bin takes the value of the segment over its midpoint, so an event narrower than a bin can be missed; the caption says so. Unit is the SAMPLE, not the patient. Exactly two cohorts add a per-bin two-sided Fisher test (gains and losses separately, Benjamini–Hochberg across bins), drawn as a strip coloured by which cohort is higher. Studies on different reference genomes (hg19/hg38) are refused rather than drawn on one axis. Counts only; a remote peer cannot answer yet and is named as left out |
 | `pathways` | `pathways?:[names], sets?:[{name, genes:[≤40]} ×≤4], measure?:"driver"|"any", topGenes?:6, cohorts:[names] (≤4)` | **oncogenic signalling pathways**: the ten canonical pathways of Sanchez-Vega et al. (Cell 2018, Table S3: RTK-RAS, PI3K, TP53, Cell cycle, MYC, WNT, NOTCH, Hippo, TGF-β, NRF2 — 334 genes), and/or the document's own `sets`, each as the share of the cohort with at least one member altered. `measure` defaults to `"driver"` (OncoKB-annotated drivers, as the paper counted curated oncogenic events; refused without an annotation pin) or `"any"`. A pathway's denominator is the patients profiled for at least ONE member (the union of the members' panels, the oncoprint's merged-row rule, computed in the database with the same event table, CNA rule and driver join as `compare`, so a one-gene set equals that gene's own count); each member's % is over the patients profiled for THAT gene. The `topGenes` most-altered members are drawn per pathway; the rest are pooled as "+N more altered", and members on no participating panel are listed as never profiled. Two cohorts add Fisher tests with BH q across pathways, and separately across member genes. Counts only; a remote peer cannot answer yet and is named |
@@ -371,19 +371,29 @@ overlay a single-study box can fall back to (that needs the same shared-scale bi
 uses, not yet built for a box); its quartiles are a size-weighted approximation across sites, the
 same one Explore's federated numeric histograms already disclose.
 
-**What sits behind the boxes.** cBioPortal draws every value as a jittered point over its box.
-So does this, up to 5,000 values, and only when the study is one this participant may see cases
-in — the points carry case ids, so they come from the same entitlement that lets a
-patient-level participant list cohort members, and an aggregate-only participant has no method
-that could return them. The jitter is fixed per case, so the figure does not move between the
-server SVG, the browser and the Python package.
-
-Above the cap, or with `points: false`, or from a participant that may not disclose a case, the
-same values are drawn as a **violin** from per-group bins: a quarter of a million jittered dots
-is a solid block, while the density is 19KB and is what the reader was looking for. Each violin
-is scaled to its own densest bin, because one group holding 178,489 of the values would
-otherwise flatten every other group to nothing; how many cases a group has is printed under its
-name. The caption always says which of the two it drew.
+**Points: every case when it is a drawing, the outliers when it is not.** cBioPortal draws every
+case as a point. So does this, up to 5,000 cases, on a scatter as on a box, and only when the
+study is one this participant may see cases in — the points carry case ids, so they come from the
+same entitlement that lets a patient-level participant list cohort members, and an aggregate-only
+participant has no method that could return them. The jitter across a box is fixed per case, so
+the figure does not move between the server SVG, the browser and the Python package.
+
+Past 5,000 the crowd is drawn as density — a quarter of a million dots is a solid block, and a
+hover on it would land on an arbitrary case — and, by default, the **outliers** are a point layer
+over it (see **Points**): on a box, the
+values beyond each group's Tukey whiskers, drawn over a **violin** (from per-group bins) that stops
+at the whiskers; on a scatter, the cases in **sparse cells** of the grid — every cell holding at
+most 3 cases (fewer, if that is what keeps the points under 5,000) is drawn as its cases instead of
+as a shade. Both subsets are chosen in the database, against the same grid and whiskers the figure
+draws, and if a subset is itself past 5,000 none of it is drawn, never the first 5,000. With
+`allPoints: false` and `points: []`, or from a participant that may not disclose a case, the
+figure is density alone.
+The caption always says which it drew, how many points, and why there are none when there are
+none. Each violin is scaled to its own densest bin, because one group holding 178,489 of the
+values would otherwise flatten every other group to nothing; how many cases a group has is
+printed under its name. A box's axis spans the points it draws but reaches at most one whisker
+span past the whiskers, so one extreme value cannot flatten every box; a point beyond that is a
+triangle at the frame's edge, counted in the caption.
 
 **Colour.** `colorBy` fills each value with the colour of a category and `ringBy` rings it, the
 portal's "Color samples by" with its two checkboxes — so a case that is amplified *and* mutated
@@ -406,17 +416,26 @@ or per sample following the plot's `unit`. Because it is a categorical axis, it
 `colorBy`/`ringBy` and as a Cox or logistic covariate, where "Unaltered" is the reference level.
 OQL is for alteration axes only: a molecular axis stays one gene's value.
 
-**Highlight.** `highlight` names up to four other cohorts of the document to draw over the
-plotted one, each in its own colour, with the plotted cohort turned grey beneath them — your trial
-patients, the responders, the KRAS G12C carriers, against everyone. A highlight's cases are the
-plotted cohort's cases that are also in it; how many of its patients fall outside the plotted
-cohort is stated, and they are not drawn. Its cases are **points** when every study they come from
-may show cases and there are at most 5,000 of them; otherwise the same cases are drawn as an
-aggregate on the plot's own scale — cells on the scatter's grid, or a narrow box per group — and the
-caption says which and why. A highlight is never cut to its first 5,000 cases. Highlighting changes
-no statistic: the coefficients and quartiles stay those of the whole plotted cohort. A contingency
-table has no points to mark, so its highlights are counted but not drawn. On a box plot a
-highlighted value beyond the whiskers is pinned to the frame's edge as a triangle and counted.
+**Points.** Every case is a point when there are at most 5,000 of them and every study may show
+cases (`allPoints: false` draws the density alone at any size). Over that the plotted cohort is a
+density, and `points` lists the subsets worth seeing one by one, each drawn in its own colour with
+the plotted cohort turned grey beneath them (at most four layers, in order):
+`{"rule": "outliers"}` — where the cohort is density, a box's values beyond its Tukey whiskers
+(the violin then stops at the whiskers) and a single study's scatter's cases in sparse cells (every
+grid cell holding at most 3 cases, left unshaded under its points); `{"rule": "extremes", "axis":
+"y", "n": 50}` — the `n` highest and lowest values of a numeric axis (per group on a box);
+`{"rule": "trend", "n": 50}` — on a scatter, the `n` cases furthest from the fitted line; and
+`{"cohort": "KRAS G12C"}` — the plotted cohort's cases that are also in that cohort (how many of its
+patients fall outside the plotted cohort is stated, and they are not drawn). The default is
+`[{"rule": "outliers"}]`; `[]` draws none. A case in two layers is drawn by the first, and the
+caption counts what each layer left to an earlier one. Every layer shares one 5,000-point budget,
+and a layer is never cut to its first cases: a cohort layer past the budget, or from a study that
+may not show cases, is drawn as an aggregate on the plot's own scale (cells on the scatter's grid,
+or a narrow box per group), and a rule layer is not drawn — the caption says which and why.
+Extremes and trend are exact over several studies (each returns its own top `n`). Layers change no
+statistic: the coefficients and quartiles stay those of the whole plotted cohort. A contingency
+table has no points to mark. On a box plot a value beyond the axis is pinned to the frame's edge as
+a triangle and counted; with the cases coloured by a category, a layer is a ring round the case.
 
 A case with no value on an axis is simply absent, so a pair is an inner join: only cases measured
 on both axes are counted, and the figure reports how many that was.
@@ -1865,7 +1884,7 @@ ERBB2-amplified TCGA breast tumors with an mRNA z-score heatmap under the gene t
 
 ### Example 16: A plot of 13,000 samples, drawn as density
 
-Tumour mutational burden against fraction of the genome altered, over every sample of a TP53-mutant cohort. The figure is a density field: the samples are counted into a 240x160 grid, and only the occupied cells travel. Pearson, Spearman and the fitted line are computed over EVERY sample inside ClickHouse, so they describe the whole cohort rather than the points that happened to be painted last. The second view groups the same measure by TP53 mutation class, as quartiles with Tukey whiskers.
+Tumour mutational burden against fraction of the genome altered, over every sample of a TP53-mutant cohort. The figure is a density field: the samples are counted into a 240x160 grid, and only the occupied cells travel, plus the outliers — the cases in the sparse cells at the fringe, drawn as points. Pearson, Spearman and the fitted line are computed over EVERY sample inside ClickHouse, so they describe the whole cohort rather than the points that happened to be painted last. The second view groups the same measure by TP53 mutation class, as quartiles with Tukey whiskers over a violin, with the values beyond the whiskers drawn as points.
 
 ```json
 {
@@ -1916,7 +1935,7 @@ Tumour mutational burden against fraction of the genome altered, over every samp
 }
 ```
 
-### Example 17: Highlight cohorts on a plot: KRAS G12C and STK11 against 25,000 patients
+### Example 17: Point layers on a plot: KRAS G12C and STK11 against 25,000 patients
 
 Age against tumour mutational burden for every patient in MSK-CHORD (24,947 with both), drawn as a grey density. KRAS G12C (1,113 patients) and STK11-mutant (1,206) are drawn over it as points, each in its own colour. The coefficients and the fitted line are still those of the whole cohort. The second view groups the same measure by cancer type: KRAS G12C is again points, while TP53-mutant patients (13,105) are too many for points, so they are drawn as a narrow box per group beside the cohort's own box, and the caption says why.
 
@@ -1955,6 +1974,7 @@ Age against tumour mutational burden for every patient in MSK-CHORD (24,947 with
   "views": [
     {
       "kind": "plot",
+      "unit": "patient",
       "cohorts": [
         "All patients"
       ],
@@ -1966,13 +1986,21 @@ Age against tumour mutational burden for every patient in MSK-CHORD (24,947 with
         "source": "clinical",
         "attribute": "TMB_NONSYNONYMOUS"
       },
-      "highlight": [
-        "KRAS G12C",
-        "STK11 mut"
+      "points": [
+        {
+          "rule": "outliers"
+        },
+        {
+          "cohort": "KRAS G12C"
+        },
+        {
+          "cohort": "STK11 mut"
+        }
       ]
     },
     {
       "kind": "plot",
+      "unit": "patient",
       "cohorts": [
         "All patients"
       ],
@@ -1984,16 +2012,20 @@ Age against tumour mutational burden for every patient in MSK-CHORD (24,947 with
         "source": "clinical",
         "attribute": "TMB_NONSYNONYMOUS"
       },
-      "highlight": [
-        "KRAS G12C",
-        "TP53 mut"
+      "points": [
+        {
+          "cohort": "KRAS G12C"
+        },
+        {
+          "cohort": "TP53 mut"
+        }
       ]
     }
   ]
 }
 ```
 
-### Example 18: A highlight that reaches beyond the plotted cohort
+### Example 18: A cohort layer that reaches beyond the plotted cohort
 
 Non-small cell lung cancer in MSK-CHORD (7,809 patients), with KRAS G12C highlighted. 916 of the 1,113 KRAS G12C patients have a lung sample; the other 197 are outside the plotted cohort, and the caption says so. The second view counts samples instead of patients, so a patient with two sequenced samples is drawn twice.
 
@@ -2025,6 +2057,7 @@ Non-small cell lung cancer in MSK-CHORD (7,809 patients), with KRAS G12C highlig
   "views": [
     {
       "kind": "plot",
+      "unit": "patient",
       "cohorts": [
         "NSCLC"
       ],
@@ -2036,8 +2069,10 @@ Non-small cell lung cancer in MSK-CHORD (7,809 patients), with KRAS G12C highlig
         "source": "clinical",
         "attribute": "TMB_NONSYNONYMOUS"
       },
-      "highlight": [
-        "KRAS G12C"
+      "points": [
+        {
+          "cohort": "KRAS G12C"
+        }
       ]
     },
     {
@@ -2054,15 +2089,17 @@ Non-small cell lung cancer in MSK-CHORD (7,809 patients), with KRAS G12C highlig
         "source": "clinical",
         "attribute": "TMB_NONSYNONYMOUS"
       },
-      "highlight": [
-        "KRAS G12C"
+      "points": [
+        {
+          "cohort": "KRAS G12C"
+        }
       ]
     }
   ]
 }
 ```
 
-### Example 19: Highlights across two studies
+### Example 19: Point layers across two studies
 
 TCGA lung adenocarcinoma and squamous cell carcinoma pooled (1,053 patients). KRAS-mutant (175) and TP53-mutant (699) patients are drawn over the pooled plot of age against tumour mutational burden; each study returns its own highlighted cases. In the second view, KRAS-mutant patients are drawn over the TMB distribution by sex. If any study in a highlight could not show individual cases, the whole highlight would be drawn as an aggregate, never half points and half cells.
 
@@ -2105,6 +2142,7 @@ TCGA lung adenocarcinoma and squamous cell carcinoma pooled (1,053 patients). KR
   "views": [
     {
       "kind": "plot",
+      "unit": "patient",
       "cohorts": [
         "Lung (TCGA)"
       ],
@@ -2116,13 +2154,18 @@ TCGA lung adenocarcinoma and squamous cell carcinoma pooled (1,053 patients). KR
         "source": "clinical",
         "attribute": "TMB_NONSYNONYMOUS"
       },
-      "highlight": [
-        "KRAS mut",
-        "TP53 mut"
+      "points": [
+        {
+          "cohort": "KRAS mut"
+        },
+        {
+          "cohort": "TP53 mut"
+        }
       ]
     },
     {
       "kind": "plot",
+      "unit": "patient",
       "cohorts": [
         "Lung (TCGA)"
       ],
@@ -2134,8 +2177,10 @@ TCGA lung adenocarcinoma and squamous cell carcinoma pooled (1,053 patients). KR
         "source": "clinical",
         "attribute": "TMB_NONSYNONYMOUS"
       },
-      "highlight": [
-        "KRAS mut"
+      "points": [
+        {
+          "cohort": "KRAS mut"
+        }
       ]
     }
   ]
@@ -2166,6 +2211,7 @@ Non-small cell lung cancer in MSK-CHORD (7,809 patients). The first view groups
   "views": [
     {
       "kind": "plot",
+      "unit": "patient",
       "cohorts": [
         "NSCLC"
       ],
@@ -2184,7 +2230,8 @@ Non-small cell lung cancer in MSK-CHORD (7,809 patients). The first view groups
       "cohorts": [
         "NSCLC"
       ],
-      "points": false,
+      "allPoints": false,
+      "points": [],
       "x": {
         "source": "clinical",
         "attribute": "SAMPLE_TYPE"
@@ -4071,6 +4118,7 @@ Runs on custom data: `spectrum-sc-composition` (SPECTRUM scRNA: cell-type compos
     },
     {
       "kind": "plot",
+      "unit": "patient",
       "cohorts": [
         "all patients"
       ],
@@ -4085,6 +4133,7 @@ Runs on custom data: `spectrum-sc-composition` (SPECTRUM scRNA: cell-type compos
     },
     {
       "kind": "plot",
+      "unit": "patient",
       "cohorts": [
         "all patients"
       ],
@@ -4099,6 +4148,7 @@ Runs on custom data: `spectrum-sc-composition` (SPECTRUM scRNA: cell-type compos
     },
     {
       "kind": "plot",
+      "unit": "patient",
       "cohorts": [
         "all patients"
       ],
@@ -4113,6 +4163,7 @@ Runs on custom data: `spectrum-sc-composition` (SPECTRUM scRNA: cell-type compos
     },
     {
       "kind": "plot",
+      "unit": "patient",
       "cohorts": [
         "all patients"
       ],
diff --git a/docs/plot-case-level.md b/docs/plot-case-level.md
index d06f15a4..bc2f1067 100644
--- a/docs/plot-case-level.md
+++ b/docs/plot-case-level.md
@@ -1,125 +1,112 @@
-# Plot view: case-level colouring (gene alterations, clinical values)
+# Plot view: case-level points, colouring and interaction
 
-Status: **proposed, not started.** Written so a later session can pick it up cold. Read the
-whole file, then `docs/DATA-BOUNDARY.md` (this plan leans on it throughout), then start at
-"Phases" step 1.
+Status: in progress on `session/plots`. Written so a later session can pick it up cold. Read the
+whole file, then `docs/DATA-BOUNDARY.md` (this plan leans on it throughout).
 
 ## The gap
 
-cBioPortal's results-view **Plots tab** colours each case. Its rules are in
-`src/shared/components/plots/PlotsTabUtils.tsx`, `makeScatterPlotPointAppearance`, in the
-reference clone at `~/cbioportal-frontend`:
+cBioPortal's results-view **Plots tab** draws every sample as a point and makes each one
+interactive. Its rules are in `src/shared/components/plots/PlotsTabUtils.tsx`
+(`makeScatterPlotPointAppearance`) in the reference clone at `~/cbioportal-frontend`:
 
 - **Fill = mutation type** of the case's mutation in the chosen gene, using the oncoprint's
-  palette. With driver annotation on, drivers and VUS get separate shades
-  (`oncoprintMutationTypeToAppearanceDrivers`).
-- **Border = copy number or structural variant**: amplification red, deep deletion blue
-  (`CNA_COLOR_AMP` / `CNA_COLOR_HOMDEL`), SV its own colour (`getCnaAndSvAppearance`).
-- **"Not profiled"** has its own look (`notProfiledMutationsAppearance`), distinct from "not
-  mutated". This is the panel-aware distinction this repo already insists on elsewhere.
-- **Clinical colouring** (`ColoringType.ClinicalData`) replaces all of the above.
-- Every point has a hover tooltip naming the sample, and cases can be searched and highlighted.
-- The portal fetches every case to the browser and, for big scatters, merges nearby points
-  with a quadtree (`downsampleByGrouping.ts`).
-
-Our plot view (`lib/plot.ts`, `lib/federation.ts` `plot()`/`plotPoints()`, `plotSvg` in
-`lib/view-svg.ts`) is aggregate-first:
-
-- A scatter is a density grid, a box is quartiles plus a violin, a table is counts.
-- Colour and ring exist **only on box plots**.
-- Case-level points exist only as the box plot's overlay: `PatientLevelResolver.plotPoints`,
-  capped at `POINTS_CAP` = 5,000.
-
-So a scatter can't be coloured by gene alteration at all.
-
-## Constraints that shape the design
-
-- **The patient-data boundary** (`docs/DATA-BOUNDARY.md`, invariant 10). Only a patient-level
-  participant can return case rows. `plotPoints` lives on `PatientLevelResolver` alone, and
-  `isPatientLevel` is the type guard; this is the "missing method, not a flag" rule. An
-  aggregate-only or remote participant must still get a useful, honest answer.
-- **Nothing is dropped without saying so** (`CLAUDE.md`, UI conventions). If points are merged,
-  or the plot falls back to density, the caption says so and says why. A legend lists every
-  category it colours, or pools the rest into a disclosed "other" (`legendFor`, `COLOR_CAP`).
-- **Panel-aware profiling.** "Not profiled" is a category of its own, never folded into "not
-  mutated". Reuse the oncoprint's coverage logic; don't re-derive it.
-- **One renderer per figure.** Chat and MCP need a static image, so the server SVG stays. An
-  interactive client renderer is added *next to* it, the way the oncoprint has both. The
-  interactive version is not a replacement.
-- **The document holds what changes the picture** (invariant 9). A colour choice goes in the
-  view (`colorBy`); hover and highlighted cases stay in browser state.
-
-## Design: two tiers
-
-### Tier 1: case-level, for entitled participants
-
-When every site in the plot is patient-level (the common single-study case):
-
-1. **One row per case**, from a generalised `plotPoints` that covers scatter and table as well
-   as box. Each row carries:
-   - `id` (sample or patient id; allowed here because the participant is entitled)
-   - `x` and `y` (numbers, or categories for a categorical axis)
-   - `fill`: the mutation class
-   - `stroke`: the CNA/SV class
-   - optionally a clinical colour value
-2. **Colour by gene**, as a new colour source mirroring the portal's `ColoringType`:
-   `colorBy: { source: "gene", gene, show?: ["mutation", "cna", "sv"] }`. Computed per case in
-   SQL, in one pass beside the axis selects:
-   - `fill`: the case's highest-priority mutation in the gene, using the oncoprint's mutation
-     priority (`lib/oncoprint-style.ts`, so nothing forks), split driver/VUS by the pinned
-     OncoKB, as the oncoprint and the lollipop do.
-   - `stroke`: amplification / deep deletion / SV / none.
-   - Not profiled for the gene (panel coverage) is its own class.
-   - Clinical `colorBy` stays as it is and replaces gene colouring, as on the portal.
-3. **Payload and the cap.** About 30 bytes a case gives roughly 0.75 MB for MSK-CHORD's 25k
-   samples, which is fine. GENIE's 290k would be about 9 MB, which is not. Raise the case cap
-   (start at ~50k and measure). Above the cap, or on any aggregate-only site, the plot uses
-   tier 2 and says so. Don't copy the portal's silent quadtree merge. If merging is ever
-   added, each merged glyph must state how many cases it stands for.
-4. **Rendering.** Add a client `PlotFigure` on a `<canvas>`, like `OncoprintFigure`: points by
-   fill and stroke, hover showing the sample id, the axis values and the alterations,
-   search-to-highlight, and a legend of the classes actually present. `plotSvg` keeps drawing
-   the same points for chat and MCP (SVG up to a few thousand, density above that, with a
-   caption).
-
-### Tier 2: aggregates, for everyone else
-
-For federated, aggregate-only or over-cap plots, colour still works, as **counts per (bin,
-category)**. That's an aggregate, so any participant can answer it, and sites pool by summing
-against the shared extent the federated scatter already negotiates (`plotExtent` /
-`plotBinCounts`):
-
-- **Scatter:** each density cell is coloured by its commonest class. Its mix shows on hover,
-  and the caption states the share of cases in mixed cells.
-- **Box:** unchanged. The violin already splits by colour class.
-- **Table:** each cell shows its class split as a small stacked bar.
-- The site applies the suppression floor before returning (`minCount`, as `lollipopCte` does)
-  wherever a (bin, category) count could single someone out.
-
-## Phases
-
-Do these in order; each one ships on its own. Run `npm test` and a focused Playwright check
-per phase, not the full gate each time.
-
-1. **Per-case gene classes, in SQL.** A builder next to `plotPointsSql` that produces `fill`
-   and `stroke` per case for one gene: mutation priority, driver split, CNA, SV, not profiled.
-   Unit tests for the class rules. A boundary test that only `PatientLevelResolver` can call it.
-2. **Scatter points, tier 1.** Generalise `plotPoints` beyond box. Add `colorBy.source =
-   "gene"` to the document, `validateAxis` and `lib/dsl-reference.ts` (then `npm run
-   docs:gen`). Have `plotSvg` draw coloured points for a small cohort. Check against the
-   portal: for one study and gene, the per-class case counts must match its Plots tab.
-3. **The interactive `PlotFigure`** (canvas): hover with sample id, search/highlight, legend.
-   The app uses it; chat and MCP keep the SVG.
-4. **Borders and clinical colouring on scatter**: CNA/SV strokes, the not-profiled look,
-   clinical colour, `ringBy` carried over.
-5. **Tier 2**: `(bin, category)` count builders (boundary-swept), pooled across sites,
-   rendered as dominant-class cells with the mix on hover. Captions for every fallback.
+  palette. With driver annotation on, drivers and VUS get separate shades.
+- **Border = copy number or structural variant**: amplification red, deep deletion blue, SV its
+  own colour. SV takes precedence over CNA.
+- **"Not profiled"** has its own look, distinct from "not mutated".
+- **Clinical colouring** replaces all of the above (categorical, or a numeric gradient).
+- Every point has a hover tooltip (sample link, both values, mutations, CNA, SV), cases can be
+  searched by id or protein change and highlighted, a legend entry click highlights its class,
+  and a brush on the scatter selects cases for the study view.
+- A point is always a **sample**: a patient attribute is copied to each of its samples, and the
+  only patient-aware option is "connect samples from the same patient" on a box plot.
+- Everything is Victory SVG, one DOM node per point, with no cap and no downsampling.
+
+Our plot view (`lib/plot.ts`, `lib/views/plot.ts`, `lib/federation.ts`, the figure in
+`lib/figures/plot.ts`, the controls in `app/lab/plot-controls.tsx`) is aggregate-first: a scatter is
+a density grid, a box is quartiles plus a violin, a table is counts.
+
+## The model: every point when it is a drawing, the cases that matter when it is not
+
+Past a few thousand cases a scatter is a density picture whatever renders it: points overlap and
+a hover lands on an arbitrary one. So:
+
+- **A point is a sample** by default, as on the portal. `unit: "patient"` makes it a patient and
+  combines the patient's samples by a stated rule: a number is their mean, a category their common
+  value or "Multiple" where they differ, an alteration counts if any sample has it, and the caption
+  says how many patients had more than one sample.
+- **At or under `POINTS_CAP` (5,000), every case is a point** (`allPoints`, default true), on a
+  scatter as on a box — the portal's picture, and what most single studies get.
+- **Over the cap, the crowd is density, and point layers draw chosen subsets in colour over it.**
+  `points` is an ordered list of at most four layers (`lib/plot-layers.ts`):
+  - `{rule:"outliers"}` (the default): where the plotted cohort is density, a box's values beyond
+    its whiskers (the violin then stops at the whiskers) and a single study's scatter's cases in
+    sparse cells (every cell holding at most `k` cases, `k` the largest value up to
+    `OUTLIER_CELL_MAX` that fits the budget; those cells are left unshaded under their points).
+  - `{rule:"extremes", axis, n}`: the `n` highest and lowest values of a numeric axis, per group
+    on a box. Each study returns its own top `n`, so the pooled top `n` is exact.
+  - `{rule:"trend", n}`: on a scatter, the `n` cases furthest from the fitted line.
+  - `{cohort}`: the plotted cohort's cases that are also in that cohort (once called a highlight).
+  `[]` draws none. Every layer shares one `POINTS_CAP` budget; a case two layers share is drawn by
+  the first. A layer is never cut to its first cases: a cohort layer past the budget becomes density
+  cells or a box per group, a rule layer is not drawn, and the caption says which and why. With a
+  box's cases coloured by a category, a layer is a ring round the case.
+- **Nothing is dropped silently.** `PlotData.pointSet` says whether the plotted cohort's own cases
+  are points; each `PlotLayer` says what it holds, how many it drew, how many an earlier layer drew,
+  and why it is not points when it is not. The caption says all of it in words, and that ties at a
+  ranked layer's cut are broken by case id.
+- **The boundary.** Only `PatientLevelResolver` returns points (`plotPoints`, `plotScatterPoints`,
+  `plotRankedPoints`, `plotHighlightPoints`), and only it may build their SQL. An aggregate-only
+  participant gets the density, its rule layers are not drawn, its cohort layers are aggregates,
+  and the caption says why.
+- **The document holds the rules** (`unit`, `allPoints`, `points` — invariant 9: they change the
+  server SVG). Hover, search text, a legend-click highlight and a brush stay in browser state.
+- **SVG stays.** Canvas would mean a second renderer to keep in step with MCP, the exports and the
+  figure lint, for point counts nobody can tell apart. Interaction (phase 3) goes through one hover
+  overlay over the SVG, not one listener per circle.
+
+## Order of work
+
+One commit per item; `npm test` and a focused check per item; the gate before each push.
+
+1. **Done.** Point subsets on the server: every case at or under the cap, density plus outliers
+   over it; `pointSet` and captions; the box axis spans the points it draws; one point radius.
+2. **Done.** The legacy Plots tab's layout: each axis defined in a block of a sidebar, Swap axes,
+   the figure beside it (`PlotControls`, shared by the lab card and the Results page).
+3. **Done.** A point is a sample by default; patient mode combines samples by a stated rule.
+4. **Done.** Point layers (above), replacing `highlight`, with the sidebar's Points section.
+5. **Measure the cap.** SVG draw time and payload at 5k, 10k, 20k and 50k points on msk_chord;
+   set `POINTS_CAP` from it.
+6. **Multiple genes.** An alteration axis whose OQL has several statements gets one category per
+   statement (overlaps as their own category, never assigned arbitrarily), and commas separate
+   statements as well as `;` and newlines.
+7. **Colour by gene per case** (phase 2). `colorBy: { source: "gene", gene }`: fill from the case's
+   highest-priority mutation (oncoprint priority, driver/VUS by the pinned OncoKB), ring from
+   CNA/SV, "not profiled" its own class (panel coverage, reuse the oncoprint's). On scatters too;
+   the rare classes become a point layer over the cap. Check per-class counts against the portal's
+   Plots tab for one study and gene.
+8. **Interaction** (phase 3): one overlay over the SVG maps the cursor to the nearest point (a grid
+   index over the drawn points); hover tooltip (sample id linking to the patient view, values,
+   alterations), legend-click highlight, case-id / protein-change search whose matches come back
+   from the server as a layer.
+9. **Brush and drill-down** (phase 4): a region or a cell returns its cases as a layer; "N cases →
+   study view" built from the full list on the server.
+10. **Sidebar parity** (phase 5): "same gene", Driver vs VUS and VAF axes, box category filter and
+    sort-by-median, regression line toggle, R² and the equation, connect samples from the same
+    patient.
+
+Backlog: waterfall ("ordered samples"), generic assays and SV axes, bar charts for two
+categoricals, the examples bar, SVG/PNG/data export, a method record for the plot's correlations
+(it is on the method-check exempt list as "no statistic", which it is not), a horizontal box (a box
+is always drawn with its categories across today).
 
 ## Open questions
 
-- **The cap**: 50k to start? Measure the SQL time and payload on GENIE before deciding.
+- **`OUTLIER_CELL_MAX`**: 3 on the default 240×160 grid. A coarser grid makes "sparse" mean
+  more; revisit if `bins` becomes a UI control.
+- **Federated scatter outliers**: a pooled scatter's sparse cells are known only after pooling, so
+  it needs a second pass per site with the pooled cell list; until then that layer says so.
 - **Driver definition**: OncoKB-only here; the portal also counts hotspots and custom
   annotations. Say so in the legend, as the lollipop's note already does.
-- **Multiple genes**: the portal colours by one gene at a time. Keep it to one unless asked.
-- **Sample vs patient unit**: in patient mode, which of a patient's samples sets the colour?
-  Probably the highest-priority alteration across them. Decide and caption it.
+- **Sample vs patient unit for colour**: in patient mode, which of a patient's samples sets the
+  colour? Probably the highest-priority alteration across them. Decide and caption it.
diff --git a/e2e.cjs b/e2e.cjs
index 323499fb..f178f942 100644
--- a/e2e.cjs
+++ b/e2e.cjs
@@ -545,6 +545,53 @@ async function main() {
       } catch (e) { geneEdit = String(e.message).split("\n")[0]; }
       ok("a view's genes can be changed without editing JSON", geneOk, geneEdit);
 
+      // A plot's axes are defined in a sidebar, as on cBioPortal's Plots tab: a horizontal block,
+      // Swap axes, a vertical block, each field named, the figure beside them. Swap rewrites the
+      // document's x and y; the fields stay on one control height, as a toolbar's do.
+      let sideWhat = "no plot rendered", sideOk = false;
+      try {
+        await page.goto(BASE + "/lab?tab=analysis&doc=" + encodeURIComponent(Buffer.from(JSON.stringify({
+          study: "msk_chord_2024",
+          cohorts: { "TP53 mut": { all: [{ kind: "oql", q: "TP53: MUT" }] } },
+          views: [{ kind: "plot", cohorts: ["TP53 mut"], unit: "sample",
+            x: { source: "clinical", attribute: "MUTATION_COUNT" }, y: { source: "clinical", attribute: "FRACTION_GENOME_ALTERED" } }]
+        })).toString("base64")));
+        await page.waitForSelector(".plot-side", { timeout: 300000 });
+        await page.waitForSelector(".figwidth svg", { timeout: 300000 });
+        const blocks = await page.locator(".plot-side .plot-axis h3").allInnerTexts();
+        const names = await page.locator(".plot-side .plot-axis").first().locator(".axfield-name").allInnerTexts();
+        const side = await page.locator(".plot-side").boundingBox(), fig = await page.locator(".figwidth").first().boundingBox();
+        const beside = side && fig && fig.x >= side.x + side.width - 1;
+        const heights = await page.locator(".plot-side [data-slot=select-trigger]").evaluateAll((els) => [...new Set(els.map((e) => Math.round(e.getBoundingClientRect().height)))]);
+        await page.locator(".plot-side .plot-swap").click();
+        await page.waitForFunction(() => {
+          try { const v = JSON.parse(document.querySelector("#docjson").value).views[0];
+            return v.x.attribute === "FRACTION_GENOME_ALTERED" && v.y.attribute === "MUTATION_COUNT"; } catch { return false; }
+        }, null, { timeout: 30000 });
+        sideOk = blocks.join(",") === "Horizontal axis,Vertical axis" && names.join(",") === "Data type,Clinical attribute" && !!beside && heights.length === 1;
+        sideWhat = "blocks " + blocks.join(",") + "; fields " + names.join(",") + "; figure beside: " + beside + "; select heights " + heights.join(",") + "; swap rewrote x/y";
+      } catch (e) { sideWhat = String(e.message).split("\n")[0]; }
+      ok("a plot's axes are defined in a sidebar beside the figure, and Swap axes swaps them", sideOk, sideWhat);
+
+      // Point layers: the sidebar lists the view's layers (the outliers by default) and adds one to
+      // the document; the figure's key then names it.
+      let layerWhat = "no plot rendered", layerOk = false;
+      try {
+        const chips = async () => page.locator(".plot-side .plot-layer").allInnerTexts();
+        const before = await chips();
+        await page.locator(".plot-side .plot-layers [role=combobox]").click();
+        await page.locator("[role=option]", { hasText: "furthest from the fit" }).click();
+        await page.waitForFunction(() => {
+          try { const v = JSON.parse(document.querySelector("#docjson").value).views[0];
+            return Array.isArray(v.points) && v.points.some((l) => l.rule === "trend"); } catch { return false; }
+        }, null, { timeout: 30000 });
+        await page.waitForFunction(() => /furthest from the fit \(/.test(document.querySelector(".figwidth svg")?.textContent || ""), null, { timeout: 300000 });
+        const after = await chips();
+        layerOk = before.length === 1 && /outliers/.test(before[0]) && after.length === 2;
+        layerWhat = "before " + JSON.stringify(before) + " -> after " + JSON.stringify(after) + "; the key names the new layer";
+      } catch (e) { layerWhat = String(e.message).split("\n")[0]; }
+      ok("a plot's point layers are listed in the sidebar, and adding one draws it with a key entry", layerOk, layerWhat);
+
       // The oncoprint's gear keeps ONLY the link out to cBioPortal; genes moved
       // to a named button and a modal, so the gear is not where editing hides.
       let gearSplit = "no oncoprint rendered", gearOk = false;
diff --git a/lib/dsl-reference.ts b/lib/dsl-reference.ts
index 7955609f..af3aa848 100644
--- a/lib/dsl-reference.ts
+++ b/lib/dsl-reference.ts
@@ -369,7 +369,7 @@ export const EXAMPLES: DslExample[] = [
     title: "A plot of 13,000 samples, drawn as density",
     demonstrates: "The portal's Plots tab fetches every point to the browser. This one counts them in the database and sends the counts, so the same picture draws for a hundred cases or four hundred thousand.",
     tags: ["scale"],
-    note: "Tumour mutational burden against fraction of the genome altered, over every sample of a TP53-mutant cohort. The figure is a density field: the samples are counted into a 240x160 grid, and only the occupied cells travel. Pearson, Spearman and the fitted line are computed over EVERY sample inside ClickHouse, so they describe the whole cohort rather than the points that happened to be painted last. The second view groups the same measure by TP53 mutation class, as quartiles with Tukey whiskers.",
+    note: "Tumour mutational burden against fraction of the genome altered, over every sample of a TP53-mutant cohort. The figure is a density field: the samples are counted into a 240x160 grid, and only the occupied cells travel, plus the outliers — the cases in the sparse cells at the fringe, drawn as points. Pearson, Spearman and the fitted line are computed over EVERY sample inside ClickHouse, so they describe the whole cohort rather than the points that happened to be painted last. The second view groups the same measure by TP53 mutation class, as quartiles with Tukey whiskers over a violin, with the values beyond the whiskers drawn as points.",
     doc: {
       study: "msk_chord_2024",
       cohorts: {
@@ -386,9 +386,9 @@ export const EXAMPLES: DslExample[] = [
     }
   },
   {
-    title: "Highlight cohorts on a plot: KRAS G12C and STK11 against 25,000 patients",
-    demonstrates: "A `highlight` on a plot view: other cohorts drawn over the plotted one, each in its own colour, so the cases you care about are visible against a density that no longer has individual points.",
-    tags: ["highlight", "scale"],
+    title: "Point layers on a plot: KRAS G12C and STK11 against 25,000 patients",
+    demonstrates: "`points` on a plot view: subsets drawn in their own colours over the plotted cohort — here two cohorts, after the outliers — so the cases you care about are visible against a density of everyone else.",
+    tags: ["points", "scale"],
     note: "Age against tumour mutational burden for every patient in MSK-CHORD (24,947 with both), drawn as a grey density. KRAS G12C (1,113 patients) and STK11-mutant (1,206) are drawn over it as points, each in its own colour. The coefficients and the fitted line are still those of the whole cohort. The second view groups the same measure by cancer type: KRAS G12C is again points, while TP53-mutant patients (13,105) are too many for points, so they are drawn as a narrow box per group beside the cohort's own box, and the caption says why.",
     doc: {
       study: "msk_chord_2024",
@@ -399,21 +399,21 @@ export const EXAMPLES: DslExample[] = [
         "TP53 mut": { all: [{ kind: "oql", q: "TP53: MUT" }] }
       },
       views: [
-        { kind: "plot", cohorts: ["All patients"],
+        { kind: "plot", unit: "patient", cohorts: ["All patients"],
           x: { source: "clinical", attribute: "CURRENT_AGE_DEID" },
           y: { source: "clinical", attribute: "TMB_NONSYNONYMOUS" },
-          highlight: ["KRAS G12C", "STK11 mut"] },
-        { kind: "plot", cohorts: ["All patients"],
+          points: [{ rule: "outliers" }, { cohort: "KRAS G12C" }, { cohort: "STK11 mut" }] },
+        { kind: "plot", unit: "patient", cohorts: ["All patients"],
           x: { source: "clinical", attribute: "CANCER_TYPE" },
           y: { source: "clinical", attribute: "TMB_NONSYNONYMOUS" },
-          highlight: ["KRAS G12C", "TP53 mut"] }
+          points: [{ cohort: "KRAS G12C" }, { cohort: "TP53 mut" }] }
       ]
     }
   },
   {
-    title: "A highlight that reaches beyond the plotted cohort",
-    demonstrates: "A highlight's cases are the plotted cohort's cases that are also in it. Patients of the highlight outside the plotted cohort are counted in the caption, not drawn.",
-    tags: ["highlight"],
+    title: "A cohort layer that reaches beyond the plotted cohort",
+    demonstrates: "A cohort layer's cases are the plotted cohort's cases that are also in it. Patients of the layer's cohort outside the plotted cohort are counted in the caption, not drawn.",
+    tags: ["points"],
     note: "Non-small cell lung cancer in MSK-CHORD (7,809 patients), with KRAS G12C highlighted. 916 of the 1,113 KRAS G12C patients have a lung sample; the other 197 are outside the plotted cohort, and the caption says so. The second view counts samples instead of patients, so a patient with two sequenced samples is drawn twice.",
     doc: {
       study: "msk_chord_2024",
@@ -422,21 +422,21 @@ export const EXAMPLES: DslExample[] = [
         "KRAS G12C": { all: [{ kind: "oql", q: "KRAS: G12C" }] }
       },
       views: [
-        { kind: "plot", cohorts: ["NSCLC"],
+        { kind: "plot", unit: "patient", cohorts: ["NSCLC"],
           x: { source: "clinical", attribute: "CURRENT_AGE_DEID" },
           y: { source: "clinical", attribute: "TMB_NONSYNONYMOUS" },
-          highlight: ["KRAS G12C"] },
+          points: [{ cohort: "KRAS G12C" }] },
         { kind: "plot", unit: "sample", cohorts: ["NSCLC"],
           x: { source: "clinical", attribute: "SAMPLE_TYPE" },
           y: { source: "clinical", attribute: "TMB_NONSYNONYMOUS" },
-          highlight: ["KRAS G12C"] }
+          points: [{ cohort: "KRAS G12C" }] }
       ]
     }
   },
   {
-    title: "Highlights across two studies",
-    demonstrates: "A highlight on a federated plot: each study answers for its own cases, and the points are pooled onto one figure.",
-    tags: ["highlight"],
+    title: "Point layers across two studies",
+    demonstrates: "Point layers on a federated plot: each study answers for its own cases, and the points are pooled onto one figure.",
+    tags: ["points"],
     note: "TCGA lung adenocarcinoma and squamous cell carcinoma pooled (1,053 patients). KRAS-mutant (175) and TP53-mutant (699) patients are drawn over the pooled plot of age against tumour mutational burden; each study returns its own highlighted cases. In the second view, KRAS-mutant patients are drawn over the TMB distribution by sex. If any study in a highlight could not show individual cases, the whole highlight would be drawn as an aggregate, never half points and half cells.",
     doc: {
       study: "luad_tcga_pan_can_atlas_2018",
@@ -446,14 +446,14 @@ export const EXAMPLES: DslExample[] = [
         "TP53 mut": { studies: ["luad_tcga_pan_can_atlas_2018", "lusc_tcga_pan_can_atlas_2018"], all: [{ kind: "oql", q: "TP53: MUT" }] }
       },
       views: [
-        { kind: "plot", cohorts: ["Lung (TCGA)"],
+        { kind: "plot", unit: "patient", cohorts: ["Lung (TCGA)"],
           x: { source: "clinical", attribute: "AGE" },
           y: { source: "clinical", attribute: "TMB_NONSYNONYMOUS" },
-          highlight: ["KRAS mut", "TP53 mut"] },
-        { kind: "plot", cohorts: ["Lung (TCGA)"],
+          points: [{ cohort: "KRAS mut" }, { cohort: "TP53 mut" }] },
+        { kind: "plot", unit: "patient", cohorts: ["Lung (TCGA)"],
           x: { source: "clinical", attribute: "SEX" },
           y: { source: "clinical", attribute: "TMB_NONSYNONYMOUS" },
-          highlight: ["KRAS mut"] }
+          points: [{ cohort: "KRAS mut" }] }
       ]
     }
   },
@@ -468,10 +468,10 @@ export const EXAMPLES: DslExample[] = [
         "NSCLC": { all: [{ kind: "clinical", attribute: "CANCER_TYPE", values: ["Non-Small Cell Lung Cancer"], per: "sample" }] }
       },
       views: [
-        { kind: "plot", cohorts: ["NSCLC"],
+        { kind: "plot", unit: "patient", cohorts: ["NSCLC"],
           x: { source: "alteration", oql: "STK11: MUT; KEAP1: MUT" },
           y: { source: "clinical", attribute: "TMB_NONSYNONYMOUS" } },
-        { kind: "plot", unit: "sample", cohorts: ["NSCLC"], points: false,
+        { kind: "plot", unit: "sample", cohorts: ["NSCLC"], allPoints: false, points: [],
           x: { source: "clinical", attribute: "SAMPLE_TYPE" },
           y: { source: "clinical", attribute: "TMB_NONSYNONYMOUS" },
           colorBy: { source: "alteration", oql: "STK11: MUT; KEAP1: MUT" } }
@@ -1047,16 +1047,16 @@ export const EXAMPLES: DslExample[] = [
         { kind: "oncoprint", cohorts: ["all patients"], genes: ["TP53", "BRCA1", "BRCA2", "CCNE1", "MYC", "CDK12"],
           clinical: ["CONSENSUS_SIGNATURE", "custom:spectrum-sc-cancer/CA_6P_STATUS", "custom:spectrum-sc-tnk/TNK_DYSFUNC", "custom:spectrum-sc-tnk/TNK_NAIVE_CM"],
           sort: ["CONSENSUS_SIGNATURE"] },
-        { kind: "plot", cohorts: ["all patients"],
+        { kind: "plot", unit: "patient", cohorts: ["all patients"],
           x: { source: "clinical", attribute: "CONSENSUS_SIGNATURE" },
           y: { source: "clinical", attribute: "custom:spectrum-sc-tnk/TNK_DYSFUNC" } },
-        { kind: "plot", cohorts: ["all patients"],
+        { kind: "plot", unit: "patient", cohorts: ["all patients"],
           x: { source: "clinical", attribute: "CONSENSUS_SIGNATURE" },
           y: { source: "clinical", attribute: "custom:spectrum-sc-tnk/TNK_NAIVE_CM" } },
-        { kind: "plot", cohorts: ["all patients"],
+        { kind: "plot", unit: "patient", cohorts: ["all patients"],
           x: { source: "clinical", attribute: "CONSENSUS_SIGNATURE" },
           y: { source: "clinical", attribute: "custom:spectrum-sc-cancer/ADX_CA_JAKSTAT" } },
-        { kind: "plot", cohorts: ["all patients"],
+        { kind: "plot", unit: "patient", cohorts: ["all patients"],
           x: { source: "clinical", attribute: "custom:spectrum-sc-cancer/CA_JAKSTAT" },
           y: { source: "clinical", attribute: "custom:spectrum-sc-tnk/TNK_JAKSTAT" } },
         { kind: "plot", unit: "sample", cohorts: ["all patients"],
@@ -1522,7 +1522,7 @@ patient — so the arm counts summing to more than the base cohort is expected,
 | \`logistic\` | \`outcome:axis, outcomeEvent?:"<level>", covariates:[axis, ...(max 8)], cohorts:[names]\` | multivariate logistic regression: a BINARY outcome (not time-to-event \u2014 no endpoint/months convention here) regressed on several covariates at once, reported as odds ratios with Wald confidence intervals, drawn as a forest plot the same shape as \`cox\`'s. \`outcome\` is a plot axis, exactly like a covariate (clinical, molecular, or alteration status). A categorical outcome (a clinical attribute, or an alteration axis) needs \`outcomeEvent\` naming which observed value counts as the event (1) \u2014 every other observed value collapses into "not event" (0), and which values got collapsed is disclosed in the caveat; omitting it, or naming a value never observed, is refused with the actual observed values listed rather than guessed at. A numeric outcome must already be coded exactly 0/1 (refused otherwise) and must NOT be given \`outcomeEvent\`. Covariates use the exact same dummy-coding and reference-level rules as \`cox\` (see above): a mutated-vs-not axis defaults to \`\"Not mutated\"\`, others default to the most frequent level, \`reference\` overrides either. Same patient-level-only boundary as \`cox\` |
 | \`course\` | \`eventTypes:[\u22646], anchor?:{eventType,key?,value?,occurrence?}, binMonths?:3, fromMonths?:-12, toMonths?:60, cohorts:[names]\` | the **clinical course**: per time bin, the share of the cohort in each event state. Two things it refuses to fake. (1) The denominator is the patients still under observation in that bin \u2014 first recorded event to last contact (the later of their last event and their OS follow-up) \u2014 never the whole cohort, which would make a curve fall merely because follow-up ran out. (2) \`anchor\` is optional for one study but **required across studies**: day 0 is birth in some studies and first sequencing in others, and nothing in the schema records which, so raw day 0 compares incomparable clocks. Event types that carry real durations are drawn as a state the patient is IN; the rest as an event that HAPPENED \u2014 read from the data, not from the name. Bins are half-open [t, t+w). Event-name spellings differing only in case are folded (\`Treatment\`/\`TREATMENT\`) and the fold is named in the caveat; nothing else is merged |
 | \`sequence\` | \`labelKey?:"SUBTYPE", eventType?:"treatment", lineClasses?:"systemic"|"all"|[classes], exclude?:[values], lineGap?:90, maxSteps?:3, topN?:8, cohorts:[names]\` | **what follows what**: therapy transitions as lines, drawn as a Sankey. Records are first grouped into LINES \u2014 therapies less than \`lineGap\` days apart are one line, labelled by their whole combination (sorted, so \`A + B\` and \`B + A\` are one regimen). That grouping is the point: a patient has a median of 6 treatment records and 4 distinct agents, and combination therapy is several records describing ONE decision. Paths that end flow into TWO explicit terminals, never one: **no further line** (the study watched for at least one \`lineGap\` and saw no further therapy) and **record ends here** (it did not, so nothing can be concluded). Measured on MSK-CHORD, 68% of patients have under three months of observation after their last therapy and the median is 15 days \u2014 so collapsing the two would turn record-keeping into an apparent clinical decision. Flows out of a node sum to it, so nobody vanishes. Up to two cohorts are drawn as panels sharing one scale and one colour per regimen. Lines are the shared definition (see "Treatment line (derived)" above): systemic-therapy records by default, \`lineClasses\` \`"all"\` for every treatment record or a list of class names for your own; \`labelKey\` only names a line\u2019s therapies (e.g. AGENT), it never decides which records form lines. \`exclude\` drops records by label value, matched ignoring case. More than two cohorts is refused |
-| \`plot\` | \`x:axis, y:axis, unit?:"patient"\\|"sample", bins?:[240,160], points?:true, colorBy?:axis, ringBy?:axis, highlight?:[names(max 4)], cohorts:[names]\` | two axes over the same cases, aggregated **inside the database**: a scatter comes back as counts per grid cell, a box as quartiles per group, two categoricals as a contingency table. The payload is a few kilobytes whatever the cohort's size |
+| \`plot\` | \`x:axis, y:axis, unit?:"sample"\\|"patient", bins?:[240,160], allPoints?:true, points?:[layer(max 4)], colorBy?:axis, ringBy?:axis, cohorts:[names]\` | two axes over the same cases, aggregated **inside the database**: a scatter comes back as counts per grid cell, a box as quartiles per group, two categoricals as a contingency table. The payload is a few kilobytes whatever the cohort's size. A point is a sample, as on cBioPortal's Plots tab; \`unit:"patient"\` makes it a patient, combining a patient's samples: a numeric value is their mean, a category their common value or "Multiple" where they differ, an alteration counts if any sample has it, and the caption says how many patients had more than one sample. Every case is a point up to 5,000 (\`allPoints: false\` turns that off), from a participant that may show cases; \`points\` lists up to four subsets drawn in colour over it — \`{rule:"outliers"}\` (the default), \`{rule:"extremes",axis,n}\`, \`{rule:"trend",n}\`, \`{cohort}\` — see **Points** below |
 | \`attrition\` | \`cohorts:[names] (≤6)\` | **cohort attrition**, CONSORT-style: for each cohort, the study base and then the patients left after each clause of its \`all\`, in the order written, with how many that clause alone removed. Each step is evaluated as its own cohort (the first k clauses ANDed), with the same compiler and the same per-study counts, so the last step is the cohort's own count by construction — a mismatch is reported, never smoothed over. The order of clauses changes the path, never the final count. Counts only, so every participant (aggregate-only and remote included) can answer; across studies the counts are summed and overlap is not deduplicated |
 | \`genome\` | \`binMb?:2, threshold?:0.2, includeX?:false, cohorts:[names] (≤4)\` | **genome-wide copy-number frequency** from the copy-number SEGMENTS: the share of each cohort's segmented samples gained (log2 segment mean ≥ \`threshold\`) or lost (≤ −\`threshold\`) in every \`binMb\`-megabase bin (1–50) along chromosomes 1–22 (and X with \`includeX\` — its log ratio mostly records sex, so it is off by default), drawn as gains up and losses down, one panel per cohort. Each bin's denominator is the samples whose segmentation covers it — a bin nothing covers is drawn as unmeasured, never as copy-neutral. A bin takes the value of the segment over its midpoint, so an event narrower than a bin can be missed; the caption says so. Unit is the SAMPLE, not the patient. Exactly two cohorts add a per-bin two-sided Fisher test (gains and losses separately, Benjamini–Hochberg across bins), drawn as a strip coloured by which cohort is higher. Studies on different reference genomes (hg19/hg38) are refused rather than drawn on one axis. Counts only; a remote peer cannot answer yet and is named as left out |
 | \`pathways\` | \`pathways?:[names], sets?:[{name, genes:[≤40]} ×≤4], measure?:"driver"\|"any", topGenes?:6, cohorts:[names] (≤4)\` | **oncogenic signalling pathways**: the ten canonical pathways of Sanchez-Vega et al. (Cell 2018, Table S3: RTK-RAS, PI3K, TP53, Cell cycle, MYC, WNT, NOTCH, Hippo, TGF-β, NRF2 — 334 genes), and/or the document's own \`sets\`, each as the share of the cohort with at least one member altered. \`measure\` defaults to \`"driver"\` (OncoKB-annotated drivers, as the paper counted curated oncogenic events; refused without an annotation pin) or \`"any"\`. A pathway's denominator is the patients profiled for at least ONE member (the union of the members' panels, the oncoprint's merged-row rule, computed in the database with the same event table, CNA rule and driver join as \`compare\`, so a one-gene set equals that gene's own count); each member's % is over the patients profiled for THAT gene. The \`topGenes\` most-altered members are drawn per pathway; the rest are pooled as "+N more altered", and members on no participating panel are listed as never profiled. Two cohorts add Fisher tests with BH q across pathways, and separately across member genes. Counts only; a remote peer cannot answer yet and is named |
@@ -1618,19 +1618,29 @@ overlay a single-study box can fall back to (that needs the same shared-scale bi
 uses, not yet built for a box); its quartiles are a size-weighted approximation across sites, the
 same one Explore's federated numeric histograms already disclose.
 
-**What sits behind the boxes.** cBioPortal draws every value as a jittered point over its box.
-So does this, up to 5,000 values, and only when the study is one this participant may see cases
-in — the points carry case ids, so they come from the same entitlement that lets a
-patient-level participant list cohort members, and an aggregate-only participant has no method
-that could return them. The jitter is fixed per case, so the figure does not move between the
-server SVG, the browser and the Python package.
-
-Above the cap, or with \`points: false\`, or from a participant that may not disclose a case, the
-same values are drawn as a **violin** from per-group bins: a quarter of a million jittered dots
-is a solid block, while the density is 19KB and is what the reader was looking for. Each violin
-is scaled to its own densest bin, because one group holding 178,489 of the values would
-otherwise flatten every other group to nothing; how many cases a group has is printed under its
-name. The caption always says which of the two it drew.
+**Points: every case when it is a drawing, the outliers when it is not.** cBioPortal draws every
+case as a point. So does this, up to 5,000 cases, on a scatter as on a box, and only when the
+study is one this participant may see cases in — the points carry case ids, so they come from the
+same entitlement that lets a patient-level participant list cohort members, and an aggregate-only
+participant has no method that could return them. The jitter across a box is fixed per case, so
+the figure does not move between the server SVG, the browser and the Python package.
+
+Past 5,000 the crowd is drawn as density — a quarter of a million dots is a solid block, and a
+hover on it would land on an arbitrary case — and, by default, the **outliers** are a point layer
+over it (see **Points**): on a box, the
+values beyond each group's Tukey whiskers, drawn over a **violin** (from per-group bins) that stops
+at the whiskers; on a scatter, the cases in **sparse cells** of the grid — every cell holding at
+most 3 cases (fewer, if that is what keeps the points under 5,000) is drawn as its cases instead of
+as a shade. Both subsets are chosen in the database, against the same grid and whiskers the figure
+draws, and if a subset is itself past 5,000 none of it is drawn, never the first 5,000. With
+\`allPoints: false\` and \`points: []\`, or from a participant that may not disclose a case, the
+figure is density alone.
+The caption always says which it drew, how many points, and why there are none when there are
+none. Each violin is scaled to its own densest bin, because one group holding 178,489 of the
+values would otherwise flatten every other group to nothing; how many cases a group has is
+printed under its name. A box's axis spans the points it draws but reaches at most one whisker
+span past the whiskers, so one extreme value cannot flatten every box; a point beyond that is a
+triangle at the frame's edge, counted in the caption.
 
 **Colour.** \`colorBy\` fills each value with the colour of a category and \`ringBy\` rings it, the
 portal's "Color samples by" with its two checkboxes — so a case that is amplified *and* mutated
@@ -1653,17 +1663,26 @@ or per sample following the plot's \`unit\`. Because it is a categorical axis, i
 \`colorBy\`/\`ringBy\` and as a Cox or logistic covariate, where "Unaltered" is the reference level.
 OQL is for alteration axes only: a molecular axis stays one gene's value.
 
-**Highlight.** \`highlight\` names up to four other cohorts of the document to draw over the
-plotted one, each in its own colour, with the plotted cohort turned grey beneath them — your trial
-patients, the responders, the KRAS G12C carriers, against everyone. A highlight's cases are the
-plotted cohort's cases that are also in it; how many of its patients fall outside the plotted
-cohort is stated, and they are not drawn. Its cases are **points** when every study they come from
-may show cases and there are at most 5,000 of them; otherwise the same cases are drawn as an
-aggregate on the plot's own scale — cells on the scatter's grid, or a narrow box per group — and the
-caption says which and why. A highlight is never cut to its first 5,000 cases. Highlighting changes
-no statistic: the coefficients and quartiles stay those of the whole plotted cohort. A contingency
-table has no points to mark, so its highlights are counted but not drawn. On a box plot a
-highlighted value beyond the whiskers is pinned to the frame's edge as a triangle and counted.
+**Points.** Every case is a point when there are at most 5,000 of them and every study may show
+cases (\`allPoints: false\` draws the density alone at any size). Over that the plotted cohort is a
+density, and \`points\` lists the subsets worth seeing one by one, each drawn in its own colour with
+the plotted cohort turned grey beneath them (at most four layers, in order):
+\`{"rule": "outliers"}\` — where the cohort is density, a box's values beyond its Tukey whiskers
+(the violin then stops at the whiskers) and a single study's scatter's cases in sparse cells (every
+grid cell holding at most 3 cases, left unshaded under its points); \`{"rule": "extremes", "axis":
+"y", "n": 50}\` — the \`n\` highest and lowest values of a numeric axis (per group on a box);
+\`{"rule": "trend", "n": 50}\` — on a scatter, the \`n\` cases furthest from the fitted line; and
+\`{"cohort": "KRAS G12C"}\` — the plotted cohort's cases that are also in that cohort (how many of its
+patients fall outside the plotted cohort is stated, and they are not drawn). The default is
+\`[{"rule": "outliers"}]\`; \`[]\` draws none. A case in two layers is drawn by the first, and the
+caption counts what each layer left to an earlier one. Every layer shares one 5,000-point budget,
+and a layer is never cut to its first cases: a cohort layer past the budget, or from a study that
+may not show cases, is drawn as an aggregate on the plot's own scale (cells on the scatter's grid,
+or a narrow box per group), and a rule layer is not drawn — the caption says which and why.
+Extremes and trend are exact over several studies (each returns its own top \`n\`). Layers change no
+statistic: the coefficients and quartiles stay those of the whole plotted cohort. A contingency
+table has no points to mark. On a box plot a value beyond the axis is pinned to the frame's edge as
+a triangle and counted; with the cases coloured by a category, a layer is a ring round the case.
 
 A case with no value on an axis is simply absent, so a pair is an inner join: only cases measured
 on both axes are counted, and the figure reports how many that was.
@@ -1874,13 +1893,16 @@ export const AGENT_GRAMMAR = `Document shape:
                // lines: systemic-therapy records (SUBTYPE, else TREATMENT_TYPE) by a lineGap-day gap —
                // the same definition as "Treatment line (derived)" and the "lines" derived metric
              {"kind":"plot","x":<axis>,"y":<axis>,"unit":"sample|patient","cohorts":[names?],
-              "colorBy":<axis>?,"ringBy":<axis>?,"points":true,"bins":[240,160],"highlight":[names?(max 4)]},
+              "colorBy":<axis>?,"ringBy":<axis>?,"allPoints":true,"bins":[240,160],
+              "points":[<layer>?(max 4)]},
+               // <layer> = {"rule":"outliers"} | {"rule":"extremes","axis":"x|y","n":50?} | {"rule":"trend","n":50?} | {"cohort":C}
+               //   default [{"rule":"outliers"}]; [] draws none; the first layer draws a case two share
                // <axis> = {"source":"clinical","attribute":A,"log":?}
                //        | {"source":"molecular","profileType":P,"gene":G,"log":?}
                //        | {"source":"alteration","gene":G,"by":"mutated|mutationType|cna|driver"?}
                //        | {"source":"alteration","genes":[G,...(2-20)],"by":"mutated"?}  // any-of-N as one category; only "mutated"
                //        | {"source":"alteration","oql":"KRAS: G12C; STK11: MUT"}  // Altered (matches any entry) vs Unaltered
-               // two numeric axes -> scatter (binned, never points); one categorical -> box;
+               // two numeric axes -> scatter (binned; every case a point up to 5,000, else sparse-cell outliers); one categorical -> box;
                // two categorical -> a contingency table
              {"kind":"attrition","cohorts":[names?(max 6)]},
              {"kind":"genome","binMb":2,"threshold":0.2,"includeX":false,"cohorts":[names?(max 4)]},
diff --git a/lib/federation.ts b/lib/federation.ts
index 9dae5189..63c0c2e2 100644
--- a/lib/federation.ts
+++ b/lib/federation.ts
@@ -27,12 +27,13 @@ import { compileCohortDef, eventTypeMatchSql, memberSamplesSql, lockDriftSql } f
 import { axisKind, axisLabel, axisSelect, corrPValue, plotShape, tukey, validateAxis,
   categoryColor, CATEGORY_CAP, COLOR_CAP, DEFAULT_BINS, POINTS_CAP, VIOLIN_BINS,
   plotBinsSql, plotBoxSql, plotCountSql, plotCoverageSql, plotMomentsSql, plotPointsSql, plotStatsSql, plotTableSql, plotViolinSql,
-  highlightCohortSql, plotHighlightCountSql, plotScatterPointsSql,
-  type AxisKind, type HighlightPoint, type PlotAxis, type PlotData, type PlotPoint, type PlotRequest, type PlotShape } from "./plot.ts";
+  highlightCohortSql, plotHighlightCountSql, plotScatterPointsSql, plotRankedPointsSql,
+  type AxisKind, type HighlightPoint, type PlotAxis, type PlotData, type PlotPoint, type PlotRequest, type PlotShape,
+  type PlotXYPoint, type SparseCells, type Whiskers, type PointRank } from "./plot.ts";
 // re-exported so test/boundary.test.ts sweeps them with the other aggregate SQL builders
 export * from "./federation-views.ts";
 export { plotBinsSql, plotBoxSql, plotCountSql, plotCoverageSql, plotHighlightCountSql, plotMomentsSql, plotStatsSql, plotTableSql, plotViolinSql };
-export type { PlotData, PlotRequest, PlotGroup, PlotPoint, PlotHighlight, HighlightPoint } from "./plot.ts";
+export type { PlotData, PlotRequest, PlotGroup, PlotPoint, PlotXYPoint, PlotLayer, HighlightPoint } from "./plot.ts";
 import { impactSql } from "./lollipop.ts";
 import type { Moments } from "./stats.ts";
 // a table view's row queries return ids: imported for PatientLevelResolver.rowsPage, never re-exported
@@ -47,6 +48,9 @@ export function legendFor(values: string[], ring = false): { label: string; colo
 }
 
 const num = (v: unknown): number | null => { const x = Number(v); return Number.isFinite(x) ? x : null; };
+/** a plot's coverage row: the cohort's cases, each axis's, and (patient mode) the patients with several samples */
+const coverageOf = (row: Record<string, unknown>): NonNullable<PlotData["coverage"]> =>
+  ({ total: Number(row.total || 0), nx: Number(row.nx || 0), ny: Number(row.ny || 0), ...(row.multi != null ? { multi: Number(row.multi) } : {}) });
 import type { CohortDef, CompileCtx, ChRow, ChResult, PatientTimeline } from "./types.ts";
 import type { StudyAccess } from "./view-coverage.ts";
 import { PATIENT_ID, patientEventsSql, patientSamplesSql, toEvents, toSamples } from "./patient-timeline.ts";
@@ -1272,9 +1276,13 @@ export interface QueryLogEntry { label: string; sql: string; ms?: number; remote
 
 /** Additionally available when the instance permits patient-level access. */
 export interface PatientLevelCapable extends AggregateCapable {
-  /** the values behind a box plot, with their case ids — the entitlement, in one method */
-  plotPoints(def: CohortDef | null | undefined, spec: PlotRequest, cap?: number): Promise<PlotPoint[]>;
-  /** a highlight cohort's points over the plot, with their case ids; null past the cap */
+  /** the values behind a box plot (every one, or those beyond `outside`'s whiskers), with their case ids; null past the cap */
+  plotPoints(def: CohortDef | null | undefined, spec: PlotRequest, cap?: number, outside?: Whiskers[]): Promise<PlotPoint[] | null>;
+  /** a scatter's cases (every one, or those in `sparse` cells), with their case ids; null past the cap */
+  plotScatterPoints(def: CohortDef | null | undefined, spec: PlotRequest, cap?: number, sparse?: SparseCells): Promise<PlotXYPoint[] | null>;
+  /** a ranked layer's points (the extremes on an axis, or the cases furthest from the fit), with their case ids */
+  plotRankedPoints(def: CohortDef | null | undefined, spec: PlotRequest, xk: AxisKind, yk: AxisKind, rank: PointRank): Promise<HighlightPoint[]>;
+  /** a cohort layer's points over the plot, with their case ids; null past the cap */
   plotHighlightPoints(def: CohortDef | null | undefined, highlight: CohortDef, spec: PlotRequest, xk: AxisKind, yk: AxisKind,
     cap?: number): Promise<HighlightPoint[] | null>;
   readonly instance: Instance & { mode: "patient-level" };
@@ -1389,7 +1397,7 @@ export interface FederatedPlotCapable {
   plotBoxRows(def: CohortDef | null | undefined, spec: PlotRequest, xk: AxisKind, yk: AxisKind):
     Promise<{ g: string; n: number; lo: number; hi: number; q1: number; median: number; q3: number }[]>;
   plotCoverage(def: CohortDef | null | undefined, spec: PlotRequest, xk: AxisKind, yk: AxisKind):
-    Promise<{ total: number; nx: number; ny: number }>;
+    Promise<NonNullable<PlotData["coverage"]>>;
   /** a highlight's patients that are in the plotted cohort, here — a count */
   plotHighlightCount(def: CohortDef | null | undefined, highlight: CohortDef): Promise<number>;
   /** a highlight's cases as cells on the plotted scatter's own grid and extent */
@@ -1691,7 +1699,7 @@ abstract class BaseResolver implements AggregateCapable {
     const label = { x: { label: axisLabel(spec.x), kind: xk, ...logOf(spec.x) }, y: { label: axisLabel(spec.y), kind: yk, ...logOf(spec.y) } };
     // alongside the plot's own queries, never failing it: a missing coverage just means no note
     const coverage = this.runLogged<ChRow>("plot:coverage", plotCoverageSql(xSel, ySel, ctx), conn)
-      .then((r) => ({ total: Number(r.data[0]?.total || 0), nx: Number(r.data[0]?.nx || 0), ny: Number(r.data[0]?.ny || 0) }))
+      .then((r) => coverageOf(r.data[0] || {}))
       .catch(() => undefined);
     const done = async (d: PlotData): Promise<PlotData> => { const c = await coverage; return c ? { ...d, coverage: c } : d; };
 
@@ -1788,12 +1796,11 @@ abstract class BaseResolver implements AggregateCapable {
 
   /** This site's cases, and how many carry each axis — summed across sites by lib/views/plot.ts. */
   async plotCoverage(def: CohortDef | null | undefined, spec: PlotRequest, xk: AxisKind, yk: AxisKind):
-    Promise<{ total: number; nx: number; ny: number }> {
+    Promise<NonNullable<PlotData["coverage"]>> {
     const ctx = this.plotCtx(def, spec);
     const r = await this.runLogged<ChRow>("plot:coverage",
       plotCoverageSql(axisSelect(spec.x, ctx, xk), axisSelect(spec.y, ctx, yk), ctx), this.instance.conn);
-    const row = r.data[0] || {};
-    return { total: Number(row.total || 0), nx: Number(row.nx || 0), ny: Number(row.ny || 0) };
+    return coverageOf(r.data[0] || {});
   }
 
   /** Pass 1 of a federated numeric pair: this site's count and extent (plotBinsSql's `extent` arg). */
@@ -1938,15 +1945,16 @@ export class PatientLevelResolver extends BaseResolver implements PatientLevelCa
     this.instance = { ...instance, mode: "patient-level" };
   }
   /**
-   * The points behind a box plot, with their case ids, so a reader can find one on the figure.
+   * The points behind a box plot, with their case ids, so a reader can find one on the figure:
+   * every value, or with `outside` only the values beyond their group's whiskers (the outliers
+   * drawn over a violin once the cohort is past the cap).
    *
    * It lives here and nowhere else. `AggregateResolver` has no such method, and neither does a
    * remote peer, so a participant that may not disclose a case cannot be asked for one — the
    * same guarantee as `members()`, and for the same reason. The cap is what stops a quarter of
-   * a million dots being called a drawing; above it the caller falls back to the density every
-   * participant can compute.
+   * a million dots being called a drawing: past it this returns null, never the first `cap`.
    */
-  async plotPoints(def: CohortDef | null | undefined, spec: PlotRequest, cap = POINTS_CAP): Promise<PlotPoint[]> {
+  async plotPoints(def: CohortDef | null | undefined, spec: PlotRequest, cap = POINTS_CAP, outside?: Whiskers[]): Promise<PlotPoint[] | null> {
     const db = this.instance.conn.db, conn = this.instance.conn;
     const unit = spec.unit === "sample" ? "sample" as const : "patient" as const;
     const ctx = { study: this.study, db, unit, cohortSql: this.cohortSql(def), ...this.oqlCtx() };
@@ -1958,16 +1966,50 @@ export class PatientLevelResolver extends BaseResolver implements PatientLevelCa
     const catSel = axisSelect(numFirst ? spec.y : spec.x, ctx, "cat");
     const colorSel = spec.colorBy ? axisSelect(spec.colorBy, ctx, "cat") : undefined;
     const ringSel = spec.ringBy ? axisSelect(spec.ringBy, ctx, "cat") : undefined;
-    const r = await this.runLogged<ChRow>("plot:points",
-      plotPointsSql(numSel, catSel, ctx.cohortSql, cap, colorSel, ringSel), conn);
-    // one over the cap means there were more than a drawing can hold: the caller draws density
-    if (r.data.length > cap) return [];
+    const r = await this.runLogged<ChRow>(outside ? "plot:outliers" : "plot:points",
+      plotPointsSql(numSel, catSel, ctx.cohortSql, cap, colorSel, ringSel, outside), conn);
+    if (r.data.length > cap) return null;
     return r.data.map((x) => ({ id: String(x.id), g: String(x.g), v: Number(x.v),
       ...(colorSel ? { c: String(x.c ?? "") } : {}), ...(ringSel ? { r: String(x.r ?? "") } : {}) }));
   }
 
   /**
-   * A highlight's points: the plotted cohort's cases that are also in `highlight`, each with its
+   * A scatter's cases with their ids: every one, or with `sparse` only those in the density's
+   * sparse cells (binned against the plot's own grid and extent, so they are exactly the cells
+   * the figure leaves undrawn). Case-level, so here and nowhere else, for the reason plotPoints
+   * is; null past the cap.
+   */
+  async plotScatterPoints(def: CohortDef | null | undefined, spec: PlotRequest, cap = POINTS_CAP, sparse?: SparseCells): Promise<PlotXYPoint[] | null> {
+    const db = this.instance.conn.db, conn = this.instance.conn;
+    const unit = spec.unit === "sample" ? "sample" as const : "patient" as const;
+    const ctx = { study: this.study, db, unit, cohortSql: this.cohortSql(def), ...this.oqlCtx() };
+    const kinds = await this.clinicalKinds([spec.x, spec.y]);
+    const xk = axisKind(spec.x, (a) => kinds.get(a)), yk = axisKind(spec.y, (a) => kinds.get(a));
+    if (plotShape(xk, yk) !== "scatter") return [];
+    const r = await this.runLogged<ChRow>(sparse ? "plot:outliers" : "plot:points",
+      plotScatterPointsSql(axisSelect(spec.x, ctx, xk), axisSelect(spec.y, ctx, yk), ctx.cohortSql, cap, sparse), conn);
+    if (r.data.length > cap) return null;
+    return r.data.map((p) => ({ id: String(p.id), x: Number(p.x), y: Number(p.y) }));
+  }
+
+  /**
+   * A ranked layer's points with their case ids: the highest and lowest values of one axis (per
+   * group on a box), or on a scatter the cases furthest from the fitted line. Case-level, so here
+   * and nowhere else, for the reason plotPoints is; bounded by the rank's `n`.
+   */
+  async plotRankedPoints(def: CohortDef | null | undefined, spec: PlotRequest, xk: AxisKind, yk: AxisKind, rank: PointRank): Promise<HighlightPoint[]> {
+    const ctx = this.plotCtx(def, spec);
+    const shape = plotShape(xk, yk);
+    if (shape !== "scatter" && shape !== "box") return [];
+    const r = await this.runLogged<ChRow>("plot:layer:" + rank.by,
+      plotRankedPointsSql(axisSelect(spec.x, ctx, xk), axisSelect(spec.y, ctx, yk), ctx.cohortSql, shape, xk === "num", rank), this.instance.conn);
+    return shape === "scatter"
+      ? r.data.map((p) => ({ id: String(p.id), x: Number(p.x), y: Number(p.y) }))
+      : r.data.map((p) => ({ id: String(p.id), g: String(p.g), v: Number(p.v) }));
+  }
+
+  /**
+   * A cohort layer's points: the plotted cohort's cases that are also in `highlight`, each with its
    * case id — (x, y) on a scatter, (group, value) on a box. Case-level, so here and nowhere else,
    * for the reason plotPoints is. null when there are more than `cap`: the caller draws the same
    * cases as an aggregate rather than the first `cap` of them.
diff --git a/lib/figures/plot.ts b/lib/figures/plot.ts
index b33bcd22..e49fd3a7 100644
--- a/lib/figures/plot.ts
+++ b/lib/figures/plot.ts
@@ -1,12 +1,13 @@
 // The plot view, from the aggregated contract: a density field for a scatter, boxes for a numeric
 // axis grouped by a categorical one, a shaded contingency for two categoricals.
 //
-// Nothing here has ever seen a point. The cells, the quartiles and the coefficients arrive already
-// computed, which is why the same picture draws for a hundred cases or four hundred thousand.
+// The cells, the quartiles and the coefficients arrive already computed, which is why the same
+// picture draws for a hundred cases or four hundred thousand. The only cases drawn one by one are
+// the points the engine chose (every case under the cap, the outliers over it), at most POINTS_CAP.
 import type { ViewResult } from "../types.ts";
 import type { PlotData } from "../plot.ts";
 import { isAbsent, jitterFor } from "../plot-draw.ts";
-import { HIGHLIGHT_BASE } from "../plot-highlight.ts";
+import { LAYER_BASE } from "../plot-layers.ts";
 import {
   esc, palette, frame, caption, linear, axisLeft, axisBottom, leftAxisWidth, bottomAxisHeight, bandLabels, legend, label,
   textWidth, fmtInt, fmtNum, fmtP, FS, SW, SERIES, OTHER, type Scale, type SvgOpts, type LegendItem
@@ -15,6 +16,12 @@ import {
 type Pal = ReturnType<typeof palette>;
 const r1 = (n: number) => Math.round(n * 10) / 10;
 
+/**
+ * The radius of every case drawn as a point on a plot — scatter or box, the plotted cohort or a
+ * point layer, five points or five thousand — so a dot means the same thing on every figure.
+ */
+export const PLOT_POINT_R = 2.5;
+
 /** the plot's height for a figure `w` wide */
 const plotHeight = (w: number) => Math.round(Math.max(240, Math.min(420, w * 0.36)));
 
@@ -52,16 +59,18 @@ export function plotSvg(v: ViewResult, o: SvgOpts): string {
   return "";
 }
 
-/** the highlight cohorts' key: one dot per highlight drawn, its name and how many cases it holds */
-function highlightItems(d: PlotData): LegendItem[] {
-  return (d.highlights || []).filter((h) => h.shown !== "none")
-    .map((h) => ({ label: h.name + " (" + fmtInt(h.n) + ")", color: h.color, kind: "dot" as const }));
+/** the point layers' key: one dot per layer drawn, what it holds and how many cases */
+function layerItems(d: PlotData): LegendItem[] {
+  return (d.layers || []).filter((l) => l.shown !== "none")
+    .map((l) => ({ label: l.label + " (" + fmtInt(l.n) + ")", color: l.color, kind: "dot" as const }));
 }
+/** the layers drawn at all: with any, the plotted cohort steps back to a grey so their colours read */
+const drawnLayers = (d: PlotData) => (d.layers || []).filter((l) => l.shown !== "none");
 
 function scatter(v: ViewResult, d: PlotData, W: number, p: Pal): string {
   const { x0, x1, y0, y1 } = d.extent!, [gx, gy] = d.grid!;
-  const hs = d.highlights || [];
-  const base = hs.length ? HIGHLIGHT_BASE : SERIES[0];
+  const hs = drawnLayers(d);
+  const base = hs.length ? LAYER_BASE : SERIES[0];
   const st = d.stats;
   const statLine = st ? [st.pearson != null ? "Pearson r = " + fmtNum(st.pearson, 2) + " (" + fmtP(st.pPearson ?? 1) + ")" : "",
     st.spearman != null ? "Spearman ρ = " + fmtNum(st.spearman, 2) + " (" + fmtP(st.pSpearman ?? 1) + ")" : ""].filter(Boolean).join("   ·   ") : "";
@@ -85,17 +94,23 @@ function scatter(v: ViewResult, d: PlotData, W: number, p: Pal): string {
   const cell = (b: { bx: number; by: number }, fill: string, opacity: number) =>
     `<rect x="${r1(L + b.bx * cw)}" y="${r1(T + PLOT - (b.by + 1) * ch)}" width="${r1(Math.max(cw, 0.8))}" ` +
     `height="${r1(Math.max(ch, 0.8))}" fill="${fill}" fill-opacity="${r1(opacity * 100) / 100}"/>`;
-  // under highlights the plotted cohort is a floor-raised grey, so its faintest cells still read
-  for (const b of d.bins!) out.push(cell(b, base, hs.length ? 0.3 + 0.7 * shade(b.n) : shade(b.n)));
-  // a highlight too large to draw as points is cells on the same grid, shaded by its own densest cell
+  // Cells whose cases are drawn as points are not also shaded: every case, or the sparse
+  // cells (at most cellMax cases) an outliers layer stands in for.
+  const cellMax = hs.find((l) => l.kind === "outliers" && l.shown === "points")?.cellMax;
+  const shaded = d.pointSet?.rule === "all" && d.xyPoints?.length ? []
+    : cellMax ? d.bins!.filter((b) => b.n > cellMax) : d.bins!;
+  // under point layers the plotted cohort is a floor-raised grey, so its faintest cells still read
+  for (const b of shaded) out.push(cell(b, base, hs.length ? 0.3 + 0.7 * shade(b.n) : shade(b.n)));
+  const own = d.xyPoints || [];
+  for (const pt of own)
+    out.push(`<circle cx="${r1(xs(pt.x))}" cy="${r1(ys(pt.y))}" r="${PLOT_POINT_R}" fill="${base}" fill-opacity="0.7"/>`);
+  // a cohort layer too large to draw as points is cells on the same grid, shaded by its own densest cell
   for (const h of hs) if (h.shown === "density" && h.bins) {
     const hMax = Math.max(1, ...h.bins.map((b) => b.n));
     for (const b of h.bins) out.push(cell(b, h.color, 0.3 + 0.7 * Math.log1p(b.n) / Math.log1p(hMax)));
   }
-  const nPts = hs.reduce((a, h) => a + (h.shown === "points" ? h.points!.length : 0), 0);
-  const rPt = Math.max(1.8, Math.min(3.6, 70 / Math.sqrt(Math.max(1, nPts))));
   for (const h of hs) if (h.shown === "points") for (const pt of h.points!) if ("x" in pt)
-    out.push(`<circle cx="${r1(xs(pt.x))}" cy="${r1(ys(pt.y))}" r="${r1(rPt)}" fill="${h.color}" fill-opacity="0.9" stroke="${p.bg}" stroke-width="0.6"/>`);
+    out.push(`<circle cx="${r1(xs(pt.x))}" cy="${r1(ys(pt.y))}" r="${PLOT_POINT_R}" fill="${h.color}" fill-opacity="0.9" stroke="${p.bg}" stroke-width="0.6"/>`);
   // the fitted line, over every case rather than over what is visible, clipped to the frame
   if (st && st.slope != null && st.intercept != null && x1 > x0) {
     const yAt = (xv: number) => st.intercept! + st.slope! * xv;
@@ -106,9 +121,11 @@ function scatter(v: ViewResult, d: PlotData, W: number, p: Pal): string {
   out.push(`<rect x="${L}" y="${T}" width="${r1(plotW)}" height="${PLOT}" fill="none" stroke="${p.line}" stroke-width="${SW.line}"/>`);
 
   let y = T + PLOT + bottomAxisHeight(xTitle) + 8;
-  const hk = highlightItems(d);
-  if (hk.length) { const lg = legend(hk, 8, y, W - 16, p, { title: "highlighted" }); out.push(lg.svg); y += lg.height + 4; }
-  const cap = caption((v.note ? v.note + "  " : "") + "Darker is more " + (d.n > 1 ? "cases" : "case") + "; the shade is logarithmic." +
+  const hk = layerItems(d);
+  if (hk.length) { const lg = legend(hk, 8, y, W - 16, p, { title: "point layers" }); out.push(lg.svg); y += lg.height + 4; }
+  const cap = caption((v.note ? v.note + "  " : "") + (shaded.length
+    ? "Darker is more " + (d.n > 1 ? "cases" : "case") + "; the shade is logarithmic." + (own.length ? " Each dot is one case." : "")
+    : "Each dot is one case.") +
     (st && st.slope != null ? " The dashed line is the least-squares fit over every case." : ""), W, y, p.muted);
   return frame(W, y + cap.height + 8, out.join("") + cap.svg, p.bg, false, "Plot — " + yTitle + " against " + xTitle);
 }
@@ -118,12 +135,18 @@ function box(v: ViewResult, d: PlotData, W0: number, p: Pal): string {
   // scrolls) rather than dropping the smaller groups, whose cases would otherwise be missing from
   // a figure that still claims the full count.
   const gs = d.groups!;
-  const hs = d.highlights || [];
-  const base = hs.length ? HIGHLIGHT_BASE : SERIES[0];
+  const hs = drawnLayers(d);
+  const base = hs.length ? LAYER_BASE : SERIES[0];
   const numAxis = d.x.kind === "num" ? d.x : d.y, catAxis = d.x.kind === "num" ? d.y : d.x;
   const numTitle = axisTitle(numAxis), catTitle = axisTitle(catAxis);
   const T = 12, R = 16, PLOT = plotHeight(W0);
-  const lo = Math.min(...gs.map((g) => g.loWhisker)), hi = Math.max(...gs.map((g) => g.hiWhisker));
+  // The axis spans the whiskers and the points beyond them, but reaches at most one whisker
+  // span further each way: one TMB of 570 would otherwise flatten every box to a line. A point
+  // past that is pinned to the frame's edge as a triangle and counted in the caption.
+  const ptVals = [...(d.points || []), ...hs.flatMap((l) => l.points || [])].flatMap((pt) => "v" in pt ? [pt.v] : []);
+  const wLo = Math.min(...gs.map((g) => g.loWhisker)), wHi = Math.max(...gs.map((g) => g.hiWhisker));
+  const wSpan = Math.max(1e-9, wHi - wLo);
+  const lo = Math.max(Math.min(wLo, ...ptVals), wLo - wSpan), hi = Math.min(Math.max(wHi, ...ptVals), wHi + wSpan);
   // the whiskers' own range, padded a little, with round ticks inside it: rounding the ends out
   // would stretch a −1 whisker into an empty band down to −20
   const pad = (hi - lo) * 0.03 || 1;
@@ -174,8 +197,15 @@ function box(v: ViewResult, d: PlotData, W0: number, p: Pal): string {
   const otherLabel = (n: number, noValue: boolean) =>
     "other (" + [n ? n + " more categor" + (n === 1 ? "y" : "ies") : "", noValue ? "no value" : ""].filter(Boolean).join(", ") + ")";
   const vBins = d.violinBins || 40;
-  let offScale = 0;
+  let offScale = 0, ptOffScale = 0;
+  /** a value off the axis: a triangle at the frame's edge pointing the way it lies */
+  const edgeMark = (px: number, up: boolean, r: number, fill: string) => {
+    const ty = up ? T + 1 : T + PLOT - 1, k = r * 1.3;
+    return `<path d="M${r1(px - k)} ${r1(up ? ty + k * 1.6 : ty - k * 1.6)} L${r1(px + k)} ${r1(up ? ty + k * 1.6 : ty - k * 1.6)} ` +
+      `L${r1(px)} ${r1(ty)} Z" fill="${fill}" stroke="${p.bg}" stroke-width="0.5"/>`;
+  };
   const inAxis = (val: number) => Math.max(vlo, Math.min(vhi, val));
+  const categorised = colorKey.length > 0 || ringKey.length > 0;
 
   gs.forEach((g, i) => {
     const cx = L + bw * (i + 0.5), half = Math.min(24, bw * 0.32);
@@ -184,13 +214,15 @@ function box(v: ViewResult, d: PlotData, W0: number, p: Pal): string {
       // a bin stands for a range of VALUES, mapped through the extent the bins were cut over
       const [vx0, vx1] = d.violinExtent || [lo, hi];
       const binW = (vx1 - vx0) / vBins;
+      // with the outliers drawn as points, the density stops at this group's whiskers
+      const [cLo, cHi] = hs.some((l) => l.kind === "outliers" && l.shown === "points") ? [g.loWhisker, g.hiWhisker] : [vlo, vhi];
       for (const [b, byClass] of cells) {
         const vLo = vx0 + b * binW, vHi = vLo + binW;
-        if (vHi < vlo || vLo > vhi) continue;
+        if (vHi < cLo || vLo > cHi) continue;
         const total = [...byClass.values()].reduce((a, n) => a + n, 0);
         const w = half * 1.6 * Math.sqrt(total / (vioMax.get(g.g) || 1));
-        const yTop = ys(Math.min(vhi, vHi));
-        const step = Math.max(1.2, ys(Math.max(vlo, vLo)) - yTop);
+        const yTop = ys(Math.min(cHi, vHi));
+        const step = Math.max(1.2, ys(Math.max(cLo, vLo)) - yTop);
         if (!colorKey.length) {
           out.push(`<rect x="${r1(cx - w)}" y="${r1(yTop)}" width="${r1(w * 2)}" height="${r1(step)}" fill="${base}" fill-opacity="0.28"/>`);
           continue;
@@ -206,15 +238,19 @@ function box(v: ViewResult, d: PlotData, W0: number, p: Pal): string {
         }
       }
     }
-    if (d.overlay === "points" && byGroup.has(g.g)) {
-      // two encodings on one dot need a dot big enough to carry them; a crowded plot gets smaller ones
-      const rBase = Math.max(1.4, Math.min(4.5, 90 / Math.sqrt(Math.max(1, d.points!.length))));
+    if (byGroup.has(g.g)) {
+      const rBase = PLOT_POINT_R;
       for (const pt of byGroup.get(g.g)!) {
         const fill = pt.c != null && colorKey.length ? fillOf(pt.c) : base;
         const ring = pt.r != null && !isAbsent(pt.r) ? ringOf(pt.r) : null;
+        if (pt.v > vhi || pt.v < vlo) {
+          ptOffScale++;
+          out.push(edgeMark(cx + jitterFor(pt.id) * half * 0.9, pt.v > vhi, rBase, fill));
+          continue;
+        }
         out.push(`<circle cx="${r1(cx + jitterFor(pt.id) * half * 0.9)}" cy="${r1(ys(pt.v))}" ` +
-          `r="${r1(ring ? rBase * 1.25 : rBase)}" fill="${fill}" fill-opacity="0.85"` +
-          (ring ? ` stroke="${ring}" stroke-width="${r1(Math.max(0.6, rBase * 0.28))}"` : "") + `/>`);
+          `r="${rBase}" fill="${fill}" fill-opacity="0.85"` +
+          (ring ? ` stroke="${ring}" stroke-width="${r1(rBase * 0.36)}"` : "") + `/>`);
       }
     }
     out.push(`<line x1="${r1(cx)}" y1="${r1(ys(g.loWhisker))}" x2="${r1(cx)}" y2="${r1(ys(g.hiWhisker))}" stroke="${p.muted}" stroke-width="${SW.line}"/>`);
@@ -222,8 +258,8 @@ function box(v: ViewResult, d: PlotData, W0: number, p: Pal): string {
       `fill="${base}" fill-opacity="${d.overlay === "none" ? 0.25 : 0.1}" stroke="${base}"><title>${esc(g.g)}: median ${fmtNum(g.median)}, ` +
       `quartiles ${fmtNum(g.q1)}–${fmtNum(g.q3)}, n = ${fmtInt(g.n)}</title></rect>`);
     out.push(`<line x1="${r1(cx - half)}" y1="${r1(ys(g.median))}" x2="${r1(cx + half)}" y2="${r1(ys(g.median))}" stroke="${base}" stroke-width="2"/>`);
-    // highlights over the box: a narrow box of their own (side by side when several), then their
-    // points at the same fixed jitter the plotted cohort's points use
+    // cohort layers past the budget: a narrow box of their own (side by side when several); then every
+    // layer's points at the same fixed jitter the plotted cohort's points use
     const boxed = hs.filter((h) => h.shown === "boxes");
     boxed.forEach((h, j) => {
       const hg = h.groups!.find((x) => x.g === g.g);
@@ -233,20 +269,21 @@ function box(v: ViewResult, d: PlotData, W0: number, p: Pal): string {
         `<rect x="${r1(hx - hw / 2)}" y="${r1(ys(hg.q3))}" width="${r1(hw)}" height="${r1(Math.max(1, ys(hg.q1) - ys(hg.q3)))}" fill="${h.color}" fill-opacity="0.85"/>` +
         `<line x1="${r1(hx - hw / 2 - 1)}" y1="${r1(ys(hg.median))}" x2="${r1(hx + hw / 2 + 1)}" y2="${r1(ys(hg.median))}" stroke="${p.ink}" stroke-width="1.5"/>`);
     });
-    // a highlighted value past the axis is pinned to the frame's edge as a triangle pointing off
-    // it, and counted in the caption, rather than drawn outside the figure
+    // A layer's value past the axis is pinned to the frame's edge as a triangle pointing off it, and
+    // counted in the caption, rather than drawn outside the figure. With the cases coloured by a
+    // category, a layer is a ring round the case, so fill and ring each keep one meaning.
     for (const h of hs) if (h.shown === "points") {
-      const rH = Math.max(1.8, Math.min(4.2, 80 / Math.sqrt(Math.max(1, h.points!.length))));
+      const rH = PLOT_POINT_R;
       for (const pt of h.points!) if ("g" in pt && pt.g === g.g) {
         const px = cx + jitterFor(pt.id) * half * 0.9;
         if (pt.v > vhi || pt.v < vlo) {
           offScale++;
-          const up = pt.v > vhi, ty = up ? T + 1 : T + PLOT - 1, k = rH * 1.3;
-          out.push(`<path d="M${r1(px - k)} ${r1(up ? ty + k * 1.6 : ty - k * 1.6)} L${r1(px + k)} ${r1(up ? ty + k * 1.6 : ty - k * 1.6)} ` +
-            `L${r1(px)} ${r1(ty)} Z" fill="${h.color}" stroke="${p.bg}" stroke-width="0.5"/>`);
+          out.push(edgeMark(px, pt.v > vhi, rH, h.color));
           continue;
         }
-        out.push(`<circle cx="${r1(px)}" cy="${r1(ys(pt.v))}" r="${r1(rH)}" fill="${h.color}" fill-opacity="0.9" stroke="${p.bg}" stroke-width="0.6"/>`);
+        out.push(categorised
+          ? `<circle cx="${r1(px)}" cy="${r1(ys(pt.v))}" r="${r1(rH + 1.4)}" fill="none" stroke="${h.color}" stroke-width="1.4"/>`
+          : `<circle cx="${r1(px)}" cy="${r1(ys(pt.v))}" r="${rH}" fill="${h.color}" fill-opacity="0.9" stroke="${p.bg}" stroke-width="0.6"/>`);
       }
     }
   });
@@ -272,8 +309,8 @@ function box(v: ViewResult, d: PlotData, W0: number, p: Pal): string {
     if (ringOthers.size) items.push({ label: otherLabel(ringOthers.size, false), color: OTHER, kind: "dot", opacity: 0.6 });
     const lg = legend(items, 8, y, W - 16, p, { title: (d.ringLabel || "ring") + " (ring)" }); out.push(lg.svg); y += lg.height;
   }
-  const hk = highlightItems(d);
-  if (hk.length) { const lg = legend(hk, 8, y, W - 16, p, { title: "highlighted" }); out.push(lg.svg); y += lg.height; }
+  const hk = layerItems(d);
+  if (hk.length) { const lg = legend(hk, 8, y, W - 16, p, { title: "point layers" }); out.push(lg.svg); y += lg.height; }
   y += 4;
   // the engine's note leads, as it does under the scatter: it is where the view says what it drew
   // over and what it had to leave out
@@ -281,8 +318,10 @@ function box(v: ViewResult, d: PlotData, W0: number, p: Pal): string {
     (d.overlay === "points" ? " Every value is drawn over its box; the jitter is fixed per case."
       : d.overlay === "violin" ? " The shaded width is the share of that group's values sitting at that height, scaled per group."
       : "") +
-    (offScale ? " " + fmtInt(offScale) + " highlighted value" + (offScale === 1 ? " lies" : "s lie") +
-      " beyond the axis and " + (offScale === 1 ? "is" : "are") + " drawn as a triangle at the frame's edge." : ""), W, y, p.muted);
+    (ptOffScale ? " " + fmtInt(ptOffScale) + " value" + (ptOffScale === 1 ? " lies" : "s lie") + " more than a whisker span" +
+      " past the whiskers and " + (ptOffScale === 1 ? "is" : "are") + " drawn as a triangle at the frame's edge." : "") +
+    (offScale ? " " + fmtInt(offScale) + (offScale === 1 ? " value of a point layer lies" : " values of point layers lie") +
+      " more than a whisker span past the whiskers and " + (offScale === 1 ? "is" : "are") + " drawn as a triangle at the frame's edge." : ""), W, y, p.muted);
   return frame(W, y + cap.height + 8, out.join("") + cap.svg, p.bg, W > W0, "Plot — " + numTitle + " by " + catTitle);
 }
 
diff --git a/lib/plot-highlight.ts b/lib/plot-highlight.ts
deleted file mode 100644
index 0679375f..00000000
--- a/lib/plot-highlight.ts
+++ /dev/null
@@ -1,9 +0,0 @@
-// A plot's highlight cohorts: how many, and their colours. Browser-safe, so the page's picker
-// and the server's figure agree on both.
-
-/** cohorts one plot may highlight: each takes a colour of its own, and past four they stop being told apart */
-export const HIGHLIGHT_CAP = 4;
-/** a highlight's colour, by its place in the view's list */
-export const HIGHLIGHT_COLORS = ["#D55E00", "#0072B2", "#009E73", "#CC79A7"] as const;
-/** the plotted cohort under highlights: a grey lighter than a colour key's "other", so the two never read alike */
-export const HIGHLIGHT_BASE = "#adb6bc";
diff --git a/lib/plot-layers.ts b/lib/plot-layers.ts
new file mode 100644
index 00000000..14913bf3
--- /dev/null
+++ b/lib/plot-layers.ts
@@ -0,0 +1,39 @@
+// A plot's point layers as the document asks for them: how many, their colours, their defaults and
+// what the key calls each. Browser-safe, so the page's picker and the server's figure agree.
+
+/**
+ * How many cases a plot draws as points before it stops being a drawing: at or under it every case
+ * is a point; past it the plotted cohort is density, and the point layers share this many points.
+ */
+export const POINTS_CAP = 5000;
+/** layers one plot may draw: each takes a colour of its own, and past four they stop being told apart */
+export const POINT_LAYER_CAP = 4;
+/** a layer's colour, by its place in the view's list */
+export const LAYER_COLORS = ["#D55E00", "#0072B2", "#009E73", "#CC79A7"] as const;
+/** the plotted cohort under its layers: a grey lighter than a colour key's "other", so the two never read alike */
+export const LAYER_BASE = "#adb6bc";
+
+/**
+ * A point layer, as the document asks for it: a subset of the plotted cohort's cases drawn in its
+ * own colour over the plot. A rule picks the subset (the outliers, the extremes on an axis, the
+ * cases furthest from the fitted line) or a cohort does (its cases that are in the plotted one).
+ */
+export type PointLayerSpec =
+  | { rule: "outliers" }
+  | { rule: "extremes"; axis: "x" | "y"; n?: number }
+  | { rule: "trend"; n?: number }
+  | { cohort: string };
+/** the layers a view without `points` gets: past the cap, the outliers */
+export const DEFAULT_POINT_LAYERS: PointLayerSpec[] = [{ rule: "outliers" }];
+/** how many cases an extremes or trend layer takes when the view does not say (per end, per group for extremes on a box) */
+export const POINT_RULE_N = 50;
+/** the most an extremes or trend layer may ask for */
+export const POINT_RULE_N_MAX = 500;
+
+/** what the key and the picker call a layer; `axis` names an axis by its label */
+export function layerLabel(l: PointLayerSpec, axis: (side: "x" | "y") => string): string {
+  if ("cohort" in l) return l.cohort;
+  if (l.rule === "outliers") return "outliers";
+  if (l.rule === "trend") return (l.n ?? POINT_RULE_N) + " furthest from the fit";
+  return "top and bottom " + (l.n ?? POINT_RULE_N) + " by " + axis(l.axis);
+}
diff --git a/lib/plot.ts b/lib/plot.ts
index 105e1633..bf9e071e 100644
--- a/lib/plot.ts
+++ b/lib/plot.ts
@@ -50,6 +50,8 @@ export { OQL_ALTERED, OQL_UNALTERED };
 function alterationGenes(a: { gene?: string; genes?: string[] }): string[] {
   return (a.genes && a.genes.length ? a.genes : a.gene != null ? [a.gene] : []).map((g) => String(g).toUpperCase());
 }
+/** a patient-mode category for a patient whose samples carry different values */
+export const MULTIPLE = "Multiple";
 /** a gene-set alteration axis takes at most this many genes */
 export const ALTERATION_GENE_SET_CAP = 20;
 export type AxisKind = "num" | "cat" | "none";
@@ -59,15 +61,17 @@ export type PlotShape = "scatter" | "box" | "table" | "waterfall";
 export const CATEGORY_CAP = 150;
 /** the grid a scatter is binned onto: the payload is bounded by this, never by the cohort */
 export const DEFAULT_BINS: [number, number] = [240, 160];
-/**
- * How many points a box plot will draw over its boxes before it stops being a drawing. Above
- * this the same values come back as a violin: 290,000 jittered dots are a solid block, and the
- * density is both smaller to send and what the reader was looking for.
- */
-export const POINTS_CAP = 5000;
-export { HIGHLIGHT_CAP, HIGHLIGHT_COLORS, HIGHLIGHT_BASE } from "./plot-highlight.ts";
+export { POINTS_CAP, POINT_LAYER_CAP, LAYER_COLORS, LAYER_BASE, DEFAULT_POINT_LAYERS, POINT_RULE_N, POINT_RULE_N_MAX, layerLabel, type PointLayerSpec } from "./plot-layers.ts";
+import { POINTS_CAP, POINT_RULE_N_MAX } from "./plot-layers.ts";
 export { isAbsent, jitterFor } from "./plot-draw.ts";
 import { isAbsent } from "./plot-draw.ts";
+/**
+ * Over the points cap, a scatter cell holding at most this many cases is drawn as its cases
+ * rather than as a shade: the sparse fringe of the density, which is where the outliers are.
+ * The threshold actually used is the largest value up to this whose points fit under the cap
+ * (`sparseCellMax`).
+ */
+export const OUTLIER_CELL_MAX = 3;
 /** bins per group in a violin */
 export const VIOLIN_BINS = 40;
 /** distinct colours a legend can carry before it stops being a legend */
@@ -197,8 +201,10 @@ export function axisSelect(a: PlotAxis, ctx: AxisCtx, kind: AxisKind = "num"): s
   const inCohort = (col: string) => strip(col, study) + " IN (SELECT pid FROM cohort)";
 
   if (a.source === "clinical") {
-    // patient rows and sample rows both exist; in sample mode a patient's value repeats across
-    // that patient's samples, in patient mode a sample's value stands in for the patient.
+    // Patient rows and sample rows both exist, and a case's own kind of row wins. In sample mode a
+    // patient's value repeats across that patient's samples. In patient mode the patient's samples
+    // are combined: a number is their mean, a category is the samples' common value, or "Multiple"
+    // when they differ (combineNote says so in the caption).
     // Only the study knows whether the attribute is a number, so the caller says which.
     const val = kind === "num" ? logOf(a, "toFloat64OrNull(attribute_value)") : "attribute_value";
     const valCd = kind === "num" ? logOf(a, "toFloat64OrNull(cd.attribute_value)") : "cd.attribute_value";
@@ -218,7 +224,9 @@ export function axisSelect(a: PlotAxis, ctx: AxisCtx, kind: AxisKind = "num"): s
         "  FROM " + clinicalTable(db, [a.attribute]) + "\n" +
         "  WHERE cancer_study_identifier = " + sq(study) + " AND attribute_name = " + sq(a.attribute) +
         " AND attribute_value != ''" + defined(val) + "\n    AND type = 'sample' AND " + inCohort("patient_unique_id");
-    return "SELECT id, argMax(v, pref) AS v FROM (\n" + own + "\n  UNION ALL\n" + other + "\n) GROUP BY id";
+    const combined = kind === "num" ? "avgIf(v, pref = 0)"
+      : "if(uniqExactIf(v, pref = 0) > 1, " + sq(MULTIPLE) + ", anyIf(v, pref = 0))";
+    return "SELECT id, if(countIf(pref = 1) > 0, anyIf(v, pref = 1), " + combined + ") AS v FROM (\n" + own + "\n  UNION ALL\n" + other + "\n) GROUP BY id";
   }
 
   if (a.source === "molecular") {
@@ -310,7 +318,22 @@ export function plotCoverageSql(xSel: string, ySel: string, ctx: AxisCtx): strin
     : "SELECT pid AS id FROM cohort";
   return "WITH cohort AS (" + ctx.cohortSql + "),\n     cases AS (" + universe + "),\n" +
     "     xs AS (" + xSel + "),\n     ys AS (" + ySel + ")\n" +
-    "SELECT count() AS total, countIf(id IN (SELECT id FROM xs)) AS nx, countIf(id IN (SELECT id FROM ys)) AS ny FROM cases";
+    "SELECT count() AS total, countIf(id IN (SELECT id FROM xs)) AS nx, countIf(id IN (SELECT id FROM ys)) AS ny" +
+    (ctx.unit === "sample" ? "" : ",\n  (SELECT count() FROM (SELECT patient_unique_id FROM " + db + ".sample_derived\n" +
+      "    WHERE cancer_study_identifier = " + sq(ctx.study) + " AND " + strip("patient_unique_id", ctx.study) + " IN (SELECT pid FROM cohort)\n" +
+      "    GROUP BY patient_unique_id HAVING count() > 1)) AS multi") +
+    " FROM cases";
+}
+
+/**
+ * In patient mode, how a patient's several samples became one point: said whenever the cohort has
+ * such patients, since every kind of axis combines them by its own rule. Empty in sample mode.
+ */
+export function combineNote(d: PlotData, unit: "patient" | "sample"): string {
+  const m = d.coverage?.multi;
+  if (unit !== "patient" || !m) return "";
+  return m.toLocaleString("en-US") + " patient" + (m === 1 ? " has" : "s have") + " more than one sample: a numeric value is the mean of " +
+    (m === 1 ? "its" : "their") + " samples', a category the samples' common value or \u201c" + MULTIPLE + "\u201d where they differ, and an alteration counts if any sample has it.";
 }
 
 /** The sentence a plot leads its caption with when the pair left cases out; empty when none were. */
@@ -358,21 +381,51 @@ export function plotMomentsSql(xSel: string, ySel: string, cohortSql: string): s
  */
 export function plotBinsSql(xSel: string, ySel: string, cohortSql: string, bins: [number, number] = DEFAULT_BINS,
   extent?: { x0: number; x1: number; y0: number; y1: number }): string {
-  const [bx, by] = [Math.max(2, Math.min(600, Math.round(bins[0]))), Math.max(2, Math.min(600, Math.round(bins[1])))];
+  const [bx, by] = clampGrid(bins);
   const eCte = extent
     ? ",    e AS (SELECT " + num(extent.x0) + " AS x0, " + num(extent.x1) + " AS x1, " +
         num(extent.y0) + " AS y0, " + num(extent.y1) + " AS y1)\n"
     : ",    e AS (SELECT min(x) x0, max(x) x1, min(y) y0, max(y) y1 FROM pair)\n";
   return pairCte(xSel, ySel, cohortSql) + eCte +
-    "SELECT least(" + (bx - 1) + ", toUInt32(floor((x - x0) / nullIf(x1 - x0, 0) * " + bx + "))) AS bx,\n" +
-    "       least(" + (by - 1) + ", toUInt32(floor((y - y0) / nullIf(y1 - y0, 0) * " + by + "))) AS by,\n" +
+    "SELECT " + binIndex("x", bx) + " AS bx,\n" +
+    "       " + binIndex("y", by) + " AS by,\n" +
     "       count() AS n\n" +
     "FROM pair, e GROUP BY bx, by";
 }
 
-/** a finite number as a SQL literal — extents cross this module's boundary as numbers, never strings */
+/** the grid a request asks for, held to what a figure can draw */
+function clampGrid(bins: [number, number]): [number, number] {
+  return [Math.max(2, Math.min(600, Math.round(bins[0]))), Math.max(2, Math.min(600, Math.round(bins[1])))];
+}
+
+/**
+ * Which of `n` cells a value falls in, against the extent CTE `e`. One expression for the
+ * density and for the sparse-cell points, so a point is never assigned a cell the density did
+ * not count it in.
+ */
+function binIndex(col: "x" | "y", n: number): string {
+  return "least(" + (n - 1) + ", toUInt32(floor((" + col + " - " + col + "0) / nullIf(" + col + "1 - " + col + "0, 0) * " + n + ")))";
+}
+
+/**
+ * The cell threshold for a scatter's outlier points: the largest k up to `max` such that every
+ * case in a cell of at most k cases fits under `cap` points. 0 when even the cells of one case
+ * hold more than `cap` — then no subset is drawn, and the caller says so rather than drawing
+ * some of them.
+ */
+export function sparseCellMax(bins: { n: number }[], cap: number, max = OUTLIER_CELL_MAX): number {
+  let k = 0;
+  for (let t = 1; t <= max; t++) {
+    const cases = bins.reduce((a, b) => b.n <= t ? a + b.n : a, 0);
+    if (cases > cap) break;
+    k = t;
+  }
+  return k;
+}
+
+/** a finite number as a SQL literal — extents and whiskers cross this module's boundary as numbers, never strings */
 function num(x: number): string {
-  if (!Number.isFinite(x)) throw new Error("plotBinsSql: extent must be finite numbers");
+  if (!Number.isFinite(x)) throw new Error("a plot's extent and whiskers must be finite numbers");
   return String(x);
 }
 
@@ -420,7 +473,7 @@ export function plotViolinSql(numSel: string, catSel: string, cohortSql: string,
  * site has no method that could call it — see docs/DATA-BOUNDARY.md.
  */
 export function plotPointsSql(numSel: string, catSel: string, cohortSql: string, cap = POINTS_CAP,
-  colorSel?: string, ringSel?: string): string {
+  colorSel?: string, ringSel?: string, outside?: Whiskers[]): string {
   return "WITH cohort AS (" + cohortSql + "),\n" +
     "     vs AS (" + numSel + "),\n" +
     "     gs AS (" + catSel + ")" +
@@ -430,9 +483,58 @@ export function plotPointsSql(numSel: string, catSel: string, cohortSql: string,
     "FROM vs INNER JOIN gs ON gs.id = vs.id" +
     (colorSel ? "\n  LEFT JOIN cs ON cs.id = vs.id" : "") +
     (ringSel ? "\n  LEFT JOIN rs ON rs.id = vs.id" : "") + "\n" +
+    (outside ? outsideWhiskers(outside) + "\n" : "") +
     "LIMIT " + (Math.max(1, Math.min(50000, Math.round(cap))) + 1);
 }
 
+/**
+ * A ranked layer's points, WITH their case ids: the `n` highest and `n` lowest values of one axis
+ * (per group on a box), or on a scatter the `n` cases furthest from the fitted line. Returns ids,
+ * so like plotPointsSql it stays out of lib/federation.ts's aggregate builders and is reachable
+ * only from `PatientLevelResolver`. Bounded by `n`, so no cap is needed.
+ */
+export function plotRankedPointsSql(xSel: string, ySel: string, cohortSql: string, shape: "scatter" | "box",
+  numFirst: boolean, rank: PointRank): string {
+  const n = Math.max(1, Math.min(POINT_RULE_N_MAX, Math.round(rank.n)));
+  const head = pairIdCte(xSel, ySel, cohortSql);
+  if (shape === "box") {
+    // the numeric axis is the value, the categorical one the group, whichever the document put first
+    const cols = numFirst ? "id, y AS g, x AS v" : "id, x AS g, y AS v";
+    return head + "SELECT * FROM (\n" +
+      "  (SELECT " + cols + " FROM pair ORDER BY v DESC, id LIMIT " + n + " BY g)\n  UNION DISTINCT\n" +
+      "  (SELECT " + cols + " FROM pair ORDER BY v ASC, id LIMIT " + n + " BY g))";
+  }
+  if (rank.by === "residual")
+    return head + "SELECT id, x, y FROM pair ORDER BY abs(y - (" + num(rank.intercept) + " + " + num(rank.slope) + " * x)) DESC, id LIMIT " + n;
+  const col = rank.by;
+  return head + "SELECT * FROM (\n" +
+    "  (SELECT id, x, y FROM pair ORDER BY " + col + " DESC, id LIMIT " + n + ")\n  UNION DISTINCT\n" +
+    "  (SELECT id, x, y FROM pair ORDER BY " + col + " ASC, id LIMIT " + n + "))";
+}
+
+/** the pair of axes per case, keeping the case id: the start of every id-returning plot query */
+const pairIdCte = (x: string, y: string, cohortSql: string) =>
+  "WITH cohort AS (" + cohortSql + "),\n" +
+  "     xs AS (" + x + "),\n" +
+  "     ys AS (" + y + "),\n" +
+  "     pair AS (SELECT xs.id AS id, xs.v AS x, ys.v AS y FROM xs INNER JOIN ys ON ys.id = xs.id)\n";
+
+/** one group's whiskers, which is all a box's outlier query needs to know about it */
+export interface Whiskers { g: string; loWhisker: number; hiWhisker: number }
+
+/**
+ * WHERE a value lies beyond its own group's Tukey whiskers. The whiskers were computed by the
+ * box query and cross back in as literals, a group label quoted and a bound a finite number. A
+ * group not listed has no whiskers to be outside of, so none of its values match.
+ */
+function outsideWhiskers(ws: Whiskers[]): string {
+  if (!ws.length) return "WHERE 0";
+  const at = "indexOf([" + ws.map((w) => sq(w.g)).join(", ") + "], gs.v)";
+  const arr = (f: (w: Whiskers) => number) => "[" + ws.map((w) => num(f(w))).join(", ") + "]";
+  return "WHERE " + at + " > 0 AND (vs.v < arrayElement(" + arr((w) => w.loWhisker) + ", " + at + ")" +
+    " OR vs.v > arrayElement(" + arr((w) => w.hiWhisker) + ", " + at + "))";
+}
+
 /**
  * The cases of a plotted cohort that are also in a highlight cohort: the plotted cohort's SQL
  * narrowed by the highlight's. A cohort expression like any other (it projects `pid`), so the
@@ -453,15 +555,30 @@ export function plotHighlightCountSql(cohortSql: string, highlightSql: string):
  * Like plotPointsSql it returns identifiers, so it stays out of lib/federation.ts's aggregate
  * builders and is reachable only from `PatientLevelResolver`.
  */
-export function plotScatterPointsSql(xSel: string, ySel: string, cohortSql: string, cap = POINTS_CAP): string {
-  return "WITH cohort AS (" + cohortSql + "),\n" +
+export function plotScatterPointsSql(xSel: string, ySel: string, cohortSql: string, cap = POINTS_CAP,
+  sparse?: SparseCells): string {
+  const limit = "LIMIT " + (Math.max(1, Math.min(50000, Math.round(cap))) + 1);
+  if (!sparse) return "WITH cohort AS (" + cohortSql + "),\n" +
     "     xs AS (" + xSel + "),\n" +
     "     ys AS (" + ySel + ")\n" +
     "SELECT xs.id AS id, xs.v AS x, ys.v AS y\n" +
-    "FROM xs INNER JOIN ys ON ys.id = xs.id\n" +
-    "LIMIT " + (Math.max(1, Math.min(50000, Math.round(cap))) + 1);
+    "FROM xs INNER JOIN ys ON ys.id = xs.id\n" + limit;
+  // the cases of every cell holding at most `cellMax` of them, binned exactly as plotBinsSql
+  // bins the density over the same extent and grid
+  const [bx, by] = clampGrid(sparse.grid), e = sparse.extent;
+  if (!(sparse.cellMax >= 1)) throw new Error("plotScatterPointsSql: cellMax must be at least 1");
+  return "WITH cohort AS (" + cohortSql + "),\n" +
+    "     xs AS (" + xSel + "),\n" +
+    "     ys AS (" + ySel + "),\n" +
+    "     e AS (SELECT " + num(e.x0) + " AS x0, " + num(e.x1) + " AS x1, " + num(e.y0) + " AS y0, " + num(e.y1) + " AS y1),\n" +
+    "     c AS (SELECT xs.id AS id, xs.v AS x, ys.v AS y, " + binIndex("x", bx) + " AS bx, " + binIndex("y", by) + " AS by\n" +
+    "           FROM xs INNER JOIN ys ON ys.id = xs.id, e),\n" +
+    "     sparse AS (SELECT bx, by FROM c GROUP BY bx, by HAVING count() <= " + Math.round(sparse.cellMax) + ")\n" +
+    "SELECT id, x, y FROM c WHERE (bx, by) IN (SELECT bx, by FROM sparse)\n" + limit;
 }
 
+/** which cells of a scatter's density are drawn as their cases: the plot's own grid and extent, and the threshold */
+export interface SparseCells { grid: [number, number]; extent: { x0: number; x1: number; y0: number; y1: number }; cellMax: number }
 
 /** the contingency table, one row per occupied cell */
 export function plotTableSql(xSel: string, ySel: string, cohortSql: string): string {
@@ -531,34 +648,54 @@ function lgamma(z: number): number {
 /** what a plot asks for; the shape it draws as is decided from the axes, not requested */
 /** one drawn value, with its case id and whatever it is coloured by */
 export interface PlotPoint { id: string; g: string; v: number; c?: string; r?: string }
-
-export interface PlotRequest {
-  x: PlotAxis; y: PlotAxis; unit?: "patient" | "sample"; bins?: [number, number];
-  /** colour the values by a category: the fill, and optionally a ring, as the portal does */
-  colorBy?: PlotAxis; ringBy?: PlotAxis;
-}
-/** one highlighted case: a scatter's (x, y), or a box's group and value */
-export type HighlightPoint = { id: string; x: number; y: number } | { id: string; g: string; v: number };
+/** one drawn scatter case, with its id */
+export interface PlotXYPoint { id: string; x: number; y: number }
 /**
- * A cohort drawn over the plotted one. Its cases are the plotted cohort's cases that are also in
- * it; each is a point when an entitled participant can name them and there are few enough,
- * otherwise the same cases as an aggregate (cells on the scatter's grid, or a box per group).
+ * Whether the plotted cohort's own cases are drawn as points. `all`: every case, at or under the
+ * points cap. `none`: density alone, and `why` says why. Subsets drawn in colour over it are the
+ * view's point layers (`PlotLayer`).
  */
-export interface PlotHighlight {
-  name: string;
+export interface PointSet {
+  rule: "all" | "none";
+  /** points drawn */
+  drawn: number;
+  why?: string;
+}
+
+/** how a ranked layer orders the cases: by one axis's value (per group on a box), or by distance from the fitted line */
+export type PointRank = { by: "x" | "y"; n: number } | { by: "residual"; n: number; slope: number; intercept: number };
+
+/** A point layer as drawn: what it holds, how many of its cases are on the figure, and as what. */
+export interface PlotLayer {
+  kind: "outliers" | "extremes" | "trend" | "cohort";
+  /** what the key calls it */
+  label: string;
   color: string;
-  /** patients in the highlight cohort, and how many of them are in the plotted cohort */
-  patients: number;
-  inPlot: number;
-  /** cases drawn (in the plot's unit): those with a value on both axes */
+  /** a cohort layer: the cohort, its patients, and how many of them are in the plotted cohort */
+  name?: string;
+  patients?: number;
+  inPlot?: number;
+  /** the layer's cases with a value on both axes, in the plot's unit */
   n: number;
+  /** points drawn, once cases an earlier layer already drew are left to it */
+  drawn?: number;
   shown: "points" | "density" | "boxes" | "none";
   /** why it is not drawn as points, when it is not */
   why?: string;
   points?: HighlightPoint[];
   bins?: { bx: number; by: number; n: number }[];
   groups?: PlotGroup[];
+  /** a scatter's outliers: the cells holding at most this many cases, left unshaded under their points */
+  cellMax?: number;
+}
+
+export interface PlotRequest {
+  x: PlotAxis; y: PlotAxis; unit?: "patient" | "sample"; bins?: [number, number];
+  /** colour the values by a category: the fill, and optionally a ring, as the portal does */
+  colorBy?: PlotAxis; ringBy?: PlotAxis;
 }
+/** one highlighted case: a scatter's (x, y), or a box's group and value */
+export type HighlightPoint = { id: string; x: number; y: number } | { id: string; g: string; v: number };
 export interface PlotGroup { g: string; n: number; lo: number; hi: number; q1: number; median: number; q3: number; loWhisker: number; hiWhisker: number }
 export interface PlotData {
   shape: "scatter" | "box" | "table";
@@ -572,8 +709,12 @@ export interface PlotData {
   stats?: { pearson: number | null; spearman: number | null; slope: number | null; intercept: number | null;
             pPearson: number | null; pSpearman: number | null };
   groups?: PlotGroup[];
-  /** the values behind the boxes: points when few enough and the reader may see cases, else a density */
+  /** the values behind the boxes: every one, when few enough and the reader may see cases */
   points?: PlotPoint[];
+  /** a scatter's cases drawn as points: every one, when few enough and the reader may see cases */
+  xyPoints?: PlotXYPoint[];
+  /** whether the plotted cohort's own cases are points, how many, and why not when they are not */
+  pointSet?: PointSet;
   violin?: { g: string; b: number; n: number; c?: string }[];
   /** what the colours mean: the fill category, the ring category, and the key to draw */
   colorLabel?: string;
@@ -586,8 +727,8 @@ export interface PlotData {
   overlay?: "points" | "violin" | "none";
   cells?: { cx: string; cy: string; n: number }[];
   note?: string;
-  /** cases in the cohort, and how many carry each axis — what the inner join left out, and why */
-  coverage?: { total: number; nx: number; ny: number };
-  /** cohorts drawn over this one, in the view's order */
-  highlights?: PlotHighlight[];
+  /** cases in the cohort, how many have each axis, and (patient mode) how many patients have several samples */
+  coverage?: { total: number; nx: number; ny: number; multi?: number };
+  /** the point layers drawn over the plot, in the view's order (the first holds a case two share) */
+  layers?: PlotLayer[];
 }
diff --git a/lib/result-text.ts b/lib/result-text.ts
index 5eee2165..ad11d685 100644
--- a/lib/result-text.ts
+++ b/lib/result-text.ts
@@ -187,8 +187,8 @@ export function analysisText(document: AnalysisDoc, r: AnalysisResult): string[]
           (pd.overlay === "points" ? `\n  Values are drawn as individual points.`
             : pd.overlay === "violin" ? `\n  Values are drawn as a DENSITY, not points — either above the point cap or from a participant that discloses no cases.`
             : "") +
-          // a highlight drawn as boxes is a second set of quartiles the figure shows and the note does not
-          (pd.highlights || []).filter((h) => h.groups && h.groups.length).map((h) => `\n  Highlight “${h.name}”:\n` +
+          // a cohort layer drawn as boxes is a second set of quartiles the figure shows and the note does not
+          (pd.layers || []).filter((h) => h.groups && h.groups.length).map((h) => `\n  Point layer “${h.name}”:\n` +
             h.groups!.slice(0, 12).map((g) => `    ${g.g}: median ${g.median.toFixed(2)} (IQR ${g.q1.toFixed(2)}–${g.q3.toFixed(2)}, n=${g.n.toLocaleString()})`).join("\n")).join("") +
           caveatOf(v) + noteOf(v));
       } else {
diff --git a/lib/types.ts b/lib/types.ts
index f14a341c..4dc954f8 100644
--- a/lib/types.ts
+++ b/lib/types.ts
@@ -544,16 +544,23 @@ export interface PlotView {
   /** the analyst's own one-line annotation, drawn above the figure (plain text, never markdown) */
   note?: string;
   kind: "plot"; x: PlotAxis; y: PlotAxis; cohorts?: string[];
-  /** what a point is (default "sample"); patient mode averages a patient's samples */
+  /** what a point is (default "sample"); patient mode combines a patient's samples (mean, common value or "Multiple", any alteration) */
   unit?: "patient" | "sample";
   /** the grid a scatter is binned onto (default 240 x 160) */
   bins?: [number, number];
   /**
-   * Draw the values over a box plot's boxes when there are few enough of them and the study is
-   * one this participant may see cases in (default true). Above the cap, or from an
-   * aggregate-only participant, the same values are drawn as a density instead.
+   * Every case is a point when there are at most 5,000 of them and the reader may see cases
+   * (default true); false draws the density alone at any size.
    */
-  points?: boolean;
+  allPoints?: boolean;
+  /**
+   * Subsets of the plotted cohort's cases drawn in colour over the plot, in order (at most 4): the
+   * outliers (past the cap: a box's values beyond its whiskers, a scatter's sparse cells), the
+   * extremes on an axis, the cases furthest from the fitted line, or a cohort's cases. Default
+   * [{rule:"outliers"}]; [] draws none. A case in two layers is drawn by the first. Every layer
+   * shares one 5,000-point budget; a cohort layer past it is drawn as density cells or boxes.
+   */
+  points?: PointLayerSpec[];
   /**
    * Colour the values by a category, as the portal's "Color samples by" does: `colorBy` fills
    * each point, `ringBy` rings it, so a case that is both amplified and mutated stays legible.
@@ -561,13 +568,6 @@ export interface PlotView {
    */
   colorBy?: PlotAxis;
   ringBy?: PlotAxis;
-  /**
-   * Cohorts drawn over the plotted one (at most 4), each in its own colour: the plotted cohort's
-   * cases that are also in it, as points when this participant may see cases and there are few
-   * enough, otherwise as density cells (scatter) or a box per group. The plotted cohort's
-   * statistics are unchanged; the figure says how many of each highlight it drew.
-   */
-  highlight?: string[];
 }
 export interface CooccurrenceView {
   /** the analyst's own one-line annotation, drawn above the figure (plain text, never markdown) */
@@ -1522,6 +1522,7 @@ export interface AlterationsResult extends TableRows<string | number | null> {
   oncokbPin: string | null;
 }
 import type { PlotAxis, PlotData } from "./plot.ts";
+import type { PointLayerSpec } from "./plot-layers.ts";
 export type { PlotAxis, PlotData };
 export type View = CompareView | SurvivalView | OncoprintView | CooccurrenceView | ClinicalView | CoexpressionView | HotspotsView | CourseView | SequenceView | PlotView | CoxView | LogisticView
   | AttritionView | GenomeView | PathwaysView | DiffexprView | PairedView | ClonalityView | IncidenceView | LabsView
diff --git a/lib/views/plot.ts b/lib/views/plot.ts
index 3f11720a..e74e7561 100644
--- a/lib/views/plot.ts
+++ b/lib/views/plot.ts
@@ -2,9 +2,10 @@
 // the axes decide; local, or federated where every participant can answer.
 import type { PlotView, ViewResult } from "../types.ts";
 import { pearsonFromMoments, regressionFromMoments, type Moments } from "../stats.ts";
-import { isPatientLevel, hasFederatedPlot, legendFor, type Resolver, type FederatedPlotCapable } from "../federation.ts";
-import { DEFAULT_BINS, CATEGORY_CAP, POINTS_CAP, HIGHLIGHT_CAP, HIGHLIGHT_COLORS, tukey, coverageNote,
-  type PlotData, type PlotGroup, type PlotHighlight, type PlotRequest } from "../plot.ts";
+import { isPatientLevel, hasFederatedPlot, legendFor, type Resolver, type FederatedPlotCapable, type PatientLevelResolver } from "../federation.ts";
+import { DEFAULT_BINS, CATEGORY_CAP, POINTS_CAP, OUTLIER_CELL_MAX, tukey, coverageNote, combineNote, sparseCellMax,
+  type AxisKind, type HighlightPoint, type PlotData, type PlotGroup, type PlotLayer, type PlotPoint, type PlotRequest, type PointRank } from "../plot.ts";
+import { DEFAULT_POINT_LAYERS, LAYER_COLORS, POINT_LAYER_CAP, POINT_RULE_N, POINT_RULE_N_MAX, layerLabel, type PointLayerSpec } from "../plot-layers.ts";
 import { untimed, type Untimed, type ViewRun, type DocView } from "./run.ts";
 
 type BoxRow = { g: string; n: number; lo: number; hi: number; q1: number; median: number; q3: number };
@@ -29,89 +30,263 @@ function poolBoxRows(parts: BoxRow[][]): PlotGroup[] {
   });
 }
 
+type Def = ViewRun["doc"]["cohorts"][string];
+const TABLE_WHY = "a contingency table counts cases and has no points to mark";
+const fmt = (n: number) => n.toLocaleString("en-US");
+
 /**
- * The view's highlight cohorts, each drawn over the plotted one: points when every study it
- * draws from may show cases and there are at most POINTS_CAP of them, otherwise the same cases
- * as an aggregate on the plot's own scale (cells on the scatter's grid, a box per group). A
- * highlight is never cut to its first POINTS_CAP cases.
+ * The plotted cohort's own cases as points, set on `data`: every case at or under POINTS_CAP, from
+ * a participant entitled to see cases, unless the view says `allPoints: false`. Over the cap the
+ * crowd is density, and the subsets worth seeing one by one are the view's point layers.
+ * isPatientLevel is a type guard, so asking an aggregate-only participant is a compile error.
  */
-async function highlightLayers(pv: PlotView, data: PlotData, c: ViewRun, cn: string, sites: string[],
-  spec: PlotRequest): Promise<PlotHighlight[]> {
-  const names = pv.highlight || [];
-  if (!names.length) return [];
-  const missing = sites.filter((s) => !hasFederatedPlot(c.resolvers[s]));
-  if (missing.length) throw new Error("highlight: " + missing.join(", ") + " cannot answer a highlight (a remote peer over MCP, most likely)");
+async function basePoints(pv: PlotView, r0: Resolver, def: Def, spec: PlotRequest, data: PlotData, site: string): Promise<void> {
+  if (data.shape === "table" || !data.n) return;
+  const none = (why: string) => { data.pointSet = { rule: "none", drawn: 0, why }; };
+  if (pv.allPoints === false) return none("allPoints: false");
+  if (data.n > POINTS_CAP) return none("more than " + fmt(POINTS_CAP) + " cases");
+  if (!isPatientLevel(r0)) return none(site + " may not show individual cases");
+  if (data.shape === "box") {
+    const all = await r0.plotPoints(def, spec);
+    if (!all || !all.length) return;
+    data.points = all; data.overlay = "points";
+    data.pointSet = { rule: "all", drawn: all.length };
+    if (spec.colorBy) data.legend = legendFor(all.map((x) => x.c || ""));
+    if (spec.ringBy) data.legend = [...(data.legend || []), ...legendFor(all.map((x) => x.r || ""), true)];
+    return;
+  }
+  const all = await r0.plotScatterPoints(def, spec);
+  if (!all || !all.length) return;
+  data.xyPoints = all;
+  data.pointSet = { rule: "all", drawn: all.length };
+}
+
+/** what the caption says when the plotted cohort is drawn as density rather than as its cases */
+function densityNote(data: PlotData, unit: "patient" | "sample"): string {
+  if (data.shape === "table" || !data.n || data.pointSet?.rule === "all") return "";
+  const cases = (n: number) => fmt(n) + " " + unit + (n === 1 ? "" : "s");
+  const lead = data.shape === "scatter"
+    ? "Drawn as density: " + cases(data.n) + " counted into " + fmt((data.bins || []).length) + " cells. The coefficients are over every " +
+      unit + ", not over what you can see."
+    : "Drawn as a density per group" + (data.n > POINTS_CAP ? ": " + fmt(data.n) + " values is past what a cloud of dots can show, and" : ";") +
+      " the quartiles are over every value.";
+  const why = data.pointSet?.why;
+  return lead + (why && why !== "allPoints: false" && !why.startsWith("more than") ? " No case is drawn as a point: " + why + "." : "");
+}
+
+/** what is wrong with a view's point settings, before anything is queried; null when nothing is */
+function layersProblem(pv: PlotView, c: ViewRun, cn: string): string | null {
+  if ("highlight" in (pv as object))
+    return "highlight is now a point layer: list each cohort in the view's points as {\"cohort\": \"<name>\"}";
+  if (pv.allPoints != null && typeof pv.allPoints !== "boolean") return "allPoints: give true or false";
+  const ls = pv.points;
+  if (ls == null) return null;
+  if (!Array.isArray(ls)) return "points: give a list of layers, e.g. [{\"rule\": \"outliers\"}, {\"cohort\": \"KRAS G12C\"}]; [] draws none";
+  if (ls.length > POINT_LAYER_CAP) return "a plot draws at most " + POINT_LAYER_CAP + " point layers; this view asks for " + ls.length;
+  const cohortsSeen = new Set<string>();
+  for (const l of ls as unknown[]) {
+    if (!l || typeof l !== "object") return "points: each layer is an object, {\"rule\": …} or {\"cohort\": …}";
+    const o = l as Record<string, unknown>;
+    if ("cohort" in o) {
+      const h = o.cohort;
+      if (typeof h !== "string" || !c.cohorts[h]) return "points: there is no cohort named “" + String(h) + "”";
+      if (h === cn) return "points: “" + h + "” is the plotted cohort itself, so it would mark every case";
+      if (cohortsSeen.has(h)) return "points: the cohort “" + h + "” is named twice";
+      cohortsSeen.add(h);
+      continue;
+    }
+    if (o.rule !== "outliers" && o.rule !== "extremes" && o.rule !== "trend")
+      return "points: unknown rule “" + String(o.rule) + "” — use outliers, extremes or trend, or name a cohort";
+    if (o.rule === "extremes" && o.axis !== "x" && o.axis !== "y") return "points: an extremes layer names its axis, \"x\" or \"y\"";
+    if (o.n != null && !(Number.isInteger(o.n) && (o.n as number) >= 1 && (o.n as number) <= POINT_RULE_N_MAX))
+      return "points: n is a whole number from 1 to " + POINT_RULE_N_MAX + "; this layer asks for " + String(o.n);
+  }
+  return null;
+}
+
+/** a layer's points, each with the key that says whether an earlier layer already drew the case */
+type Picked = { layer: PlotLayer; keys?: string[] };
+
+/**
+ * The view's point layers, in order, each drawn in its own colour over the plotted cohort. Every
+ * layer shares one POINTS_CAP budget; a case two layers share is drawn by the first. A layer that
+ * does not fit is never cut to its first cases: a cohort layer becomes density cells or a box per
+ * group, a rule layer is not drawn, and either way the caption says why. Points come only from
+ * participants entitled to see cases, and a layer is drawn from all of its studies or not at all.
+ */
+async function pointLayers(pv: PlotView, data: PlotData, c: ViewRun, cn: string, sites: string[], spec: PlotRequest): Promise<PlotLayer[]> {
+  const specs = pv.points ?? DEFAULT_POINT_LAYERS;
+  if (!specs.length) return [];
   const fr = c.resolvers as Record<string, Resolver & FederatedPlotCapable>;
   const def = c.doc.cohorts[cn];
   const xk = data.x.kind, yk = data.y.kind;
-  return Promise.all(names.map(async (name, i): Promise<PlotHighlight> => {
-    const hDef = c.doc.cohorts[name], hc = c.cohorts[name];
-    // a highlight's cases in a study the plot does not draw are outside the plotted cohort by definition
-    const hSites = sites.filter((s) => hc.studies.includes(s));
-    const base = { name, color: HIGHLIGHT_COLORS[i], patients: hc.count };
-    const inPlot = (await Promise.all(hSites.map((s) => fr[s].plotHighlightCount(def, hDef)))).reduce((a, n) => a + n, 0);
-    if (data.shape === "table")
-      return { ...base, inPlot, n: 0, shown: "none", why: "a contingency table counts cases and has no points to mark" };
-    if (!inPlot || !data.n) return { ...base, inPlot, n: 0, shown: "none" };
+  const closed = sites.filter((s) => !isPatientLevel(c.resolvers[s]));
+  const seen = new Set<string>();
+  let budget = POINTS_CAP;
+  const out: PlotLayer[] = [];
+  for (const [i, l] of specs.entries()) {
+    const base = { label: layerLabel(l, (side) => data[side].label), color: LAYER_COLORS[i] };
+    const kind = "cohort" in l ? "cohort" as const : l.rule;
+    let picked: Picked;
+    if ("cohort" in l) picked = await cohortLayer(l.cohort, base, data, c, def, sites, spec, budget);
+    else if (data.shape === "table" || !data.n)
+      picked = { layer: { kind, ...base, n: 0, shown: "none", why: data.n ? TABLE_WHY : undefined } };
+    else if (closed.length) picked = { layer: { kind, ...base, n: 0, shown: "none", why: closed.join(", ") + " may not show individual cases" } };
+    else picked = await ruleLayer(l, base, data, fr, def, sites, spec, xk, yk, budget);
+    const { layer, keys } = picked;
+    if (layer.shown === "points" && layer.points && keys) {
+      const kept = layer.points.filter((_, j) => !seen.has(keys[j]));
+      for (const k of keys) seen.add(k);
+      layer.drawn = kept.length; layer.points = kept;
+      budget -= kept.length;
+    }
+    out.push(layer);
+  }
+  return out;
+}
 
-    let why: string;
-    const closed = hSites.filter((s) => !isPatientLevel(c.resolvers[s]));
-    if (!closed.length) {
-      const parts = await Promise.all(hSites.map((s) => {
-        const r = c.resolvers[s];
-        return isPatientLevel(r) ? r.plotHighlightPoints(def, hDef, spec, xk, yk, POINTS_CAP) : Promise.resolve(null);
-      }));
-      const pts = parts.every((p) => p) ? parts.flatMap((p) => p!) : null;
-      if (pts && pts.length <= POINTS_CAP) return { ...base, inPlot, n: pts.length, shown: "points", points: pts };
-      why = "more than " + POINTS_CAP.toLocaleString("en-US") + " cases, too many to draw as points";
-    } else {
-      why = closed.join(", ") + " may not show individual cases";
+/** points gathered from several studies, keyed by study and case so two studies' ids never collide */
+function gather<T extends { id: string }>(parts: T[][], sites: string[]): { points: T[]; keys: string[] } {
+  const points: T[] = [], keys: string[] = [];
+  parts.forEach((part, k) => { for (const p of part) { points.push(p); keys.push(sites[k] + "\u0000" + p.id); } });
+  return { points, keys };
+}
+
+/** a cohort layer: the plotted cohort's cases that are also in `name` */
+async function cohortLayer(name: string, base: { label: string; color: string }, data: PlotData, c: ViewRun, def: Def,
+  sites: string[], spec: PlotRequest, budget: number): Promise<Picked> {
+  const fr = c.resolvers as Record<string, Resolver & FederatedPlotCapable>;
+  const hDef = c.doc.cohorts[name], hc = c.cohorts[name];
+  const xk = data.x.kind, yk = data.y.kind;
+  // the layer's cases in a study the plot does not draw are outside the plotted cohort by definition
+  const hSites = sites.filter((s) => hc.studies.includes(s));
+  const head = { kind: "cohort" as const, ...base, name, patients: hc.count };
+  const unable = hSites.filter((s) => !hasFederatedPlot(c.resolvers[s]));
+  if (unable.length) return { layer: { ...head, inPlot: 0, n: 0, shown: "none", why: unable.join(", ") + " cannot answer a cohort layer (a remote peer over MCP, most likely)" } };
+  const inPlot = (await Promise.all(hSites.map((s) => fr[s].plotHighlightCount(def, hDef)))).reduce((a, n) => a + n, 0);
+  if (data.shape === "table") return { layer: { ...head, inPlot, n: 0, shown: "none", why: TABLE_WHY } };
+  if (!inPlot || !data.n) return { layer: { ...head, inPlot, n: 0, shown: "none" } };
+  let why: string;
+  const closed = hSites.filter((s) => !isPatientLevel(c.resolvers[s]));
+  if (!closed.length && budget > 0) {
+    const parts = await Promise.all(hSites.map((s) => {
+      const r = c.resolvers[s];
+      return isPatientLevel(r) ? r.plotHighlightPoints(def, hDef, spec, xk, yk, budget) : Promise.resolve(null);
+    }));
+    if (parts.every((p) => p)) {
+      const g = gather(parts as HighlightPoint[][], hSites);
+      if (g.points.length <= budget) return { layer: { ...head, inPlot, n: g.points.length, shown: "points", points: g.points }, keys: g.keys };
     }
+    why = budget === POINTS_CAP ? "more than " + fmt(POINTS_CAP) + " cases, too many to draw as points"
+      : "more cases than the " + fmt(budget) + " points the earlier layers left";
+  } else {
+    why = closed.length ? closed.join(", ") + " may not show individual cases" : "the earlier layers used every point the figure draws";
+  }
+  if (data.shape === "scatter" && data.extent && data.grid) {
+    const parts = await Promise.all(hSites.map((s) => fr[s].plotHighlightBins(def, hDef, spec, xk, yk, data.grid!, data.extent!)));
+    const cells = new Map<string, number>();
+    for (const part of parts) for (const b of part) cells.set(b.bx + "," + b.by, (cells.get(b.bx + "," + b.by) || 0) + b.n);
+    const bins = [...cells.entries()].map(([k, n]) => { const [bx, by] = k.split(",").map(Number); return { bx, by, n }; });
+    return { layer: { ...head, inPlot, n: bins.reduce((a, b) => a + b.n, 0), shown: "density", bins, why } };
+  }
+  const groups = poolBoxRows(await Promise.all(hSites.map((s) => fr[s].plotHighlightBoxRows(def, hDef, spec, xk, yk))));
+  return { layer: { ...head, inPlot, n: groups.reduce((a, g) => a + g.n, 0), shown: "boxes", groups, why } };
+}
 
-    if (data.shape === "scatter" && data.extent && data.grid) {
-      const parts = await Promise.all(hSites.map((s) => fr[s].plotHighlightBins(def, hDef, spec, xk, yk, data.grid!, data.extent!)));
-      const cells = new Map<string, number>();
-      for (const part of parts) for (const b of part) cells.set(b.bx + "," + b.by, (cells.get(b.bx + "," + b.by) || 0) + b.n);
-      const bins = [...cells.entries()].map(([k, n]) => { const [bx, by] = k.split(",").map(Number); return { bx, by, n }; });
-      return { ...base, inPlot, n: bins.reduce((a, b) => a + b.n, 0), shown: "density", bins, why };
+/**
+ * A rule layer, from participants that may all show cases. Outliers apply where the plotted cohort
+ * is density: a box's values beyond its whiskers, a single study's scatter's cases in sparse cells.
+ * Extremes and trend ask each study for its own top `n` and keep the overall top `n`, which is exact.
+ */
+async function ruleLayer(l: Exclude<PointLayerSpec, { cohort: string }>, base: { label: string; color: string }, data: PlotData,
+  fr: Record<string, Resolver & FederatedPlotCapable>, def: Def, sites: string[], spec: PlotRequest,
+  xk: AxisKind, yk: AxisKind, budget: number): Promise<Picked> {
+  const kind = l.rule;
+  const none = (why: string): Picked => ({ layer: { kind, ...base, n: 0, shown: "none", why } });
+  const tooMany = (n: number) => none(fmt(n) + " cases, more than the " + fmt(budget) + " points " + (budget === POINTS_CAP ? "a figure draws" : "the earlier layers left"));
+  const entitled = sites.map((s) => fr[s] as unknown as PatientLevelResolver);
+  if (l.rule === "outliers") {
+    // outliers stand out of a density too large to draw as points; under the cap there is none
+    if (data.n <= POINTS_CAP) return none("at or under " + fmt(POINTS_CAP) + " cases there is no density for them to stand out of");
+    if (data.shape === "box") {
+      if (budget <= 0) return none("the earlier layers used every point the figure draws");
+      const parts = await Promise.all(entitled.map((r) => r.plotPoints(def, spec, budget, data.groups || [])));
+      if (parts.some((p) => !p)) return none("more than " + fmt(budget) + " values lie beyond the whiskers");
+      const g = gather(parts as PlotPoint[][], sites);
+      return { layer: { kind, ...base, n: g.points.length, shown: "points", points: g.points.map(({ id, g: gr, v }) => ({ id, g: gr, v })) }, keys: g.keys };
     }
-    const groups = poolBoxRows(await Promise.all(hSites.map((s) => fr[s].plotHighlightBoxRows(def, hDef, spec, xk, yk))));
-    return { ...base, inPlot, n: groups.reduce((a, g) => a + g.n, 0), shown: "boxes", groups, why };
-  }));
+    if (sites.length > 1) return none("a pooled scatter's sparse cells are known only after pooling, and no study can be asked for them yet");
+    if (!data.bins || !data.grid || !data.extent) return none("the plot has no density to find sparse cells in");
+    const cellMax = sparseCellMax(data.bins, budget, OUTLIER_CELL_MAX);
+    if (!cellMax) return none("the cases alone in a cell are more than the " + fmt(budget) + " points left to draw");
+    const pts = await entitled[0].plotScatterPoints(def, spec, budget, { grid: data.grid, extent: data.extent, cellMax });
+    if (!pts) return none("the sparse cells hold more than " + fmt(budget) + " cases");
+    const g = gather([pts], sites);
+    return { layer: { kind, ...base, n: pts.length, shown: "points", points: pts, cellMax }, keys: g.keys };
+  }
+  const n = l.n ?? POINT_RULE_N;
+  let rank: PointRank;
+  if (l.rule === "trend") {
+    if (data.shape !== "scatter") return none("a fitted line exists only on a scatter");
+    const st = data.stats;
+    if (!st || st.slope == null || st.intercept == null) return none("the plot has no fitted line");
+    rank = { by: "residual", n, slope: st.slope, intercept: st.intercept };
+  } else {
+    if (data[l.axis].kind !== "num") return none(data[l.axis].label + " is not numeric, so it has no extremes");
+    rank = { by: l.axis, n };
+  }
+  const g = gather(await Promise.all(entitled.map((r) => r.plotRankedPoints(def, spec, xk, yk, rank))), sites);
+  const kept = topRanked(g.points, g.keys, rank, data.shape === "box");
+  if (kept.points.length > budget) return tooMany(kept.points.length);
+  return { layer: { kind, ...base, n: kept.points.length, shown: "points", points: kept.points }, keys: kept.keys };
 }
 
-/** what is wrong with a view's highlight list, before anything is queried; null when nothing is */
-function highlightProblem(pv: PlotView, c: ViewRun, cn: string): string | null {
-  const names = pv.highlight;
-  if (names == null) return null;
-  if (!Array.isArray(names) || names.some((h) => typeof h !== "string")) return "highlight: give a list of cohort names";
-  if (names.length > HIGHLIGHT_CAP) return "a plot highlights at most " + HIGHLIGHT_CAP + " cohorts; this view names " + names.length;
-  for (const h of names) {
-    if (!c.cohorts[h]) return "highlight: there is no cohort named “" + h + "”";
-    if (h === cn) return "highlight: “" + h + "” is the plotted cohort itself, so it would mark every case";
+/** each study's own top `n` pooled into the overall top `n` (per end, and per group on a box) */
+function topRanked(points: HighlightPoint[], keys: string[], rank: PointRank, box: boolean): { points: HighlightPoint[]; keys: string[] } {
+  const rows = points.map((p, i) => ({ p, k: keys[i] }));
+  const val = (p: HighlightPoint) => "v" in p ? p.v : rank.by === "residual" ? Math.abs(p.y - (rank.intercept + rank.slope * p.x))
+    : rank.by === "x" ? p.x : p.y;
+  const groups = new Map<string, typeof rows>();
+  for (const r of rows) { const g = box && "g" in r.p ? r.p.g : ""; (groups.get(g) ?? groups.set(g, []).get(g)!).push(r); }
+  const keep = new Map<string, (typeof rows)[number]>();
+  for (const rs of groups.values()) {
+    const byVal = [...rs].sort((a, b) => val(b.p) - val(a.p) || (a.k < b.k ? -1 : 1));
+    for (const r of byVal.slice(0, rank.n)) keep.set(r.k, r);
+    if (rank.by !== "residual") for (const r of byVal.slice(-rank.n)) keep.set(r.k, r);
   }
-  if (new Set(names).size !== names.length) return "highlight: a cohort is named twice";
-  return null;
+  const kept = [...keep.values()];
+  return { points: kept.map((r) => r.p), keys: kept.map((r) => r.k) };
 }
 
-/** what the caption says about the highlights: how many of each were drawn, and as what */
-function highlightNote(hs: PlotHighlight[], unit: "patient" | "sample"): string {
-  if (!hs.length) return "";
-  const f = (n: number) => n.toLocaleString("en-US");
-  const cases = (n: number) => f(n) + " " + unit + (n === 1 ? "" : "s");
-  const one = (h: PlotHighlight) => {
-    const where = h.inPlot === h.patients ? f(h.patients) + " patient" + (h.patients === 1 ? "" : "s")
-      : f(h.inPlot) + " of its " + f(h.patients) + " patients in the plotted cohort";
-    // in patient units, "all" when every patient in the plot had both axes; samples are counted as samples
-    const count = unit === "patient" && h.n === h.inPlot ? "all" : cases(h.n);
-    const drawn = h.shown === "points" ? count + " drawn as points"
-      : h.shown === "density" ? count + " drawn as shaded cells (" + h.why + ")"
-      : h.shown === "boxes" ? count + " drawn as a box per group (" + h.why + ")"
-      : h.why ? "not drawn: " + h.why : h.inPlot ? "none with a value on both axes" : "none drawn";
-    return "“" + h.name + "”: " + where + ", " + drawn;
+/** what the caption says about the point layers: what each holds, how much of it was drawn, and as what */
+function layerNote(ls: PlotLayer[], unit: "patient" | "sample"): string {
+  if (!ls.length) return "";
+  const cases = (n: number) => fmt(n) + " " + unit + (n === 1 ? "" : "s");
+  const one = (l: PlotLayer) => {
+    const shared = l.drawn != null && l.drawn < l.n ? " (" + fmt(l.n - l.drawn) + " drawn by an earlier layer)" : "";
+    if (l.kind === "cohort") {
+      const where = l.inPlot === l.patients ? fmt(l.patients!) + " patient" + (l.patients === 1 ? "" : "s")
+        : fmt(l.inPlot!) + " of its " + fmt(l.patients!) + " patients in the plotted cohort";
+      // in patient units, "all" when every patient in the plot had both axes; samples are counted as samples
+      const count = unit === "patient" && l.n === l.inPlot ? "all" : cases(l.n);
+      const drawn = l.shown === "points" ? count + " drawn as points" + shared
+        : l.shown === "density" ? count + " drawn as shaded cells (" + l.why + ")"
+        : l.shown === "boxes" ? count + " drawn as a box per group (" + l.why + ")"
+        : l.why ? "not drawn: " + l.why : l.inPlot ? "none with a value on both axes" : "none drawn";
+      return "“" + l.name + "”: " + where + ", " + drawn;
+    }
+    if (l.shown !== "points") return l.label + ": not drawn, " + (l.why || "nothing to draw");
+    const what = l.kind === "outliers"
+      ? (l.cellMax ? cases(l.n) + " in cells holding at most " + l.cellMax + ", left unshaded under them"
+        : fmt(l.n) + " value" + (l.n === 1 ? "" : "s") + " beyond the whiskers")
+      : cases(l.n);
+    return l.label + ": " + what + shared;
   };
-  return "Highlighted — " + hs.map(one).join("; ") + "." +
-    (hs.some((h) => h.shown !== "none") ? " The statistics are over the whole plotted cohort." : "");
+  // many cases can share the value at a ranked layer's cut (a fraction of 0 or 1, a count of 0)
+  const ranked = ls.some((l) => (l.kind === "extremes" || l.kind === "trend") && l.shown === "points");
+  return "Point layers — " + ls.map(one).join("; ") + "." +
+    (ranked ? " A ranked layer breaks ties at its cut by case id." : "") +
+    (ls.some((l) => l.shown !== "none") ? " The statistics are over the whole plotted cohort." : "");
 }
 
 export async function runPlot(view: DocView, c: ViewRun): Promise<ViewResult | Untimed> {
@@ -119,47 +294,27 @@ export async function runPlot(view: DocView, c: ViewRun): Promise<ViewResult | U
   const pv = view as PlotView;
   const cn = vNames[0];
   const sites = cohorts[cn].studies;
-  const unit = pv.unit === "sample" ? "sample" as const : "patient" as const;
+  // a point is a sample unless the view asks for patients, as on cBioPortal's Plots tab
+  const unit = pv.unit === "patient" ? "patient" as const : "sample" as const;
   const spec = { x: pv.x, y: pv.y, unit,
     ...(pv.colorBy ? { colorBy: pv.colorBy } : {}), ...(pv.ringBy ? { ringBy: pv.ringBy } : {}) };
   const bins: [number, number] = Array.isArray(pv.bins) && pv.bins.length === 2
     ? [Number(pv.bins[0]), Number(pv.bins[1])] : DEFAULT_BINS;
-  const hlProblem = highlightProblem(pv, c, cn);
-  if (hlProblem) return untimed({ kind: "plot", error: hlProblem });
+  const problem = layersProblem(pv, c, cn);
+  if (problem) return untimed({ kind: "plot", error: problem });
   try {
     if (sites.length === 1) {
       const r0 = resolvers[sites[0]];
       const data = await r0.plot(doc.cohorts[cn], { ...spec, bins: pv.bins ? bins : undefined });
-      // The points behind a box come only from a participant entitled to see cases, and only
-      // when there are few enough to be a drawing. isPatientLevel is a type guard, so asking an
-      // aggregate-only participant for them is a compile error rather than a review catch.
-      if (data.shape === "box" && pv.points !== false && isPatientLevel(r0)) {
-        const pts = await r0.plotPoints(doc.cohorts[cn], spec);
-        if (pts.length) {
-          data.points = pts;
-          data.overlay = "points";
-          // the key describes what is drawn, so it is built from the points themselves
-          if (pv.colorBy) data.legend = legendFor(pts.map((x) => x.c || ""));
-          if (pv.ringBy) data.legend = [...(data.legend || []), ...legendFor(pts.map((x) => x.r || ""), true)];
-        }
-      }
-      const shapeNote = data.shape === "box" && data.overlay === "violin"
-          ? "Drawn as a density per group: " + data.n.toLocaleString("en-US") + " values is past what a cloud of dots can show, " +
-            "and the quartiles are over every one of them."
-          : data.shape === "box" && data.overlay === "points"
-          ? "Every value is drawn over its box; the jitter is fixed per case, so the figure does not move between renderings."
-          : data.shape === "scatter" && data.n > 5000
-          ? "Drawn as density: " + data.n.toLocaleString("en-US") + " " + (unit === "sample" ? "samples" : "patients") +
-            " counted into " + (data.bins || []).length.toLocaleString("en-US") + " cells. The coefficients are over every " +
-            (unit === "sample" ? "sample" : "patient") + ", not over what you can see."
-          : undefined;
-      const hs = await highlightLayers(pv, data, c, cn, sites, spec);
-      if (hs.length) data.highlights = hs;
+      await basePoints(pv, r0, doc.cohorts[cn], spec, data, sites[0]);
+      const ls = await pointLayers(pv, data, c, cn, sites, spec);
+      if (ls.length) data.layers = ls;
+      if (ls.some((l) => l.kind === "outliers" && l.shown === "points" && data.shape === "box")) data.overlay = "violin";
       // what the pair left out leads: cases missing either axis are not on the figure at all
       const pr: ViewResult = {
         kind: "plot", plot: data, cohorts: [cn], studies: sites,
         participation: participationFor(sites, false),
-        note: [coverageNote(data, unit), shapeNote, highlightNote(hs, unit)].filter(Boolean).join(" ") || undefined
+        note: [coverageNote(data, unit), combineNote(data, unit), densityNote(data, unit), layerNote(ls, unit)].filter(Boolean).join(" ") || undefined
       };
       return pr;
     } else {
@@ -248,12 +403,13 @@ export async function runPlot(view: DocView, c: ViewRun): Promise<ViewResult | U
         // Points, unlike a density, just concatenate: each entitled site's own case-level
         // rows are already independent of any shared scale. A site that may not disclose
         // cases contributes none, the same rule the oncoprint's columns follow.
-        if (pv.points !== false) {
+        if (pv.allPoints !== false) {
           const perSite = await Promise.all(sites.map((s) =>
             isPatientLevel(resolvers[s]) ? resolvers[s].plotPoints(doc.cohorts[cn], spec) : Promise.resolve([])));
-          const pts = perSite.flat();
+          const pts = perSite.every((p) => p) ? perSite.flatMap((p) => p!) : [];
           if (pts.length && pts.length <= POINTS_CAP) {
             data.points = pts; data.overlay = "points";
+            data.pointSet = { rule: "all", drawn: pts.length };
             if (pv.colorBy) data.legend = legendFor(pts.map((x) => x.c || ""));
             if (pv.ringBy) data.legend = [...(data.legend || []), ...legendFor(pts.map((x) => x.r || ""), true)];
           }
@@ -263,13 +419,14 @@ export async function runPlot(view: DocView, c: ViewRun): Promise<ViewResult | U
       // each site counts its own cases and their axes; the sums are exact. A failed count fails the
       // view: dropping the coverage note would hide how many cases the figure leaves out
       const covs = await Promise.all(sites.map((s) => fr[s].plotCoverage(doc.cohorts[cn], spec, xk, yk)));
-      data.coverage = covs.reduce<{ total: number; nx: number; ny: number }>(
-        (a, c) => ({ total: a.total + c.total, nx: a.nx + c.nx, ny: a.ny + c.ny }), { total: 0, nx: 0, ny: 0 });
-      const hs = await highlightLayers(pv, data, c, cn, sites, spec);
-      if (hs.length) data.highlights = hs;
+      data.coverage = covs.reduce<NonNullable<PlotData["coverage"]>>(
+        (a, c) => ({ total: a.total + c.total, nx: a.nx + c.nx, ny: a.ny + c.ny, ...(c.multi != null || a.multi != null ? { multi: (a.multi || 0) + (c.multi || 0) } : {}) }),
+        { total: 0, nx: 0, ny: 0 });
+      const ls = await pointLayers(pv, data, c, cn, sites, spec);
+      if (ls.length) data.layers = ls;
       const pr: ViewResult = { kind: "plot", plot: data, cohorts: [cn], studies: sites,
         participation: participationFor(sites, false),
-        note: [coverageNote(data, unit), data.note, highlightNote(hs, unit)].filter(Boolean).join(" ") || undefined };
+        note: [coverageNote(data, unit), combineNote(data, unit), data.note, layerNote(ls, unit)].filter(Boolean).join(" ") || undefined };
       return pr;
     }
   } catch (e) {
diff --git a/scripts/figure-stress.json b/scripts/figure-stress.json
index e37d50c1..2fb0e3df 100644
--- a/scripts/figure-stress.json
+++ b/scripts/figure-stress.json
@@ -964,8 +964,10 @@
      "gene": "TP53",
      "by": "mutationType"
     },
-    "highlight": [
-     "KRAS mut"
+    "points": [
+     {
+      "cohort": "KRAS mut"
+     }
     ]
    }
   ]
diff --git a/test/boundary.test.ts b/test/boundary.test.ts
index 760ce5bf..d5a52d3c 100644
--- a/test/boundary.test.ts
+++ b/test/boundary.test.ts
@@ -29,7 +29,7 @@ import {
   AggregateResolver, PatientLevelResolver, isPatientLevel
 } from "../lib/federation.ts";
 import * as federation from "../lib/federation.ts";
-import { axisSelect, highlightCohortSql, plotPointsSql, plotScatterPointsSql } from "../lib/plot.ts";
+import { axisSelect, highlightCohortSql, plotPointsSql, plotScatterPointsSql, plotRankedPointsSql } from "../lib/plot.ts";
 import { clinicalRowSource } from "../lib/clinical-table.ts";
 import { mutationRowSource } from "../lib/mutation-table.ts";
 import { alterationPatientRowSource, alterationSource, patientSamplesSource } from "../lib/patient-alterations.ts";
@@ -221,6 +221,21 @@ describe("remote peers: nothing identifying leaves before the network is touched
       "AggregateResolver must not be able to return the points behind a box");
     assert.equal(typeof (PatientLevelResolver.prototype as unknown as Record<string, unknown>).plotPoints, "function",
       "the entitled participant is the one that answers with points");
+    // a scatter's own points (every case, or its sparse-cell outliers) are the same entitlement
+    for (const R of [AggregateResolver, RemoteAggregateResolver])
+      assert.equal(typeof (R.prototype as unknown as Record<string, unknown>).plotScatterPoints, "undefined",
+        R.name + " must not be able to return a scatter's points");
+    assert.equal(typeof (PatientLevelResolver.prototype as unknown as Record<string, unknown>).plotScatterPoints, "function");
+    assert.match(plotScatterPointsSql("SELECT 1 AS id, 1 AS v", "SELECT 1 AS id, 2 AS v", "SELECT '' AS pid", 10,
+      { grid: [4, 4], extent: { x0: 0, x1: 1, y0: 0, y1: 1 }, cellMax: 2 }), /xs\.id AS id/);
+    // a ranked layer (extremes, or furthest from the fit) names its cases: the same entitlement
+    for (const R of [AggregateResolver, RemoteAggregateResolver])
+      assert.equal(typeof (R.prototype as unknown as Record<string, unknown>).plotRankedPoints, "undefined",
+        R.name + " must not be able to return a ranked layer's points");
+    assert.equal(typeof (PatientLevelResolver.prototype as unknown as Record<string, unknown>).plotRankedPoints, "function");
+    assert.equal("plotRankedPointsSql" in (federation as Record<string, unknown>), false,
+      "plotRankedPointsSql returns case ids and must not sit among the aggregate builders");
+    assert.match(plotRankedPointsSql("SELECT 1 AS id, 1 AS v", "SELECT 1 AS id, 2 AS v", "SELECT '' AS pid", "scatter", true, { by: "y", n: 5 }), /xs\.id AS id/);
   });
 
   test("a highlight's points are the entitlement too; its aggregates are anyone's", () => {
@@ -562,7 +577,7 @@ describe("patient-level federation is opt-in, on both sides, per study and kind"
     try { await fn(); } finally { for (const [k, v] of Object.entries(saved)) { if (v == null) delete process.env[k]; else process.env[k] = v; } }
   };
   const PEERS = "s1=http://peer.invalid/api/mcp,s2=http://peer.invalid/api/mcp";
-  const PATIENT_METHODS = ["members", "rowsPage", "rowsCounts", "rowsValues", "rowsRank", "plotPoints", "plotHighlightPoints", "coxRows", "logisticRows", "viewRows", "viewAggregate"];
+  const PATIENT_METHODS = ["members", "rowsPage", "rowsCounts", "rowsValues", "rowsRank", "plotPoints", "plotScatterPoints", "plotRankedPoints", "plotHighlightPoints", "coxRows", "logisticRows", "viewRows", "viewAggregate"];
 
   test("the rules: a study (or *) and the kinds allowed for it; a bare study is the timeline alone; an unknown kind is refused", () => {
     const r = parseRules("s1:timeline+alterations, s2 *:alterations", "X");
diff --git a/test/fixtures/example-counts.json b/test/fixtures/example-counts.json
index 4ee9d6df..31d70c4c 100644
--- a/test/fixtures/example-counts.json
+++ b/test/fixtures/example-counts.json
@@ -63,17 +63,17 @@
     "A plot of 13,000 samples, drawn as density": {
       "TP53 mut": 13105
     },
-    "Highlight cohorts on a plot: KRAS G12C and STK11 against 25,000 patients": {
+    "Point layers on a plot: KRAS G12C and STK11 against 25,000 patients": {
       "All patients": 24950,
       "KRAS G12C": 1113,
       "STK11 mut": 1206,
       "TP53 mut": 13105
     },
-    "A highlight that reaches beyond the plotted cohort": {
+    "A cohort layer that reaches beyond the plotted cohort": {
       "NSCLC": 7809,
       "KRAS G12C": 1113
     },
-    "Highlights across two studies": {
+    "Point layers across two studies": {
       "Lung (TCGA)": 1053,
       "KRAS mut": 175,
       "TP53 mut": 699
diff --git a/test/plot-highlight.test.ts b/test/plot-layers.test.ts
similarity index 51%
rename from test/plot-highlight.test.ts
rename to test/plot-layers.test.ts
index ed888587..68011bdb 100644
--- a/test/plot-highlight.test.ts
+++ b/test/plot-layers.test.ts
@@ -1,10 +1,11 @@
-// A plot's highlight cohorts: which participant is asked for what, when a highlight falls back
-// from points to an aggregate, how sites pool, and what is refused before anything is queried.
-// The resolvers are fakes that record their calls, so the test can say what was NOT asked.
+// A plot's point layers: which participant is asked for what, when a cohort layer falls back from
+// points to an aggregate, how rule layers rank and pool, how layers share the budget and their
+// cases, and what is refused before anything is queried. The resolvers are fakes that record their
+// calls, so the test can say what was NOT asked.
 import { test, describe } from "node:test";
 import assert from "node:assert/strict";
 import { runPlot } from "../lib/views/plot.ts";
-import { highlightCohortSql, plotHighlightCountSql, plotScatterPointsSql, axisSelect, POINTS_CAP, HIGHLIGHT_COLORS } from "../lib/plot.ts";
+import { highlightCohortSql, plotHighlightCountSql, plotScatterPointsSql, plotRankedPointsSql, axisSelect, POINTS_CAP, LAYER_COLORS } from "../lib/plot.ts";
 import type { ViewRun, EvaluatedCohort } from "../lib/views/run.ts";
 import type { PlotData, ViewResult } from "../lib/types.ts";
 
@@ -20,6 +21,7 @@ const box = (): PlotData => ({ shape: "box", n: 1000, x: { label: "CANCER_TYPE",
 function fake(mode: "patient-level" | "aggregate-only", calls: Calls, o: {
   data?: () => PlotData; count?: number; points?: unknown[] | null; bins?: { bx: number; by: number; n: number }[];
   boxRows?: { g: string; n: number; lo: number; hi: number; q1: number; median: number; q3: number }[];
+  ranked?: unknown[];
 } = {}) {
   const r: Record<string, unknown> = {
     instance: { mode, conn: { db: "db" }, label: mode },
@@ -32,6 +34,13 @@ function fake(mode: "patient-level" | "aggregate-only", calls: Calls, o: {
     plotHighlightBoxRows: async () => { calls.push("boxRows"); return o.boxRows || [{ g: "A", n: 7, lo: 1, hi: 9, q1: 3, median: 5, q3: 7 }]; },
   };
   // the case-level method exists only where the entitlement does, exactly as on the real resolvers
+  if (mode === "patient-level") {
+    r.plotScatterPoints = async () => [{ id: "P1", x: 10, y: 5 }];
+    r.plotPoints = async () => [{ id: "P1", g: "A", v: 5 }];
+    r.plotRankedPoints = async (_d: unknown, _s: unknown, _xk: unknown, _yk: unknown, rank: unknown) => {
+      calls.push("ranked " + JSON.stringify(rank)); return o.ranked || [{ id: "P1", x: 10, y: 5 }, { id: "P9", x: 90, y: 45 }];
+    };
+  }
   if (mode === "patient-level")
     r.plotHighlightPoints = async (_d: unknown, _h: unknown, _s: unknown, _xk: unknown, _yk: unknown, cap: number) => {
       calls.push("points cap=" + cap);
@@ -44,7 +53,7 @@ const evaluated = (studies: string[], count: number): EvaluatedCohort =>
   ({ studies, perStudy: Object.fromEntries(studies.map((s) => [s, { sql: "", count, mode: "patient-level" }])), count, text: "" });
 
 function run(resolvers: Record<string, unknown>, opts: {
-  highlight?: unknown; plotStudies?: string[]; hl?: Record<string, EvaluatedCohort>;
+  points?: unknown; plotStudies?: string[]; hl?: Record<string, EvaluatedCohort>; extra?: Record<string, unknown>;
 } = {}): Promise<ViewResult> {
   const plotStudies = opts.plotStudies || Object.keys(resolvers);
   const cohorts: Record<string, EvaluatedCohort> = { All: evaluated(plotStudies, 1000), ...(opts.hl || { R: evaluated(plotStudies, 10) }) };
@@ -54,8 +63,8 @@ function run(resolvers: Record<string, unknown>, opts: {
     participationFor: (studies: string[]) => ({ studies: studies.map((s) => ({ study: s, mode: "patient-level", instance: "" })), requiresPatientLevel: false, aggregateOnly: [] }),
     pin: null, studyProfiles: async () => ({ profiles: [], gaProfiles: [] }),
   } as unknown as ViewRun;
-  const view = { kind: "plot", cohorts: ["All"], x: { source: "clinical", attribute: "AGE" }, y: { source: "clinical", attribute: "TMB" },
-    ...(opts.highlight !== undefined ? { highlight: opts.highlight } : { highlight: ["R"] }) };
+  const view = { kind: "plot", unit: "patient", cohorts: ["All"], x: { source: "clinical", attribute: "AGE" }, y: { source: "clinical", attribute: "TMB" },
+    points: opts.points !== undefined ? opts.points : [{ cohort: "R" }], ...opts.extra };
   return runPlot(view as never, c).then((r) => ("result" in (r as object) ? (r as { result: ViewResult }).result : r as ViewResult));
 }
 
@@ -63,11 +72,11 @@ describe("a highlight on one study", () => {
   test("an entitled participant with few enough cases answers with points, in the first colour", async () => {
     const calls: Calls = [];
     const r = await run({ s: fake("patient-level", calls) });
-    const h = r.plot!.highlights![0];
+    const h = r.plot!.layers![0];
     assert.equal(h.shown, "points");
     assert.equal(h.points!.length, 2);
     assert.equal(h.n, 2);
-    assert.equal(h.color, HIGHLIGHT_COLORS[0]);
+    assert.equal(h.color, LAYER_COLORS[0]);
     assert.ok(calls.includes("points cap=" + POINTS_CAP));
     assert.ok(!calls.some((x) => x.startsWith("bins")), "points answered it, so no aggregate was asked for");
     assert.match(r.note!, /“R”: 10 patients, 2 patients drawn as points/);
@@ -77,7 +86,7 @@ describe("a highlight on one study", () => {
   test("past the cap the same cases come back as cells on the plot's own grid and extent, never the first 5,000", async () => {
     const calls: Calls = [];
     const r = await run({ s: fake("patient-level", calls, { points: null }) });
-    const h = r.plot!.highlights![0];
+    const h = r.plot!.layers![0];
     assert.equal(h.shown, "density");
     assert.equal(h.points, undefined);
     assert.deepEqual(h.bins, [{ bx: 2, by: 3, n: 7 }]);
@@ -89,7 +98,7 @@ describe("a highlight on one study", () => {
   test("an aggregate-only participant is never asked for points, and its highlight is an aggregate", async () => {
     const calls: Calls = [];
     const r = await run({ s: fake("aggregate-only", calls) });
-    const h = r.plot!.highlights![0];
+    const h = r.plot!.layers![0];
     assert.equal(h.shown, "density");
     assert.ok(!calls.some((x) => x.startsWith("points")));
     assert.match(h.why!, /may not show individual cases/);
@@ -98,7 +107,7 @@ describe("a highlight on one study", () => {
   test("on a box plot the fallback is a box per group", async () => {
     const calls: Calls = [];
     const r = await run({ s: fake("aggregate-only", calls, { data: box }) });
-    const h = r.plot!.highlights![0];
+    const h = r.plot!.layers![0];
     assert.equal(h.shown, "boxes");
     assert.equal(h.groups![0].median, 5);
     assert.equal(h.n, 7);
@@ -108,7 +117,8 @@ describe("a highlight on one study", () => {
     const calls: Calls = [];
     const table = (): PlotData => ({ shape: "table", n: 5, x: { label: "A", kind: "cat" }, y: { label: "B", kind: "cat" }, cells: [{ cx: "a", cy: "b", n: 5 }] });
     const r = await run({ s: fake("patient-level", calls, { data: table }) });
-    assert.equal(r.plot!.highlights![0].shown, "none");
+    assert.equal(r.error, undefined);
+    assert.equal(r.plot!.layers![0].shown, "none");
     assert.ok(!calls.some((x) => x.startsWith("points") || x.startsWith("bins")));
     assert.doesNotMatch(r.note!, /statistics are over/, "nothing is drawn, so there is nothing to tell apart from the statistics");
   });
@@ -116,15 +126,15 @@ describe("a highlight on one study", () => {
   test("a highlight's patients outside the plotted cohort are counted, and said so", async () => {
     const calls: Calls = [];
     const r = await run({ s: fake("patient-level", calls, { count: 6 }) });
-    assert.equal(r.plot!.highlights![0].inPlot, 6);
+    assert.equal(r.plot!.layers![0].inPlot, 6);
     assert.match(r.note!, /6 of its 10 patients in the plotted cohort/);
   });
 
   test("no highlight, no highlight queries", async () => {
     const calls: Calls = [];
-    const r = await run({ s: fake("patient-level", calls) }, { highlight: [] });
+    const r = await run({ s: fake("patient-level", calls) }, { points: [] });
     assert.deepEqual(calls, ["plot"]);
-    assert.equal(r.plot!.highlights, undefined);
+    assert.equal(r.plot!.layers, undefined);
   });
 });
 
@@ -141,7 +151,7 @@ describe("a highlight across studies", () => {
       plotCoverage: async () => ({ total: 500, nx: 500, ny: 500 }),
     });
     const r = await run(fed, { hl: { R: evaluated(["a", "b"], 20) } });
-    const h = r.plot!.highlights![0];
+    const h = r.plot!.layers![0];
     assert.equal(h.shown, "density", "never half points, half cells");
     assert.ok(!a.some((x) => x.startsWith("points")), "the entitled site is not asked for points it could not be drawn beside");
     assert.deepEqual(h.bins!.sort((p, q) => p.bx - q.bx), [{ bx: 1, by: 1, n: 7 }, { bx: 5, by: 5, n: 1 }]);
@@ -152,7 +162,7 @@ describe("a highlight across studies", () => {
   test("a highlight defined in a study the plot does not draw has none of its patients in the plot", async () => {
     const calls: Calls = [];
     const r = await run({ s: fake("patient-level", calls) }, { hl: { R: evaluated(["elsewhere"], 9) } });
-    const h = r.plot!.highlights![0];
+    const h = r.plot!.layers![0];
     assert.equal(h.inPlot, 0);
     assert.equal(h.shown, "none");
     assert.ok(!calls.includes("count"), "no study of the plot holds it, so none is asked");
@@ -160,24 +170,131 @@ describe("a highlight across studies", () => {
 });
 
 describe("what is refused before anything runs", () => {
-  for (const [highlight, re] of [
-    [["nope"], /no cohort named “nope”/],
-    [["All"], /is the plotted cohort itself/],
-    [["R", "R"], /named twice/],
-    [["R", "R2", "R3", "R4", "R5"], /at most 4/],
-    ["R", /a list of cohort names/],
-  ] as [unknown, RegExp][]) {
-    test(JSON.stringify(highlight), async () => {
+  const c = (n: string) => ({ cohort: n });
+  for (const [points, re, extra] of [
+    [[c("nope")], /no cohort named “nope”/],
+    [[c("All")], /is the plotted cohort itself/],
+    [[c("R"), c("R")], /named twice/],
+    [[c("R"), c("R2"), c("R3"), c("R4"), c("R5")], /at most 4 point layers/],
+    ["R", /give a list of layers/],
+    [[{ rule: "sideways" }], /unknown rule “sideways”/],
+    [[{ rule: "extremes" }], /names its axis/],
+    [[{ rule: "trend", n: 0 }], /n is a whole number from 1 to 500/],
+    [[{ rule: "trend", n: 501 }], /n is a whole number from 1 to 500/],
+    [[], /highlight is now a point layer/, { highlight: ["R"] }],
+    [[], /allPoints: give true or false/, { allPoints: "yes" }],
+  ] as [unknown, RegExp, Record<string, unknown>?][]) {
+    test(JSON.stringify(points) + (extra ? " " + JSON.stringify(extra) : ""), async () => {
       const calls: Calls = [];
       const hl = Object.fromEntries(["R", "R2", "R3", "R4", "R5"].map((n) => [n, evaluated(["s"], 1)]));
-      const r = await run({ s: fake("patient-level", calls) }, { highlight, hl });
+      const r = await run({ s: fake("patient-level", calls) }, { points, hl, extra });
       assert.match(r.error!, re);
       assert.deepEqual(calls, [], "refused before the plot itself was queried");
     });
   }
 });
 
-describe("the SQL a highlight adds", () => {
+describe("rule layers", () => {
+  test("extremes ask the entitled study for its top and bottom n on that axis, in the layer's colour", async () => {
+    const calls: Calls = [];
+    const r = await run({ s: fake("patient-level", calls) }, { points: [{ rule: "extremes", axis: "y", n: 2 }] });
+    const l = r.plot!.layers![0];
+    assert.equal(l.kind, "extremes");
+    assert.equal(l.label, "top and bottom 2 by TMB");
+    assert.equal(l.color, LAYER_COLORS[0]);
+    assert.equal(l.shown, "points");
+    assert.equal(l.points!.length, 2);
+    assert.ok(calls.includes('ranked {"by":"y","n":2}'), calls.join("; "));
+    assert.match(r.note!, /Point layers — top and bottom 2 by TMB: 2 patients\./);
+  });
+
+  test("trend ranks by distance from the plot's own fitted line, and n defaults to 50", async () => {
+    const calls: Calls = [];
+    await run({ s: fake("patient-level", calls) }, { points: [{ rule: "trend" }] });
+    assert.ok(calls.includes('ranked {"by":"residual","n":50,"slope":1,"intercept":0}'), calls.join("; "));
+  });
+
+  test("an axis with no numbers has no extremes, and a box has no fitted line: not drawn, saying why", async () => {
+    const calls: Calls = [];
+    const r = await run({ s: fake("patient-level", calls, { data: box }) }, { points: [{ rule: "extremes", axis: "x" }, { rule: "trend" }] });
+    assert.deepEqual(r.plot!.layers!.map((l) => [l.shown, l.why]),
+      [["none", "CANCER_TYPE is not numeric, so it has no extremes"], ["none", "a fitted line exists only on a scatter"]]);
+    assert.ok(!calls.some((x) => x.startsWith("ranked")));
+  });
+
+  test("outliers wait for the density: at or under the cap there is none, whether or not every case is drawn", async () => {
+    for (const extra of [{}, { allPoints: false }]) {
+      const r = await run({ s: fake("patient-level", []) }, { points: [{ rule: "outliers" }], extra });
+      assert.deepEqual([r.plot!.layers![0].shown, r.plot!.layers![0].why],
+        ["none", "at or under 5,000 cases there is no density for them to stand out of"], JSON.stringify(extra));
+    }
+  });
+
+  test("an aggregate-only participant is asked for no case at all: rule layers are not drawn, and say why", async () => {
+    const calls: Calls = [];
+    const r = await run({ s: fake("aggregate-only", calls) }, { points: [{ rule: "extremes", axis: "y" }] });
+    assert.equal(r.plot!.layers![0].shown, "none");
+    assert.match(r.plot!.layers![0].why!, /^s may not show individual cases$/);
+    assert.ok(!calls.some((x) => x.startsWith("ranked")));
+  });
+});
+
+describe("rule layers across studies", () => {
+  test("each study's own top n pools into the exact overall top n, and two studies' equal ids stay two cases", async () => {
+    const a: Calls = [], b: Calls = [];
+    const fed = {
+      a: fake("patient-level", a, { ranked: [{ id: "P1", x: 1, y: 50 }, { id: "P2", x: 2, y: 3 }] }),
+      b: fake("patient-level", b, { ranked: [{ id: "P1", x: 3, y: 40 }, { id: "P3", x: 4, y: 1 }] }),
+    };
+    for (const r of Object.values(fed)) Object.assign(r, {
+      plotAxisKinds: async () => ({ xk: "num", yk: "num", shape: "scatter", xLabel: "AGE", yLabel: "TMB" }),
+      plotExtent: async () => ({ n: 500, x0: 0, x1: 100, y0: 0, y1: 50 }),
+      plotBinCounts: async () => [{ bx: 1, by: 1, n: 500 }],
+      plotMoments: async () => ({ n: 500, sx: 1, sy: 1, sxy: 1, sxx: 2, syy: 2 }),
+      plotCoverage: async () => ({ total: 500, nx: 500, ny: 500 }),
+    });
+    const r = await run(fed, { points: [{ rule: "extremes", axis: "y", n: 1 }], hl: {} });
+    const l = r.plot!.layers![0];
+    assert.deepEqual(l.points!.map((p) => "y" in p ? p.y : null).sort((x, y) => x! - y!), [1, 50], "the highest of all, and the lowest of all");
+    assert.ok(a.includes('ranked {"by":"y","n":1}') && b.includes('ranked {"by":"y","n":1}'), "every study is asked for its own top n");
+  });
+});
+
+describe("layers together", () => {
+  test("a case two layers share is drawn by the first, and the caption counts what the second left to it", async () => {
+    const calls: Calls = [];
+    const r = await run({ s: fake("patient-level", calls) }, { points: [{ rule: "extremes", axis: "y", n: 1 }, { cohort: "R" }] });
+    const [first, second] = r.plot!.layers!;
+    assert.deepEqual(first.points!.map((p) => p.id).sort(), ["P1", "P9"]);
+    assert.equal(second.color, LAYER_COLORS[1], "colour follows place in the list");
+    assert.deepEqual(second.points!.map((p) => p.id), ["P2"], "P1 is the first layer's");
+    assert.equal(second.n, 2);
+    assert.equal(second.drawn, 1);
+    assert.match(r.note!, /2 patients drawn as points \(1 drawn by an earlier layer\)|2 samples drawn as points \(1 drawn by an earlier layer\)/);
+  });
+
+  test("the layers share one budget: once it is spent, a cohort layer becomes an aggregate and a rule layer is not drawn", async () => {
+    const calls: Calls = [];
+    const many = Array.from({ length: POINTS_CAP }, (_, i) => ({ id: "C" + i, x: 1, y: 1 }));
+    const r = await run({ s: fake("patient-level", calls, { points: many }) }, {
+      points: [{ cohort: "R" }, { rule: "extremes", axis: "y" }, { cohort: "R2" }], hl: { R: evaluated(["s"], 9), R2: evaluated(["s"], 9) } });
+    const [a, b, c] = r.plot!.layers!;
+    assert.equal(a.drawn, POINTS_CAP);
+    assert.equal(b.shown, "none");
+    assert.match(b.why!, /more than the 0 points the earlier layers left/);
+    assert.equal(c.shown, "density");
+    assert.match(c.why!, /the earlier layers used every point the figure draws/);
+  });
+
+  test("the default is the outliers alone, and [] draws none", async () => {
+    const r = await run({ s: fake("patient-level", []) }, { points: undefined, extra: {} });
+    const view = await run({ s: fake("patient-level", []) }, { points: [] });
+    assert.equal(view.plot!.layers, undefined);
+    assert.ok(r.plot!.layers);
+  });
+});
+
+describe("the SQL a point layer adds", () => {
   const ctx = { study: "x", db: "db", unit: "sample" as const, cohortSql: "SELECT pid FROM p" };
   test("a highlight narrows the plotted cohort; it never widens it", () => {
     const sql = highlightCohortSql("SELECT pid FROM plotted", "SELECT pid FROM hl");
@@ -186,6 +303,14 @@ describe("the SQL a highlight adds", () => {
   test("its count is a count", () => {
     assert.match(plotHighlightCountSql("SELECT pid FROM a", "SELECT pid FROM b"), /^SELECT count\(\) AS n FROM /);
   });
+  test("a ranked layer takes n from each end, per group on a box, and the fit's residual on a scatter", () => {
+    const x = axisSelect({ source: "clinical", attribute: "AGE" }, ctx, "num");
+    const box2 = plotRankedPointsSql(x, x, ctx.cohortSql, "box", true, { by: "y", n: 7 });
+    assert.match(box2, /ORDER BY v DESC, id LIMIT 7 BY g\)\n {2}UNION DISTINCT\n {2}\(SELECT id, y AS g, x AS v FROM pair ORDER BY v ASC, id LIMIT 7 BY g\)/);
+    assert.match(plotRankedPointsSql(x, x, ctx.cohortSql, "scatter", true, { by: "residual", n: 3, slope: 2, intercept: 1 }),
+      /ORDER BY abs\(y - \(1 \+ 2 \* x\)\) DESC, id LIMIT 3$/);
+    assert.match(plotRankedPointsSql(x, x, ctx.cohortSql, "scatter", true, { by: "x", n: 9999 }), /LIMIT 500\)/, "held to the maximum");
+  });
   test("a scatter's points carry their ids, and ask for one more than the cap so an overflow is seen", () => {
     const x = axisSelect({ source: "clinical", attribute: "AGE" }, ctx, "num");
     const sql = plotScatterPointsSql(x, x, ctx.cohortSql, 100);
diff --git a/test/plot-points.test.ts b/test/plot-points.test.ts
new file mode 100644
index 00000000..82c38c88
--- /dev/null
+++ b/test/plot-points.test.ts
@@ -0,0 +1,149 @@
+// Which cases a plot draws as points: every case at or under the cap; over it the default outliers
+// layer (a box's values beyond its whiskers, a scatter's sparse cells); none from a participant
+// that may not show cases. The resolvers are fakes that record their calls, so the test can say
+// what was asked of whom, and what was NOT.
+import { test, describe } from "node:test";
+import assert from "node:assert/strict";
+import { runPlot } from "../lib/views/plot.ts";
+import { POINTS_CAP, OUTLIER_CELL_MAX, sparseCellMax } from "../lib/plot.ts";
+import type { ViewRun, EvaluatedCohort } from "../lib/views/run.ts";
+import type { PlotData, ViewResult } from "../lib/types.ts";
+
+const EXTENT = { x0: 0, x1: 100, y0: 0, y1: 50 };
+const scatter = (n: number, bins: { bx: number; by: number; n: number }[]): PlotData => ({
+  shape: "scatter", n, x: { label: "AGE", kind: "num" }, y: { label: "TMB", kind: "num" },
+  extent: { ...EXTENT }, grid: [240, 160], bins,
+  stats: { pearson: 0.1, spearman: 0.1, slope: 1, intercept: 0, pPearson: 0.5, pSpearman: 0.5 } });
+const box = (n: number): PlotData => ({ shape: "box", n, x: { label: "CANCER_TYPE", kind: "cat" }, y: { label: "TMB", kind: "num" },
+  groups: [{ g: "A", n, lo: 0, hi: 100, q1: 2, median: 4, q3: 6, loWhisker: 0, hiWhisker: 12 }], overlay: "violin", violin: [] });
+
+type Call = { m: string; cap?: number; extra?: unknown };
+function fake(mode: "patient-level" | "aggregate-only", calls: Call[], data: () => PlotData, answers: {
+  all?: unknown[] | null; outliers?: unknown[] | null;
+} = {}) {
+  const r: Record<string, unknown> = {
+    instance: { mode, conn: { db: "db" }, label: mode },
+    plot: async () => data(),
+  };
+  if (mode === "patient-level") {
+    r.plotScatterPoints = async (_d: unknown, _s: unknown, cap?: number, sparse?: unknown) => {
+      calls.push({ m: "scatterPoints", cap, extra: sparse });
+      return sparse ? (answers.outliers === undefined ? [{ id: "o1", x: 99, y: 49 }] : answers.outliers)
+        : (answers.all === undefined ? [{ id: "a1", x: 1, y: 1 }, { id: "a2", x: 2, y: 2 }] : answers.all);
+    };
+    r.plotPoints = async (_d: unknown, _s: unknown, cap?: number, outside?: unknown) => {
+      calls.push({ m: "boxPoints", cap, extra: outside });
+      return outside ? (answers.outliers === undefined ? [{ id: "o1", g: "A", v: 90 }] : answers.outliers)
+        : (answers.all === undefined ? [{ id: "a1", g: "A", v: 3 }] : answers.all);
+    };
+  }
+  return r;
+}
+
+const evaluated = (studies: string[], count: number): EvaluatedCohort =>
+  ({ studies, perStudy: Object.fromEntries(studies.map((s) => [s, { sql: "", count, mode: "patient-level" }])), count, text: "" });
+
+async function run(resolver: Record<string, unknown>, view: Record<string, unknown> = {}): Promise<ViewResult> {
+  const c = {
+    doc: { cohorts: { All: { all: [] } } },
+    cohorts: { All: evaluated(["s"], 1000) }, resolvers: { s: resolver }, vNames: ["All"], vStudies: ["s"],
+    participationFor: (studies: string[]) => ({ studies: studies.map((s) => ({ study: s, mode: "patient-level", instance: "" })), requiresPatientLevel: false, aggregateOnly: [] }),
+    pin: null, studyProfiles: async () => ({ profiles: [], gaProfiles: [] }),
+  } as unknown as ViewRun;
+  const v = { kind: "plot", cohorts: ["All"], x: { source: "clinical", attribute: "AGE" }, y: { source: "clinical", attribute: "TMB" }, ...view };
+  const r = await runPlot(v as never, c);
+  return "result" in (r as object) ? (r as { result: ViewResult }).result : r as ViewResult;
+}
+
+describe("sparseCellMax: the cell threshold for a scatter's outlier points", () => {
+  test("the largest threshold whose cases fit under the cap, never above the maximum", () => {
+    const bins = [{ n: 1 }, { n: 1 }, { n: 2 }, { n: 3 }, { n: 50 }];
+    assert.equal(sparseCellMax(bins, 100, 3), 3, "1+1+2+3 = 7 cases fit");
+    assert.equal(sparseCellMax(bins, 4, 3), 2, "1+1+2 = 4 fit; adding the 3 does not");
+    assert.equal(sparseCellMax(bins, 100, 2), 2, "held to the maximum asked for");
+    assert.equal(sparseCellMax(bins, 1, 3), 0, "the lone cases alone are 2, more than 1: none is drawn");
+    assert.equal(sparseCellMax([{ n: 50 }], 100, 3), 3, "no sparse cell at all draws nothing, at any threshold");
+  });
+});
+
+describe("a scatter's points", () => {
+  test("at or under the cap every case is a point and no subset is asked for", async () => {
+    const calls: Call[] = [];
+    const r = await run(fake("patient-level", calls, () => scatter(2, [{ bx: 0, by: 0, n: 2 }])));
+    assert.deepEqual(r.plot!.pointSet, { rule: "all", drawn: 2 });
+    assert.equal(r.plot!.xyPoints!.length, 2);
+    assert.deepEqual(calls.map((c) => [c.m, c.extra]), [["scatterPoints", undefined]]);
+  });
+
+  test("over the cap the cases in sparse cells are points, against the plot's own grid and extent", async () => {
+    const calls: Call[] = [];
+    const n = POINTS_CAP + 1000;
+    const bins = [{ bx: 0, by: 0, n: n - 4 }, { bx: 5, by: 5, n: 1 }, { bx: 9, by: 9, n: 3 }];
+    const r = await run(fake("patient-level", calls, () => scatter(n, bins)));
+    assert.equal(calls.length, 1, "over the cap the every-case query is not run");
+    assert.deepEqual(calls[0].extra, { grid: [240, 160], extent: EXTENT, cellMax: OUTLIER_CELL_MAX });
+    assert.equal(calls[0].cap, POINTS_CAP);
+    assert.deepEqual(r.plot!.pointSet, { rule: "none", drawn: 0, why: "more than 5,000 cases" });
+    const l = r.plot!.layers![0];
+    assert.deepEqual([l.kind, l.shown, l.n, l.drawn, l.cellMax], ["outliers", "points", 1, 1, OUTLIER_CELL_MAX]);
+    assert.match(r.note!, /outliers: 1 sample in cells holding at most 3, left unshaded under them/);
+    assert.match(r.note!, /coefficients are over every sample/);
+  });
+
+  test("when even the lone cases are more than the cap, none is drawn and the caption says why", async () => {
+    const calls: Call[] = [];
+    const lone = Array.from({ length: POINTS_CAP + 1 }, (_, i) => ({ bx: i % 240, by: Math.floor(i / 240), n: 1 }));
+    const r = await run(fake("patient-level", calls, () => scatter(POINTS_CAP + 1, lone)));
+    assert.equal(calls.length, 0, "nothing is fetched to be thrown away");
+    assert.equal(r.plot!.pointSet!.rule, "none");
+    assert.equal(r.plot!.xyPoints, undefined);
+    assert.equal(r.plot!.layers![0].shown, "none");
+    assert.match(r.note!, /outliers: not drawn, the cases alone in a cell are more than the 5,000 points left to draw/);
+  });
+
+  test("an aggregate-only participant is never asked, and the caption names it", async () => {
+    const calls: Call[] = [];
+    const r = await run(fake("aggregate-only", calls, () => scatter(10, [{ bx: 0, by: 0, n: 10 }])));
+    assert.equal(calls.length, 0);
+    assert.deepEqual(r.plot!.pointSet, { rule: "none", drawn: 0, why: "s may not show individual cases" });
+    assert.match(r.note!, /No case is drawn as a point: s may not show individual cases/);
+    assert.match(r.note!, /outliers: not drawn, s may not show individual cases/);
+  });
+
+  test("allPoints: false and no layers ask for none", async () => {
+    const calls: Call[] = [];
+    const r = await run(fake("patient-level", calls, () => scatter(10, [{ bx: 0, by: 0, n: 10 }])), { allPoints: false, points: [] });
+    assert.equal(calls.length, 0);
+    assert.equal(r.plot!.pointSet!.rule, "none");
+    assert.equal(r.plot!.layers, undefined);
+  });
+});
+
+describe("a box's points", () => {
+  test("at or under the cap every value is a point", async () => {
+    const calls: Call[] = [];
+    const r = await run(fake("patient-level", calls, () => box(10)));
+    assert.deepEqual(r.plot!.pointSet, { rule: "all", drawn: 1 });
+    assert.equal(r.plot!.overlay, "points");
+    assert.deepEqual(calls.map((c) => c.m), ["boxPoints"]);
+  });
+
+  test("over the cap the values beyond each group's whiskers are points over the violin", async () => {
+    const calls: Call[] = [];
+    const r = await run(fake("patient-level", calls, () => box(POINTS_CAP + 1)));
+    assert.equal(calls.length, 1, "over the cap the every-value query is not run");
+    assert.deepEqual(calls[0].extra, [{ g: "A", n: POINTS_CAP + 1, lo: 0, hi: 100, q1: 2, median: 4, q3: 6, loWhisker: 0, hiWhisker: 12 }]);
+    assert.equal(r.plot!.overlay, "violin", "the violin stays: the outliers are drawn over it");
+    assert.equal(r.plot!.pointSet!.rule, "none");
+    assert.deepEqual([r.plot!.layers![0].kind, r.plot!.layers![0].drawn], ["outliers", 1]);
+    assert.match(r.note!, /outliers: 1 value beyond the whiskers/);
+  });
+
+  test("more outliers than the cap: none, never the first 5,000", async () => {
+    const calls: Call[] = [];
+    const r = await run(fake("patient-level", calls, () => box(POINTS_CAP * 3), { outliers: null }));
+    assert.equal(r.plot!.points, undefined);
+    assert.equal(r.plot!.layers![0].shown, "none");
+    assert.match(r.note!, /outliers: not drawn, more than 5,000 values lie beyond the whiskers/);
+  });
+});
diff --git a/test/plot.test.ts b/test/plot.test.ts
index 0a07fd48..8bd7d4e8 100644
--- a/test/plot.test.ts
+++ b/test/plot.test.ts
@@ -4,7 +4,7 @@ import test from "node:test";
 import assert from "node:assert/strict";
 import { axisKind, axisLabel, axisSelect, corrPValue, plotBinsSql, plotBoxSql, plotCountSql,
   plotShape, plotStatsSql, plotTableSql, plotPointsSql, plotViolinSql, categoryColor, isAbsent,
-  tukey, validateAxis, CATEGORY_CAP, DEFAULT_BINS , coverageNote } from "../lib/plot.ts";
+  tukey, validateAxis, CATEGORY_CAP, DEFAULT_BINS , coverageNote, combineNote, plotCoverageSql, plotScatterPointsSql, type PlotData } from "../lib/plot.ts";
 import { STYLE } from "../lib/oncoprint-style.ts";
 
 const ctx = { study: "x", db: "db", unit: "sample" as const, cohortSql: "SELECT pid FROM p" };
@@ -132,6 +132,26 @@ test("sample mode and patient mode ask different questions of the same table", (
   assert.equal(/toFloat64OrNull/.test(axisSelect(cat, ctx, "cat")), false);
 });
 
+test("patient mode combines a patient's samples by a stated rule, never by whichever row comes first", () => {
+  const n = axisSelect(num, { ...ctx, unit: "patient" }, "num"), c = axisSelect(cat, { ...ctx, unit: "patient" }, "cat");
+  // the patient's own row wins; otherwise a number is the samples' mean, a category their common value or "Multiple"
+  assert.match(n, /if\(countIf\(pref = 1\) > 0, anyIf\(v, pref = 1\), avgIf\(v, pref = 0\)\)/);
+  assert.match(c, /uniqExactIf\(v, pref = 0\) > 1, 'Multiple', anyIf\(v, pref = 0\)/);
+  assert.doesNotMatch(n + c, /argMax/, "argMax over equal preferences picks an arbitrary sample");
+  // in sample mode the patient's value is one row per sample, so the same rule copies it unchanged
+  assert.match(axisSelect(num, ctx, "num"), /avgIf\(v, pref = 0\)/);
+});
+
+test("patient mode's coverage counts the patients with several samples, and the caption says how they were combined", () => {
+  const pc = { ...ctx, unit: "patient" as const };
+  assert.match(plotCoverageSql("SELECT 1 AS id, 1 AS v", "SELECT 1 AS id, 1 AS v", pc), /HAVING count\(\) > 1\)\) AS multi/);
+  assert.doesNotMatch(plotCoverageSql("SELECT 1 AS id, 1 AS v", "SELECT 1 AS id, 1 AS v", ctx), /AS multi/, "sample mode has nothing to combine");
+  const d = { n: 10, x: { label: "A", kind: "num" }, y: { label: "B", kind: "num" }, coverage: { total: 10, nx: 10, ny: 10, multi: 3 } } as unknown as PlotData;
+  assert.match(combineNote(d, "patient"), /^3 patients have more than one sample: a numeric value is the mean of their samples', a category the samples' common value or “Multiple” where they differ, and an alteration counts if any sample has it\.$/);
+  assert.equal(combineNote(d, "sample"), "");
+  assert.equal(combineNote({ ...d, coverage: { ...d.coverage!, multi: 0 } }, "patient"), "");
+});
+
 test("an alteration axis answers for every case in the cohort, not only the altered ones", () => {
   const sql = axisSelect(alt, ctx, "cat");
   assert.match(sql, /LEFT JOIN/, "a case with no mutation still has an answer: 'Not mutated'");
@@ -225,3 +245,33 @@ test("unaltered is absence: neutral, and never a ring", () => {
   assert.equal(isAbsent("Unaltered"), true);
   assert.equal(isAbsent("Altered"), false);
 });
+
+test("a box's outlier query keeps the values beyond their own group's whiskers, labels quoted", () => {
+  const numSel = "SELECT 1 AS id, 1 AS v", catSel = "SELECT 1 AS id, 'g' AS v";
+  const sql = plotPointsSql(numSel, catSel, "SELECT '' AS pid", 100, undefined, undefined,
+    [{ g: "Missense", loWhisker: 0.5, hiWhisker: 12 }, { g: "it's", loWhisker: -1, hiWhisker: 3 }]);
+  assert.match(sql, /indexOf\(\['Missense', 'it\\'s'\], gs\.v\)/, "a label is a quoted literal, never spliced");
+  assert.match(sql, /vs\.v < arrayElement\(\[0\.5, -1\]/);
+  assert.match(sql, /vs\.v > arrayElement\(\[12, 3\]/);
+  assert.match(sql, /WHERE indexOf\([^)]*\) > 0 AND/, "a group with no whiskers matches nothing");
+  assert.match(plotPointsSql(numSel, catSel, "SELECT '' AS pid", 100, undefined, undefined, []), /WHERE 0/);
+  assert.throws(() => plotPointsSql(numSel, catSel, "SELECT '' AS pid", 100, undefined, undefined,
+    [{ g: "A", loWhisker: NaN, hiWhisker: 1 }]), /finite/);
+});
+
+test("a scatter's sparse cells are binned exactly as its density is", () => {
+  const x = "SELECT 1 AS id, 1 AS v", y = "SELECT 1 AS id, 2 AS v";
+  const extent = { x0: 0, x1: 696, y0: 0, y1: 1 };
+  const bins = plotBinsSql(x, y, "SELECT '' AS pid", [240, 160], extent);
+  const pts = plotScatterPointsSql(x, y, "SELECT '' AS pid", 5000, { grid: [240, 160], extent, cellMax: 3 });
+  // the same cell expression on both sides, so a point is in a cell the density did not shade
+  for (const axis of ["x", "y"]) {
+    const expr = bins.match(new RegExp("least\\(\\d+, toUInt32\\(floor\\(\\(" + axis + " - [^\\n]*?\\)\\)\\)"))![0];
+    assert.ok(pts.includes(expr), axis + ": " + expr);
+  }
+  assert.match(pts, /HAVING count\(\) <= 3/);
+  assert.match(pts, /0 AS x0, 696 AS x1, 0 AS y0, 1 AS y1/);
+  assert.match(pts, /LIMIT 5001$/, "one past the cap, so an overflow is seen and refused rather than cut");
+  assert.throws(() => plotScatterPointsSql(x, y, "SELECT '' AS pid", 5000, { grid: [240, 160], extent, cellMax: 0 }), /cellMax/);
+  assert.throws(() => plotScatterPointsSql(x, y, "SELECT '' AS pid", 5000, { grid: [240, 160], extent: { ...extent, x1: Infinity }, cellMax: 2 }), /finite/);
+});
diff --git a/test/view-svg.test.ts b/test/view-svg.test.ts
index f18d3416..c960905d 100644
--- a/test/view-svg.test.ts
+++ b/test/view-svg.test.ts
@@ -4,9 +4,10 @@
 import { test, describe } from "node:test";
 import assert from "node:assert/strict";
 import { viewToSvg, viewTitle, esc } from "../lib/view-svg.ts";
+import { PLOT_POINT_R } from "../lib/figures/plot.ts";
 import { buildLollipopGene } from "../lib/lollipop.ts";
 import type { ViewResult } from "../lib/types.ts";
-import { HIGHLIGHT_BASE, HIGHLIGHT_COLORS } from "../lib/plot-highlight.ts";
+import { LAYER_BASE, LAYER_COLORS } from "../lib/plot-layers.ts";
 
 const survival = (cohort: string): ViewResult => ({
   kind: "survival", cohorts: [cohort],
@@ -348,36 +349,38 @@ describe("sequence Sankey keeps everyone accounted for", () => {
 // grows (and the app's container scrolls), and past the colour key the rest is one disclosed
 // "other". Each is pinned here by counting what the SVG actually draws, so a fixed cap on
 // groups, categories or caption lines fails a test rather than hiding cases.
-describe("plot highlights: other cohorts drawn over the plotted one", () => {
-  const scatter = (highlights: any[]): ViewResult => ({ kind: "plot", note: "n", plot: {
+describe("plot point layers: subsets drawn over the plotted cohort", () => {
+  const scatter = (layers: any[]): ViewResult => ({ kind: "plot", note: "n", plot: {
     shape: "scatter", n: 100, x: { label: "AGE", kind: "num" }, y: { label: "TMB", kind: "num" },
     extent: { x0: 0, x1: 100, y0: 0, y1: 50 }, grid: [10, 10], bins: [{ bx: 1, by: 1, n: 100 }],
-    stats: { pearson: 0.1, spearman: null, slope: 0.1, intercept: 1, pPearson: 0.5, pSpearman: null }, highlights } as any });
-  const hl = (o: any) => ({ name: "R", color: HIGHLIGHT_COLORS[0], patients: 2, inPlot: 2, n: 2, shown: "points", ...o });
+    stats: { pearson: 0.1, spearman: null, slope: 0.1, intercept: 1, pPearson: 0.5, pSpearman: null }, layers } as any });
+  const hl = (o: any) => ({ kind: "cohort", name: "R", label: o.name || "R", color: LAYER_COLORS[0], patients: 2, inPlot: 2, n: 2, shown: "points", ...o });
 
-  test("the plotted cohort turns grey and each highlight's points draw in its colour, with a key", () => {
+  test("the plotted cohort turns grey and each layer's points draw in its colour, with a key", () => {
     const svg = viewToSvg(scatter([hl({ points: [{ id: "a", x: 10, y: 5 }, { id: "b", x: 90, y: 45 }] })]))!;
-    assert.match(svg, new RegExp('<rect [^>]*fill="' + HIGHLIGHT_BASE + '"'), "the base density is grey");
-    assert.equal((svg.match(new RegExp('<circle [^>]*fill="' + HIGHLIGHT_COLORS[0] + '" fill-opacity', "g")) || []).length, 2);
-    assert.match(svg, />R \(2\)</, "the key names the highlight and how many it drew");
-    assert.doesNotMatch(svg, /stroke="#D55E00" stroke-width="1.5" stroke-dasharray/, "the fitted line leaves the first highlight colour to the highlight");
+    assert.match(svg, new RegExp('<rect [^>]*fill="' + LAYER_BASE + '"'), "the base density is grey");
+    assert.equal((svg.match(new RegExp('<circle [^>]*fill="' + LAYER_COLORS[0] + '" fill-opacity', "g")) || []).length, 2);
+    assert.match(svg, />R \(2\)</, "the key names the layer and how many cases it holds");
+    assert.match(svg, />point layers</);
+    assert.doesNotMatch(svg, /stroke="#D55E00" stroke-width="1.5" stroke-dasharray/, "the fitted line leaves the first layer colour to the layer");
   });
 
-  test("without highlights the figure is as it was", () => {
+  test("without layers the figure is as it was", () => {
     const svg = viewToSvg(scatter([]))!;
-    assert.doesNotMatch(svg, new RegExp(HIGHLIGHT_BASE));
-    assert.doesNotMatch(svg, />highlighted</);
+    assert.doesNotMatch(svg, new RegExp(LAYER_BASE));
+    assert.doesNotMatch(svg, />point layers</);
   });
 
-  test("a highlight too large for points is cells on the same grid, in its colour", () => {
+  test("a cohort layer too large for points is cells on the same grid, in its colour", () => {
     const svg = viewToSvg(scatter([hl({ shown: "density", n: 9000, bins: [{ bx: 3, by: 4, n: 9000 }] })]))!;
-    assert.match(svg, new RegExp('<rect [^>]*fill="' + HIGHLIGHT_COLORS[0] + '"'));
-    assert.doesNotMatch(svg, new RegExp('<circle [^>]*fill="' + HIGHLIGHT_COLORS[0] + '" fill-opacity'));
+    assert.match(svg, new RegExp('<rect [^>]*fill="' + LAYER_COLORS[0] + '"'));
+    assert.doesNotMatch(svg, new RegExp('<circle [^>]*fill="' + LAYER_COLORS[0] + '" fill-opacity'));
   });
 
-  test("a highlight drawn as nothing gets no key entry", () => {
+  test("a layer drawn as nothing gets no key entry, and leaves the plotted cohort its colour", () => {
     const svg = viewToSvg(scatter([hl({ shown: "none", n: 0 })]))!;
-    assert.doesNotMatch(svg, />highlighted</);
+    assert.doesNotMatch(svg, />point layers</);
+    assert.doesNotMatch(svg, new RegExp(LAYER_BASE));
   });
 
   test("a cohort's name is escaped wherever the figure prints it", () => {
@@ -386,19 +389,86 @@ describe("plot highlights: other cohorts drawn over the plotted one", () => {
     assert.match(svg, /&lt;b&gt;&amp;evil/);
   });
 
-  test("on a box, a highlight's box sits in its group, and a value past the whiskers is pinned and counted", () => {
+  test("on a box, a cohort layer's box sits in its group, and a value past the axis is pinned and counted", () => {
     const v: ViewResult = { kind: "plot", plot: {
       shape: "box", n: 10, x: { label: "CANCER_TYPE", kind: "cat" }, y: { label: "TMB", kind: "num" },
       groups: [{ g: "A", n: 10, lo: 0, hi: 100, q1: 2, median: 4, q3: 6, loWhisker: 0, hiWhisker: 10 }], overlay: "none",
-      highlights: [
+      layers: [
         hl({ points: [{ id: "a", g: "A", v: 5 }, { id: "b", g: "A", v: 80 }] }),
-        hl({ name: "S", color: HIGHLIGHT_COLORS[1], shown: "boxes", n: 4, groups: [{ g: "A", n: 4, lo: 1, hi: 9, q1: 3, median: 5, q3: 7, loWhisker: 1, hiWhisker: 9 }] }),
+        hl({ name: "S", color: LAYER_COLORS[1], shown: "boxes", n: 4, groups: [{ g: "A", n: 4, lo: 1, hi: 9, q1: 3, median: 5, q3: 7, loWhisker: 1, hiWhisker: 9 }] }),
       ] } as any };
     const svg = viewToSvg(v)!;
-    assert.match(svg, new RegExp('<rect [^>]*fill="' + HIGHLIGHT_COLORS[1] + '" fill-opacity="0.85"'), "S is a box of its own");
-    assert.equal((svg.match(new RegExp('<circle [^>]*fill="' + HIGHLIGHT_COLORS[0] + '" fill-opacity', "g")) || []).length, 1, "the value inside the whiskers is a dot");
-    assert.match(svg, new RegExp('<path d="M[^"]*Z" fill="' + HIGHLIGHT_COLORS[0] + '"'), "the value past them is a triangle at the edge");
-    assert.match(svg, /1 highlighted value lies beyond the axis/);
+    assert.match(svg, new RegExp('<rect [^>]*fill="' + LAYER_COLORS[1] + '" fill-opacity="0.85"'), "S is a box of its own");
+    assert.equal((svg.match(new RegExp('<circle [^>]*fill="' + LAYER_COLORS[0] + '" fill-opacity', "g")) || []).length, 1, "the value inside the whiskers is a dot");
+    assert.match(svg, new RegExp('<path d="M[^"]*Z" fill="' + LAYER_COLORS[0] + '"'), "the value past them is a triangle at the edge");
+    assert.match(svg, /1 value of a point layer lies more than a whisker span past the/);
+  });
+
+  test("with the cases coloured by a category, a layer is a ring round the case, not a second fill", () => {
+    const v: ViewResult = { kind: "plot", plot: {
+      shape: "box", n: 3, x: { label: "G", kind: "cat" }, y: { label: "V", kind: "num" },
+      groups: [{ g: "A", n: 3, lo: 0, hi: 10, q1: 2, median: 4, q3: 6, loWhisker: 0, hiWhisker: 10 }], overlay: "points",
+      points: [{ id: "a", g: "A", v: 5, c: "X" }], legend: [{ label: "X", color: "#123456" }], colorLabel: "kind",
+      layers: [hl({ points: [{ id: "a", g: "A", v: 5 }] })] } as any };
+    const svg = viewToSvg(v)!;
+    assert.match(svg, new RegExp('<circle [^>]*fill="none" stroke="' + LAYER_COLORS[0] + '"'));
+    assert.doesNotMatch(svg, new RegExp('<circle [^>]*fill="' + LAYER_COLORS[0] + '" fill-opacity'));
+  });
+});
+
+describe("plot points: every case, or the outliers over the density", () => {
+  const base = { x: { label: "AGE", kind: "num" }, y: { label: "TMB", kind: "num" },
+    extent: { x0: 0, x1: 10, y0: 0, y1: 10 }, grid: [10, 10],
+    stats: { pearson: 0.1, spearman: 0.1, slope: 0, intercept: 0, pPearson: 0.5, pSpearman: 0.5 } };
+  const cells = (svg: string) => (svg.match(/<rect x="[^"]*" y="[^"]*" width="[^"]*" height="[^"]*" fill="[^"]*" fill-opacity/g) || []).length;
+  const dots = (svg: string) => (svg.match(/<circle /g) || []).length;
+
+  test("every case a point: no cell is shaded, and the caption says a dot is a case", () => {
+    const svg = viewToSvg({ kind: "plot", plot: { ...base, shape: "scatter", n: 3, bins: [{ bx: 1, by: 1, n: 2 }, { bx: 5, by: 5, n: 1 }],
+      xyPoints: [{ id: "a", x: 1, y: 1 }, { id: "b", x: 1.2, y: 1.1 }, { id: "c", x: 5, y: 5 }], pointSet: { rule: "all", drawn: 3 } } as any })!;
+    assert.equal(cells(svg), 0);
+    assert.equal(dots(svg), 3);
+    assert.match(svg, /Each dot is one case\./);
+    assert.doesNotMatch(svg, /Darker is more/);
+  });
+
+  test("outliers: the sparse cells are left to their points, the dense ones stay shaded", () => {
+    const svg = viewToSvg({ kind: "plot", plot: { ...base, shape: "scatter", n: 105,
+      bins: [{ bx: 1, by: 1, n: 100 }, { bx: 2, by: 2, n: 3 }, { bx: 9, by: 9, n: 2 }], pointSet: { rule: "none", drawn: 0 },
+      layers: [{ kind: "outliers", label: "outliers", color: LAYER_COLORS[0], n: 5, drawn: 5, shown: "points", cellMax: 3,
+        points: [{ id: "a", x: 2.1, y: 2.1 }, { id: "b", x: 2.2, y: 2.3 }, { id: "c", x: 2.4, y: 2.2 }, { id: "d", x: 9.5, y: 9.5 }, { id: "e", x: 9.6, y: 9.1 }] }] } as any })!;
+    assert.equal(cells(svg), 1, "only the cell of 100 is shaded");
+    assert.equal((svg.match(new RegExp('<circle [^>]*fill="' + LAYER_COLORS[0] + '" fill-opacity', "g")) || []).length, 5);
+    assert.match(svg, /Darker is more cases; the shade is logarithmic\./);
+  });
+
+  test("a point is the same size on every plot, whatever the count or shape", () => {
+    // a plotted case carries a fill-opacity; a legend swatch does not, and is not a case
+    const radii = (svg: string) => new Set([...svg.matchAll(/<circle [^>]*\br="([^"]+)"[^>]*fill-opacity/g)].map((m) => m[1]));
+    const few = viewToSvg({ kind: "plot", plot: { ...base, shape: "scatter", n: 2, bins: [{ bx: 1, by: 1, n: 2 }],
+      xyPoints: [{ id: "a", x: 1, y: 1 }, { id: "b", x: 2, y: 2 }], pointSet: { rule: "all", drawn: 2 } } as any })!;
+    const many = viewToSvg({ kind: "plot", plot: { ...base, shape: "scatter", n: 4000, bins: [{ bx: 1, by: 1, n: 4000 }],
+      xyPoints: Array.from({ length: 4000 }, (_, i) => ({ id: "p" + i, x: (i % 100) / 10, y: Math.floor(i / 100) / 4 })),
+      pointSet: { rule: "all", drawn: 4000 } } as any })!;
+    const boxed = viewToSvg({ kind: "plot", plot: { shape: "box", n: 3, x: { label: "G", kind: "cat" }, y: { label: "V", kind: "num" },
+      groups: [{ g: "A", n: 3, lo: 0, hi: 10, q1: 2, median: 4, q3: 6, loWhisker: 0, hiWhisker: 10 }], overlay: "points",
+      points: [{ id: "a", g: "A", v: 1 }, { id: "b", g: "A", v: 5, r: "Amplification" }, { id: "c", g: "A", v: 9 }],
+      legend: [{ label: "Amplification", color: "#f00", ring: true }], pointSet: { rule: "all", drawn: 3 } } as any })!;
+    for (const svg of [few, many, boxed]) assert.deepEqual([...radii(svg)], [String(PLOT_POINT_R)]);
+  });
+
+  test("a box's axis reaches its outliers, at most a whisker span past the whiskers; beyond that a counted triangle", () => {
+    const svg = viewToSvg({ kind: "plot", plot: { shape: "box", n: 1000, x: { label: "CANCER_TYPE", kind: "cat" }, y: { label: "TMB", kind: "num" },
+      groups: [{ g: "A", n: 1000, lo: 0, hi: 570, q1: 2, median: 4, q3: 6, loWhisker: 0, hiWhisker: 10 }],
+      overlay: "violin", violin: [{ g: "A", b: 0, n: 500 }, { g: "A", b: 15, n: 3 }], violinBins: 40, violinExtent: [0, 40], pointSet: { rule: "none", drawn: 0 },
+      layers: [{ kind: "outliers", label: "outliers", color: LAYER_COLORS[0], n: 2, drawn: 2, shown: "points",
+        points: [{ id: "a", g: "A", v: 15 }, { id: "b", g: "A", v: 570 }] }] } as any })!;
+    assert.match(svg, />20<\/text>/, "the axis tops out at whisker + one whisker span (10 + 10)");
+    assert.equal((svg.match(/<circle [^>]*fill-opacity/g) || []).length, 1, "the 15 is a dot on the axis");
+    assert.equal((svg.match(/<path d="M[^"]*Z"/g) || []).length, 1, "the 570 is a triangle at the edge");
+    assert.match(svg, /1 value of a point layer lies more than a whisker span past the whiskers and is drawn as a triangle/);
+    // the violin stops at the whiskers: its bin at 15..16 lies past them but inside the axis, where the points are
+    assert.equal((svg.match(/fill-opacity="0\.28"/g) || []).length, 1, "one violin bin drawn, the one inside the whiskers");
   });
 });