mulmoclaude 0.5.2 → 0.6.0

package/src/composables/useHealth.ts

@@ -1,25 +1,12 @@
-// Composable for the server /api/health probe.
-//
-// Owns three refs that the UI reads (gemini key availability +
-// sandbox toggle + server CPU load ratio) plus a one-shot fetch
-// that populates them on mount, plus an optional periodic refresh
-// for the CPU ratio (the favicon's "overloaded" rule needs a live
-// signal, not a boot-time snapshot).
-//
-// On fetch failure we assume Gemini is unavailable so dependent UI
-// (e.g. the "generate image" plugin buttons) falls back gracefully
-// — the sandbox flag keeps its initial `true` so the lock indicator
-// doesn't momentarily flash "sandbox disabled" on a transient error,
-// and the CPU ratio goes to null so the favicon resolver skips the
-// overloaded rule rather than guessing.
+// On fetch failure: assume gemini unavailable (so "generate image" buttons fall back gracefully); keep sandbox=true
+// so the lock indicator doesn't flash off on a transient error; null cpu so the favicon resolver skips overloaded
+// rather than guessing.
 
 import { computed, onScopeDispose, ref, type ComputedRef, type Ref } from "vue";
 import { API_ROUTES } from "../config/apiRoutes";
 import { apiGet } from "../utils/api";
 
-// Once every 15 s is enough for a sustained load spike to light the
-// favicon. Shorter would mostly flap on short-lived spikes that
-// aren't actually user-visible as lag.
+// 15s catches sustained load without flapping on short-lived spikes that aren't user-visible as lag.
 const HEALTH_REFRESH_MS = 15_000;
 
 interface CpuPayload {
@@ -44,37 +31,26 @@ export function useHealth(): {
   const cpuLoad1 = ref<number | null>(null);
   const cpuCores = ref<number | null>(null);
 
-  // Separate flag so transient poll failures don't flip
-  // `geminiAvailable` back to false after a successful boot-time
-  // fetch. `geminiAvailable` / `sandboxEnabled` are config-derived
-  // and don't change at runtime — once we've observed them once,
-  // the next 15 s poll's network blip shouldn't mask them.
+  // gemini/sandbox are config-derived and don't change at runtime; once observed, a poll blip shouldn't unmask them.
   let bootFetchCompleted = false;
 
   async function fetchHealth(): Promise<void> {
     const result = await apiGet<HealthResponse>(API_ROUTES.health);
     if (!result.ok) {
-      // Only the CPU figures get nulled — the favicon resolver
-      // reads null as "skip overloaded" which is the correct fail-
-      // closed behaviour. The config flags keep their last-known
-      // values, and stay at the initial defaults if we never
-      // succeeded (gemini=true → request lands, gets an auth error
-      // handled elsewhere; sandbox=true → lock indicator reads on).
+      // Null only the CPU figures — the resolver reads null as "skip overloaded" (fail-closed). Config flags keep
+      // their last-known values, defaults if never observed (gemini=true → auth error elsewhere, sandbox=true → on).
       cpuLoad1.value = null;
       cpuCores.value = null;
       if (!bootFetchCompleted) {
-        // On the FIRST fetch we do still flip gemini → false so
-        // the "Gemini key required" banner can show immediately
-        // without waiting for a second attempt. Subsequent poll
-        // failures don't re-enter this branch.
+        // First-fetch only: flip gemini → false so the "Gemini key required" banner shows without waiting for retry.
         geminiAvailable.value = false;
       }
       return;
     }
-    geminiAvailable.value = !!result.data.geminiAvailable;
-    sandboxEnabled.value = !!result.data.sandboxEnabled;
+    geminiAvailable.value = Boolean(result.data.geminiAvailable);
+    sandboxEnabled.value = Boolean(result.data.sandboxEnabled);
     bootFetchCompleted = true;
-    const cpu = result.data.cpu;
+    const { cpu } = result.data;
     if (cpu && typeof cpu.load1 === "number" && Number.isFinite(cpu.load1) && typeof cpu.cores === "number" && cpu.cores > 0) {
       cpuLoad1.value = cpu.load1;
       cpuCores.value = cpu.cores;
@@ -84,20 +60,15 @@ export function useHealth(): {
     }
   }
 
-  // Refresh the CPU figure periodically. The flag-style booleans
-  // (gemini / sandbox) don't change at runtime so re-fetching them
-  // is waste; but piggy-backing on the same endpoint keeps the
-  // server side to a single route and the client to a single poll.
+  // Piggy-backs cpu refresh on the health endpoint to keep server + client to a single route/poll.
   const refreshHandle = window.setInterval(() => {
     fetchHealth().catch(() => {
-      /* intentionally swallowed — a failed poll just stalls the
-         favicon's overloaded rule, not user-visible UI */
+      /* swallowed: a failed poll just stalls the favicon overloaded rule, not user-visible UI */
     });
   }, HEALTH_REFRESH_MS);
   onScopeDispose(() => window.clearInterval(refreshHandle));
 
-  // Expose the normalised ratio the favicon resolver expects (load
-  // per logical core). Null when either component is missing.
+  // load1 per logical core; null if either side is missing.
   const cpuLoadRatio = computed<number | null>(() => {
     if (cpuLoad1.value === null || cpuCores.value === null) return null;
     return cpuLoad1.value / cpuCores.value;

package/src/composables/useImageErrorRepair.ts

@@ -0,0 +1,104 @@
+import { onMounted, onBeforeUnmount } from "vue";
+import { IMAGE_REPAIR_PATTERN, IMAGE_REPAIR_INLINE_SCRIPT } from "../utils/image/imageRepairInlineScript.js";
+
+// Re-exported from the pure module so existing callers keep working.
+// New callers (server/index.ts splice, future iframe-injection
+// surfaces) should import from `../utils/image/imageRepairInlineScript.js`
+// directly to avoid pulling Vue lifecycle hooks into Node code paths.
+export { IMAGE_REPAIR_PATTERN, IMAGE_REPAIR_INLINE_SCRIPT };
+
+// Whitespace- and comma-bounded URL token inside a `srcset` value.
+// `srcset` is a comma-list of `<url> [descriptor]` entries; the
+// regex picks each non-whitespace, non-comma run so the descriptor
+// (`1x`, `2x`, `100w`, …) survives the repair pass untouched.
+const SRCSET_TOKEN_RE = /[^\s,]+/g;
+
+export function repairImageSrc(img: HTMLImageElement): boolean {
+  if (img.dataset.imageRepairTried) return false;
+  // Set the one-shot marker only AFTER confirming the URL matches the
+  // repair pattern. Otherwise an unrelated 404 (different domain, no
+  // artifacts/images segment) would pin the marker and silently block
+  // any future repair attempt on the same DOM element if the src is
+  // later replaced with a repairable one.
+  const match = img.src.match(IMAGE_REPAIR_PATTERN);
+  if (!match) return false;
+  img.dataset.imageRepairTried = "1";
+  img.src = `/${match[0]}`;
+  return true;
+}
+
+// Repair a `<source>` element used inside `<picture>` / `<audio>` /
+// `<video>`. Handles both shapes:
+//   - `srcset="..."` (the picture form, often comma-list with size
+//     descriptors)
+//   - `src="..."` (the audio/video form, single URL)
+// One-shot via the same `imageRepairTried` marker as <img>.
+export function repairSourceSrc(source: HTMLSourceElement): boolean {
+  if (source.dataset.imageRepairTried) return false;
+  let repaired = false;
+  const src = source.getAttribute("src");
+  if (src) {
+    const match = src.match(IMAGE_REPAIR_PATTERN);
+    if (match) {
+      source.setAttribute("src", `/${match[0]}`);
+      repaired = true;
+    }
+  }
+  if (source.srcset) {
+    const original = source.srcset;
+    const next = original.replace(SRCSET_TOKEN_RE, (token) => {
+      const tokenMatch = token.match(IMAGE_REPAIR_PATTERN);
+      return tokenMatch ? `/${tokenMatch[0]}` : token;
+    });
+    if (next !== original) {
+      source.srcset = next;
+      repaired = true;
+    }
+  }
+  if (repaired) source.dataset.imageRepairTried = "1";
+  return repaired;
+}
+
+// Attach a document-level capture-phase error listener so any
+// `<img>` / `<source>` / `<audio>` / `<video>` 404 in the app
+// shell (wiki / markdown / news / Files preview etc) gets one
+// repair attempt. Capture phase is required because the relevant
+// error events don't bubble. The repair is a no-op for src values
+// that don't match the artifacts/images pattern, so attaching at
+// document scope is safe — it never touches non-image-bearing UI.
+export function useGlobalImageErrorRepair(): void {
+  function onError(event: Event): void {
+    const { target } = event;
+    if (target instanceof HTMLImageElement) {
+      repairImageSrc(target);
+      // Source-element error events don't fire reliably in Chromium
+      // when a `<picture><source>` srcset 404s — only the inner
+      // `<img>` reaches a target. Walk siblings so a wrong-prefix
+      // `<source>` next to a repairable `<img>` gets the same fix.
+      const picture = target.closest("picture");
+      if (picture) {
+        for (const src of picture.querySelectorAll("source")) {
+          repairSourceSrc(src);
+        }
+      }
+    } else if (target instanceof HTMLSourceElement) {
+      repairSourceSrc(target);
+    } else if (target instanceof HTMLMediaElement) {
+      // `<audio>` / `<video>` fire `error` on themselves when ALL
+      // their `<source>` children fail. The source elements never
+      // get a target of their own in that path, so reach into
+      // each child and repair it.
+      for (const src of target.querySelectorAll<HTMLSourceElement>(":scope > source")) {
+        repairSourceSrc(src);
+      }
+    }
+  }
+
+  onMounted(() => {
+    document.addEventListener("error", onError, { capture: true });
+  });
+
+  onBeforeUnmount(() => {
+    document.removeEventListener("error", onError, { capture: true });
+  });
+}

package/src/composables/useLatestDaily.ts

@@ -0,0 +1,40 @@
+// #876. Distinguish data===null ("no journal yet") from response.ok===false ("load failed") so a real auth/network/
+// backend failure isn't misreported as empty state (Codex review iter 1). Crude alerts pending a toast composable.
+
+import { ref } from "vue";
+import { useRouter } from "vue-router";
+import { useI18n } from "vue-i18n";
+import { apiGet } from "../utils/api";
+import { API_ROUTES } from "../config/apiRoutes";
+
+interface LatestDailyResult {
+  path: string;
+  isoDate: string;
+}
+
+export function useLatestDaily() {
+  const router = useRouter();
+  const { t } = useI18n();
+  const loading = ref(false);
+
+  async function openLatestDaily(): Promise<void> {
+    if (loading.value) return;
+    loading.value = true;
+    try {
+      const response = await apiGet<LatestDailyResult | null>(API_ROUTES.journal.latestDaily);
+      if (!response.ok) {
+        window.alert(t("sidebarHeader.todayJournalLoadFailed", { status: response.status, error: response.error }));
+        return;
+      }
+      if (response.data === null) {
+        window.alert(t("sidebarHeader.todayJournalNotFound"));
+        return;
+      }
+      await router.push(`/files/${response.data.path}`);
+    } finally {
+      loading.value = false;
+    }
+  }
+
+  return { openLatestDaily, loading };
+}

package/src/composables/useMarkdownDoc.ts

@@ -0,0 +1,39 @@
+// #895 PR A: shared frontmatter handling for every markdown-from-disk view. parseFrontmatter never throws —
+// malformed header degrades to "render the whole input as body" instead of breaking the view.
+
+import { computed, type ComputedRef, type Ref } from "vue";
+import { parseFrontmatter, type ParsedMarkdown } from "../utils/markdown/frontmatter";
+
+export interface MarkdownDocField {
+  key: string;
+  // Templates branch on Array.isArray and pass scalars through formatScalarField — nested objects would otherwise
+  // render as `[object Object]` (codex review iter-1 #902).
+  value: unknown;
+}
+
+export function formatScalarField(value: unknown): string {
+  if (value === null || value === undefined) return "";
+  if (typeof value === "object") {
+    try {
+      return JSON.stringify(value);
+    } catch {
+      // Cyclic object → can't stringify; fall back to String() rather than throw inside a template.
+      return String(value);
+    }
+  }
+  return String(value);
+}
+
+export interface MarkdownDocView extends ParsedMarkdown {
+  fields: MarkdownDocField[];
+}
+
+// Pass null/undefined to get the empty state — so callers can wire a load-state ref without a null-guard wrapper.
+export function useMarkdownDoc(content: Ref<string | null | undefined>): ComputedRef<MarkdownDocView> {
+  return computed(() => {
+    const raw = content.value ?? "";
+    const parsed = parseFrontmatter(raw);
+    const fields = Object.entries(parsed.meta).map(([key, value]) => ({ key, value }));
+    return { ...parsed, fields };
+  });
+}

package/src/composables/useMarkdownLinkHandler.ts

@@ -16,7 +16,7 @@ export function useMarkdownLinkHandler(selectedPath: Ref<string | null>, handler
   function handleMarkdownLinkClick(event: MouseEvent): void {
     if (event.button !== 0) return;
     if (event.ctrlKey || event.metaKey || event.shiftKey) return;
-    const target = event.target;
+    const { target } = event;
     if (!(target instanceof Element)) return;
     const anchor = target.closest("a");
     if (!anchor) return;

package/src/composables/useMcpTools.ts

@@ -1,9 +1,3 @@
-// Composable that owns the MCP tool state used by the sidebar:
-// which tools are currently disabled, their per-tool prompts, and
-// the derived `availableTools` / `toolDescriptions` computeds. The
-// pure rules live in src/utils/mcpTools so they are unit-testable
-// independently of fetch / Vue.
-
 import { computed, ref, type ComputedRef } from "vue";
 import { API_ROUTES } from "../config/apiRoutes";
 import type { Role } from "../config/roles";
@@ -12,20 +6,14 @@ import { apiGet } from "../utils/api";
 
 interface UseMcpToolsOptions {
   currentRole: ComputedRef<Role>;
-  // Injection point for the in-app plugin registry lookup. Real
-  // callers pass `(name) => getPlugin(name)?.toolDefinition ?? null`,
-  // tests can stub it.
+  // Plugin-registry lookup, injectable so tests can stub it.
   getDefinition: (name: string) => ToolDefinitionMetadata | null;
 }
 
 export function useMcpTools(opts: UseMcpToolsOptions) {
   const disabledMcpTools = ref(new Set<string>());
   const mcpToolDescriptions = ref<Record<string, string>>({});
-  // Surfaces the most recent GET /api/mcp-tools failure so consumers
-  // (e.g. the Settings modal's MCP tab) can render a small warning.
-  // We intentionally keep the "all tools visible" fallback below so
-  // the UI stays usable; this ref lets the UI tell the user *why* the
-  // list looks incomplete / unfiltered.
+  // Surfaces /api/mcp-tools failures so the Settings MCP tab can explain *why* the list looks unfiltered.
   const mcpToolsError = ref<string | null>(null);
 
   const availableTools = computed(() => availableToolsFor(opts.currentRole.value.availablePlugins, disabledMcpTools.value));
@@ -46,8 +34,7 @@ export function useMcpTools(opts: UseMcpToolsOptions) {
     const result = await apiGet<McpToolStatus[]>(API_ROUTES.mcpTools.list);
     if (!result.ok) {
       mcpToolsError.value = result.error;
-      // Keep the "all tools visible" fallback — not clearing
-      // disabledMcpTools or descriptions means the UI remains usable.
+      // Don't clear disabledMcpTools / descriptions — falling back to "all tools visible" keeps the UI usable.
       return;
     }
     if (!Array.isArray(result.data)) {

package/src/composables/useNotifications.ts

@@ -1,95 +1,104 @@
-// Web-side subscriber for the `notifications` pub-sub channel.
-// Stores incoming NotificationPayloads for the bell badge + panel.
+// Bell-side composable backed by the notifier engine.
 //
-// Uses a singleton subscription pattern: the first component that
-// calls useNotifications() subscribes to the pub-sub channel; the
-// last one to unmount unsubscribes. All consumers share the same
-// module-level state (notifications + readIds).
+// PR 4 of feat-encore migrated `publishNotification()` onto the new
+// engine, so the bell consumes the same data as the dev-mode debug
+// popup: a single global pubsub channel (`PUBSUB_CHANNELS.notifier`),
+// primed via `POST /api/notifier {action: "list" | "listHistory"}`.
 //
-// Read tracking is per-id via a Set. The unread badge decreases
-// only when the user **interacts** with a notification — either
-// clicking it (markRead) or dismissing it via × (dismiss removes
-// the notification entirely, so it leaves the unread tally as a
-// side effect). Opening the panel does NOT auto-mark everything
-// read; the user has to explicitly act on each item, or hit the
-// "Mark all read" button.
-
-import { onUnmounted, ref, computed, type Ref, type ComputedRef } from "vue";
+// Singleton state shared across consumers: a single subscription is
+// shared between the bell badge, the panel, and any other surface
+// that wants to render the same source of truth. Subscriber counting
+// + ref-counted teardown matches the legacy composable's pattern so
+// the websocket subscription doesn't leak when every consumer
+// unmounts.
+
+import { computed, onUnmounted, ref, type ComputedRef, type Ref } from "vue";
+import { API_ROUTES } from "../config/apiRoutes";
 import { PUBSUB_CHANNELS } from "../config/pubsubChannels";
+import { apiPost } from "../utils/api";
 import { usePubSub } from "./usePubSub";
-import { NOTIFICATION_ACTION_TYPES, NOTIFICATION_KINDS, NOTIFICATION_VIEWS } from "../types/notification";
-import type { NotificationPayload } from "../types/notification";
-import { isRecord } from "../utils/types";
-
-const MAX_RECENT = 50;
-
-const VALID_KINDS = new Set<string>(Object.values(NOTIFICATION_KINDS));
-const VALID_VIEWS = new Set<string>(Object.values(NOTIFICATION_VIEWS));
-
-function isNotificationPayload(value: unknown): value is NotificationPayload {
-  if (!isRecord(value)) return false;
-  if (typeof value.id !== "string") return false;
-  if (typeof value.kind !== "string" || !VALID_KINDS.has(value.kind)) return false;
-  if (typeof value.title !== "string") return false;
-  if (typeof value.firedAt !== "string") return false;
-  if (!isValidAction(value.action)) return false;
-  return true;
+
+// Mirror of `server/notifier/types.ts` — repeated here rather than
+// imported because the server tree pulls in fs / pubsub deps that
+// shouldn't bleed into the client bundle. The two definitions are
+// kept in sync by code review.
+export interface NotifierEntry {
+  id: string;
+  pluginPkg: string;
+  severity: "info" | "nudge" | "urgent";
+  lifecycle?: "fyi" | "action";
+  title: string;
+  body?: string;
+  navigateTarget?: string;
+  pluginData?: unknown;
+  createdAt: string;
 }
 
-// Tighter than a plain `typeof type === "string"` check — confirms
-// the discriminator is one we know AND, for `navigate`, that the
-// target carries a known view. Stops malformed payloads from
-// landing in the panel and crashing later in the click handler.
-function isValidAction(action: unknown): boolean {
-  if (!isRecord(action)) return false;
-  if (action.type === NOTIFICATION_ACTION_TYPES.none) return true;
-  if (action.type !== NOTIFICATION_ACTION_TYPES.navigate) return false;
-  const target = action.target;
-  if (!isRecord(target)) return false;
-  return typeof target.view === "string" && VALID_VIEWS.has(target.view);
+export interface NotifierHistoryEntry extends NotifierEntry {
+  terminalType: "cleared" | "cancelled";
+  terminalAt: string;
 }
 
-// Module-level state so all components share the same list and the
-// same per-id read state.
-const notifications = ref<NotificationPayload[]>([]);
-// Set of notification ids the user has explicitly read (clicked or
-// dismissed-as-read). A Set so add/lookup are O(1) per entry.
-const readIds = ref<Set<string>>(new Set());
+type NotifierEvent = { type: "published"; entry: NotifierEntry } | { type: "cleared"; id: string } | { type: "cancelled"; id: string };
+
+const HISTORY_CAP = 50;
+
+const entries = ref<NotifierEntry[]>([]);
+const history = ref<NotifierHistoryEntry[]>([]);
+const ready = ref(false);
 
-// Singleton subscription — ref-counted across consumers.
 let subscriberCount = 0;
 let unsubscribeFn: (() => void) | null = null;
-
-function ensureSubscribed(subscribe: ReturnType<typeof usePubSub>["subscribe"]): void {
-  subscriberCount++;
-  if (unsubscribeFn) return; // already listening
-  unsubscribeFn = subscribe(PUBSUB_CHANNELS.notifications, (data) => {
-    if (!isNotificationPayload(data)) return;
-    const next = [data, ...notifications.value].slice(0, MAX_RECENT);
-    notifications.value = next;
-    // Drop read-state entries for notifications that just rolled
-    // off the end of the bounded list — readIds is otherwise an
-    // unbounded leak across a long-lived session.
-    pruneReadIds(next);
-  });
+let primePromise: Promise<void> | null = null;
+
+async function prime(): Promise<void> {
+  if (primePromise) return primePromise;
+  primePromise = (async () => {
+    const [activeResult, historyResult] = await Promise.all([
+      apiPost<{ entries: NotifierEntry[] }>(API_ROUTES.notifier.dispatch, { action: "list" }),
+      apiPost<{ history: NotifierHistoryEntry[] }>(API_ROUTES.notifier.dispatch, { action: "listHistory" }),
+    ]);
+    if (activeResult.ok) entries.value = activeResult.data.entries;
+    if (historyResult.ok) history.value = historyResult.data.history;
+    ready.value = true;
+  })();
+  return primePromise;
 }
 
-function pruneReadIds(currentList: readonly NotificationPayload[]): void {
-  if (readIds.value.size === 0) return;
-  const liveIds = new Set(currentList.map((notif) => notif.id));
-  const next = new Set<string>();
-  for (const readId of readIds.value) {
-    if (liveIds.has(readId)) next.add(readId);
-  }
-  // Only assign when the contents actually changed — avoids
-  // unnecessary reactive churn when nothing rolled off.
-  if (next.size !== readIds.value.size) {
-    readIds.value = next;
+function applyEvent(event: NotifierEvent): void {
+  switch (event.type) {
+    case "published":
+      // Dedup against optimistic local update — the host UI clear
+      // button already removed the entry; ignore the echoing event.
+      if (!entries.value.some((entry) => entry.id === event.entry.id)) {
+        entries.value = [...entries.value, event.entry];
+      }
+      return;
+    case "cleared":
+    case "cancelled": {
+      const removed = entries.value.find((entry) => entry.id === event.id);
+      entries.value = entries.value.filter((entry) => entry.id !== event.id);
+      if (removed) {
+        const historyEntry: NotifierHistoryEntry = {
+          ...removed,
+          terminalType: event.type === "cleared" ? "cleared" : "cancelled",
+          terminalAt: new Date().toISOString(),
+        };
+        history.value = [historyEntry, ...history.value].slice(0, HISTORY_CAP);
+      }
+    }
   }
 }
 
+function ensureSubscribed(subscribe: ReturnType<typeof usePubSub>["subscribe"]): void {
+  subscriberCount += 1;
+  if (unsubscribeFn) return;
+  unsubscribeFn = subscribe(PUBSUB_CHANNELS.notifier, (data) => applyEvent(data as NotifierEvent));
+  void prime();
+}
+
 function releaseSubscription(): void {
-  subscriberCount--;
+  subscriberCount -= 1;
   if (subscriberCount <= 0 && unsubscribeFn) {
     unsubscribeFn();
     unsubscribeFn = null;
@@ -98,56 +107,73 @@ function releaseSubscription(): void {
 }
 
 export function useNotifications(): {
-  notifications: Ref<NotificationPayload[]>;
-  latest: ComputedRef<NotificationPayload | null>;
-  unreadCount: ComputedRef<number>;
-  isRead: (id: string) => boolean;
-  markRead: (id: string) => void;
-  markAllRead: () => void;
-  dismiss: (id: string) => void;
+  entries: ComputedRef<NotifierEntry[]>;
+  history: Ref<NotifierHistoryEntry[]>;
+  badgeCount: ComputedRef<number>;
+  /** Worst-severity-wins Tailwind class. Mirrors the dev debug popup
+   *  and matches the bell-badge encoding in `feat-notifier-ux.md`. */
+  badgeColor: ComputedRef<string>;
+  ready: Ref<boolean>;
+  clear: (id: string) => Promise<void>;
+  cancel: (id: string) => Promise<void>;
 } {
   const { subscribe } = usePubSub();
   ensureSubscribed(subscribe);
   onUnmounted(releaseSubscription);
 
-  const latest = computed(() => notifications.value[0] ?? null);
+  // Sort oldest-first so a row's vertical position doesn't jump when
+  // a fresh entry arrives at the bottom — the same scan order the
+  // debug popup uses. The bell panel then visually inverts via flex
+  // direction, matching today's "newest at the top" expectation.
+  const sortedEntries = computed(() => [...entries.value].sort((left, right) => left.createdAt.localeCompare(right.createdAt)));
 
-  const unreadCount = computed(() => notifications.value.filter((notif) => !readIds.value.has(notif.id)).length);
+  const badgeCount = computed(() => entries.value.length);
 
-  function isRead(notifId: string): boolean {
-    return readIds.value.has(notifId);
-  }
+  const badgeColor = computed(() => {
+    if (entries.value.some((entry) => entry.severity === "urgent")) return "bg-red-500";
+    if (entries.value.some((entry) => entry.severity === "nudge")) return "bg-amber-500";
+    return "bg-gray-400";
+  });
 
-  function markRead(notifId: string): void {
-    if (readIds.value.has(notifId)) return;
-    // Replace the Set so Vue's reactivity fires on consumers that
-    // depend on `readIds` via `unreadCount` / `isRead`.
-    const next = new Set(readIds.value);
-    next.add(notifId);
-    readIds.value = next;
+  /** Remove an entry from the active list and prepend a synthetic
+   *  history record. Used optimistically by `clear` / `cancel` so the
+   *  bell reacts before the server round-trip completes; `applyEvent`
+   *  is idempotent on the eventual pubsub echo (the entry is already
+   *  gone from `entries`, so its `cleared`/`cancelled` branch finds
+   *  nothing to remove and skips the history append).
+   *
+   *  No-op if the entry was already taken out (e.g. another tab raced
+   *  us via the pubsub event); preserves single-history-entry-per-id
+   *  semantics. */
+  function moveToHistoryLocally(entryId: string, terminalType: "cleared" | "cancelled"): void {
+    const removed = entries.value.find((entry) => entry.id === entryId);
+    if (!removed) return;
+    entries.value = entries.value.filter((entry) => entry.id !== entryId);
+    const historyEntry: NotifierHistoryEntry = {
+      ...removed,
+      terminalType,
+      terminalAt: new Date().toISOString(),
+    };
+    history.value = [historyEntry, ...history.value].slice(0, HISTORY_CAP);
   }
 
-  function markAllRead(): void {
-    if (notifications.value.length === 0) return;
-    const next = new Set(readIds.value);
-    for (const notif of notifications.value) {
-      next.add(notif.id);
+  async function clear(entryId: string): Promise<void> {
+    moveToHistoryLocally(entryId, "cleared");
+    const result = await apiPost<{ ok: true }>(API_ROUTES.notifier.dispatch, { action: "clear", id: entryId });
+    if (!result.ok) {
+      // Rendering this in console rather than the panel itself —
+      // the panel is small and we don't want a transient API error
+      // shouting at the user. A future prime() would resync state
+      // if the server is genuinely out of sync.
+      console.error("[useNotifications] clear failed", result.error);
     }
-    readIds.value = next;
   }
 
-  function dismiss(notifId: string): void {
-    notifications.value = notifications.value.filter((notif) => notif.id !== notifId);
-    // Drop the matching readIds entry too. Without this, a long
-    // session that dismisses thousands of notifications leaks one
-    // ~36-char id per dismissal even though the user can't see
-    // them — pruneReadIds keeps the Set tied to `notifications`.
-    if (readIds.value.has(notifId)) {
-      const next = new Set(readIds.value);
-      next.delete(notifId);
-      readIds.value = next;
-    }
+  async function cancel(entryId: string): Promise<void> {
+    moveToHistoryLocally(entryId, "cancelled");
+    const result = await apiPost<{ ok: true }>(API_ROUTES.notifier.dispatch, { action: "cancel", id: entryId });
+    if (!result.ok) console.error("[useNotifications] cancel failed", result.error);
   }
 
-  return { notifications, latest, unreadCount, isRead, markRead, markAllRead, dismiss };
+  return { entries: sortedEntries, history, badgeCount, badgeColor, ready, clear, cancel };
 }