@12-apps/notifications 4.10.3 → 4.12.0

package/src/preferences-core.ts

@@ -70,11 +70,118 @@ export function mergeStoredRow(stored: unknown, base: ChannelRow): ChannelRow {
   return row;
 }
 
+/**
+ * What ONE notification type says about its own channels, independent of the
+ * user's category preferences: {@link NotificationGenerator.channels} (the hard
+ * availability cap) and {@link NotificationGenerator.channelDefaults} (a
+ * starting point the user can still move).
+ *
+ * Structurally what a generator already is, rather than the generator itself,
+ * so the policy here stays free of the registry and the router.
+ */
+export interface TypeChannelRules {
+  channels?: readonly NotificationChannel[];
+  channelDefaults?: Partial<ChannelRow>;
+}
+
+/**
+ * The channels a type may EVER use, coerced onto the closed channel set.
+ *
+ * `undefined` — a generator that never declared a list — means every channel,
+ * which is what keeps every generator written before the field working. An
+ * EMPTY list means no transport channel at all and is legal: the inbox record
+ * is written by the router regardless, and the inbox is not a channel a user
+ * opts out of.
+ *
+ * Filtering through {@link NOTIFICATION_CHANNELS} rather than returning the
+ * declaration is deliberate: it drops a value that is not a channel (a typo, a
+ * channel removed from the set since) instead of carrying it into an
+ * intersection where it would silently match nothing anyway, and it fixes the
+ * order so two declarations of the same set compare equal.
+ */
+export function availableChannelsOf(
+  declared: readonly NotificationChannel[] | undefined,
+): NotificationChannel[] {
+  if (!declared) return [...NOTIFICATION_CHANNELS];
+  const offered = new Set<string>(declared);
+  return NOTIFICATION_CHANNELS.filter((channel) => offered.has(channel));
+}
+
+/**
+ * Drop the channels a type does not offer. Applied by the router AFTER every
+ * other gate, so no later stage can hand back a channel the type never offered
+ * — including the plan gate's own error fallback, which degrades to the free
+ * channels and would otherwise restore an e-mail this type had just refused.
+ */
+export function capToAvailable(
+  channels: readonly NotificationChannel[],
+  declared: readonly NotificationChannel[] | undefined,
+): NotificationChannel[] {
+  if (!declared) return [...channels];
+  const offered = new Set(availableChannelsOf(declared));
+  return channels.filter((channel) => offered.has(channel));
+}
+
+/**
+ * The channels one (user, category, TYPE) actually enables — the whole policy
+ * in one pure function, so the router's gate can be argued about without a
+ * database.
+ *
+ * The order is the meaning:
+ *   1. the category's defaults, with the TYPE's defaults over them — a type
+ *      moves the starting point;
+ *   2. the user's stored row over that — an explicit choice beats any default,
+ *      which is what makes step 1 a default rather than a rule;
+ *   3. the type's AVAILABILITY over everything — a channel this type does not
+ *      offer is gone even when the user's stored row explicitly asked for it,
+ *      because it was never on offer for this message.
+ *
+ * Step 3 overriding a stored `true` is the one place a user's saved choice is
+ * discarded, and it is the point of the field: the answer they gave was about
+ * the CATEGORY, and a category can hold messages this channel was never right
+ * for. Step 2 beating step 1 is what keeps the other field a default.
+ */
+export function resolveTypeChannels(input: {
+  /** The stored `channels` JSON for this (user, category), if any. */
+  stored?: unknown;
+  /** The category's effective default row (host defaults already merged). */
+  categoryDefaults: ChannelRow;
+  /** The type's own declarations. */
+  rules?: TypeChannelRules;
+}): NotificationChannel[] {
+  const { stored, categoryDefaults, rules } = input;
+  const base: ChannelRow = { ...categoryDefaults, ...rules?.channelDefaults };
+  const row = stored === undefined || stored === null ? base : mergeStoredRow(stored, base);
+  return capToAvailable(enabledChannelsOf(row), rules?.channels);
+}
+
 /** The channels enabled by one effective row — the router's gate. */
 export function enabledChannelsOf(row: ChannelRow): NotificationChannel[] {
   return NOTIFICATION_CHANNELS.filter((channel) => row[channel]);
 }
 
+/**
+ * The channels a stored row states an EXPLICIT choice for, dropping everything
+ * else — the inverse of {@link mergeStoredRow}, which fills the gaps in.
+ *
+ * The package's storage model is "only explicit choices are stored; a missing
+ * key falls back to the default", and this is what lets a writer keep that
+ * promise. Merging a save onto the user's EFFECTIVE row instead turns every
+ * defaulted channel into an explicit one the moment they touch any switch, and
+ * the row can never say "no opinion" about a channel again.
+ */
+export function explicitChoicesOf(stored: unknown): Partial<ChannelRow> {
+  const choices: Partial<ChannelRow> = {};
+  if (stored && typeof stored === 'object') {
+    const record = stored as Record<string, unknown>;
+    for (const channel of NOTIFICATION_CHANNELS) {
+      const value = record[channel];
+      if (typeof value === 'boolean') choices[channel] = value;
+    }
+  }
+  return choices;
+}
+
 /**
  * What a PUT writes for one category: the caller's toggles merged over the
  * user's CURRENT effective row. A single-toggle save (how the settings UI

package/src/react/bell-badge.ts

@@ -0,0 +1,147 @@
+/**
+ * What the bell shows: ONE number, and whether any of it is news.
+ *
+ * The badge answers two different questions with one glyph, and keeping them
+ * apart is the whole design:
+ *
+ * - the COUNT is how many things the centre is holding for the reader;
+ * - the TONE is whether any of them has happened since they last looked.
+ *
+ * An inbox row makes those the same question — an unread row is by definition
+ * both present and unseen — which is why the distinction did not exist before
+ * live activities did. A live activity separates them: a pedido that has been
+ * `Preparo` for ten minutes is still worth a `1`, and shouting about it every
+ * render is how a badge teaches people to stop reading it.
+ *
+ * ## This is here so a host can DRAW it
+ *
+ * The numbers were already correct inside this package's own `BellButton`, and
+ * unreachable from a host that cannot take that component — a header whose cart
+ * and search buttons are one styled icon-button is importing a second trigger
+ * style the moment it does. Such a host had `useUnreadCount` and nothing else,
+ * so its bell showed NOTHING while a pinned pedido sat inside the panel it
+ * opens. Both bells now read these hooks, so a host cannot drift from what this
+ * package renders.
+ *
+ * ## What it does NOT yet do
+ *
+ * A live subject usually also writes inbox rows as it moves, and this counts
+ * both: a pedido with one unread row about it reads `2`. Subtracting the double
+ * needs the server to say which unread rows name which subject, and that was
+ * built, reviewed and pulled — for reasons about the CONTRACT rather than the
+ * arithmetic, and worth recording so the next attempt starts past them:
+ *
+ *  - it added a field to `GET /notifications/unread-count`, and at least one
+ *    adopter publishes that response as a closed schema to LLM clients. An
+ *    additive field is a breaking change against `additionalProperties: false`.
+ *  - the scan is per READER, so every host paid it — including the two SPAs in
+ *    that adopter that share one factory and configure no live activities at
+ *    all, and read the count through `useUnreadCount`, which never sees the
+ *    breakdown.
+ *  - it narrowed `NotificationsApiClient.unreadCount()` from `Promise<number>`,
+ *    which is a breaking change on a commit the release rules cut as a minor.
+ *
+ * The way through is an opt-in the surface asks for — a host with no live
+ * activities then sends nothing different and receives nothing different.
+ *
+ * (An earlier revision of this docblock blamed a missing index instead. That
+ * was wrong: `[userId, deletedAt, readAt]` is a full equality prefix over the
+ * filter, and the `ORDER BY` the scan carried was not load-bearing, since a
+ * tally does not care what order it counts in.)
+ */
+import { useMemo, useSyncExternalStore } from 'react';
+
+import { useBadgeState, type BadgeSyncOptions } from './hooks';
+import type { InboxStore } from './inbox-state';
+import type { LiveActivitiesConfig } from './live-config';
+import { hasUnseenActivity, type LiveSeenStore } from './live-seen';
+
+/** The bell's whole state — see the file docblock for what each half means. */
+export interface BellBadge {
+  /** What the badge shows. `0` renders no badge at all. */
+  count: number;
+  /**
+   * Whether any of it has arrived or moved since the reader last looked.
+   *
+   * The trigger paints this as its accent colour; a host with its own chrome
+   * decides how to say it, but it should be a difference somebody notices.
+   */
+  hasNew: boolean;
+}
+
+/**
+ * The badge for a host with no live activities: unread rows, and that is all.
+ *
+ * `hasNew` is `count > 0` here, and not as a simplification — an UNREAD row is
+ * one the reader has not seen, so for this host presence and novelty really are
+ * the same fact.
+ */
+export function useInboxBellBadge(store: InboxStore, options: BadgeSyncOptions = {}): BellBadge {
+  // `useBadgeState` already blanks itself when disabled — the gate lives there,
+  // once, rather than at each of the three hooks that layer on it.
+  const { unread } = useBadgeState(store, options);
+  // MEMOISED, unlike the number `useUnreadCount` returns. `useSyncExternalStore`
+  // re-renders on every `patch` and `patch` always allocates, so a poll that
+  // comes back with an unchanged count would otherwise hand a host a new object
+  // every 60 s — enough to re-fire a `useEffect` keyed on it, or defeat a
+  // `React.memo` on the trigger, forever.
+  return useMemo(() => ({ count: unread, hasNew: unread > 0 }), [unread]);
+}
+
+/**
+ * The badge for a host that configured live activities.
+ *
+ * A SECOND hook rather than a flag on the one above, for the reason the bell
+ * itself is two components: `live.useActivities` is a hook, so a single hook
+ * reading an optional config would be calling one conditionally — which React
+ * reports as a crash somewhere else entirely. The factory knows statically
+ * which host it is building for and binds one.
+ *
+ * ## `enabled` is enforced HERE, not taken on trust
+ *
+ * A host is explicitly allowed to ignore the `active` hint and always answer —
+ * `./live-config` calls that "behaving correctly and merely paying for it" — so
+ * a signed-out header, which still MOUNTS the bell, can be handed a list of
+ * somebody's pedidos. The guard below is the only thing between that and a
+ * badge counting them.
+ *
+ * Defensive against the CONTRACT, not against an observed adopter: today's one
+ * honours the hint on every lever it has. That is exactly why the guard needs
+ * saying — nothing about the current tree would fail if it went, and the case
+ * that covers it has to build the ignoring host itself.
+ *
+ * ## What it costs the host, stated plainly
+ *
+ * The bell is mounted for as long as the app is, so unlike the panel's copy of
+ * this hook there is no "nobody is looking" state to stand down in — `active`
+ * is simply `enabled`. A host that answers by polling therefore polls for every
+ * signed-in reader whether or not they ever open the centre. That is the price
+ * of a badge that knows about live activities at all, and the reason to answer
+ * this hook from a pushed cache rather than from an interval.
+ */
+export function useLiveBellBadge(
+  store: InboxStore,
+  live: LiveActivitiesConfig,
+  seen: LiveSeenStore,
+  options: BadgeSyncOptions = {},
+): BellBadge {
+  const enabled = options.enabled ?? true;
+  const { unread } = useBadgeState(store, options);
+  const activities = live.useActivities({ active: enabled });
+  const seenAt = useSyncExternalStore(seen.subscribe, seen.read, seen.read);
+  // The store's own half is already blanked by `useBadgeState`; the `enabled`
+  // guard here is for the ACTIVITIES half, which comes from a host hook that
+  // may have ignored the hint.
+  //
+  // A live entry COUNTS. It is a notification — it is the one the reader most
+  // wants to know about — and the panel it opens lists it.
+  const count = enabled ? unread + activities.length : 0;
+  const hasNew = enabled && (unread > 0 || hasUnseenActivity(activities, seenAt));
+  // Memoised on the two RESULTS, not on `activities`. A host's hook returns a
+  // fresh array every render — the storefront's maps its query's rows, so
+  // structural sharing keeps the DATA identical and the array new — so an
+  // `activities` dependency would invalidate on every render and the memo would
+  // buy nothing at all. `hasUnseenActivity` runs unmemoised in front of it,
+  // which is a `.some()` over the handful of things happening at once.
+  return useMemo(() => ({ count, hasNew }), [count, hasNew]);
+}

package/src/react/bell-button.tsx

@@ -1,19 +1,26 @@
 /**
  * Bare bell trigger with the live unread badge — for hosts that do not already
- * have a styled icon-button slot. A host with its own trigger chrome uses
- * `useUnreadCount` + `Panel` directly.
+ * have a styled icon-button slot.
+ *
+ * A host with its own trigger chrome uses `useBellBadge` + `Panel` directly,
+ * and NOT `useUnreadCount`, which is what this sentence used to say. That
+ * advice was taken, verbatim and by name, by a storefront whose header needed
+ * its own trigger — and it gave that storefront a bell showing nothing at all
+ * while a live pedido sat in the panel it opens, because `useUnreadCount`
+ * counts inbox rows and knows nothing about what is happening right now.
  */
-import { useSyncExternalStore, type JSX } from 'react';
+import type { JSX } from 'react';
 
 import { Badge } from '@12-apps/ui/data-display/Badge';
 import { Box } from '@12-apps/ui/mui/Box';
 
 import type { NotificationMessages } from '../messages';
 
+import { useInboxBellBadge, useLiveBellBadge } from './bell-badge';
 import { BellIcon } from './bell-icon';
-import { useUnreadCount, type NotificationsSignalHook, type NotificationsSubscribe } from './hooks';
+import type { NotificationsSignalHook, NotificationsSubscribe } from './hooks';
 import type { LiveActivitiesConfig } from './live-config';
-import { hasUnseenActivity, type LiveSeenStore } from './live-seen';
+import type { LiveSeenStore } from './live-seen';
 import type { InboxStore } from './inbox-state';
 
 const triggerSx = {
@@ -111,14 +118,12 @@ export function BellButton({
   subscribe?: NotificationsSubscribe;
   useSignal?: NotificationsSignalHook;
 }): JSX.Element {
-  const count = useUnreadCount(store, {
+  const badge = useInboxBellBadge(store, {
     enabled,
     ...(subscribe ? { subscribe } : {}),
     ...(useSignal ? { useSignal } : {}),
   });
-  // No live config on this host: unread IS the whole count, and an unread row
-  // is by definition something the reader has not seen.
-  return <BellTrigger onClick={onClick} count={count} hasNew={count > 0} messages={messages} />;
+  return <BellTrigger onClick={onClick} {...badge} messages={messages} />;
 }
 
 /**
@@ -130,14 +135,9 @@ export function BellButton({
  * unrelated component rather than here. The factory knows statically which host
  * it is building for and picks one.
  *
- * ## What it costs the host, stated plainly
- *
- * The bell is mounted for as long as the app is, so unlike the panel's copy of
- * this hook there is no "nobody is looking" state to stand down in — `active`
- * is simply `enabled`. A host that answers by polling therefore polls for every
- * signed-in reader whether or not they ever open the centre. That is the price
- * of a badge that knows about live activities at all, and the reason to answer
- * this hook from a pushed cache rather than from an interval.
+ * What the number MEANS, and what it costs the host, is `bell-badge.ts` — the
+ * same hook a host with its own trigger chrome reaches through the factory's
+ * `useBellBadge`, so the two bells can never disagree about the count.
  */
 export function LiveBellButton({
   onClick,
@@ -156,22 +156,10 @@ export function LiveBellButton({
   live: LiveActivitiesConfig;
   seen: LiveSeenStore;
 }): JSX.Element {
-  const unread = useUnreadCount(store, {
+  const badge = useLiveBellBadge(store, live, seen, {
     enabled,
     ...(subscribe ? { subscribe } : {}),
     ...(useSignal ? { useSignal } : {}),
   });
-  const activities = live.useActivities({ active: enabled });
-  const seenIso = useSyncExternalStore(seen.subscribe, seen.read, seen.read);
-  const liveCount = enabled ? activities.length : 0;
-  return (
-    <BellTrigger
-      onClick={onClick}
-      // A live entry counts. It is a notification — it is the one the reader
-      // most wants to know about — and the panel it opens lists it.
-      count={unread + liveCount}
-      hasNew={unread > 0 || (enabled && hasUnseenActivity(activities, seenIso))}
-      messages={messages}
-    />
-  );
+  return <BellTrigger onClick={onClick} {...badge} messages={messages} />;
 }

package/src/react/create-web-notifications.tsx

@@ -3,6 +3,7 @@ import { useState, type ComponentType, type JSX } from 'react';
 import { messagesOf, type NotificationMessages } from '../messages';
 
 import { createNotificationsApiClient, type NotificationsApiClient } from './api';
+import { useInboxBellBadge, useLiveBellBadge, type BellBadge } from './bell-badge';
 import { BellButton, LiveBellButton, type BellButtonProps } from './bell-button';
 import {
   useUnreadCount,
@@ -11,7 +12,7 @@ import {
 } from './hooks';
 import { createInboxStore, type InboxStore } from './inbox-state';
 import type { LiveActivitiesConfig } from './live-config';
-import { createLiveSeenStore } from './live-seen';
+import { createLiveSeenStore, type LiveSeenStore } from './live-seen';
 import { lazyNotificationsPanel } from './panel-lazy';
 import type { NotificationsPanelProps } from './panel';
 import { lazyPreferencesPage } from './page-lazy';
@@ -94,8 +95,31 @@ export interface WebNotifications {
     enabled?: boolean;
     onNavigate?: (link: string) => void;
   }>;
-  /** The badge number, for a host with its own trigger chrome. */
+  /**
+   * The unread INBOX count.
+   *
+   * For a host with its own trigger chrome only when that host configured no
+   * live activities — otherwise it is a bell that ignores everything happening
+   * right now, and `useBellBadge` below is the door. Still the right hook for
+   * anything that genuinely wants "how many unread rows".
+   */
   useUnreadCount: (options?: { enabled?: boolean }) => number;
+  /**
+   * The badge's NUMBER AND TONE, for a host with its own trigger chrome.
+   *
+   * What `useUnreadCount` should have been for a host that also configured live
+   * activities, and the reason it is a second door rather than a change to that
+   * one: a count alone cannot express a bell, because a live entry is present
+   * without being news (see `./bell-badge`). A host that renders
+   * `useUnreadCount` in its own chrome gets a badge that ignores everything
+   * happening right now — which is not a subtle wrongness, it is the pinned
+   * pedido on screen going uncounted.
+   *
+   * Identical to what this package's own `BellButton` draws, because it is the
+   * hook that bell uses. Without live activities configured it is
+   * `useUnreadCount` plus `hasNew: count > 0`.
+   */
+  useBellBadge: (options?: { enabled?: boolean }) => BellBadge;
   /** The shared client state, for host glue. */
   store: InboxStore;
   /** The bound wire client. */
@@ -104,6 +128,33 @@ export interface WebNotifications {
   messages: NotificationMessages;
 }
 
+/** What the factory passes both badge hooks: whatever realtime wiring it has. */
+type SubscribeOption = {
+  subscribe?: NotificationsSubscribe;
+  useSignal?: NotificationsSignalHook;
+};
+
+/**
+ * The two badge hooks, bound to this factory's store.
+ *
+ * `useBellBadge` is chosen ONCE here, the same way `Bell` is below and for the
+ * same reason: `live.useActivities` is a hook, so which implementation runs
+ * must not be a per-render decision.
+ */
+function bindBadgeHooks(
+  store: InboxStore,
+  subscribeOption: SubscribeOption,
+  liveSeen: LiveSeenStore,
+  live: LiveActivitiesConfig | undefined,
+): Pick<WebNotifications, 'useUnreadCount' | 'useBellBadge'> {
+  return {
+    useUnreadCount: (options = {}) => useUnreadCount(store, { ...options, ...subscribeOption }),
+    useBellBadge: live
+      ? (options = {}) => useLiveBellBadge(store, live, liveSeen, { ...options, ...subscribeOption })
+      : (options = {}) => useInboxBellBadge(store, { ...options, ...subscribeOption }),
+  };
+}
+
 export function createWebNotifications(config: NotificationsWebConfig): WebNotifications {
   const messages = messagesOf(config);
   const api = createNotificationsApiClient(
@@ -147,9 +198,7 @@ export function createWebNotifications(config: NotificationsWebConfig): WebNotif
     ...(live ? { live, liveSeen } : {}),
   });
 
-  function useBoundUnreadCount(options: { enabled?: boolean } = {}): number {
-    return useUnreadCount(store, { ...options, ...subscribeOption });
-  }
+  const badgeHooks = bindBadgeHooks(store, subscribeOption, liveSeen, live);
 
   function BellWithPanel({
     enabled = true,
@@ -176,7 +225,7 @@ export function createWebNotifications(config: NotificationsWebConfig): WebNotif
     BellButton: Bell,
     Panel,
     BellWithPanel,
-    useUnreadCount: useBoundUnreadCount,
+    ...badgeHooks,
     store,
     api,
     messages,

package/src/react/hooks.ts

@@ -48,23 +48,60 @@ export function useInboxState(store: InboxStore): InboxState {
   return useSyncExternalStore(store.subscribe, store.getState, store.getState);
 }
 
+/** What both badge hooks below take, and what the bell passes them. */
+export interface BadgeSyncOptions {
+  enabled?: boolean;
+  subscribe?: NotificationsSubscribe;
+  useSignal?: NotificationsSignalHook;
+}
+
+/**
+ * What a disabled badge reads, instead of whatever the store happens to hold.
+ *
+ * A CONSTANT, so `useSyncExternalStore`'s identity comparison sees no change
+ * across the renders of a signed-out session.
+ */
+const NOTHING_TO_SHOW: InboxState = {
+  unread: 0,
+  items: [],
+  status: 'idle',
+  nextCursor: null,
+  loadingMore: false,
+};
+
 /**
- * The bell badge number: pushed while a subscription is live, polled otherwise.
+ * The badge's server state, kept fresh: pushed while a subscription is live,
+ * polled otherwise.
+ *
+ * The whole state rather than the count, because every badge hook that layers
+ * on top of it needs the poll and the subscription mounted exactly ONCE per
+ * bell — read through two hooks, a bell that showed both a number and a tone
+ * would open two of everything.
+ *
+ * ## `enabled` gates the ANSWER, not only the fetching
  *
- * `enabled` gates the poll AND the subscription. A signed-out header still
- * mounts the bell, and there is nothing for it to hear.
+ * It gates the poll and the subscription, which is the obvious half. It also
+ * blanks the returned state, which is the half that was missing and matters
+ * more: the store is per FACTORY and a host builds one at module scope for the
+ * whole app, so signing out does not empty it — `refreshBadge` swallows the 401
+ * and leaves the last number in place. Without this, a hook told there is
+ * nobody signed in hands back the PREVIOUS reader's unread count and their
+ * inbox rows.
+ *
+ * Deliberately here rather than at each caller. It was at each caller, three
+ * times, in three shapes, and two of them were dead weight no test could reach
+ * — which is what an invariant looks like just before one copy of it goes
+ * missing.
+ *
+ * INTERNAL. Not exported from `./index`: it hands back rows as well as a count,
+ * and a host wanting a number has `useUnreadCount` or the factory's
+ * `useBellBadge`.
  */
-export function useUnreadCount(
-  store: InboxStore,
-  options: {
-    enabled?: boolean;
-    subscribe?: NotificationsSubscribe;
-    useSignal?: NotificationsSignalHook;
-  } = {},
-): number {
+export function useBadgeState(store: InboxStore, options: BadgeSyncOptions = {}): InboxState {
   const enabled = options.enabled ?? true;
   const subscribe = options.subscribe;
-  const { unread } = useInboxState(store);
+  const live = useInboxState(store);
+  const state = enabled ? live : NOTHING_TO_SHOW;
 
   // Called unconditionally — it is a hook, so it cannot sit behind `enabled`.
   // The host's own hook decides what to do when there is nothing to hear.
@@ -91,7 +128,18 @@ export function useUnreadCount(
     };
   }, [store, enabled, subscribe]);
 
-  return enabled ? unread : 0;
+  return state;
+}
+
+/**
+ * The bell badge number, for a host with its own trigger chrome.
+ *
+ * A host that also publishes live activities wants `useBellBadge` from the
+ * factory instead — this one counts inbox rows and knows nothing about what is
+ * happening right now.
+ */
+export function useUnreadCount(store: InboxStore, options: BadgeSyncOptions = {}): number {
+  return useBadgeState(store, options).unread;
 }
 
 /** The panel's list — only fetches while the panel is open. */

package/src/react/index.ts

@@ -26,6 +26,15 @@ export {
   type PushRegistrationPayload,
 } from './api';
 
+// `useInboxBellBadge` and `useLiveBellBadge` are deliberately NOT exported, and
+// the live one is why: it takes a `LiveSeenStore`, and the only store that
+// works is the factory's own — the panel writes "seen" into THAT one. A host
+// handed the hook and no way to build the store would either hand-roll a
+// `{read, mark, subscribe}` nothing ever writes to, and get a badge that is
+// permanently `new`, or reach for `createLiveSeenStore` and find it unexported
+// too. `useBellBadge` off the factory is the door, already bound to both.
+export type { BellBadge } from './bell-badge';
+
 export {
   BADGE_POLL_MS,
   BADGE_RECONCILE_MS,
@@ -36,10 +45,14 @@ export {
   type InboxStore,
 } from './inbox-state';
 
+// `useBadgeState` is NOT here, for the reason the raw badge hooks above are
+// not: it hands back the inbox ROWS as well as the count, and a host wanting a
+// number already has `useUnreadCount` and the factory's `useBellBadge`.
 export {
   useInboxList,
   useInboxState,
   useUnreadCount,
+  type BadgeSyncOptions,
   type NotificationsSignalHook,
   type NotificationsSubscribe,
 } from './hooks';

package/src/server/preferences.ts

@@ -1,10 +1,11 @@
 import {
   DEFAULT_CHANNEL_ROW,
-  enabledChannelsOf,
-  mergeChoices,
+  explicitChoicesOf,
   mergeStoredRow,
+  resolveTypeChannels,
   type ChannelMatrix,
   type ChannelRow,
+  type TypeChannelRules,
 } from '../preferences-core';
 import type {
   NotificationCategory,
@@ -32,10 +33,20 @@ export interface NotificationPreferenceStore {
     userId: string,
     input: Partial<Record<NotificationCategory, Partial<ChannelRow>>>,
   ): Promise<void>;
-  /** The channels enabled for one (user, category) — the router's gate. */
+  /**
+   * The channels enabled for one (user, category) — the router's gate.
+   *
+   * `rules` carries the emitting TYPE's own declarations (availability and
+   * per-type defaults). It is OPTIONAL, and that is what keeps a host store
+   * written before it working: a two-parameter implementation is assignable to
+   * this signature unchanged, and omitting the argument asks the same question
+   * the store has always answered. The router does not rely on a store
+   * honouring it — it caps the result by availability itself.
+   */
   enabledChannels(
     userId: string,
     category: NotificationCategory,
+    rules?: TypeChannelRules,
   ): Promise<NotificationChannel[]>;
 }
 
@@ -72,6 +83,14 @@ export function createPreferenceStore(
      * A category outside the taxonomy is IGNORED rather than stored: the DB
      * CHECK would reject it anyway, and a 500 from a stale client's extra key
      * would fail the whole save including the toggle the user did flip.
+     *
+     * What is written is the user's EXPLICIT choices only, never their
+     * effective row. Merging onto the effective row wrote a boolean for all
+     * four channels the moment anyone touched any switch, so the row could
+     * never again say "no opinion" about a channel — which silently disabled
+     * every per-type and per-host default for that user, and defeated the
+     * missing-key fallback that lets a new channel ship without a data
+     * migration.
      */
     async save(userId, input) {
       const client = await db();
@@ -80,8 +99,7 @@ export function createPreferenceStore(
         const existing = await client.notificationPreference.findUnique({
           where: { userId_category: { userId, category } },
         });
-        const current = existing ? mergeStoredRow(existing.channels, defaultRow) : defaultRow;
-        const channels = mergeChoices(current, choices);
+        const channels = { ...explicitChoicesOf(existing?.channels), ...choices };
         await client.notificationPreference.upsert({
           where: { userId_category: { userId, category } },
           create: { userId, category, channels },
@@ -90,14 +108,16 @@ export function createPreferenceStore(
       }
     },
 
-    async enabledChannels(userId, category) {
+    async enabledChannels(userId, category, rules) {
       const client = await db();
       const row = await client.notificationPreference.findUnique({
         where: { userId_category: { userId, category } },
       });
-      return enabledChannelsOf(
-        row ? mergeStoredRow(row.channels, defaultRow) : defaultRow,
-      );
+      return resolveTypeChannels({
+        stored: row?.channels,
+        categoryDefaults: defaultRow,
+        rules,
+      });
     },
   };
 }