@12-apps/notifications 4.9.0 → 4.10.1

package/src/react/live-card.tsx

@@ -0,0 +1,279 @@
+/**
+ * ONE pinned live entry: a mark, what is happening, its lane, and when it last
+ * moved.
+ *
+ * Visually a WASH rather than a fill — a tinted card with a brand-tinted border
+ * — for the reason the inbox's unread row uses the same treatment: this sits at
+ * the top of a list of other people's news, and a saturated block there
+ * out-shouts everything it is supposed to be introducing.
+ *
+ * ## The card is a DIV, and the button is inside it
+ *
+ * The obvious shape — one `<button>` wrapping the whole card — is not
+ * available, because `Stepper` draws every stop as a real `<button>`
+ * (`@12-apps/ui`'s `StepButton` is `styled(Button)`), and `clickable={false}`
+ * only sets `pointer-events: none`. A button inside a button is invalid HTML:
+ * the parser auto-closes the outer one at the first nested one, so any host
+ * that server-renders the panel open hydrates against a tree the browser
+ * rewrote, and every adopter's dev console carries a React error besides.
+ *
+ * `aria-hidden` and `inert` on the lane fix the tab stops and the accessible
+ * name — they do NOT fix the nesting, and an earlier draft of this file claimed
+ * they did. So the tap target is the TEXT block, and the lane and the timestamp
+ * are its siblings: valid markup, and a target that still covers everything a
+ * reader would aim at.
+ */
+import { useId, type JSX, type ReactNode } from 'react';
+
+import { Stepper } from '@12-apps/ui/data-display/Stepper';
+import { Box } from '@12-apps/ui/mui/Box';
+import { alpha, type Theme } from '@12-apps/ui/mui/styles';
+import { Text } from '@12-apps/ui/typography/Text';
+
+import { liveActivityLane, type LiveActivity } from '../live';
+import type { NotificationMessages } from '../messages';
+
+import type { LiveActivitiesConfig, LiveActivityMessages } from './live-config';
+import { relativeTime } from './relative-time';
+
+const cardSx = {
+  // `relative`, so the button below can stretch a hit area over the whole card
+  // — see `targetSx`.
+  position: 'relative',
+  border: '1px solid',
+  borderColor: (t: Theme) => alpha(t.palette.primary.main, 0.35),
+  bgcolor: (t: Theme) => alpha(t.palette.primary.main, 0.06),
+  borderRadius: 1.5,
+  p: 1.25,
+  mb: 1,
+} as const;
+
+/** The text block: the mark, the heading and the sentence under it. */
+const targetSx = {
+  display: 'flex',
+  alignItems: 'center',
+  gap: 1,
+  width: '100%',
+  textAlign: 'left',
+  font: 'inherit',
+  color: 'inherit',
+  border: 'none',
+  background: 'none',
+  p: 0,
+} as const;
+
+/**
+ * The button, stretched over the WHOLE card.
+ *
+ * Taking the lane out of the link fixed the markup and left the card looking
+ * like one target while only its top half was one — the lane is the most
+ * visually distinctive part of it, and aiming at the obvious thing did nothing.
+ *
+ * A stretched pseudo-element is the remedy that keeps the structure: the
+ * `<button>` stays a sibling of the lane in the tree, so nothing nests, and its
+ * `::after` covers the card. All three declarations are load-bearing — a
+ * pseudo-element with no `content` generates no box at all, and an absolutely
+ * positioned box with auto offsets is 0×0.
+ *
+ * ## What actually lets a click on the LANE reach it
+ *
+ * Not paint order. `@12-apps/ui` gives each `StepItem` `position: relative`, and
+ * this overlay is positioned too — so the two sit in the SAME painting layer
+ * (positioned, `z-index: auto`), where tree order decides, and the lane comes
+ * after the button. Every stop, and its label, therefore sits over this
+ * overlay. `clickable={false}` does not save it either: the package puts
+ * `pointer-events: none` on the step CIRCLE and not on the label beside it.
+ *
+ * It is `inert` on {@link ActivityLane} that does it: an inert subtree is
+ * skipped by hit-testing, so a click on a stop falls through to the overlay
+ * underneath. That makes the attribute load-bearing for the TARGET as well as
+ * for the tab order it was added for — remove it and the lane silently swallows
+ * clicks again, which is why the two are pinned by one test.
+ */
+const stretchedSx = {
+  ...targetSx,
+  cursor: 'pointer',
+  '&::after': { content: '""', position: 'absolute', inset: 0 },
+} as const;
+
+/**
+ * Make a four-stop lane fit the panel.
+ *
+ * The drawer is 400px on a desktop and the full viewport on a phone, so the
+ * narrow case is ~320px of card minus its padding. `Stepper` renders its labels
+ * at `body2` for every size but `sm` and reserves 24px of connector plus 8px of
+ * margin on each side, which is more row than four short words have — measured
+ * on a 320px viewport, the last stop hung off the edge and the DRAWER scrolled
+ * sideways.
+ *
+ * Three overrides, each buying back a specific number of pixels: 11px labels, a
+ * step column allowed to shrink below the package's 44px floor (so the row's
+ * min-content width is the longest WORD rather than the longest phrase), and
+ * thinner connectors. `overflow: hidden` is the backstop and not the mechanism
+ * — a locale with longer words than any of this anticipates clips its own card
+ * instead of making the panel scroll.
+ */
+const laneSx = {
+  pt: 1.25,
+  px: 0.5,
+  overflow: 'hidden',
+  '& .MuiTypography-root': { fontSize: 11, lineHeight: 1.25 },
+  '& [data-testid^="stepper-step-content-"]': { minWidth: 0 },
+  '& [data-testid^="stepper-connector-"]': { minWidth: 6, mx: 0.75 },
+} as const;
+
+/**
+ * The lane, or nothing.
+ *
+ * `aria-hidden` AND `inert`, and each earns its place twice over. The stops are
+ * real buttons, so leaving four focusable, named controls per entry in front of
+ * an inbox would cost a keyboard user the list they opened the panel for —
+ * that is what the pair was added for. `inert` then turns out to be what makes
+ * the card's own hit area work as well, because an inert subtree is skipped by
+ * hit-testing: see {@link stretchedSx}.
+ *
+ * Nothing is lost by hiding it — the stop the subject is at is already the
+ * card's heading, and the row of dots restates it visually.
+ */
+function ActivityLane({ activity }: { activity: LiveActivity }): JSX.Element | null {
+  const lane = liveActivityLane(activity);
+  if (lane === null) return null;
+  return (
+    <Box sx={laneSx} aria-hidden inert>
+      <Stepper
+        steps={lane.steps.map((step) => ({ id: step.id, label: step.label }))}
+        activeId={lane.activeStepId}
+        completed={new Set(lane.completed)}
+        orientation="horizontal"
+        size="xs"
+        clickable={false}
+        data-testid={`live-activity-steps-${activity.id}`}
+      />
+    </Box>
+  );
+}
+
+/** The card's props. Not part of the package's surface — see `./index`. */
+interface LiveActivityCardProps {
+  activity: LiveActivity;
+  messages: NotificationMessages;
+  live: LiveActivityMessages;
+  renderIcon?: LiveActivitiesConfig['renderIcon'];
+  /** The clock this render reads, so the "last moved" line can be ticked. */
+  now: number;
+  /**
+   * Follow the card's link.
+   *
+   * Absent — as it is for a host with no router — renders the text as text. A
+   * named, focusable control that does nothing is worse than no control.
+   */
+  onOpen?: (activity: LiveActivity) => void;
+}
+
+/**
+ * The mark on the left, when the host draws one.
+ *
+ * PRESENTATIONAL ONLY. It is rendered inside the card's `<button>` and inside
+ * an `aria-hidden` wrapper, so a host returning anything focusable — an
+ * icon-button, a link — puts a button inside a button (invalid HTML, and the
+ * defect this card was restructured to remove) and hides a focusable node from
+ * the accessibility tree. An icon, an emoji, an `<svg>`: yes. A control: no.
+ */
+function ActivityIcon({ icon }: { icon: ReactNode }): JSX.Element | null {
+  if (icon === undefined || icon === null) return null;
+  return (
+    <Box aria-hidden sx={{ display: 'flex', flex: '0 0 auto', color: 'primary.main' }}>
+      {icon}
+    </Box>
+  );
+}
+
+/** The mark, the heading and the line under it. */
+function ActivityTarget({
+  activity,
+  renderIcon,
+  bodyId,
+}: Pick<LiveActivityCardProps, 'activity' | 'renderIcon'> & {
+  /** Ties the sentence to the button, so a label does not swallow it. */
+  bodyId: string;
+}): JSX.Element {
+  return (
+    <>
+      <ActivityIcon icon={renderIcon?.(activity)} />
+      {/* A COLUMN, not a bare block: `Text` sets no `display`, so two adjacent
+          spans in an ordinary div run together on one line with not even a
+          space between them — which is how the heading and the sentence under
+          it ended up as one word in an earlier draft. `row.tsx` gets this right
+          the same way. */}
+      <Box sx={{ display: 'flex', flexDirection: 'column', gap: 0.25, minWidth: 0 }}>
+        {/*
+          The live region is THIS LINE and nothing else. The card also carries a
+          relative timestamp that moves every minute for as long as the subject
+          lasts, and announcing that is a polite interruption per minute for
+          news the reader did not ask to be read. What is worth interrupting for
+          is the subject MOVING, which is what the heading says.
+        */}
+        <Text
+          variant="body"
+          size="sm"
+          weight="semibold"
+          as="span"
+          aria-live="polite"
+          data-testid={`live-activity-title-${activity.id}`}
+        >
+          {activity.title}
+        </Text>
+        {activity.body === null ? null : (
+          <Text id={bodyId} variant="caption" size="xs" color="secondary" as="span">
+            {activity.body}
+          </Text>
+        )}
+      </Box>
+    </>
+  );
+}
+
+export function LiveActivityCard({
+  activity,
+  messages,
+  live,
+  renderIcon,
+  now,
+  onOpen,
+}: LiveActivityCardProps): JSX.Element {
+  const followable = activity.link !== null && onOpen !== undefined;
+  const bodyId = useId();
+  const target = (
+    <ActivityTarget
+      activity={activity}
+      bodyId={bodyId}
+      {...(renderIcon ? { renderIcon } : {})}
+    />
+  );
+  return (
+    <Box data-testid={`live-activity-${activity.id}`} sx={cardSx}>
+      {followable ? (
+        <Box
+          component="button"
+          type="button"
+          onClick={() => onOpen(activity)}
+          // `aria-label` REPLACES the contents, so the sentence under the
+          // heading — the detail that makes the heading actionable — would be
+          // announced to nobody. `aria-describedby` puts it back.
+          aria-label={live.openActivity(activity.title)}
+          {...(activity.body === null ? {} : { 'aria-describedby': bodyId })}
+          data-testid={`live-activity-open-${activity.id}`}
+          sx={stretchedSx}
+        >
+          {target}
+        </Box>
+      ) : (
+        <Box sx={targetSx}>{target}</Box>
+      )}
+      <ActivityLane activity={activity} />
+      <Text variant="caption" size="xs" color="secondary" as="span" italic>
+        {live.updated(relativeTime(activity.updatedAt, messages, now))}
+      </Text>
+    </Box>
+  );
+}

package/src/react/live-config.ts

@@ -0,0 +1,79 @@
+/**
+ * The host's half of live activities: where they come from, and what they say.
+ *
+ * Both are the host's because neither can be this package's. It has no idea
+ * what is happening — only the application does — and it has no words, for the
+ * same reason `NotificationMessages` is required rather than defaulted: a
+ * package that ships one product's sentences ships them to every other product
+ * too, and the adopter reached by saying nothing is the one who never notices.
+ */
+import type { ReactNode } from 'react';
+
+import type { LiveActivity } from '../live';
+
+/**
+ * Where the surface gets the activities that are live RIGHT NOW.
+ *
+ * A HOOK rather than a fetcher, and rather than a factory-time `subscribe`,
+ * because the answer almost always lives in React context: the tenant, the
+ * session, the host's query client. `NotificationsSignalHook` exists for
+ * exactly this reason one seam over, and a host in that shape had no way to
+ * pass anything at all.
+ *
+ * `active` is whether the surface currently needs the answer. It is a HINT
+ * about need, never about correctness: a host that ignores it and always
+ * answers is behaving correctly and merely paying for it.
+ *
+ * What it is NOT is the only thing standing between a shut panel and a query.
+ * The panel is fetched lazily and renders nothing until somebody first opens
+ * the bell, and the drawer unmounts its content on close — so a host that
+ * simply reads `active` and ignores it still issues nothing while the panel is
+ * away. `active` is `false` for the frames of the closing transition, which is
+ * where it earns its keep: a query told to stand down there does not fire one
+ * last time on the way out.
+ *
+ * Return whatever is live, newest activity first or in whatever order the host
+ * means; the surface renders them in the order given. An empty array is the
+ * normal answer and renders nothing — no heading, no empty state, no gap.
+ */
+export type LiveActivitiesHook = (options: {
+  active: boolean;
+}) => readonly LiveActivity[];
+
+/** The three sentences the live section says. */
+export interface LiveActivityMessages {
+  /** The heading over the pinned entries, e.g. "Em andamento". */
+  sectionTitle: string;
+  /** The link's accessible name, e.g. `(title) => `Abrir ${title}``. */
+  openActivity: (title: string) => string;
+  /**
+   * The "last moved" line, given an already-relative time.
+   *
+   * Takes the phrase rather than the instant so the relative wording stays in
+   * ONE place — `relativeTime` and the inbox rows' `há 5 min` — and a host
+   * cannot end up with two vocabularies for the same duration in one panel.
+   */
+  updated: (relative: string) => string;
+}
+
+/** Live activities, as a host turns them on. */
+export interface LiveActivitiesConfig {
+  useActivities: LiveActivitiesHook;
+  messages: LiveActivityMessages;
+  /**
+   * The mark on the left of a card — the fastest read, before any words.
+   *
+   * A node rather than a field on {@link LiveActivity} so the contract stays
+   * framework-free: the root entry is shared with the server half, and a
+   * `ReactNode` in it would put React on that import path for a backend that
+   * only ever writes rows. The host switches on `kind`, which is what `kind` is
+   * for. No renderer, no mark, and the card is text — never a placeholder box.
+   *
+   * **Return something PRESENTATIONAL.** The mark is drawn inside the card's
+   * own `<button>` and inside an `aria-hidden` wrapper, so a focusable node
+   * here is a button inside a button — invalid HTML, and the exact defect the
+   * card's structure exists to prevent — as well as a control hidden from the
+   * accessibility tree. An icon or an `<svg>`; not a control.
+   */
+  renderIcon?: (activity: LiveActivity) => ReactNode;
+}

package/src/react/live-section.tsx

@@ -0,0 +1,179 @@
+/**
+ * The pinned block at the top of the panel: everything that is happening NOW,
+ * above everything that has already happened.
+ *
+ * ## Why it is here and not a second surface
+ *
+ * The notification centre is where a person goes to find out what they missed.
+ * Splitting "happening" into its own bell would make them check two places to
+ * answer one question, and the half they would stop checking is the one that
+ * only has something in it occasionally — which is this one. Above the list,
+ * inside the same drawer, it is on the path they already walk.
+ *
+ * ## What it deliberately does NOT do
+ *
+ * - It does not touch `unread`. A live entry is not news; counting it would put
+ *   a number on the bell that no amount of reading can clear.
+ * - It renders nothing at all when there is nothing live — no heading, no empty
+ *   state, no reserved space. A panel with one permanent empty section in it is
+ *   a panel that has taught its reader to skip the top.
+ * - It does not fetch. `useActivities` is the host's, and `active` tells it
+ *   whether anyone is looking.
+ */
+import { useEffect, useId, useState, type JSX, type ReactNode } from 'react';
+
+import { Box } from '@12-apps/ui/mui/Box';
+import { Text } from '@12-apps/ui/typography/Text';
+
+import type { LiveActivity } from '../live';
+import type { NotificationMessages } from '../messages';
+
+import { LiveActivityCard } from './live-card';
+import type { LiveActivitiesConfig } from './live-config';
+import type { LiveSeenStore } from './live-seen';
+
+/**
+ * How often the section re-reads the clock.
+ *
+ * Every minute, because the timestamps under the cards are in minutes and a
+ * tick that cannot change what is on screen is a wasted render — which is why
+ * it is gated on there being something to tick as well as on the panel being
+ * open. An open panel with nothing live schedules nothing at all; the earlier
+ * gate was `active` alone, and it re-rendered a section that renders `null`
+ * once a minute for as long as somebody left the inbox open.
+ */
+const TICK_MS = 60_000;
+
+/**
+ * The current minute, re-read on a timer while there is something to tick.
+ *
+ * The caller passes `active && there are activities` — see {@link TICK_MS} for
+ * why both halves are in it.
+ */
+function useMinuteTick(active: boolean): number {
+  const [now, setNow] = useState(() => Date.now());
+  useEffect(() => {
+    if (!active) return;
+    // Re-read once on becoming active too: a panel reopened after ten minutes
+    // would otherwise show the minute it was closed at until the first tick.
+    setNow(Date.now());
+    const timer = setInterval(() => setNow(Date.now()), TICK_MS);
+    return () => clearInterval(timer);
+  }, [active]);
+  return now;
+}
+
+export interface LiveSectionProps {
+  config: LiveActivitiesConfig;
+  messages: NotificationMessages;
+  /** Whether the panel is open — passed straight through to the host's hook. */
+  active: boolean;
+  /**
+   * Follow a card's link.
+   *
+   * Optional, and the panel omits it for a host with no router: a card that
+   * cannot go anywhere renders as text rather than as a named control that
+   * does nothing.
+   */
+  onOpen?: (activity: LiveActivity) => void;
+  /**
+   * The rest of the panel, given how many entries are live.
+   *
+   * A render prop rather than a sibling, because the count is knowable only
+   * where the host's hook is CALLED, and it cannot be called anywhere else:
+   * `live` is optional on the panel, so reading it there would mean calling a
+   * hook conditionally — the failure React reports as a crash in some unrelated
+   * component.
+   *
+   * The inbox needs the number for exactly one decision, and it is the decision
+   * this section exists to inform: whether "no notifications" is true. A live
+   * entry IS a notification, so a panel showing one under that sentence is
+   * contradicting itself.
+   */
+  children?: (liveCount: number) => ReactNode;
+  /**
+   * Where "the reader has seen these" is recorded, for the bell to read.
+   *
+   * Written HERE because this is the component that puts them on screen, and
+   * being on screen is what seen means. Optional so the section stays usable by
+   * a host that mounts it outside the panel.
+   */
+  seen?: LiveSeenStore;
+}
+
+
+
+export function LiveSection({
+  config,
+  messages,
+  active,
+  onOpen,
+  children,
+  seen,
+}: LiveSectionProps): JSX.Element {
+  // Unconditional, because it is a hook. `active` is how it is told nobody is
+  // looking — the same arrangement `useSignal` has one seam over.
+  const activities = config.useActivities({ active });
+  const now = useMinuteTick(active && activities.length > 0);
+  // Per MOUNT, not per module: `LiveSection` is exported, and a host with a
+  // desktop and a mobile panel would otherwise emit one id twice and have both
+  // regions resolve their label to whichever came first.
+  const headingId = useId();
+
+  const liveCount = activities.length;
+
+  // Only while somebody is looking. The panel keeps this mounted through the
+  // closing transition, and marking there would swallow an update that arrived
+  // in the frames after the reader turned away.
+  useEffect(() => {
+    if (active && liveCount > 0) seen?.mark(activities);
+  }, [active, liveCount, activities, seen]);
+
+  if (liveCount === 0) return <>{children?.(0)}</>;
+
+  return (
+    <>
+    // A NAMED region. Without the label a screen-reader user meets a loose run
+    // of controls ahead of the inbox with nothing saying what they are; the
+    // panel's own title is the drawer's heading and cannot describe this block.
+    <Box
+      component="section"
+      aria-labelledby={headingId}
+      data-testid="live-activities"
+      sx={{ pb: 1.5 }}
+    >
+      {/*
+        A SPAN, not a heading. `aria-labelledby` names the region perfectly well
+        from one, and an `<h2>` here would sit under the drawer's own `<h6>`
+        title and ABOVE the inbox's `<h3>` empty state — an outline in which the
+        inbox's states read as part of the live block, which is the opposite of
+        what the two blocks are.
+      */}
+      <Text
+        id={headingId}
+        variant="caption"
+        size="xs"
+        color="secondary"
+        weight="semibold"
+        as="span"
+      >
+        {config.messages.sectionTitle}
+      </Text>
+      <Box sx={{ pt: 0.75 }}>
+        {activities.map((activity) => (
+          <LiveActivityCard
+            key={activity.id}
+            activity={activity}
+            messages={messages}
+            live={config.messages}
+            now={now}
+            {...(onOpen ? { onOpen } : {})}
+            {...(config.renderIcon ? { renderIcon: config.renderIcon } : {})}
+          />
+        ))}
+      </Box>
+      </Box>
+      {children?.(liveCount)}
+    </>
+  );
+}

package/src/react/live-seen.ts

@@ -0,0 +1,138 @@
+/**
+ * What the reader has already been shown, so the bell can say NEW rather than
+ * merely PRESENT.
+ *
+ * A live activity is unlike an inbox row in the one way that matters here: it
+ * stays on the panel for as long as the thing is happening, so its presence
+ * cannot mean "you have not seen this". A pedido that has been `Preparo` for
+ * ten minutes is still live and still worth counting, but nothing has happened
+ * — and a badge that shouts for a subject the reader has already looked at is a
+ * badge people stop reading.
+ *
+ * So presence and novelty are answered separately: the COUNT comes from how
+ * many are live, and the TONE comes from this. The panel writes it — being on
+ * screen is what seen means — and the bell reads it.
+ *
+ * ## Per subject, not one watermark
+ *
+ * A single "newest instant already seen" is smaller and was the first cut, and
+ * it is wrong in a way that shows up in normal use: a pedido placed ten minutes
+ * ago but only now reaching the client arrives with an `updatedAt` BEHIND the
+ * watermark, and would be silently marked as already seen. The reader has never
+ * laid eyes on it. Keyed by subject, an id that has not been recorded is new
+ * whatever its clock says.
+ *
+ * Bounded by pruning rather than by expiry: every write keeps only the subjects
+ * that are live at that moment, so the record can never outgrow the number of
+ * things happening at once. A subject that finishes and later comes back is
+ * news again, which is correct — it is a different occurrence.
+ */
+import type { LiveActivity } from '../live';
+
+const STORAGE_KEY = '12a.notifications.live-seen';
+
+/** id -> the `updatedAt` that was on screen. */
+type SeenMap = Readonly<Record<string, string>>;
+
+const EMPTY: SeenMap = {};
+
+/** ms since epoch, or `null` for an absent or unparseable stamp. */
+function instant(iso: string | undefined): number | null {
+  if (iso === undefined) return null;
+  const ms = Date.parse(iso);
+  return Number.isNaN(ms) ? null : ms;
+}
+
+/**
+ * Read/write through `try`, every time.
+ *
+ * `localStorage` is not merely absent in SSR and in a worker — the ACCESSOR
+ * itself throws in a browser set to block site data. A notification bell that
+ * cannot render because storage is blocked is a worse failure than one that
+ * forgets what was seen, and forgetting degrades in the safe direction: towards
+ * saying something is happening.
+ */
+function readStored(): SeenMap {
+  try {
+    const raw = globalThis.localStorage?.getItem(STORAGE_KEY);
+    if (!raw) return EMPTY;
+    const parsed: unknown = JSON.parse(raw);
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) return EMPTY;
+    // Anything can be in storage — another version of this package, or a person
+    // with the devtools open. Keep only what has the shape this reads.
+    const clean: Record<string, string> = {};
+    for (const [id, value] of Object.entries(parsed)) {
+      if (typeof value === 'string') clean[id] = value;
+    }
+    return clean;
+  } catch {
+    return EMPTY;
+  }
+}
+
+function writeStored(value: SeenMap): void {
+  try {
+    globalThis.localStorage?.setItem(STORAGE_KEY, JSON.stringify(value));
+  } catch {
+    // Blocked or full. The badge stays new a while longer; nothing else breaks.
+  }
+}
+
+export interface LiveSeenStore {
+  /** What has been shown, keyed by subject id. */
+  read: () => SeenMap;
+  /** Record that exactly these are on screen now, forgetting subjects that are not. */
+  mark: (activities: readonly LiveActivity[]) => void;
+  subscribe: (listener: () => void) => () => void;
+}
+
+export function createLiveSeenStore(): LiveSeenStore {
+  // Mirrored in memory as well as in storage: `useSyncExternalStore` compares
+  // snapshots by IDENTITY and calls `read` on every render, so parsing storage
+  // there would hand it a fresh object each time and re-render for ever.
+  let current = readStored();
+  const listeners = new Set<() => void>();
+
+  return {
+    read: () => current,
+    mark: (activities) => {
+      const next: Record<string, string> = {};
+      for (const activity of activities) next[activity.id] = activity.updatedAt;
+      // Identity is the snapshot, so an unchanged map must not become a new
+      // object — see `read` above.
+      const ids = Object.keys(next);
+      const same =
+        ids.length === Object.keys(current).length &&
+        ids.every((id) => current[id] === next[id]);
+      if (same) return;
+      current = next;
+      writeStored(next);
+      for (const listener of listeners) listener();
+    },
+    subscribe: (listener) => {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+  };
+}
+
+/**
+ * Whether any of these has moved, or arrived, since the reader last looked.
+ *
+ * An id with nothing recorded is new — that is the case the per-subject record
+ * exists for. An unparseable stamp is treated as new too: the alternative is
+ * silently never alerting for a host whose clock format this does not read.
+ */
+export function hasUnseenActivity(
+  activities: readonly LiveActivity[],
+  seen: SeenMap,
+): boolean {
+  return activities.some((activity) => {
+    const shown = instant(seen[activity.id]);
+    if (shown === null) return true;
+    const now = instant(activity.updatedAt);
+    return now === null || now > shown;
+  });
+}