// Pure, DOM-free model for the browser client's attention / "Needs you" surface // (R15). It mirrors android/.../ui/Attention.kt and the wording shown by // ui/components/AttentionSurface.kt, so the browser's bell, its badge and the // sheet read exactly what the app reads. // // The surface is derived here from the same `list_runs` summaries the runs list // is folded from (and from any run state already in the page). R10's live // `run_event` fold feeds these same pure functions the pushed summaries, so the // ordering and the wording are identical whether a row arrived from a read or a // push. // // Everything in this file is pure: no DOM, no clock, no storage. app.js keeps the // wiring; a malformed stored value can never throw into the page because decode // is total. Every server-provided string is only ever compared or rendered, // never parsed as markup; the caller sets it with textContent. // --------------------------------------------------------------------------- // Kinds and qualification // --------------------------------------------------------------------------- /** * The two things the attention surface ranks, most important first. The rank is * what orders the list; the name is what a dismissal identity is keyed by. */ export const AttentionKind = Object.freeze({ Decision: Object.freeze({ name: "Decision", rank: 0 }), Failed: Object.freeze({ name: "Failed", rank: 1 }), }); /** * The attention kind a run status maps to, or null when the run needs nobody. It * reads the server's own words only (trimmed/lowercased `waiting` and `failed`), * so queued, running, succeeded, canceled, interrupted and any unknown status * can never invent an entry. */ export function attentionKindOf(status) { switch (String(status ?? "").trim().toLowerCase()) { case "waiting": return AttentionKind.Decision; case "failed": return AttentionKind.Failed; default: return null; } } // --------------------------------------------------------------------------- // Identity and wording // --------------------------------------------------------------------------- /** The identity of one run+kind entry; the unit an explicit dismissal removes. */ export function attentionKey(runId, kind) { return `${runId}:${kind.name}`; } /** * What one entry asks of the operator, in the operator's words. A failed run * shows the server's own diagnostic when it recorded one so the line is * actionable rather than a bare "failed". */ export function attentionDetail(kind, run) { if (kind === AttentionKind.Decision) return "Waiting for your decision"; const diagnostic = String(run?.diagnostic ?? "").trim(); return diagnostic !== "" ? diagnostic : "Run failed"; } /** * The one-line secondary text for a row: the pipeline the run belongs to, then * what it needs. Exactly `{pipeline} · {detail}`, as AttentionSurface.kt draws. */ export function attentionRowDescription(entry) { return `${entry.pipeline} · ${entry.detail}`; } /** * The bell action's accessible name: the bare `Notifications` when nothing needs * the operator, else the count. The visible badge is drawn only in the second * case, from the same count. */ export function attentionBadgeLabel(count) { const n = Number(count) || 0; return n > 0 ? `Notifications, ${n} needing attention` : "Notifications"; } // --------------------------------------------------------------------------- // The ordered list // --------------------------------------------------------------------------- /** * The ordered attention list. Every run that needs the operator becomes one * entry, ranked by kind (decision, then failure), then newest-first within a * kind (its finish time else its creation time, as the server wrote it), then by * run id descending so the order is stable and never reshuffles between reads. * An entry the operator explicitly dismissed never returns. A run status that * asks nobody is dropped, so the surface can only ever hold actionable work. */ export function attentionEntries(runs, dismissed, { since = 0 } = {}) { const dismissedKeys = dismissed instanceof Set ? dismissed : new Set(Array.isArray(dismissed) ? dismissed : []); return (runs ?? []) .map((run) => { const kind = attentionKindOf(run?.status); if (!kind) return null; const key = attentionKey(run.id, kind); if (dismissedKeys.has(key)) return null; const title = String(run.title ?? "").trim(); const finished = String(run.finished_at ?? ""); const recency = finished.trim() !== "" ? finished : String(run.created_at ?? ""); const at = Date.parse(recency); if (since > 0 && Number.isFinite(at) && at < since) return null; return { runId: run.id, pipeline: String(run.name ?? ""), label: title !== "" ? title : String(run.name ?? ""), kind, detail: attentionDetail(kind, run), recency, key, }; }) .filter((entry) => entry != null) .sort( (a, b) => a.kind.rank - b.kind.rank || descendingText(a.recency, b.recency) || (b.runId > a.runId ? 1 : b.runId < a.runId ? -1 : 0), ); } /** * The start of the operator's local day in epoch ms. "Needs you" is a to-do list * for what changed now; yesterday's failures are history, not a badge that * follows every device and browser session for ever. */ export function startOfLocalDay(now = Date.now()) { const date = new Date(now); date.setHours(0, 0, 0, 0); return date.getTime(); } /** * Captures the entries shown when the sheet opens. Bulk dismissal uses this * snapshot so entries that arrive while the sheet is open are not removed. A * defensive copy, so the live list can never mutate what Clear all will apply. */ export function attentionDismissalSnapshot(entries) { return [...(entries ?? [])]; } // --------------------------------------------------------------------------- // Dismissal bookkeeping // --------------------------------------------------------------------------- /** Adds one identity to the dismissed set, ignoring a blank or already-present key. */ export function attentionDismiss(dismissed, key) { const next = new Set(dismissed instanceof Set ? dismissed : []); if (String(key ?? "") !== "") next.add(key); return next; } /** * Unions a snapshot's identities into the dismissed set. Only the identities in * the snapshot are added, so an entry that arrived after the sheet opened (and * is therefore not in the snapshot) is left alone. This is what Clear all does. */ export function attentionDismissAll(dismissed, snapshot) { const next = new Set(dismissed instanceof Set ? dismissed : []); for (const entry of snapshot ?? []) { if (entry?.key) next.add(entry.key); } return next; } // --------------------------------------------------------------------------- // Persistence // --------------------------------------------------------------------------- /** * The single localStorage key the dismissed identities live under: one JSON * array of `{runId}:{kind}` strings, with no expiry or TTL of any kind. */ export const ATTENTION_STORAGE_KEY = "pipelines.web.attention.v1"; /** * The one-line JSON a dismissed set is stored as: a JSON array of strings. The * array is sorted so an unchanged set always encodes to the same bytes. */ export function encodeAttentionDismissals(dismissed) { const keys = [...(dismissed instanceof Set ? dismissed : [])].filter( (key) => typeof key === "string" && key !== "", ); keys.sort(); return JSON.stringify(keys); } /** * Decodes a stored value into a dismissed set. Total: blank, unreadable JSON, a * non-array value and non-string members all decode to empty, so a malformed * value can never throw into the page. */ export function decodeAttentionDismissals(stored) { const text = stored == null ? "" : String(stored).trim(); if (text === "") return new Set(); let parsed; try { parsed = JSON.parse(text); } catch { return new Set(); } if (!Array.isArray(parsed)) return new Set(); return new Set(parsed.filter((key) => typeof key === "string" && key !== "")); } // --------------------------------------------------------------------------- // Internals // --------------------------------------------------------------------------- /** Descending compare of two strings, matching the app's `thenByDescending`. */ function descendingText(a, b) { if (a < b) return 1; if (a > b) return -1; return 0; }