@joewinke/jatui 0.38.5 → 0.39.0

package/dist/components/agent/revealCore.js

@@ -0,0 +1,160 @@
+/**
+ * Reveal ticker — the pacing core behind AgentLog / AgentTaskList.
+ *
+ * Counts how many units of a streaming log are visible. Two modes:
+ *
+ *   timer       one unit per tick: `startDelay` before the first, then
+ *               `stepInterval` between the rest, or `delayFor(i)` per unit
+ *               (the dwell before unit `i` appears) when given.
+ *   controlled  pass `revealed` and the timer is off: real events drive
+ *               the count, clamped to [0, total].
+ *
+ * `onComplete` fires exactly once each time the count reaches `total`
+ * (total > 0). Dropping back below total (total grew, `replay()`, a lower
+ * controlled value) re-arms it.
+ *
+ * Framework-free and DOM-free, with an injectable clock, so
+ * tests/unit/revealTicker.test.ts drives it with fake timers. The Svelte
+ * rune wrapper is createRevealTicker in revealTicker.svelte.ts.
+ *
+ * Behaviour adapted from BoardUI's agent-log `useRevealTicker`:
+ *   MIT License — Copyright (c) 2026 Mertcan Dundar Esmergul (BoardUI)
+ * Differences: framework-free class, an in-flight tick survives option
+ * updates that do not change the next unit (a log whose `total` grows while
+ * streaming does not stall), and switching from controlled back to timer
+ * mode resumes from the controlled count instead of jumping back.
+ */
+export const DEFAULT_STEP_INTERVAL = 850;
+export const DEFAULT_START_DELAY = 320;
+const realClock = {
+    setTimeout: (fn, ms) => globalThis.setTimeout(fn, ms),
+    clearTimeout: (id) => globalThis.clearTimeout(id)
+};
+function clampCount(n, total) {
+    if (!Number.isFinite(n))
+        return n > 0 ? total : 0;
+    return Math.max(0, Math.min(Math.floor(n), total));
+}
+/** The delay before unit `index` (pure; exported for tests and hosts). */
+export function revealDelay(index, opts) {
+    const raw = opts.delayFor
+        ? opts.delayFor(index)
+        : index === 0
+            ? (opts.startDelay ?? DEFAULT_START_DELAY)
+            : (opts.stepInterval ?? DEFAULT_STEP_INTERVAL);
+    return Number.isFinite(raw) && raw > 0 ? raw : 0;
+}
+export class RevealCore {
+    #opts;
+    #hooks;
+    #clock;
+    #ticked = 0;
+    #timer = null;
+    /** The unit index the pending timer will reveal. */
+    #pendingFor = -1;
+    #fired = false;
+    #active = false;
+    #last = -1;
+    constructor(opts, hooks = {}) {
+        this.#opts = { ...opts };
+        this.#hooks = hooks;
+        this.#clock = hooks.clock ?? realClock;
+    }
+    get total() {
+        return Math.max(0, Math.floor(this.#opts.total || 0));
+    }
+    get controlled() {
+        return this.#opts.revealed !== undefined;
+    }
+    /** Units currently visible. */
+    get revealed() {
+        const total = this.total;
+        return this.controlled
+            ? clampCount(this.#opts.revealed, total)
+            : clampCount(this.#ticked, total);
+    }
+    get complete() {
+        return this.total > 0 && this.revealed >= this.total;
+    }
+    /** True while a tick is scheduled. */
+    get pending() {
+        return this.#timer !== null;
+    }
+    /** Begin scheduling (call on mount — never during SSR). */
+    start() {
+        this.#active = true;
+        this.#sync();
+    }
+    /** Merge new options (any subset) and reconcile. */
+    update(next) {
+        const wasControlled = this.controlled;
+        const before = this.revealed;
+        this.#opts = { ...this.#opts, ...next };
+        if ('revealed' in next && next.revealed === undefined)
+            this.#opts.revealed = undefined;
+        // Leaving controlled mode: carry on from where the events left the count.
+        if (wasControlled && !this.controlled)
+            this.#ticked = before;
+        this.#ticked = Math.min(this.#ticked, this.total);
+        this.#sync();
+    }
+    /** Back to zero and run again (timer mode). */
+    replay() {
+        this.#ticked = 0;
+        this.#fired = false;
+        this.#cancel();
+        this.#sync();
+    }
+    /** Stop the timer for good (call on unmount). */
+    destroy() {
+        this.#active = false;
+        this.#cancel();
+    }
+    #cancel() {
+        if (this.#timer !== null)
+            this.#clock.clearTimeout(this.#timer);
+        this.#timer = null;
+        this.#pendingFor = -1;
+    }
+    #sync() {
+        this.#emit();
+        this.#checkComplete();
+        this.#schedule();
+    }
+    #emit() {
+        const n = this.revealed;
+        if (n !== this.#last) {
+            this.#last = n;
+            this.#hooks.onChange?.(n);
+        }
+    }
+    #checkComplete() {
+        if (!this.complete) {
+            this.#fired = false;
+            return;
+        }
+        if (this.#fired)
+            return;
+        this.#fired = true;
+        this.#hooks.onComplete?.();
+    }
+    #schedule() {
+        const n = this.revealed;
+        const canRun = this.#active && !this.controlled && this.#opts.run !== false && n < this.total;
+        if (!canRun) {
+            this.#cancel();
+            return;
+        }
+        // A tick for this very unit is already on its way: leave it alone.
+        if (this.#timer !== null && this.#pendingFor === n)
+            return;
+        this.#cancel();
+        this.#pendingFor = n;
+        this.#timer = this.#clock.setTimeout(() => {
+            this.#timer = null;
+            this.#pendingFor = -1;
+            this.#ticked = Math.min(this.#ticked + 1, this.total);
+            this.#sync();
+        }, revealDelay(n, this.#opts));
+    }
+}

package/dist/components/agent/revealTicker.d.ts

@@ -0,0 +1,34 @@
+import { type RevealClock } from './revealCore';
+type MaybeGetter<T> = T | (() => T);
+export interface RevealTickerOptions {
+    /** How many units the log has in total. */
+    total: MaybeGetter<number>;
+    /** ms between units after the first (timer mode). Default 850. */
+    stepInterval?: MaybeGetter<number>;
+    /** ms before the first unit (timer mode). Default 320. */
+    startDelay?: MaybeGetter<number>;
+    /**
+     * Drive the count yourself from real events. While this resolves to a
+     * number the timer is off; resolve to `undefined` to hand back to it.
+     * Pass a getter (`() => count`) to keep it reactive.
+     */
+    revealed?: (() => number | undefined) | number;
+    /** Dwell before unit `index` appears (overrides startDelay/stepInterval). */
+    delayFor?: (index: number) => number;
+    /** false pauses the timer. Default true. */
+    run?: MaybeGetter<boolean>;
+    /** Fired once when the last unit lands (re-armed if the count drops). */
+    onComplete?: () => void;
+    /** Injectable clock (tests). */
+    clock?: RevealClock;
+}
+export interface RevealTicker {
+    /** Units visible right now. */
+    readonly revealed: number;
+    /** Every unit is visible (total > 0). */
+    readonly complete: boolean;
+    /** Restart from zero (timer mode). */
+    replay(): void;
+}
+export declare function createRevealTicker(opts: RevealTickerOptions): RevealTicker;
+export {};

package/dist/components/agent/revealTicker.js

@@ -0,0 +1,73 @@
+/* revealTicker.svelte.js generated by Svelte v5.53.11 */
+import * as $ from 'svelte/internal/client';
+import { untrack } from 'svelte';
+import { RevealCore } from './revealCore';
+
+function read(v) {
+	return typeof v === 'function' ? v() : v;
+}
+
+function resolve(opts) {
+	return {
+		total: read(opts.total) ?? 0,
+		stepInterval: read(opts.stepInterval),
+		startDelay: read(opts.startDelay),
+		revealed: read(opts.revealed),
+		delayFor: opts.delayFor,
+		run: read(opts.run)
+	};
+}
+
+export function createRevealTicker(opts) {
+	let revealed = $.state(0);
+	let complete = $.state(false);
+
+	const core = new RevealCore(resolve(opts), {
+		clock: opts.clock,
+		onChange: (n) => {
+			$.set(revealed, n, true);
+			$.set(complete, core.complete, true);
+		},
+
+		onComplete: () => {
+			$.set(complete, true);
+			opts.onComplete?.();
+		}
+	});
+
+	// SSR / first paint: the controlled count is already known.
+	$.set(revealed, core.revealed, true);
+
+	$.set(complete, core.complete, true);
+
+	let started = false;
+
+	$.user_effect(() => {
+		const next = resolve(opts);
+
+		// Only the options are dependencies — never state read by onComplete.
+		untrack(() => {
+			core.update(next);
+
+			if (!started) {
+				started = true;
+				core.start();
+			}
+
+			$.set(complete, core.complete, true);
+		});
+	});
+
+	$.user_effect(() => () => core.destroy());
+
+	return {
+		get revealed() {
+			return $.get(revealed);
+		},
+
+		get complete() {
+			return $.get(complete);
+		},
+		replay: () => core.replay()
+	};
+}

package/dist/components/agent/streamedText.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Block splitter behind StreamedText (jatui-lltq9).
+ *
+ * Streamed assistant text is append-only, so the split has to be too: for any
+ * prefix of the final text, every block but the last is IDENTICAL to the
+ * final text's block at that index, and the last block's text is a PREFIX of
+ * the final block. That is what lets each block mount once (keyed by index)
+ * and then only grow — nothing restarts, nothing reflows backwards.
+ *
+ * Rules that keep that guarantee:
+ *   - The text after the last "\n" is the in-progress line; it never closes
+ *     a block, even when it is blank so far.
+ *   - Block text is right-trimmed, so a half-typed trailing space or a
+ *     dangling newline never has to be "taken back" later.
+ *   - 'paragraph' mode: a blank line closes a block, except inside a fenced
+ *     code block (``` or ~~~) — a markdown `renderBlock` sees whole fences.
+ *   - 'line' mode: each non-blank line is a block.
+ */
+export type StreamedTextSplit = 'paragraph' | 'line';
+export interface StreamedBlock {
+    /** Stable key: the block's index ("b0", "b1", …). */
+    key: string;
+    /** Block text, right-trimmed. */
+    text: string;
+    /** True once a later separator closed the block — it can no longer grow. */
+    complete: boolean;
+}
+export declare function splitStreamedText(text: string, split?: StreamedTextSplit): StreamedBlock[];

package/dist/components/agent/streamedText.js

@@ -0,0 +1,59 @@
+/**
+ * Block splitter behind StreamedText (jatui-lltq9).
+ *
+ * Streamed assistant text is append-only, so the split has to be too: for any
+ * prefix of the final text, every block but the last is IDENTICAL to the
+ * final text's block at that index, and the last block's text is a PREFIX of
+ * the final block. That is what lets each block mount once (keyed by index)
+ * and then only grow — nothing restarts, nothing reflows backwards.
+ *
+ * Rules that keep that guarantee:
+ *   - The text after the last "\n" is the in-progress line; it never closes
+ *     a block, even when it is blank so far.
+ *   - Block text is right-trimmed, so a half-typed trailing space or a
+ *     dangling newline never has to be "taken back" later.
+ *   - 'paragraph' mode: a blank line closes a block, except inside a fenced
+ *     code block (``` or ~~~) — a markdown `renderBlock` sees whole fences.
+ *   - 'line' mode: each non-blank line is a block.
+ */
+const FENCE = /^\s{0,3}(```|~~~)/;
+export function splitStreamedText(text, split = 'paragraph') {
+    if (!text)
+        return [];
+    const lines = text.replace(/\r\n?/g, '\n').split('\n');
+    const last = lines.length - 1; // index of the in-progress line
+    const blocks = [];
+    let open = null;
+    let inFence = false;
+    const close = (complete) => {
+        if (!open)
+            return;
+        const body = open.join('\n').trimEnd();
+        if (body)
+            blocks.push({ key: `b${blocks.length}`, text: body, complete });
+        open = null;
+    };
+    for (let i = 0; i <= last; i++) {
+        const line = lines[i];
+        const blank = line.trim() === '';
+        const partial = i === last;
+        if (split === 'line') {
+            if (!blank)
+                blocks.push({ key: `b${blocks.length}`, text: line.trimEnd(), complete: !partial });
+            continue;
+        }
+        if (blank && !inFence) {
+            // A blank in-progress line has not closed anything yet.
+            if (!partial)
+                close(true);
+            continue;
+        }
+        if (!open)
+            open = [];
+        open.push(line);
+        if (FENCE.test(line) && !partial)
+            inFence = !inFence;
+    }
+    close(false);
+    return blocks;
+}

package/dist/components/messaging/MessageInput.svelte

@@ -4,6 +4,13 @@
   Rich text input for composing and sending messages.
   Supports mentions, attachments, and drag/drop.
   All searches and uploads are via callbacks.
+
+  Agent composers (opt-in, jatui-lltq9): `busy` + `onStop` swap the send
+  button for a same-size Stop button (aria-label "Stop generating") while a
+  reply is generating; Escape inside the input also stops (an open mention
+  list still takes Escape first). Sending is held while busy — the draft is
+  kept. `statusTab` renders a slim strip attached to the input's top edge
+  (e.g. model · message count). Pair with ComposerGlow for the rim light.
 -->
 
 <script lang="ts">
@@ -18,6 +25,7 @@
   } from '../../utils/mentionParser'
   import MentionAutocomplete from './MentionAutocomplete.svelte'
   import QuotedMessageDisplay from './QuotedMessageDisplay.svelte'
+  import type { Snippet } from 'svelte'
 
   interface Props {
     placeholder?: string
@@ -37,6 +45,12 @@
     ontyping?: (data: { isTyping: boolean }) => void
     onquoteremove?: () => void
     onsearchmentions?: (query: string) => Promise<MentionItem[]>
+    /** A reply is generating: the send slot shows Stop, Escape stops, sending is held. */
+    busy?: boolean
+    /** Called by the Stop button / Escape while `busy`. */
+    onStop?: () => void
+    /** Slim strip attached to the input's top edge (status chrome). */
+    statusTab?: Snippet
   }
 
   let {
@@ -52,6 +66,9 @@
     ontyping,
     onquoteremove,
     onsearchmentions,
+    busy = false,
+    onStop,
+    statusTab,
   }: Props = $props()
 
   let selectedPriority = $state<'low' | 'normal' | 'high' | 'urgent'>('normal')
@@ -203,6 +220,7 @@
 
   function handleKeyDown(event: KeyboardEvent) {
     if (showMentionAutocomplete && ['ArrowUp', 'ArrowDown', 'Tab', 'Enter', 'Escape'].includes(event.key)) return
+    if (event.key === 'Escape' && busy && onStop) { event.preventDefault(); event.stopPropagation(); onStop(); return }
     if (event.key === 'Enter' && !event.shiftKey) { event.preventDefault(); sendMessage() }
   }
 
@@ -255,7 +273,7 @@
 
   function sendMessage() {
     const content = inputText.trim()
-    if ((!content && attachments.length === 0) || disabled) return
+    if ((!content && attachments.length === 0) || disabled || busy) return
 
     onsend?.({
       content,
@@ -368,6 +386,12 @@
     </div>
   {/if}
 
+  {#if statusTab}
+    <div class="self-start -mb-2 ml-3 max-w-[calc(100%-1.5rem)] truncate px-2.5 py-0.5 text-xs text-base-content/60 bg-base-200 border border-b-0 border-base-300 rounded-t-lg">
+      {@render statusTab()}
+    </div>
+  {/if}
+
   <div class="flex items-end gap-2 {compact ? 'p-2' : 'p-3'} border border-base-300 rounded-lg focus-within:border-primary transition-colors">
     {#if !compact}
       <button type="button" class="btn btn-ghost btn-sm btn-circle flex-shrink-0" onclick={handleFileUpload} title="Attach file" {disabled}>📎</button>
@@ -412,9 +436,15 @@
       </select>
     {/if}
 
-    <button type="button" class="btn btn-primary {compact ? 'btn-xs' : 'btn-sm'} btn-circle flex-shrink-0" onclick={sendMessage} disabled={disabled || (!inputText.trim() && attachments.length === 0) || isOverLimit} title="Send message (Enter)">
-      ➤
-    </button>
+    {#if busy}
+      <button type="button" class="btn btn-primary {compact ? 'btn-xs' : 'btn-sm'} btn-circle flex-shrink-0" onclick={() => onStop?.()} disabled={!onStop} aria-label="Stop generating" title="Stop generating (Esc)">
+        <svg viewBox="0 0 16 16" class="w-3 h-3" fill="currentColor" aria-hidden="true"><rect x="3" y="3" width="10" height="10" rx="2" /></svg>
+      </button>
+    {:else}
+      <button type="button" class="btn btn-primary {compact ? 'btn-xs' : 'btn-sm'} btn-circle flex-shrink-0" onclick={sendMessage} disabled={disabled || (!inputText.trim() && attachments.length === 0) || isOverLimit} title="Send message (Enter)">
+        ➤
+      </button>
+    {/if}
   </div>
 
   <div class="text-xs text-base-content/50">

package/dist/components/messaging/MessageInput.svelte.d.ts

@@ -1,4 +1,5 @@
 import type { QuotedMessage, PendingAttachment, MentionItem, AttachmentCallbacks } from '../../types/messaging';
+import type { Snippet } from 'svelte';
 interface Props {
     placeholder?: string;
     disabled?: boolean;
@@ -19,6 +20,12 @@ interface Props {
     }) => void;
     onquoteremove?: () => void;
     onsearchmentions?: (query: string) => Promise<MentionItem[]>;
+    /** A reply is generating: the send slot shows Stop, Escape stops, sending is held. */
+    busy?: boolean;
+    /** Called by the Stop button / Escape while `busy`. */
+    onStop?: () => void;
+    /** Slim strip attached to the input's top edge (status chrome). */
+    statusTab?: Snippet;
 }
 declare const MessageInput: import("svelte").Component<Props, {
     focus: () => void;

package/dist/components/messaging/MessageItem.svelte

@@ -290,7 +290,7 @@
     {#if !isConsecutive}
       <Avatar name={message.senderName} avatarUrl={message.senderAvatar} size="small" />
     {:else}
-      <div class="text-xs text-base-content/40 opacity-0 group-hover:opacity-100 transition-opacity text-center pt-0.5">
+      <div class="text-xs text-base-content/40 opacity-0 group-hover:opacity-100 group-focus-within:opacity-100 transition-opacity text-center pt-0.5">
         {formatTime(message.createdAt).split(' ')[1] || ''}
       </div>
     {/if}
@@ -299,7 +299,7 @@
   <!-- Content -->
   <div class="flex-1 min-w-0 relative">
     <!-- Floating action buttons -->
-    <div class="absolute right-0 {!isConsecutive ? 'top-0' : 'top-1'} opacity-0 group-hover:opacity-100 transition-opacity bg-base-200 rounded-lg border border-base-300 p-1 z-10">
+    <div class="absolute right-0 {!isConsecutive ? 'top-0' : 'top-1'} opacity-0 group-hover:opacity-100 group-focus-within:opacity-100 transition-opacity bg-base-200 rounded-lg border border-base-300 p-1 z-10">
       <div class="flex items-center">
         {#if reactionCallbacks && currentUserId}
           <div class="flex items-center gap-1 mr-1">

package/dist/components/notificationCenter.d.ts

@@ -0,0 +1,65 @@
+export type NotificationStatus = 'info' | 'success' | 'warning' | 'error';
+export interface NotificationAction {
+    label: string;
+    onSelect: (item: NotificationItem) => void;
+    /** Button weight. Default 'secondary' (a quiet outline button). */
+    variant?: 'primary' | 'secondary' | 'ghost' | 'danger';
+}
+export interface NotificationItem {
+    id: string;
+    title: string;
+    description?: string;
+    /** When it happened — Date, ISO/DB timestamp string, or epoch ms. */
+    timestamp: Date | string | number;
+    /** Host-owned read flag. Missing / false = unread. */
+    read?: boolean;
+    /** Free-form category the tabs filter on (defaults: 'mentions', 'system'). */
+    category?: string;
+    /** Status glyph shown when there is no avatar. */
+    status?: NotificationStatus;
+    avatar?: {
+        name: string;
+        src?: string | null;
+    };
+    actions?: NotificationAction[];
+    /** Opening the item follows this link. */
+    href?: string;
+}
+export interface NotificationTab {
+    id: string;
+    label: string;
+    /** Which items the tab shows. Omitted = every item. */
+    filter?: (item: NotificationItem) => boolean;
+}
+/** All / Mentions / System, filtered by `category` ('mention(s)' / 'system'). */
+export declare const DEFAULT_NOTIFICATION_TABS: NotificationTab[];
+export type DateGroupKey = 'today' | 'yesterday' | 'week' | 'earlier';
+export declare const DATE_GROUP_LABELS: Record<DateGroupKey, string>;
+/** Epoch ms for a timestamp, or NaN when it cannot be parsed. */
+export declare function toTimestampMs(ts: Date | string | number | null | undefined): number;
+/**
+ * Which date bucket a timestamp falls in, by LOCAL calendar day relative to
+ * `now`: today, yesterday, the 5 days before that ("This week" = within the
+ * last 7 calendar days), else earlier. Future and unparseable timestamps land
+ * in 'today' / 'earlier' respectively.
+ */
+export declare function dateGroupKey(ts: Date | string | number, now?: Date | number): DateGroupKey;
+export interface NotificationGroup<T extends NotificationItem = NotificationItem> {
+    key: DateGroupKey;
+    label: string;
+    items: T[];
+}
+/**
+ * Newest-first items bucketed under Today / Yesterday / This week / Earlier.
+ * Empty buckets are dropped; ties keep input order (stable sort); items with
+ * an unparseable timestamp sort last.
+ */
+export declare function groupNotificationsByDate<T extends NotificationItem>(items: readonly T[], now?: Date | number): NotificationGroup<T>[];
+/** Unread = host says not read AND not optimistically read locally. */
+export declare function isNotificationUnread(item: NotificationItem, localRead?: ReadonlySet<string>): boolean;
+export declare function unreadIds(items: readonly NotificationItem[], localRead?: ReadonlySet<string>): string[];
+export declare function filterByTab<T extends NotificationItem>(items: readonly T[], tab: NotificationTab | undefined): T[];
+/** Item count per tab id (what the tab chips show). */
+export declare function tabCounts(items: readonly NotificationItem[], tabs: readonly NotificationTab[]): Record<string, number>;
+/** The header sentence: "3 unread" / "No unread notifications". */
+export declare function unreadSummary(count: number): string;

package/dist/components/notificationCenter.js

@@ -0,0 +1,110 @@
+/**
+ * NotificationCenter — pure data helpers (DOM-free, unit-tested in
+ * tests/unit/notificationCenter.test.ts).
+ *
+ * The data model is adapted from BoardUI's notification-center.tsx
+ * (MIT License — Copyright (c) 2026 Mertcan Dundar Esmergul (BoardUI)):
+ * `category` / `status` / `avatar` / `actions[]` and the All / Mentions /
+ * System tab split. jatui changes: real timestamps (Date | string | epoch ms)
+ * grouped into calendar date buckets, configurable tabs, host-owned read state.
+ */
+import { parseTimestamp } from '../utils/dateFormatters';
+const inCategory = (...names) => (item) => item.category != null && names.includes(item.category.toLowerCase());
+/** All / Mentions / System, filtered by `category` ('mention(s)' / 'system'). */
+export const DEFAULT_NOTIFICATION_TABS = [
+    { id: 'all', label: 'All' },
+    { id: 'mentions', label: 'Mentions', filter: inCategory('mentions', 'mention') },
+    { id: 'system', label: 'System', filter: inCategory('system') }
+];
+export const DATE_GROUP_LABELS = {
+    today: 'Today',
+    yesterday: 'Yesterday',
+    week: 'This week',
+    earlier: 'Earlier'
+};
+const DATE_GROUP_ORDER = ['today', 'yesterday', 'week', 'earlier'];
+/** Epoch ms for a timestamp, or NaN when it cannot be parsed. */
+export function toTimestampMs(ts) {
+    if (ts == null || ts === '')
+        return NaN;
+    if (typeof ts === 'number')
+        return Number.isFinite(ts) ? ts : NaN;
+    const d = parseTimestamp(ts);
+    return d ? d.getTime() : NaN;
+}
+/** Local midnight of the day containing `ms`. */
+function startOfDay(ms) {
+    const d = new Date(ms);
+    d.setHours(0, 0, 0, 0);
+    return d.getTime();
+}
+/**
+ * Which date bucket a timestamp falls in, by LOCAL calendar day relative to
+ * `now`: today, yesterday, the 5 days before that ("This week" = within the
+ * last 7 calendar days), else earlier. Future and unparseable timestamps land
+ * in 'today' / 'earlier' respectively.
+ */
+export function dateGroupKey(ts, now = Date.now()) {
+    const ms = toTimestampMs(ts);
+    if (Number.isNaN(ms))
+        return 'earlier';
+    const today = startOfDay(typeof now === 'number' ? now : now.getTime());
+    const day = startOfDay(ms);
+    if (day >= today)
+        return 'today';
+    // Calendar-day difference, rounded so DST shifts (23h / 25h days) don't skew it.
+    const days = Math.round((today - day) / 86_400_000);
+    if (days === 1)
+        return 'yesterday';
+    if (days < 7)
+        return 'week';
+    return 'earlier';
+}
+/**
+ * Newest-first items bucketed under Today / Yesterday / This week / Earlier.
+ * Empty buckets are dropped; ties keep input order (stable sort); items with
+ * an unparseable timestamp sort last.
+ */
+export function groupNotificationsByDate(items, now = Date.now()) {
+    const sorted = items
+        .map((item, i) => ({ item, i, ms: toTimestampMs(item.timestamp) }))
+        .sort((a, b) => {
+        const am = Number.isNaN(a.ms) ? -Infinity : a.ms;
+        const bm = Number.isNaN(b.ms) ? -Infinity : b.ms;
+        return bm - am || a.i - b.i;
+    });
+    const buckets = new Map();
+    for (const { item } of sorted) {
+        const key = dateGroupKey(item.timestamp, now);
+        let list = buckets.get(key);
+        if (!list)
+            buckets.set(key, (list = []));
+        list.push(item);
+    }
+    return DATE_GROUP_ORDER.filter((k) => buckets.has(k)).map((key) => ({
+        key,
+        label: DATE_GROUP_LABELS[key],
+        items: buckets.get(key)
+    }));
+}
+/** Unread = host says not read AND not optimistically read locally. */
+export function isNotificationUnread(item, localRead) {
+    return item.read !== true && !(localRead?.has(item.id) ?? false);
+}
+export function unreadIds(items, localRead) {
+    return items.filter((it) => isNotificationUnread(it, localRead)).map((it) => it.id);
+}
+export function filterByTab(items, tab) {
+    return tab?.filter ? items.filter((it) => tab.filter(it)) : items.slice();
+}
+/** Item count per tab id (what the tab chips show). */
+export function tabCounts(items, tabs) {
+    const out = {};
+    for (const tab of tabs)
+        out[tab.id] = tab.filter ? items.filter(tab.filter).length : items.length;
+    return out;
+}
+/** The header sentence: "3 unread" / "No unread notifications". */
+export function unreadSummary(count) {
+    return count === 0 ? 'No unread notifications' : `${count} unread`;
+}