Merge pull request 'Live wall attention cues: NEW lane, pin pulse, opt-in tone and notifications (#238)' (#276) from feat/238-attention-cues into main

drb-frontend/components/LiveView.tsx

@@ -24,13 +24,18 @@
  * and merges them in, so a long incident's path and spine are complete. An
  * `#inc=` that is not active is fetched by id (resolved → banner; missing or
  * another org → "not found"). The scrubber hatches time the window didn't load.
+ *
+ * Attention cues (server-26#238): lib/attention.ts diffs successive snapshots
+ * (Major opened, severity up, pursuit path stop, priority keyword) after a
+ * silent baseline. Cues, the NEW lane and pin pulses only ever cover the
+ * FILTERED incidents; tone and notifications are opt-in (AttentionControls).
  */
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import dynamic from "next/dynamic";
 import { useNodes } from "@/lib/useNodes";
 import { useSystems } from "@/lib/useSystems";
 import { useActiveCalls, useCalls, useCallsByIncident } from "@/lib/useCalls";
-import { useActiveIncidents, useIncident } from "@/lib/useIncidents";
+import { useActiveIncidentsState, useIncident } from "@/lib/useIncidents";
 import { useAuth } from "@/components/AuthProvider";
 import { useAircraft } from "@/lib/useAircraft";
 import { useVessels } from "@/lib/useVessels";
@@ -54,6 +59,9 @@ import { CameraDrill } from "@/components/live/CameraDrill";
 import { IncidentPanel, RegionPanel } from "@/components/live/WallPanels";
 import { TruthStrip } from "@/components/live/TruthStrip";
 import { usePipelineHealth } from "@/lib/usePipelineHealth";
+import { DEFAULT_ATTENTION_PREFS, loadAttentionPrefs, saveAttentionPrefs, useAttention, type AttentionPrefs } from "@/lib/attention";
+import { NewLane } from "@/components/live/NewLane";
+import { AttentionControls, useAttentionCues } from "@/components/live/AttentionControls";
 
 const MapView = dynamic(() => import("@/components/MapView"), { ssr: false });
 
@@ -140,7 +148,7 @@ function Kpi({ value, label }: { value: string | number; label: string }) {
 export function LiveView() {
   const { nodes, loading: nodesLoading } = useNodes();
   const activeCalls = useActiveCalls();
-  const activeIncidents = useActiveIncidents();
+  const { incidents: activeIncidents, loaded: incidentsLoaded } = useActiveIncidentsState();
   // Wide-ish recent window: feeds incident paths, the call spine, the ticker
   // and the scrubber's density bars. Real recent calls, not a fixture.
   const { calls: recentCalls, loading: callsLoading, error: callsError, hasMore: windowFull } = useCalls(RECENT_CALLS);
@@ -399,6 +407,32 @@ export function LiveView() {
 
   // ── Navigation ────────────────────────────────────────────────────────────
   const selectIncident = useCallback((id: string) => patchLink({ inc: id, cam: null, tour: false }), [patchLink]);
+
+  // ── Attention cues (server-26#238) ────────────────────────────────────────
+  // Diffed over everything loaded (so widening the filter is never "new");
+  // emitted, laned and pulsed only for what the filter shows.
+  const [attnPrefs, setAttnPrefs] = useState<AttentionPrefs>(DEFAULT_ATTENTION_PREFS);
+  useEffect(() => { setAttnPrefs(loadAttentionPrefs()); }, []);
+  const changeAttnPrefs = useCallback((p: AttentionPrefs) => { setAttnPrefs(p); saveAttentionPrefs(p); }, []);
+  const cues = useAttentionCues(attnPrefs, selectIncident);
+  const attentionCalls = useMemo(() => {
+    if (!incidentCalls.length) return recentCalls;
+    const have = new Set(recentCalls.map((c) => c.call_id));
+    const extra = incidentCalls.filter((c) => !have.has(c.call_id));
+    return extra.length ? [...recentCalls, ...extra] : recentCalls;
+  }, [recentCalls, incidentCalls]);
+  const visibleCallIds = useMemo(() => new Set(filtered.calls.map((c) => c.call_id)), [filtered.calls]);
+  const attention = useAttention({
+    ready: incidentsLoaded && !!orgId,
+    resetKey: orgId ?? null,
+    incidents: activeIncidents,
+    calls: attentionCalls,
+    keywords: attnPrefs.keywords,
+    visible: filtered.incidents,
+    visibleIds: filtered.ids,
+    visibleCallIds,
+    onEvents: cues.fire,
+  });
   const openCamera = useCallback((c: Camera) => patchLink({ cam: c.id, tour: false }), [patchLink]);
   const stepUp = useCallback(() => {
     if (link.cam) patchLink({ cam: null, tour: false });
@@ -502,6 +536,7 @@ export function LiveView() {
             className="px-2 py-0.5 rounded border border-line text-ink-2 hover:text-ink whitespace-nowrap" aria-live="polite">
             {copied === "ok" ? "Link copied" : copied === "fail" ? "Copy failed — use the address bar" : "Copy view link"}
           </button>
+          <AttentionControls prefs={attnPrefs} onChange={changeAttnPrefs} armed={cues.armed} />
           <KioskControls kiosk={kiosk} state={kioskState} onToggleKiosk={toggleKiosk} />
           <span className="font-mono text-ink-2 tabular-nums">{clock}</span>
         </div>
@@ -539,6 +574,7 @@ export function LiveView() {
               onOpenCamera={openCamera}
               onAir={onAir}
               camCountByIncident={camCountByIncident}
+              pulseIncidentIds={attention.pulseIds}
               key={mapGen}
               initialLayers={mapState.layers}
               initialBase={mapState.base}
@@ -548,6 +584,10 @@ export function LiveView() {
           )}
           </div>
 
+          {!nodesLoading && !callsLoading && mapState && (
+            <NewLane entries={attention.lane} now={attention.now} onSelect={selectIncident} />
+          )}
+
           {/* Configured-and-quiet — distinct from "no nodes at all" (chunk 10's
               Activation screen handles the zero-node case). */}
           {configuredButQuiet && (

drb-frontend/components/live/AttentionControls.tsx

@@ -0,0 +1,253 @@
+"use client";
+
+/**
+ * Attention cues (server-26#238) — the opt-in half: an audible tone and
+ * browser notifications, both OFF by default.
+ *
+ * Tone: Web Audio beep, no asset. Browsers only let audio start from a user
+ * gesture, so the AudioContext is created by the click that turns the tone
+ * on (and that click plays one confirmation beep). After a reload with the
+ * tone already on, the first click/key anywhere on the page re-arms it; until
+ * then nothing plays and the button says so.
+ *
+ * Notifications: Notification.requestPermission() on click; fired only while
+ * the tab is hidden (a visible wall already shows the lane and pulse). The
+ * body ends with the Gate A machine-output notice — the title it carries is
+ * pipeline output. No transcript text goes into a notification.
+ */
+import { useCallback, useEffect, useRef, useState } from "react";
+import { DEFAULT_KEYWORDS, parseKeywords, type AttentionEvent, type AttentionPrefs } from "@/lib/attention";
+import { MACHINE_OUTPUT_NOTICE_TEXT } from "@/components/ui/MachineOutputNotice";
+
+const TONE_GAP_MS = 4_000;
+const MAX_NOTIFICATIONS = 3;
+
+// ── Audio (one context per page, only ever created inside a user gesture) ────
+let audioCtx: AudioContext | null = null;
+
+function createAudio(): AudioContext | null {
+  try {
+    if (!audioCtx) {
+      const AC = window.AudioContext ?? (window as unknown as { webkitAudioContext?: typeof AudioContext }).webkitAudioContext;
+      if (!AC) return null;
+      audioCtx = new AC();
+    }
+    if (audioCtx.state === "suspended") void audioCtx.resume().catch(() => undefined);
+    return audioCtx;
+  } catch {
+    return null;
+  }
+}
+
+/** n short beeps, alternating 880/660 Hz. Silent unless a gesture already started the context. */
+function beep(n: number) {
+  const a = audioCtx;
+  if (!a || a.state !== "running") return;
+  try {
+    for (let i = 0; i < n; i++) {
+      const t0 = a.currentTime + i * 0.22;
+      const osc = a.createOscillator();
+      const gain = a.createGain();
+      osc.type = "sine";
+      osc.frequency.value = i % 2 ? 660 : 880;
+      gain.gain.setValueAtTime(0.0001, t0);
+      gain.gain.exponentialRampToValueAtTime(0.25, t0 + 0.02);
+      gain.gain.exponentialRampToValueAtTime(0.0001, t0 + 0.18);
+      osc.connect(gain).connect(a.destination);
+      osc.start(t0);
+      osc.stop(t0 + 0.2);
+    }
+  } catch { /* audio unavailable */ }
+}
+
+type NotifyState = "unsupported" | "default" | "granted" | "denied";
+
+function notifyState(): NotifyState {
+  if (typeof window === "undefined" || !("Notification" in window)) return "unsupported";
+  return Notification.permission as NotifyState;
+}
+
+const HEADLINE: Record<AttentionEvent["kind"], string> = {
+  major: "Major incident",
+  escalated: "Severity escalated",
+  stop: "Pursuit path: new stop",
+  keyword: "Priority keyword",
+};
+
+/**
+ * Fires the opted-in cues for a batch of in-view events. Returns `fire` (pass
+ * to useAttention's onEvents) and the live audio state for the controls.
+ */
+export function useAttentionCues(prefs: AttentionPrefs, onOpenIncident: (id: string) => void) {
+  const [armed, setArmed] = useState(false);
+  const lastTone = useRef(0);
+  const prefsRef = useRef(prefs);
+  prefsRef.current = prefs;
+  const openRef = useRef(onOpenIncident);
+  openRef.current = onOpenIncident;
+
+  // Tone on: track the context's state. Already on from an earlier visit →
+  // the next gesture anywhere on the page creates/resumes the context.
+  useEffect(() => {
+    if (!prefs.tone) { setArmed(false); return; }
+    const sync = () => setArmed(audioCtx?.state === "running");
+    const arm = () => {
+      const a = createAudio();
+      if (a) { a.onstatechange = sync; a.resume().then(sync, () => undefined); }
+    };
+    if (audioCtx) { audioCtx.onstatechange = sync; sync(); }
+    window.addEventListener("pointerdown", arm, { once: true });
+    window.addEventListener("keydown", arm, { once: true });
+    return () => {
+      window.removeEventListener("pointerdown", arm);
+      window.removeEventListener("keydown", arm);
+    };
+  }, [prefs.tone]);
+
+  const fire = useCallback((events: AttentionEvent[]) => {
+    if (!events.length) return;
+    const p = prefsRef.current;
+    if (p.tone && Date.now() - lastTone.current > TONE_GAP_MS) {
+      lastTone.current = Date.now();
+      // Three beeps for anything reaching Major or a priority keyword, one otherwise.
+      beep(events.some((e) => e.kind === "major" || e.kind === "keyword" || e.label.endsWith("Major")) ? 3 : 1);
+    }
+    if (!p.notify || typeof document === "undefined" || !document.hidden || notifyState() !== "granted") return;
+    const send = (title: string, body: string, tag: string, incidentId: string | null) => {
+      try {
+        const n = new Notification(title, { body: `${body}\n${MACHINE_OUTPUT_NOTICE_TEXT}`, tag });
+        n.onclick = () => {
+          window.focus();
+          if (incidentId) openRef.current(incidentId);
+          n.close();
+        };
+      } catch { /* e.g. mobile Chrome needs a service worker — silently no notification */ }
+    };
+    for (const e of events.slice(0, MAX_NOTIFICATIONS)) {
+      const head = e.kind === "keyword" ? `${HEADLINE.keyword}: ${e.label}` : e.kind === "escalated" ? `${HEADLINE.escalated}: ${e.label.replace(/^↑\s*/, "")}` : HEADLINE[e.kind];
+      send(`DRB · ${head}`, e.title, `drb-attn:${e.incidentIds[0] ?? e.id}`, e.incidentIds[0] ?? null);
+    }
+    if (events.length > MAX_NOTIFICATIONS) {
+      send("DRB · More activity", `${events.length - MAX_NOTIFICATIONS} more on the live wall.`, "drb-attn:more", null);
+    }
+  }, []);
+
+  return { fire, armed };
+}
+
+interface Props {
+  prefs: AttentionPrefs;
+  onChange: (p: AttentionPrefs) => void;
+  armed: boolean;
+}
+
+export function AttentionControls({ prefs, onChange, armed }: Props) {
+  const [open, setOpen] = useState(false);
+  const [perm, setPerm] = useState<NotifyState>("default");
+  const [kwDraft, setKwDraft] = useState(prefs.keywords.join(", "));
+  const boxRef = useRef<HTMLDivElement>(null);
+
+  useEffect(() => { setPerm(notifyState()); }, [open]);
+  useEffect(() => { setKwDraft(prefs.keywords.join(", ")); }, [prefs.keywords]);
+  useEffect(() => {
+    if (!open) return;
+    const onDown = (e: MouseEvent) => { if (boxRef.current && !boxRef.current.contains(e.target as Node)) setOpen(false); };
+    const onKey = (e: KeyboardEvent) => { if (e.key === "Escape") setOpen(false); };
+    document.addEventListener("mousedown", onDown);
+    document.addEventListener("keydown", onKey);
+    return () => { document.removeEventListener("mousedown", onDown); document.removeEventListener("keydown", onKey); };
+  }, [open]);
+
+  const toggleTone = () => {
+    if (prefs.tone) { onChange({ ...prefs, tone: false }); return; }
+    // This click is the gesture that unlocks audio; confirm with one beep.
+    const a = createAudio();
+    onChange({ ...prefs, tone: true });
+    if (a) a.resume().then(() => beep(1), () => undefined);
+  };
+
+  const toggleNotify = async () => {
+    if (prefs.notify) { onChange({ ...prefs, notify: false }); return; }
+    if (notifyState() === "unsupported") { setPerm("unsupported"); return; }
+    let p: NotifyState = notifyState();
+    if (p === "default") {
+      try { p = (await Notification.requestPermission()) as NotifyState; } catch { p = notifyState(); }
+    }
+    if (p === "granted") {
+      // Confirm with one notification (as the tone confirms with a beep). It
+      // doubles as the support check: mobile Chrome grants permission but
+      // throws on `new Notification()` without a service worker, which would
+      // otherwise leave a switched-on control that never delivers anything.
+      try {
+        new Notification("DRB · Notifications on", {
+          body: `Cues will appear here while the live wall tab is hidden.\n${MACHINE_OUTPUT_NOTICE_TEXT}`,
+          tag: "drb-attn:on",
+        });
+      } catch {
+        p = "unsupported";
+      }
+    }
+    setPerm(p);
+    if (p === "granted") onChange({ ...prefs, notify: true });
+  };
+
+  const commitKeywords = () => {
+    const next = parseKeywords(kwDraft);
+    if (next.join("\u0001") !== prefs.keywords.join("\u0001")) onChange({ ...prefs, keywords: next });
+    else setKwDraft(prefs.keywords.join(", "));
+  };
+
+  const notifyOn = prefs.notify && perm !== "denied" && perm !== "unsupported";
+  const summary = [prefs.tone ? (armed ? "tone" : "tone (click to arm)") : null, notifyOn ? "notify" : null].filter(Boolean).join(" · ") || "off";
+  const on = prefs.tone || notifyOn;
+
+  return (
+    <div ref={boxRef} className="relative">
+      <button type="button" aria-expanded={open} aria-haspopup="dialog" onClick={() => setOpen((v) => !v)}
+        title="Attention cues: an audible tone and browser notifications for new Majors, escalations, pursuit stops and priority keywords"
+        className={`px-2 py-0.5 rounded border whitespace-nowrap ${on ? "border-accent text-accent" : "border-line text-ink-2 hover:text-ink"}`}>
+        Cues: {summary}
+      </button>
+      {open && (
+        <div role="dialog" aria-label="Attention cues"
+          className="absolute right-0 top-full mt-1 z-[1100] w-72 max-w-[calc(100vw-2rem)] bg-surface border border-line rounded-lg shadow-lg p-3 space-y-3 text-xs text-ink-2">
+          <p className="text-ink-muted leading-snug">
+            Cues fire on: a Major opened, severity escalated, a pursuit path gaining a stop, or a priority keyword in a new
+            call. Only for incidents the current filter shows.
+          </p>
+          <label className="flex items-start gap-2 cursor-pointer">
+            <input type="checkbox" className="mt-0.5" checked={prefs.tone} onChange={toggleTone} />
+            <span>
+              <span className="text-ink font-medium">Sound a tone</span>
+              {prefs.tone && !armed && (
+                <span className="block text-ink-muted">Click anywhere on the page to arm it — browsers block sound until you do.</span>
+              )}
+            </span>
+          </label>
+          <label className="flex items-start gap-2 cursor-pointer">
+            <input type="checkbox" className="mt-0.5" checked={notifyOn} disabled={perm === "unsupported"} onChange={() => { void toggleNotify(); }} />
+            <span>
+              <span className="text-ink font-medium">Browser notifications while this tab is hidden</span>
+              {perm === "denied" && <span className="block text-ink-muted">Blocked in this browser&apos;s site settings — allow notifications there first.</span>}
+              {perm === "unsupported" && <span className="block text-ink-muted">This browser doesn&apos;t show notifications from a web page (mobile browsers often only allow them from installed apps).</span>}
+            </span>
+          </label>
+          <div>
+            <label htmlFor="attn-kw" className="block text-ink font-medium mb-1">Priority keywords</label>
+            <input id="attn-kw" type="text" value={kwDraft} onChange={(e) => setKwDraft(e.target.value)} onBlur={commitKeywords}
+              onKeyDown={(e) => { if (e.key === "Enter") commitKeywords(); }}
+              placeholder="comma-separated"
+              className="w-full px-2 py-1 rounded border border-line bg-raised text-ink" />
+            <div className="mt-1 flex items-center justify-between text-ink-muted">
+              <span>Matched against new call transcripts.</span>
+              <button type="button" className="underline hover:text-ink"
+                onClick={() => onChange({ ...prefs, keywords: [...DEFAULT_KEYWORDS] })}>
+                Reset
+              </button>
+            </div>
+          </div>
+        </div>
+      )}
+    </div>
+  );
+}

drb-frontend/components/live/NewLane.tsx

@@ -0,0 +1,87 @@
+"use client";
+
+/**
+ * "NEW · last 15 min" (server-26#238). The rail is worst-first, so a fresh
+ * minor that is escalating sits under stale Majors; this lane is the
+ * recency view of the same FILTERED incidents, newest first, with why each
+ * one is here ("New", "↑ Major", "+1 stop", a priority keyword).
+ *
+ * Desktop: overlay at the map's top-left, right of the zoom stack and above
+ * MapView's rail (the rail starts at top-[9.5rem], so the lane is capped
+ * just short of it and its rows scroll). The Gate A notice is pinned below
+ * the rows, never inside the scroll area — same rule as the rail (#46).
+ * Mobile: a compact chip under MapView's centred "Live" chip (same top-3
+ * centre slot would cover it), right of the fit-all button; it expands.
+ * Hidden when there is nothing new.
+ */
+import { useState } from "react";
+import type { LaneEntry } from "@/lib/attention";
+import { SEVERITY_COLORS, isKnownSeverity } from "@/lib/severity";
+import { MachineOutputNotice } from "@/components/ui/MachineOutputNotice";
+
+function ago(at: number, now: number): string {
+  const m = Math.max(0, Math.floor((now - at) / 60_000));
+  return m < 1 ? "now" : `${m}m`;
+}
+
+function Row({ e, now, onSelect }: { e: LaneEntry; now: number; onSelect: (id: string) => void }) {
+  const color = isKnownSeverity(e.severity) ? SEVERITY_COLORS[e.severity] : "var(--ink-muted)";
+  const body = (
+    <>
+      <span className="w-1 self-stretch rounded-full shrink-0" style={{ background: color }} aria-hidden="true" />
+      <span className="min-w-0 flex-1 truncate text-ink">{e.title}</span>
+      <span className="shrink-0 px-1 rounded bg-accent/15 text-accent font-semibold">{e.reason}</span>
+      <span className="shrink-0 tabular-nums text-ink-muted">{ago(e.at, now)}</span>
+    </>
+  );
+  const cls = "w-full flex items-center gap-1.5 px-1.5 py-1 rounded text-xs text-left";
+  return (
+    <li>
+      {e.incidentId ? (
+        <button type="button" className={`${cls} hover:bg-raised`} onClick={() => onSelect(e.incidentId!)}
+          title={`${e.title} — ${e.reason}`}>
+          {body}
+        </button>
+      ) : (
+        <div className={cls} title={`${e.title} — ${e.reason} (call not linked to an incident yet)`}>{body}</div>
+      )}
+    </li>
+  );
+}
+
+export function NewLane({ entries, now, onSelect }: { entries: LaneEntry[]; now: number; onSelect: (id: string) => void }) {
+  const [open, setOpen] = useState(false);
+  if (!entries.length) return null;
+  const notice = <MachineOutputNotice variant="inline" className="text-[10px] leading-snug items-start px-1.5 pt-1" />;
+  return (
+    <>
+      <section aria-label="New in the last 15 minutes"
+        className="absolute top-3 left-14 z-[1002] hidden md:flex flex-col w-56 max-h-[8.5rem] bg-surface/90 backdrop-blur-sm border border-accent/60 rounded-lg shadow pointer-events-auto">
+        <h2 className="shrink-0 px-2 pt-1.5 text-[10px] font-semibold uppercase tracking-wide text-accent">
+          New · last 15 min <span className="text-ink-muted font-normal">({entries.length})</span>
+        </h2>
+        <ul className="min-h-0 overflow-y-auto px-0.5">
+          {entries.map((e) => <Row key={e.key} e={e} now={now} onSelect={onSelect} />)}
+        </ul>
+        <div className="shrink-0 border-t border-line pb-1">{notice}</div>
+      </section>
+
+      <div className="absolute top-[5.25rem] left-14 z-[1002] md:hidden flex flex-col items-start">
+        <button type="button" aria-expanded={open} onClick={() => setOpen((v) => !v)}
+          className="bg-surface/95 border border-accent/60 rounded-full px-3 py-1 text-xs text-accent font-semibold whitespace-nowrap shadow">
+          ● {entries.length} new · 15 min {open ? "▴" : "▾"}
+        </button>
+        {open && (
+          <div className="mt-1 w-64 max-w-[calc(100vw-4.5rem)] bg-surface/95 border border-line rounded-lg shadow p-0.5 flex flex-col">
+            <ul className="max-h-40 overflow-y-auto">
+              {entries.map((e) => (
+                <Row key={e.key} e={e} now={now} onSelect={(id) => { setOpen(false); onSelect(id); }} />
+              ))}
+            </ul>
+            <div className="shrink-0 border-t border-line pb-1">{notice}</div>
+          </div>
+        )}
+      </div>
+    </>
+  );
+}

drb-frontend/components/ui/MachineOutputNotice.tsx

@@ -50,6 +50,14 @@ function InfoGlyph({ className }: { className?: string }) {
 }
 
 const LEAD = "Machine-generated and unverified";
+const SHORT_BODY = "automated output, may contain errors.";
+
+/**
+ * The short notice as plain text, for surfaces that cannot render this
+ * component — e.g. a browser notification body (server-26#238). Same copy
+ * rules as above; it is the "popup"/"inline" wording verbatim.
+ */
+export const MACHINE_OUTPUT_NOTICE_TEXT = `${LEAD} — ${SHORT_BODY}`;
 
 interface Props {
   variant?: Variant;
@@ -62,7 +70,7 @@ export function MachineOutputNotice({ variant = "block", detail, className }: Pr
   const body =
     detail ??
     "transcripts, summaries and extracted details are automated output and may contain errors. Check the recording before acting on them.";
-  const shortBody = detail ?? "automated output, may contain errors.";
+  const shortBody = detail ?? SHORT_BODY;
 
   if (variant === "popup") {
     // Leaflet popups render on a white wrapper regardless of theme, so this

drb-frontend/lib/attention.ts

@@ -0,0 +1,419 @@
+/**
+ * Attention cues for the live wall (server-26#238): what changed between two
+ * snapshots that a person should look at, the "NEW · last 15 min" lane, and
+ * which pins pulse.
+ *
+ * `diffAttention` is pure: (previous state, snapshot) → (next state, events).
+ * The first snapshot is a BASELINE and emits nothing, so opening the page
+ * never fires a cue for every incident already open. Calls baseline
+ * separately, on the first non-empty call snapshot, because the incident and
+ * call subscriptions land independently.
+ *
+ * The diff runs over ALL active incidents, not the filtered list: diffing the
+ * filtered list would make widening a filter look like a burst of "new"
+ * Majors. Visibility is applied when an event is emitted (`isVisibleEvent`),
+ * against the filter in force at that moment — so a cue or notification
+ * never fires for an incident filtered out of view.
+ */
+import { useEffect, useMemo, useRef, useState } from "react";
+import type { CallRecord, IncidentRecord } from "@/lib/types";
+import { SEVERITY_LABEL, isKnownSeverity, severityRank } from "@/lib/severity";
+import { groupCallsByIncident, pathStops } from "@/lib/liveWall";
+
+/** How long something counts as "new" on the lane. */
+export const LANE_WINDOW_MS = 15 * 60_000;
+/** How long a new / changed incident's pin pulses. */
+export const PULSE_MS = 2 * 60_000;
+export const DEFAULT_KEYWORDS: readonly string[] = ["MAYDAY", "10-13", "shots fired", "officer down"];
+const MAJOR = 3;
+/** A stop on an incident with no known stops counts as new only if it started after (first seen − this). */
+const STOP_GRACE_MS = 2 * 60_000;
+/** Forget incidents gone from the active list this long (state stays bounded on an all-day wall). */
+const FORGET_MS = 6 * 3600_000;
+/** Checked-call memory: anything older than the lane window is never cued anyway. */
+const CALL_MEMORY_MS = LANE_WINDOW_MS + 30 * 60_000;
+const MAX_LANE = 12;
+const MAX_LOG = 200;
+
+export type AttentionKind = "major" | "escalated" | "stop" | "keyword";
+
+export interface AttentionEvent {
+  /** Stable key (also the notification tag's suffix). */
+  id: string;
+  kind: AttentionKind;
+  /** Incidents this concerns; empty = a call not linked to any incident yet. */
+  incidentIds: string[];
+  callId: string | null;
+  at: number;
+  /** Short reason chip, e.g. "Major", "↑ Moderate", "+1 stop", "MAYDAY". */
+  label: string;
+  /** Incident title, or the talkgroup for an unlinked call. */
+  title: string;
+}
+
+interface IncState {
+  rank: number;
+  /** When this incident first counted as new: its start for the baseline, else when the wall first saw it. */
+  seenAt: number;
+  /** When the wall started tracking it (stop-grace floor). */
+  knownSince: number;
+  lastSeen: number;
+  stopIds: Set<string>;
+  newestStopAt: number | null;
+}
+
+export interface AttentionState {
+  baselineAt: number;
+  callsBaselined: boolean;
+  incidents: Map<string, IncState>;
+  /** call_id → started_at ms, for calls whose transcript has been keyword-checked. */
+  checkedCalls: Map<string, number>;
+}
+
+const ms = (iso: string | null | undefined): number => {
+  const t = iso ? Date.parse(iso) : NaN;
+  return Number.isNaN(t) ? 0 : t;
+};
+
+function callIncidentIds(c: CallRecord): string[] {
+  return c.incident_ids?.length ? c.incident_ids : c.incident_id ? [c.incident_id] : [];
+}
+
+function transcriptOf(c: CallRecord): string {
+  return c.transcript_corrected || c.transcript || "";
+}
+
+/** Non-ghost geocoded stops of a movement incident (pursuit path), oldest first. Empty otherwise. */
+function movementStops(inc: IncidentRecord, calls: CallRecord[] | undefined): { id: string; at: number }[] {
+  const path = pathStops(inc, calls);
+  if (!path.movement) return [];
+  return path.stops.filter((s) => !s.ghost).map((s) => ({ id: s.call.call_id, at: ms(s.call.started_at) }));
+}
+
+function escapeRe(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/**
+ * Configured keywords found in `text`, case-insensitive, whole-word: "10-13"
+ * does not fire on "210-135". Spaces match any whitespace and a hyphen may be
+ * a space or absent ("10 13", "1013"), since transcription renders codes both ways.
+ */
+export function matchKeywords(text: string, keywords: readonly string[]): string[] {
+  if (!text) return [];
+  const t = text.toLowerCase();
+  const hits: string[] = [];
+  for (const k of keywords) {
+    const kw = k.trim().toLowerCase();
+    if (!kw) continue;
+    const body = kw.split(/\s+/).map((w) => escapeRe(w).replace(/-/g, "[-\\s]?")).join("\\s+");
+    if (new RegExp(`(^|[^a-z0-9])${body}($|[^a-z0-9])`).test(t)) hits.push(k.trim());
+  }
+  return hits;
+}
+
+function sevLabel(sev: string | null | undefined): string {
+  return isKnownSeverity(sev) ? SEVERITY_LABEL[sev] : "Unrated";
+}
+
+/**
+ * One snapshot step. `prev === null` → baseline (no events). Never mutates `prev`.
+ * `incidents` = every active incident (unfiltered); `calls` = every call the
+ * wall has loaded (recent window + the selected incident's own calls).
+ */
+export function diffAttention(
+  prev: AttentionState | null,
+  incidents: IncidentRecord[],
+  calls: CallRecord[],
+  keywords: readonly string[],
+  now: number = Date.now(),
+): { state: AttentionState; events: AttentionEvent[] } {
+  const byInc = groupCallsByIncident(calls);
+  const events: AttentionEvent[] = [];
+
+  if (!prev) {
+    const map = new Map<string, IncState>();
+    for (const inc of incidents) {
+      const stops = movementStops(inc, byInc.get(inc.incident_id));
+      map.set(inc.incident_id, {
+        rank: severityRank(inc.severity),
+        seenAt: ms(inc.started_at) || now,
+        knownSince: now,
+        lastSeen: now,
+        stopIds: new Set(stops.map((s) => s.id)),
+        newestStopAt: stops.length ? Math.max(...stops.map((s) => s.at)) : null,
+      });
+    }
+    const checked = new Map<string, number>();
+    for (const c of calls) if (transcriptOf(c)) checked.set(c.call_id, ms(c.started_at));
+    return { state: { baselineAt: now, callsBaselined: calls.length > 0, incidents: map, checkedCalls: checked }, events };
+  }
+
+  // The first non-empty call snapshot is the calls' own baseline: record what
+  // is there, and re-seed every known incident's stops from it, silently.
+  const baselineCalls = !prev.callsBaselined && calls.length > 0;
+  const map = new Map<string, IncState>();
+  const present = new Set<string>();
+
+  for (const inc of incidents) {
+    const id = inc.incident_id;
+    present.add(id);
+    const rank = severityRank(inc.severity);
+    const stops = movementStops(inc, byInc.get(id));
+    const p = prev.incidents.get(id);
+    const title = inc.title || "Untitled incident";
+
+    if (!p) {
+      map.set(id, {
+        rank, seenAt: now, knownSince: now, lastSeen: now,
+        stopIds: new Set(stops.map((s) => s.id)),
+        newestStopAt: stops.length ? Math.max(...stops.map((s) => s.at)) : null,
+      });
+      if (rank === MAJOR) events.push({ id: `major:${id}`, kind: "major", incidentIds: [id], callId: null, at: now, label: "Major", title });
+      continue;
+    }
+
+    const st: IncState = { ...p, rank, lastSeen: now, stopIds: new Set(p.stopIds) };
+    // An unrated incident getting its first rating is classification, not
+    // escalation — unless that first rating is Major.
+    if (rank > p.rank && (p.rank >= 0 || rank === MAJOR)) {
+      events.push({
+        id: `sev:${id}:${rank}`,
+        kind: rank === MAJOR && p.rank < 0 ? "major" : "escalated",
+        incidentIds: [id], callId: null, at: now,
+        label: p.rank < 0 ? sevLabel(inc.severity) : `↑ ${sevLabel(inc.severity)}`,
+        title,
+      });
+    }
+
+    if (stops.length) {
+      const floor = st.newestStopAt ?? st.knownSince - STOP_GRACE_MS;
+      const fresh = baselineCalls ? [] : stops.filter((s) => !p.stopIds.has(s.id) && s.at > floor);
+      for (const s of stops) st.stopIds.add(s.id);
+      st.newestStopAt = Math.max(st.newestStopAt ?? 0, ...stops.map((s) => s.at));
+      if (fresh.length) {
+        const newest = fresh[fresh.length - 1];
+        events.push({
+          id: `stop:${id}:${newest.id}`, kind: "stop", incidentIds: [id], callId: newest.id, at: now,
+          label: fresh.length === 1 ? "+1 stop" : `+${fresh.length} stops`, title,
+        });
+      }
+    }
+    map.set(id, st);
+  }
+  // Keep incidents that dropped out for a while, so one that flickers out of
+  // the active list and back is not "new" again.
+  prev.incidents.forEach((st, id) => {
+    if (!present.has(id) && now - st.lastSeen < FORGET_MS) map.set(id, st);
+  });
+
+  const checked = new Map<string, number>();
+  prev.checkedCalls.forEach((t, id) => { if (now - t < CALL_MEMORY_MS) checked.set(id, t); });
+  const incTitle = new Map(incidents.map((i) => [i.incident_id, i.title || "Untitled incident"]));
+  for (const c of calls) {
+    const text = transcriptOf(c);
+    if (!text || checked.has(c.call_id)) continue;
+    const started = ms(c.started_at);
+    checked.set(c.call_id, started || now);
+    if (baselineCalls || !prev.callsBaselined) continue;
+    if (now - started > LANE_WINDOW_MS) continue; // an old call pulled in late (e.g. by selection) is not news
+    const hits = matchKeywords(text, keywords);
+    if (!hits.length) continue;
+    const ids = callIncidentIds(c);
+    events.push({
+      id: `kw:${c.call_id}`, kind: "keyword", incidentIds: ids, callId: c.call_id, at: now,
+      label: hits.join(" · ").toUpperCase(),
+      title: ids.map((i) => incTitle.get(i)).find(Boolean) ?? c.talkgroup_name ?? (c.talkgroup_id != null ? `TG ${c.talkgroup_id}` : "Unlinked call"),
+    });
+  }
+
+  return {
+    state: { baselineAt: prev.baselineAt, callsBaselined: prev.callsBaselined || baselineCalls, incidents: map, checkedCalls: checked },
+    events,
+  };
+}
+
+/**
+ * In view under the current filter: a linked event needs one of its incidents
+ * in the filtered list (never the call alone — a filtered-out incident's call
+ * must not cue); an unlinked call needs the call itself in the filtered calls.
+ */
+export function isVisibleEvent(e: AttentionEvent, visibleIds: ReadonlySet<string>, visibleCallIds: ReadonlySet<string>): boolean {
+  if (e.incidentIds.length) return e.incidentIds.some((id) => visibleIds.has(id));
+  return !!e.callId && visibleCallIds.has(e.callId);
+}
+
+export interface LaneEntry {
+  key: string;
+  incidentId: string | null;
+  title: string;
+  severity: string | null;
+  /** Most recent reason to be on the lane (ms). */
+  at: number;
+  /** "New" or the latest event's label. */
+  reason: string;
+}
+
+/** The lane: visible incidents new in the window or with a cue in it, plus unlinked keyword calls; newest first. */
+export function laneEntries(
+  visible: IncidentRecord[],
+  seenAt: ReadonlyMap<string, number>,
+  log: AttentionEvent[],
+  now: number,
+  visibleCallIds: ReadonlySet<string>,
+): LaneEntry[] {
+  const since = now - LANE_WINDOW_MS;
+  const latest = new Map<string, AttentionEvent>();
+  for (const e of log) {
+    if (e.at < since) continue;
+    for (const id of e.incidentIds) {
+      const cur = latest.get(id);
+      if (!cur || e.at >= cur.at) latest.set(id, e);
+    }
+  }
+  const out: LaneEntry[] = [];
+  for (const inc of visible) {
+    const seen = seenAt.get(inc.incident_id) ?? 0;
+    const ev = latest.get(inc.incident_id);
+    const isNew = seen >= since;
+    if (!isNew && !ev) continue;
+    const at = Math.max(isNew ? seen : 0, ev?.at ?? 0);
+    out.push({
+      key: inc.incident_id, incidentId: inc.incident_id, title: inc.title || "Untitled incident", severity: inc.severity,
+      at, reason: ev && ev.at >= (isNew ? seen : 0) ? ev.label : "New",
+    });
+  }
+  for (const e of log) {
+    if (e.at < since || e.incidentIds.length || !e.callId || !visibleCallIds.has(e.callId)) continue;
+    out.push({ key: e.id, incidentId: null, title: e.title, severity: null, at: e.at, reason: e.label });
+  }
+  return out.sort((a, b) => b.at - a.at).slice(0, MAX_LANE);
+}
+
+/** Visible incidents first seen, or cued, within PULSE_MS. */
+export function pulseIds(visibleIds: ReadonlySet<string>, seenAt: ReadonlyMap<string, number>, log: AttentionEvent[], now: number): Set<string> {
+  const since = now - PULSE_MS;
+  const out = new Set<string>();
+  seenAt.forEach((t, id) => { if (t >= since && visibleIds.has(id)) out.add(id); });
+  for (const e of log) if (e.at >= since) for (const id of e.incidentIds) if (visibleIds.has(id)) out.add(id);
+  return out;
+}
+
+// ── Preferences (per browser; a convenience, so storage failure = defaults) ──
+
+export interface AttentionPrefs {
+  /** Audible cue. OFF until the viewer turns it on (autoplay policy + no surprise noise). */
+  tone: boolean;
+  /** Browser notifications while the tab is hidden. OFF until granted and turned on. */
+  notify: boolean;
+  keywords: string[];
+}
+
+const PREFS_KEY = "drb.wall.attention";
+export const DEFAULT_ATTENTION_PREFS: AttentionPrefs = { tone: false, notify: false, keywords: [...DEFAULT_KEYWORDS] };
+
+export function loadAttentionPrefs(): AttentionPrefs {
+  try {
+    const raw = window.localStorage.getItem(PREFS_KEY);
+    if (!raw) return DEFAULT_ATTENTION_PREFS;
+    const v = JSON.parse(raw) as Partial<AttentionPrefs>;
+    return {
+      tone: v.tone === true,
+      notify: v.notify === true,
+      keywords: Array.isArray(v.keywords)
+        ? v.keywords.filter((k): k is string => typeof k === "string" && !!k.trim()).slice(0, 30)
+        : [...DEFAULT_KEYWORDS],
+    };
+  } catch {
+    return DEFAULT_ATTENTION_PREFS;
+  }
+}
+
+export function saveAttentionPrefs(p: AttentionPrefs): void {
+  try { window.localStorage.setItem(PREFS_KEY, JSON.stringify(p)); } catch { /* storage blocked */ }
+}
+
+/** "MAYDAY, 10-13 , ,shots fired" → ["MAYDAY", "10-13", "shots fired"] (deduped, case-insensitively). */
+export function parseKeywords(s: string): string[] {
+  const seen = new Set<string>();
+  const out: string[] = [];
+  for (const part of s.split(",")) {
+    const k = part.trim().replace(/\s+/g, " ");
+    if (!k || seen.has(k.toLowerCase())) continue;
+    seen.add(k.toLowerCase());
+    out.push(k);
+  }
+  return out.slice(0, 30);
+}
+
+// ── Hook ─────────────────────────────────────────────────────────────────────
+
+interface UseAttentionInput {
+  /** True once the incident list's first server snapshot has landed (and the org is known). */
+  ready: boolean;
+  /** Changing this (e.g. the org) starts a fresh baseline. */
+  resetKey: string | null;
+  incidents: IncidentRecord[];
+  calls: CallRecord[];
+  keywords: readonly string[];
+  /** The FILTERED incidents, their ids, and the filtered call ids — what is in view right now. */
+  visible: IncidentRecord[];
+  visibleIds: ReadonlySet<string>;
+  visibleCallIds: ReadonlySet<string>;
+  /** Called with each snapshot's new, in-view events (tone / notification). */
+  onEvents?: (events: AttentionEvent[]) => void;
+}
+
+export function useAttention({ ready, resetKey, incidents, calls, keywords, visible, visibleIds, visibleCallIds, onEvents }: UseAttentionInput) {
+  const stateRef = useRef<AttentionState | null>(null);
+  const keyRef = useRef<string | null>(resetKey);
+  const [log, setLog] = useState<AttentionEvent[]>([]);
+  const [seenAt, setSeenAt] = useState<Map<string, number>>(new Map());
+  const [now, setNow] = useState(() => Date.now());
+  const visRef = useRef({ visibleIds, visibleCallIds });
+  visRef.current = { visibleIds, visibleCallIds };
+  const onEventsRef = useRef(onEvents);
+  onEventsRef.current = onEvents;
+  const kwKey = keywords.join("\u0001");
+
+  useEffect(() => {
+    const id = setInterval(() => setNow(Date.now()), 15_000);
+    return () => clearInterval(id);
+  }, []);
+
+  useEffect(() => {
+    if (keyRef.current !== resetKey) {
+      keyRef.current = resetKey;
+      stateRef.current = null;
+      setLog([]);
+      setSeenAt(new Map());
+    }
+    if (!ready) return;
+    const t = Date.now();
+    const { state, events } = diffAttention(stateRef.current, incidents, calls, keywords, t);
+    stateRef.current = state;
+    const seen = new Map<string, number>();
+    state.incidents.forEach((s, id) => seen.set(id, s.seenAt));
+    setSeenAt(seen);
+    setNow(t);
+    if (!events.length) return;
+    setLog((cur) => [...cur.filter((e) => t - e.at < LANE_WINDOW_MS), ...events].slice(-MAX_LOG));
+    const { visibleIds: vi, visibleCallIds: vc } = visRef.current;
+    const shown = events.filter((e) => isVisibleEvent(e, vi, vc));
+    if (shown.length) onEventsRef.current?.(shown);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [ready, resetKey, incidents, calls, kwKey]);
+
+  // A keyword usually fires on the transcript, before correlation links the
+  // call. Re-resolve unlinked events against the calls as they are now, so
+  // the lane row becomes the (clickable) incident and its pin pulses.
+  const linkedLog = useMemo(() => {
+    if (!log.some((e) => !e.incidentIds.length && e.callId)) return log;
+    const links = new Map<string, string[]>();
+    for (const c of calls) { const ids = callIncidentIds(c); if (ids.length) links.set(c.call_id, ids); }
+    return log.map((e) => (e.incidentIds.length || !e.callId || !links.has(e.callId) ? e : { ...e, incidentIds: links.get(e.callId)! }));
+  }, [log, calls]);
+  const lane = useMemo(() => laneEntries(visible, seenAt, linkedLog, now, visibleCallIds), [visible, seenAt, linkedLog, now, visibleCallIds]);
+  const pulse = useMemo(() => pulseIds(visibleIds, seenAt, linkedLog, now), [visibleIds, seenAt, linkedLog, now]);
+  return { lane, pulseIds: pulse, now };
+}

drb-frontend/lib/useIncidents.ts

@@ -128,15 +128,24 @@ export function useIncident(incidentId: string | null) {
   return { incident, loading: loading || (!!incidentId && settledId !== incidentId) };
 }
 
-export function useActiveIncidents() {
+/**
+ * Active incidents plus whether the first SERVER snapshot has landed
+ * (server-26#238). `loaded` is what lets the wall tell "nothing active" from
+ * "not loaded yet" — attention cues baseline on it, so opening the page never
+ * fires a cue for every incident already open. Reset on sign-out / org change.
+ */
+export function useActiveIncidentsState(): { incidents: IncidentRecord[]; loaded: boolean } {
   const [incidents, setIncidents] = useState<IncidentRecord[]>([]);
+  const [loaded, setLoaded] = useState(false);
   const { orgId } = useAuth();
 
   useEffect(() => {
     let unsubFirestore: (() => void) | undefined;
+    setLoaded(false);
 
     const unsubAuth = onAuthStateChanged(auth, (user) => {
       if (unsubFirestore) { unsubFirestore(); unsubFirestore = undefined; }
+      setLoaded(false);
 
       if (!user) {
         setIncidents([]);
@@ -148,7 +157,16 @@ export function useActiveIncidents() {
       }
 
       const q = query(collection(db, "incidents"), where("org_id", "==", orgId), where("status", "==", "active"));
-      unsubFirestore = onSnapshot(q, (snap) => {
+      // includeMetadataChanges: the fromCache → server flip arrives as a
+      // metadata-only snapshot when the data didn't change (e.g. an org with
+      // nothing active, or a start while offline). Without it `loaded` would
+      // stay false until some incident changed, and that change would be
+      // swallowed into the baseline instead of cued.
+      let first = true;
+      unsubFirestore = onSnapshot(q, { includeMetadataChanges: true }, (snap) => {
+        if (!snap.metadata.fromCache) setLoaded(true);
+        if (!first && snap.docChanges().length === 0) return; // metadata only — no new array, no re-render storm
+        first = false;
         setIncidents(snap.docs.map((d) => {
           const data = d.data();
           return {
@@ -166,5 +184,9 @@ export function useActiveIncidents() {
     };
   }, [orgId]);
 
-  return incidents;
+  return { incidents, loaded };
+}
+
+export function useActiveIncidents() {
+  return useActiveIncidentsState().incidents;
 }