@heyramzi/ui 2.0.1 → 2.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heyramzi/ui",
-  "version": "2.0.1",
+  "version": "2.1.0",
   "description": "Svelte 5 UI for apps: primitives, effects and animations, plus tasks, charts, slides, an editor, onboarding and a canvas as subpaths.",
   "license": "MIT",
   "repository": {
@@ -172,6 +172,31 @@
       "default": "./src/agents/index.ts"
     },
     "./agents/demo.svelte": "./src/agents/demo.svelte",
+    "./status": {
+      "svelte": "./src/status/index.ts",
+      "types": "./src/status/index.ts",
+      "default": "./src/status/index.ts"
+    },
+    "./panel": {
+      "svelte": "./src/panel/index.ts",
+      "types": "./src/panel/index.ts",
+      "default": "./src/panel/index.ts"
+    },
+    "./record": {
+      "svelte": "./src/record/index.ts",
+      "types": "./src/record/index.ts",
+      "default": "./src/record/index.ts"
+    },
+    "./thread": {
+      "svelte": "./src/thread/index.ts",
+      "types": "./src/thread/index.ts",
+      "default": "./src/thread/index.ts"
+    },
+    "./inbox": {
+      "svelte": "./src/inbox/index.ts",
+      "types": "./src/inbox/index.ts",
+      "default": "./src/inbox/index.ts"
+    },
     "./tasks": {
       "svelte": "./src/tasks/index.ts",
       "types": "./src/tasks/index.ts",
@@ -193,19 +218,19 @@
       "default": "./src/tasks/task-gantt.svelte"
     },
     "./tasks/status": {
-      "svelte": "./src/tasks/status-badge.svelte",
-      "types": "./src/tasks/status-badge.svelte",
-      "default": "./src/tasks/status-badge.svelte"
+      "svelte": "./src/status/status-badge.svelte",
+      "types": "./src/status/status-badge.svelte",
+      "default": "./src/status/status-badge.svelte"
     },
     "./tasks/status-dot": {
-      "svelte": "./src/tasks/status-dot.svelte",
-      "types": "./src/tasks/status-dot.svelte",
-      "default": "./src/tasks/status-dot.svelte"
+      "svelte": "./src/status/status-dot.svelte",
+      "types": "./src/status/status-dot.svelte",
+      "default": "./src/status/status-dot.svelte"
     },
     "./tasks/statuses": {
-      "svelte": "./src/tasks/define-statuses.ts",
-      "types": "./src/tasks/define-statuses.ts",
-      "default": "./src/tasks/define-statuses.ts"
+      "svelte": "./src/status/define-statuses.ts",
+      "types": "./src/status/define-statuses.ts",
+      "default": "./src/status/define-statuses.ts"
     },
     "./tasks/time": {
       "svelte": "./src/tasks/time/time-tracker.svelte",
@@ -218,9 +243,9 @@
       "default": "./src/tasks/inbox/index.ts"
     },
     "./tasks/side-panel": {
-      "svelte": "./src/tasks/side-panel.svelte",
-      "types": "./src/tasks/side-panel.svelte",
-      "default": "./src/tasks/side-panel.svelte"
+      "svelte": "./src/panel/side-panel.svelte",
+      "types": "./src/panel/side-panel.svelte",
+      "default": "./src/panel/side-panel.svelte"
     },
     "./tasks/presets/sales": {
       "svelte": "./src/tasks/presets/sales.ts",
@@ -234,11 +259,11 @@
     },
     "./tasks/detail-demo.svelte": "./src/tasks/detail/detail-demo.svelte",
     "./tasks/record": {
-      "svelte": "./src/tasks/record/index.ts",
-      "types": "./src/tasks/record/index.ts",
-      "default": "./src/tasks/record/index.ts"
+      "svelte": "./src/record/index.ts",
+      "types": "./src/record/index.ts",
+      "default": "./src/record/index.ts"
     },
-    "./tasks/record-demo.svelte": "./src/tasks/record/record-demo.svelte",
+    "./tasks/record-demo.svelte": "./src/record/record-demo.svelte",
     "./tasks/demo": {
       "svelte": "./src/tasks/demo.svelte",
       "default": "./src/tasks/demo.svelte"

package/src/canvas/README.md

@@ -9,7 +9,7 @@ MIT. It runs on any domain and costs nothing per install.
 ## What's in it
 
 - **Pen layer.** Freehand strokes (perfect-freehand), a highlighter, an eraser, plain text, and rectangle, ellipse and diamond shapes. Colours are token names, so a board drawn in light mode reads fine in dark.
-- **Tool bar.** A floating bar with the tools, undo and redo. Pick from 6 colours and 3 brush sizes. Keys: V, H, P, M, E, T, R, O, D.
+- **Tool bar.** A floating bar with the tools, a colour and a brush size. Pick from 8 colours and 3 brush sizes. Keys: V, H, L, P, M, E, T, R, O, D, F. Undo and redo are yours to wire to `createCanvasDispatcher`.
 - **Plugin API.** Register your own card types, ops and layout passes. One registry builds xyflow's `nodeTypes` for you.
 - **Ops.** 8 core ops (`addNode`, `removeNode`, `patchNode`, `moveNode`, `setParent`, `addEdge`, `removeEdge`, `patchEdge`) as plain functions over nodes and edges. Zod checks every one.
 - **Undo history.** `createCanvasDispatcher` wraps each edit in a transaction. A whole pen stroke is one undo step.
@@ -68,14 +68,15 @@ Drop this in `src/routes/+page.svelte`.
     toolbar: "Canvas tools",
     style: "Style",
     tools: {
-      select: "Select", hand: "Hand", pen: "Pen", highlighter: "Highlighter",
-      eraser: "Eraser", text: "Text", rectangle: "Rectangle", ellipse: "Ellipse",
-      diamond: "Diamond", shapes: "Shapes",
+      select: "Select", hand: "Hand", connect: "Connect", frame: "Frame", pen: "Pen",
+      highlighter: "Highlighter", eraser: "Eraser", text: "Text", rectangle: "Rectangle",
+      ellipse: "Ellipse", diamond: "Diamond", shapes: "Shapes", note: "Note",
+    },
+    colors: {
+      ink: "Ink", red: "Red", blue: "Blue", green: "Green", amber: "Amber",
+      violet: "Violet", indigo: "Indigo", terra: "Terracotta",
     },
-    colors: { ink: "Ink", red: "Red", blue: "Blue", green: "Green", amber: "Amber", violet: "Violet" },
     sizes: ["Small", "Medium", "Large"],
-    undo: "Undo",
-    redo: "Redo",
   } as const;
 </script>
 
@@ -100,10 +101,6 @@ Drop this in `src/routes/+page.svelte`.
       bind:color
       bind:level
       {labels}
-      canUndo={history.canUndo}
-      canRedo={history.canRedo}
-      onUndo={history.undo}
-      onRedo={history.redo}
     />
   </SvelteFlow>
 </div>
@@ -192,7 +189,7 @@ The pen is `PenOverlay` (or `PenLayer` inside xyflow), and it needs 2 callbacks
 
 The eraser removes whole strokes, never part of one. A swipe across a big shape doesn't wipe it.
 
-The pen has 6 colours: `ink`, `red`, `blue`, `green`, `amber` and `violet`. `pen.css` maps them to CSS variables with a light and a dark value. Dark mode applies under a `.dark` class on an ancestor or on `.svelte-flow`.
+The pen has 8 colours: `ink`, `red`, `blue`, `green`, `amber`, `violet`, `indigo` and `terra`. `pen.css` maps them to CSS variables with a light and a dark value. Dark mode applies under a `.dark` class on an ancestor or on `.svelte-flow`.
 
 ## Headless ops
 

package/src/charts/dashboard/data-panel.svelte

@@ -5,7 +5,7 @@
 import type { Snippet } from "svelte";
 import { cn } from "../../lib/utils.js";
 import { panelHeaderClass, panelShellClass } from "../../lib/panel.js";
-import { SectionLabel } from "../../components/list-page/index.js";
+import { SectionLabel } from "../../components/section-header/index.js";
 import type { PhosphorIcon } from "../../lib/icon-types.js";
 
 // =========================

package/src/components/list-page/detail-panel.svelte

@@ -3,7 +3,7 @@
 // IMPORTS
 // =========================
 import type { Snippet } from "svelte";
-import SectionLabel from "./section-label.svelte";
+import SectionLabel from "../section-header/section-label.svelte";
 import { cn } from "../../lib/utils.js";
 import { panelHeaderClass, panelShellClass } from "../../lib/panel.js";
 import type { PhosphorIcon } from "../../lib/icon-types.js";

package/src/components/list-page/filter-popover.svelte

@@ -7,7 +7,7 @@ import * as Popover from "../../shadcn/popover/index.js";
 import { Funnel as FunnelIcon } from "phosphor-svelte";
 import { cn } from "../../lib/utils.js";
 import { Button } from "../../shadcn/button/index.js";
-import { toolbarTriggerClass } from "./toolbar-trigger.js";
+import { toolbarTriggerClass } from "../toolbar/toolbar-trigger.js";
 import type { PhosphorIcon } from "../../lib/icon-types.js";
 
 // phosphor-svelte v2 (resolved here) and v3 (what consumers run) differ only in

package/src/components/list-page/index.ts

@@ -12,7 +12,7 @@ export { default as RailBody } from "./rail-body.svelte";
 export { default as RailEmpty } from "./rail-empty.svelte";
 export { default as RailHead } from "./rail-head.svelte";
 export { default as RailRow } from "./rail-row.svelte";
-export { default as SectionLabel } from "./section-label.svelte";
+export { default as SectionLabel } from "../section-header/section-label.svelte";
 export { queueRailClass, queueRailWidth } from "./queue-rail.js";
 export { default as FilterPopover } from "./filter-popover.svelte";
 export { filterSectionClass } from "./filter-section.js";
@@ -21,8 +21,8 @@ export { default as ListPageShell } from "./list-page-shell.svelte";
 export { default as MasterDetail } from "./master-detail.svelte";
 // The segmented control isn't re-exported here. Two import paths drifted, so
 // its one home is `@heyramzi/ui/components/segmented`.
-export { default as ToolbarSearch } from "./toolbar-search.svelte";
-export { toolbarTriggerClass } from "./toolbar-trigger.js";
+export { default as ToolbarSearch } from "../toolbar/toolbar-search.svelte";
+export { toolbarTriggerClass } from "../toolbar/toolbar-trigger.js";
 export { listTable } from "./list-table.js";
 export type { ViewMode } from "./types.js";
 export { getSectionHost, setSectionHost, type SectionHost } from "./section-host.js";

package/src/components/list-page/rail-head.svelte

@@ -3,7 +3,7 @@
 // IMPORTS
 // =========================
 import type { Snippet } from "svelte";
-import SectionLabel from "./section-label.svelte";
+import SectionLabel from "../section-header/section-label.svelte";
 import { cn } from "../../lib/utils.js";
 
 // =========================

package/src/components/section-header/index.ts

@@ -1 +1,2 @@
 export { default as SectionHeader } from "./section-header.svelte";
+export { default as SectionLabel } from "./section-label.svelte";

package/src/components/section-header/section-header.svelte

@@ -3,7 +3,7 @@
 	// IMPORTS
 	// =========================
 	import type { Snippet } from "svelte";
-	import SectionLabel from "../list-page/section-label.svelte";
+	import SectionLabel from "./section-label.svelte";
 
 	// =========================
 	// TYPES

package/src/components/toolbar/index.ts

@@ -3,3 +3,5 @@
  * each of those folds into a menu and the row never wraps.
  */
 export { default as Toolbar } from "./toolbar.svelte";
+export { default as ToolbarSearch } from "./toolbar-search.svelte";
+export { toolbarTriggerClass } from "./toolbar-trigger.js";

package/src/components/toolbar/toolbar.svelte

@@ -6,8 +6,8 @@
 	import { CaretDown, MagnifyingGlass } from "phosphor-svelte";
 	import { SegmentedFilter } from "../segmented/index.js";
 	import type { TabDef } from "../segmented/animated-tabs.svelte";
-	import { toolbarTriggerClass } from "../list-page/toolbar-trigger.js";
-	import ToolbarSearch from "../list-page/toolbar-search.svelte";
+	import { toolbarTriggerClass } from "./toolbar-trigger.js";
+	import ToolbarSearch from "./toolbar-search.svelte";
 	import { Input } from "../../shadcn/input/index.js";
 	import * as DropdownMenu from "../../shadcn/dropdown-menu/index.js";
 	import * as Popover from "../../shadcn/popover/index.js";

package/src/inbox/README.md

@@ -0,0 +1,29 @@
+# @heyramzi/ui/inbox
+
+One threaded inbox. Entries from any source (a comment, a status change, an assignment, a mention, an agent reply, an agent's ask) group into one thread per subject, and the screen shows the thread list on the left and the selected thread on the right. The inbox never fetches. Everything leaves through callbacks.
+
+```svelte
+<script lang="ts">
+  import { ThreadInbox, type InboxEntry } from "@heyramzi/ui/inbox";
+
+  let entries = $state<InboxEntry[]>([]);
+</script>
+
+<ThreadInbox
+  {entries}
+  unreadFirst
+  onRead={(thread, read) => mark(thread.key, read)}
+  onSnooze={({ thread, until }) => snooze(thread.key, until)}
+  onDecide={(verdict, thread) => decide(verdict)}
+/>
+```
+
+- **Grouping.** `threadsOf(entries, { unreadFirst })` keys on `subject.type` plus `subject.id`, sorts threads by their newest entry and entries oldest first. An entry with no subject id is dropped. A malformed timestamp sorts last. Each thread carries `unread`, `latestAt` and `pending`.
+- **Needs you.** A `proposal` entry whose `proposal` (an `InboxItem`) is still open pins to the top of its thread, drawn with `InboxCard`. The "Needs you" filter keeps threads that hold one. Verdicts come out of `onDecide`.
+- **Filters.** By subject type, by actor name and by Needs you. `filterThreads` runs them without the component.
+- **Keys.** `j` and `k` move, `u` marks the thread read (or unread when nothing is unread), `h` opens the snooze row (`1`, `2`, `3` pick a time), and `a`, `d`, `s`, `e` act on the pinned proposal. A key does nothing while focus is in an input, a textarea, a select or an editable element, or while a modifier is held. `inboxKeyOf(event)` is the same check.
+- **Snooze.** `onSnooze({ thread, until })` gets a `Date`: 3 hours on, tomorrow 9:00 or next Monday 9:00 (`snoozeChoices(now)`). The host decides what snoozed means and stops passing the entries.
+- **Read.** `onRead(thread, read)` is true when the thread had unread entries, so the host marks them all read.
+- **Words.** `labels` is a partial of `InboxLabels`. Status and assignment lines have `{from}`, `{to}` and `{assignee}` slots. `typeLabels` names the subject types. The `avatar` and `status` snippets let the app draw its own portrait and status badge.
+
+`@heyramzi/ui/tasks/inbox` still exports the approvals-only `Inbox`.

package/src/inbox/inbox.test.ts

@@ -0,0 +1,171 @@
+import { describe, expect, it } from "vite-plus/test";
+import {
+	NO_FILTER,
+	entryLine,
+	filterThreads,
+	inboxKeyOf,
+	resolveInboxLabels,
+	snoozeChoices,
+	threadsOf,
+} from "./logic.js";
+import type { InboxEntry, InboxSubject } from "./types.js";
+import type { InboxItem } from "../tasks/inbox/inbox-types.js";
+
+const tsk7: InboxSubject = { type: "task", id: "7", ref: "TSK-7", title: "Write the pricing page" };
+const tsk9: InboxSubject = { type: "task", id: "9", ref: "TSK-9", title: "Fix the footer" };
+const doc1: InboxSubject = { type: "doc", id: "1", title: "Brief" };
+const ada = { kind: "user", name: "Ada" } as const;
+const bot = { kind: "agent", name: "Scribe" } as const;
+
+function entry(id: string, at: string, extra: Partial<InboxEntry> = {}): InboxEntry {
+	return { id, kind: "comment", subject: tsk7, actor: ada, at, ...extra };
+}
+
+const proposal = (state: InboxItem["state"] = "proposed", tier: InboxItem["tier"] = "ask"): InboxItem => ({
+	id: "p",
+	kind: "decision",
+	tier,
+	state,
+	title: "Send the quote",
+	project: { id: "x", name: "X" },
+	proposal: { summary: "Send it" },
+	confidence: { score: 0.9 },
+	trace: { source: { type: "email", label: "Mail", at: "Mon" }, evidence: [], reasoning: "" },
+});
+
+describe("threadsOf", () => {
+	it("makes one thread of an agent comment and a status change on TSK-7", () => {
+		const threads = threadsOf([
+			entry("c1", "2026-10-22T09:00:00Z", { kind: "agent_response", actor: bot, body: "Drafted" }),
+			entry("s1", "2026-10-22T09:05:00Z", { kind: "status", status: { from: "todo", to: "review" } }),
+		]);
+		expect(threads).toHaveLength(1);
+		expect(threads[0].entries).toHaveLength(2);
+		expect(threads[0].unread).toBe(2);
+		expect(threads[0].subject.ref).toBe("TSK-7");
+		expect(threads[0].latestAt).toBe("2026-10-22T09:05:00Z");
+	});
+
+	it("counts only unread entries", () => {
+		const [thread] = threadsOf([entry("a", "2026-10-22T09:00:00Z", { read: true }), entry("b", "2026-10-22T09:01:00Z")]);
+		expect(thread.unread).toBe(1);
+	});
+
+	it("sorts threads by their latest entry, newest first", () => {
+		const threads = threadsOf([
+			entry("a", "2026-10-22T09:00:00Z"),
+			entry("b", "2026-10-22T11:00:00Z", { subject: tsk9 }),
+			entry("c", "2026-10-22T10:00:00Z", { subject: doc1 }),
+		]);
+		expect(threads.map((t) => t.subject.id)).toEqual(["9", "1", "7"]);
+	});
+
+	it("puts threads with unread entries first on request", () => {
+		const entries = [
+			entry("a", "2026-10-22T09:00:00Z"),
+			entry("b", "2026-10-22T11:00:00Z", { subject: tsk9, read: true }),
+		];
+		expect(threadsOf(entries).map((t) => t.subject.id)).toEqual(["9", "7"]);
+		expect(threadsOf(entries, { unreadFirst: true }).map((t) => t.subject.id)).toEqual(["7", "9"]);
+	});
+
+	it("drops an entry with no subject id", () => {
+		const threads = threadsOf([
+			entry("a", "2026-10-22T09:00:00Z"),
+			entry("b", "2026-10-22T09:01:00Z", { subject: undefined }),
+			entry("c", "2026-10-22T09:02:00Z", { subject: { ...tsk9, id: "" } }),
+		]);
+		expect(threads).toHaveLength(1);
+		expect(threads[0].entries.map((e) => e.id)).toEqual(["a"]);
+	});
+
+	it("sorts a malformed timestamp last, among threads and inside one", () => {
+		const threads = threadsOf([
+			entry("bad", "yesterday", { subject: tsk9 }),
+			entry("ok", "2026-10-22T09:00:00Z"),
+			entry("late", "2026-10-22T09:30:00Z"),
+			entry("junk", "??"),
+		]);
+		expect(threads.map((t) => t.subject.id)).toEqual(["7", "9"]);
+		expect(threads[0].entries.map((e) => e.id)).toEqual(["ok", "late", "junk"]);
+		expect(threads[0].latestAt).toBe("2026-10-22T09:30:00Z");
+	});
+
+	it("keeps a pending proposal and ignores a decided one", () => {
+		const [open] = threadsOf([entry("p", "2026-10-22T09:00:00Z", { kind: "proposal", proposal: proposal() })]);
+		expect(open.pending).toHaveLength(1);
+		const [done] = threadsOf([entry("p", "2026-10-22T09:00:00Z", { kind: "proposal", proposal: proposal("approved") })]);
+		expect(done.pending).toHaveLength(0);
+	});
+});
+
+describe("filterThreads", () => {
+	const threads = threadsOf([
+		entry("a", "2026-10-22T09:00:00Z", { actor: bot }),
+		entry("b", "2026-10-22T10:00:00Z", { subject: doc1 }),
+		entry("p", "2026-10-22T11:00:00Z", { subject: tsk9, kind: "proposal", proposal: proposal() }),
+	]);
+
+	it("filters by type, by who and by needs you", () => {
+		expect(filterThreads(threads, { ...NO_FILTER, type: "doc" }).map((t) => t.subject.id)).toEqual(["1"]);
+		expect(filterThreads(threads, { ...NO_FILTER, who: "Scribe" }).map((t) => t.subject.id)).toEqual(["7"]);
+		expect(filterThreads(threads, { ...NO_FILTER, needsYou: true }).map((t) => t.subject.id)).toEqual(["9"]);
+		expect(filterThreads(threads, NO_FILTER)).toHaveLength(3);
+	});
+});
+
+const press = (key: string, target: EventTarget | null = document.body) =>
+	inboxKeyOf({ key, metaKey: false, ctrlKey: false, altKey: false, defaultPrevented: false, target });
+
+describe("keys", () => {
+	it("maps the nine keys", () => {
+		expect(["j", "k", "u", "h", "a", "d", "s", "e"].map((k) => press(k))).toEqual([
+			"next",
+			"previous",
+			"toggleRead",
+			"snooze",
+			"approve",
+			"decline",
+			"steer",
+			"edit",
+		]);
+		expect(press("x")).toBeNull();
+	});
+
+	it("does nothing for u while typing", () => {
+		for (const tag of ["input", "textarea", "select"]) {
+			expect(press("u", document.createElement(tag))).toBeNull();
+		}
+		const editable = document.createElement("div");
+		Object.defineProperty(editable, "isContentEditable", { value: true });
+		expect(press("u", editable)).toBeNull();
+	});
+
+	it("ignores a held modifier", () => {
+		expect(inboxKeyOf({ key: "u", metaKey: true, ctrlKey: false, altKey: false, defaultPrevented: false, target: document.body })).toBeNull();
+	});
+});
+
+describe("snoozeChoices", () => {
+	it("offers 3 hours on, tomorrow at 9 and the next Monday at 9", () => {
+		const wed = new Date(2026, 9, 21, 14, 30);
+		const [later, tomorrow, nextWeek] = snoozeChoices(wed);
+		expect(later.until.getTime() - wed.getTime()).toBe(3 * 60 * 60 * 1000);
+		expect([tomorrow.until.getDate(), tomorrow.until.getHours()]).toEqual([22, 9]);
+		expect([nextWeek.until.getDay(), nextWeek.until.getDate(), nextWeek.until.getHours()]).toEqual([1, 26, 9]);
+	});
+
+	it("moves a Monday to the following Monday", () => {
+		const mon = new Date(2026, 9, 26, 10, 0);
+		expect(snoozeChoices(mon)[2].until.getDate()).toBe(2);
+	});
+});
+
+describe("entryLine", () => {
+	it("fills the host's own words, French included", () => {
+		const fr = resolveInboxLabels({ statusMoved: "a déplacé ceci de {from} à {to}" });
+		expect(entryLine(entry("s", "2026-10-22T09:00:00Z", { kind: "status", status: { from: "A faire", to: "Revue" } }), fr)).toBe(
+			"a déplacé ceci de A faire à Revue",
+		);
+	});
+});

package/src/inbox/index.ts

@@ -0,0 +1,31 @@
+export { default as ThreadInbox } from "./thread-inbox.svelte";
+export {
+	NO_FILTER,
+	actorNames,
+	entryLine,
+	filterThreads,
+	inboxKeyOf,
+	isPending,
+	resolveInboxLabels,
+	snoozeChoices,
+	subjectTypes,
+	threadsOf,
+} from "./logic.js";
+export type { SnoozeChoice, ThreadsOptions } from "./logic.js";
+export { ALL, DEFAULT_INBOX_LABELS } from "./types.js";
+export type {
+	InboxActor,
+	InboxActorKind,
+	InboxEntry,
+	InboxEntryKind,
+	InboxFilter,
+	InboxKey,
+	InboxLabels,
+	InboxSnooze,
+	InboxSubject,
+	InboxThread,
+} from "./types.js";
+
+// The approval card a pinned proposal is drawn with, and the types its `proposal` field carries.
+export { default as InboxCard } from "../tasks/inbox/inbox-card.svelte";
+export type { InboxItem, InboxVerdict } from "../tasks/inbox/inbox-types.js";

package/src/inbox/logic.ts

@@ -0,0 +1,166 @@
+import { isOpen, isTyping } from "../tasks/inbox/inbox-logic.js";
+import {
+	ALL,
+	DEFAULT_INBOX_LABELS,
+	type InboxEntry,
+	type InboxFilter,
+	type InboxKey,
+	type InboxLabels,
+	type InboxSubject,
+	type InboxThread,
+} from "./types.js";
+
+/** A timestamp as a number, with NaN for one that doesn't parse. */
+function ms(at: string): number {
+	return Date.parse(at);
+}
+
+function latestOf(thread: InboxThread): number {
+	const time = ms(thread.latestAt);
+	return Number.isNaN(time) ? Number.NEGATIVE_INFINITY : time;
+}
+
+export type ThreadsOptions = {
+	/** Threads with unread entries come before read ones. */
+	unreadFirst?: boolean;
+};
+
+/** True while a proposal entry still waits for a verdict. */
+export function isPending(entry: InboxEntry): boolean {
+	return entry.kind === "proposal" && !!entry.proposal && isOpen(entry.proposal);
+}
+
+/**
+ * Group entries into one thread per subject and sort by the newest entry. An entry with no subject id
+ * is dropped. A malformed timestamp sorts last, among threads and inside one.
+ */
+export function threadsOf(entries: InboxEntry[], options: ThreadsOptions = {}): InboxThread[] {
+	type Row = { entry: InboxEntry; subject: InboxSubject; index: number; time: number };
+	const groups = new Map<string, Row[]>();
+	entries.forEach((entry, index) => {
+		const subject = entry.subject;
+		if (!subject?.id) return;
+		const key = `${subject.type}:${subject.id}`;
+		groups.set(key, [...(groups.get(key) ?? []), { entry, subject, index, time: ms(entry.at) }]);
+	});
+
+	const threads: InboxThread[] = [];
+	for (const [key, rows] of groups) {
+		const ordered = rows.toSorted((a, b) => {
+			const aBad = Number.isNaN(a.time);
+			const bBad = Number.isNaN(b.time);
+			if (aBad !== bBad) return aBad ? 1 : -1;
+			return (aBad ? 0 : a.time - b.time) || a.index - b.index;
+		});
+		const newest = ordered.findLast((row) => !Number.isNaN(row.time)) ?? ordered[0];
+		const list = ordered.map((row) => row.entry);
+		threads.push({
+			key,
+			// The newest entry carries the freshest title and status.
+			subject: newest.subject,
+			entries: list,
+			unread: list.filter((entry) => !entry.read).length,
+			latestAt: newest.entry.at,
+			pending: list.filter(isPending).toReversed(),
+		});
+	}
+
+	return threads
+		.map((thread, index) => ({ thread, index }))
+		.toSorted((a, b) => {
+			if (options.unreadFirst) {
+				const unread = Number(b.thread.unread > 0) - Number(a.thread.unread > 0);
+				if (unread) return unread;
+			}
+			const aTime = latestOf(a.thread);
+			const bTime = latestOf(b.thread);
+			if (aTime === bTime) return a.index - b.index;
+			return bTime - aTime;
+		})
+		.map((row) => row.thread);
+}
+
+export const NO_FILTER: InboxFilter = { type: ALL, who: ALL, needsYou: false };
+
+/** Keep a thread when it matches the type, holds an entry from the person or agent, and has a pending proposal if asked. */
+export function filterThreads(threads: InboxThread[], filter: InboxFilter): InboxThread[] {
+	return threads.filter(
+		(thread) =>
+			(filter.type === ALL || thread.subject.type === filter.type) &&
+			(filter.who === ALL || thread.entries.some((entry) => entry.actor.name === filter.who)) &&
+			(!filter.needsYou || thread.pending.length > 0),
+	);
+}
+
+export function subjectTypes(threads: InboxThread[]): string[] {
+	return [...new Set(threads.map((thread) => thread.subject.type))];
+}
+
+export function actorNames(threads: InboxThread[]): string[] {
+	return [...new Set(threads.flatMap((thread) => thread.entries.map((entry) => entry.actor.name)))];
+}
+
+type KeyEventLike = Pick<KeyboardEvent, "key" | "metaKey" | "ctrlKey" | "altKey" | "defaultPrevented" | "target">;
+
+const KEYS: Record<string, InboxKey> = {
+	j: "next",
+	k: "previous",
+	u: "toggleRead",
+	h: "snooze",
+	a: "approve",
+	d: "decline",
+	s: "steer",
+	e: "edit",
+};
+
+/** What a key press asks for, or null when it isn't ours: a modifier is held, or focus is in a text field. */
+export function inboxKeyOf(event: KeyEventLike): InboxKey | null {
+	if (event.defaultPrevented || event.metaKey || event.ctrlKey || event.altKey) return null;
+	if (isTyping(event.target)) return null;
+	return KEYS[event.key] ?? null;
+}
+
+export type SnoozeChoice = { id: "later" | "tomorrow" | "nextWeek"; until: Date };
+
+/** The three times a snooze offers: 3 hours on, tomorrow at 9, next Monday at 9. */
+export function snoozeChoices(now: Date): SnoozeChoice[] {
+	const later = new Date(now.getTime() + 3 * 60 * 60 * 1000);
+	const tomorrow = new Date(now);
+	tomorrow.setDate(tomorrow.getDate() + 1);
+	tomorrow.setHours(9, 0, 0, 0);
+	const nextWeek = new Date(now);
+	nextWeek.setDate(nextWeek.getDate() + (((8 - nextWeek.getDay()) % 7) || 7));
+	nextWeek.setHours(9, 0, 0, 0);
+	return [
+		{ id: "later", until: later },
+		{ id: "tomorrow", until: tomorrow },
+		{ id: "nextWeek", until: nextWeek },
+	];
+}
+
+export function resolveInboxLabels(overrides?: Partial<InboxLabels>): InboxLabels {
+	return { ...DEFAULT_INBOX_LABELS, ...overrides };
+}
+
+/** One line for an entry, in the host's words. `{from}`, `{to}` and `{assignee}` are filled. */
+export function entryLine(entry: InboxEntry, labels: InboxLabels): string {
+	const fill = (text: string) =>
+		text
+			.replaceAll("{from}", entry.status?.from ?? "")
+			.replaceAll("{to}", entry.status?.to ?? "")
+			.replaceAll("{assignee}", entry.assignee ?? "");
+	switch (entry.kind) {
+		case "status":
+			return fill(entry.status?.from ? labels.statusMoved : labels.statusSet);
+		case "assigned":
+			return fill(labels.assigned);
+		case "mention":
+			return labels.mentioned;
+		case "agent_response":
+			return labels.responded;
+		case "proposal":
+			return labels.proposed;
+		default:
+			return labels.commented;
+	}
+}