@ttt-productions/notification-core 0.15.10 → 0.15.12

package/dist/types.d.ts

@@ -45,9 +45,8 @@ export interface NotificationDoc {
      * unseen. Generic field — no domain knowledge. Always present (initialized
      * to `0` on creation and reset to `0` on dedup-increment) so the unread
      * `count()` aggregation can match it with a `seenAt == 0` equality predicate.
-     * On a shared card it is the members' one shared seen state when the category
-     * declares `sharedSeenState`; otherwise the shared unread indicator is
-     * existence-based and ignores it.
+     * `seenAt` is a personal concept; shared notifications carry it for shape
+     * uniformity but their unread indicator is existence-based and ignores it.
      */
     seenAt: number;
     /**
@@ -94,13 +93,6 @@ export interface NotificationCategoryConfig {
     historyPath: (userId?: string) => string;
     /** 'personal' requires targetUserId, 'shared' = all members see everything */
     audienceType: 'personal' | 'shared';
-    /**
-     * Shared categories only: the members share one seen state, so a card any member marked seen
-     * (`seenAt` set) is seen for every member, and the unread count counts the cards no member has
-     * seen (`seenAt == 0`). Omitted, a shared category's unread indicator is existence-based: every
-     * active card counts. A personal category always counts its recipient's unseen cards.
-     */
-    sharedSeenState?: boolean;
 }
 /**
  * Per-type configuration for a notification type.
@@ -126,7 +118,7 @@ export interface NotificationTypeConfig {
     countCap?: number;
     /** Max latestActorIds array length (default 5) */
     actorCap?: number;
-    /** Icon text (e.g. an emoji) shown on the type's rows; rows of a type without one show the package's bell. */
+    /** Icon/emoji for display (optional) */
     icon?: string;
 }
 /**
@@ -156,25 +148,11 @@ export interface NotificationSystemConfig {
     /** Max delivery attempts before a row dead-letters (default 8). */
     maxDeliveryAttempts?: number;
 }
-/**
- * The cache keys the notification hooks read and refresh under, so an app names them from its
- * own key scope. Each method returns the key for one category and viewer: the active and history
- * lists read beneath theirs (each page size under it) and an archive refreshes everything beneath
- * all three. Omitted, the hooks use their own `['notifications', 'active' | 'history' |
- * 'unread-count', category, userId]` keys.
- */
-export interface NotificationQueryKeys {
-    active: (category: string, userId: string) => readonly unknown[];
-    history: (category: string, userId: string) => readonly unknown[];
-    unreadCount: (category: string, userId: string) => readonly unknown[];
-}
 export interface UseActiveNotificationsOptions {
     config: NotificationSystemConfig;
     userId: string;
     category: string;
     enabled?: boolean;
-    /** The app's cache keys (see {@link NotificationQueryKeys}); the package's own when omitted. */
-    queryKeys?: NotificationQueryKeys;
     pageSize?: number;
     /** Re-read the displayed page every `refetchInterval` ms while mounted (default 30s). */
     refetchInterval?: number;
@@ -199,8 +177,6 @@ export interface UseNotificationHistoryOptions {
     userId: string;
     category: string;
     enabled?: boolean;
-    /** The app's cache keys (see {@link NotificationQueryKeys}); the package's own when omitted. */
-    queryKeys?: NotificationQueryKeys;
     pageSize?: number;
     /** Read-freshness stale time in ms (archived rows are immutable; default 60s). */
     staleTime?: number;
@@ -210,8 +186,6 @@ export interface UseUnreadCountOptions {
     userId: string;
     category: string;
     enabled?: boolean;
-    /** The app's cache keys (see {@link NotificationQueryKeys}); the package's own when omitted. */
-    queryKeys?: NotificationQueryKeys;
     refetchInterval?: number;
     countLimit?: number;
 }
@@ -238,9 +212,6 @@ export interface UseArchiveNotificationOptions {
      * Firestore writes; it only invalidates the read keys on success.
      */
     archiveFn: NotificationArchiveFn;
-    /** The app's cache keys (see {@link NotificationQueryKeys}); the package's own when omitted. */
-    queryKeys?: NotificationQueryKeys;
-    /** Keys to refresh after an archive in place of the category's three keys. */
     invalidateKeys?: readonly unknown[][];
 }
 /**
@@ -317,9 +288,6 @@ export interface UseArchiveAllNotificationsOptions {
      * that never reaches a terminal state — default 120, i.e. ~3 min at the default interval).
      */
     maxPolls?: number;
-    /** The app's cache keys (see {@link NotificationQueryKeys}); the package's own when omitted. */
-    queryKeys?: NotificationQueryKeys;
-    /** Keys to refresh after an archive-all in place of the category's three keys. */
     invalidateKeys?: readonly unknown[][];
 }
 /**
@@ -330,12 +298,8 @@ export interface UseArchiveAllNotificationsOptions {
  * re-archived, so it is absent there).
  */
 export interface NotificationRowActions {
-    /**
-     * Archives this row and resolves the server's answer: `{ archived: false }` when it archived
-     * nothing (the card changed after it was rendered), so the app can say why the row stayed.
-     * Rejects when the archive fails.
-     */
-    archive?: () => Promise<NotificationArchiveResult>;
+    /** Archives this row; rejects when the archive fails. */
+    archive?: () => Promise<void>;
     /**
      * True while this row is archiving, including a category-wide Clear All. After an
      * archive the server confirmed, it stays true until the row leaves the active list.
@@ -353,20 +317,6 @@ export interface NotificationListErrorState {
     retrying: boolean;
     hasRows: boolean;
 }
-/**
- * The words a list shows of its own. Every key is optional; an omitted one keeps the package's
- * English default.
- */
-export interface NotificationListLabels {
-    /** The Clear All control (default "Clear All"). */
-    clearAll: string;
-    /** The Clear All control while its job runs (default "Clearing..."). */
-    clearing: string;
-    /** Shown when a Clear All ended with cards left (default "Some notifications remain — try again."). */
-    clearIncomplete: string;
-    /** The loading spinner's announced label (default "Loading notifications"). */
-    loading: string;
-}
 export interface NotificationListProps {
     config: NotificationSystemConfig;
     userId: string;
@@ -388,8 +338,6 @@ export interface NotificationListProps {
      * it to its status callable / job-doc read.
      */
     getArchiveAllStatusFn: (jobId: string) => Promise<ArchiveAllJobSnapshot>;
-    /** The app's cache keys (see {@link NotificationQueryKeys}); the package's own when omitted. */
-    queryKeys?: NotificationQueryKeys;
     /** Left-aligned title for the active-list header. */
     title?: ReactNode;
     onClearAll?: () => void;
@@ -399,8 +347,6 @@ export interface NotificationListProps {
     staleTime?: number;
     /** Empty-state text, shown only for an answered, empty first page. */
     emptyText?: string;
-    /** The list's own words; any omitted key keeps its English default. */
-    labels?: Partial<NotificationListLabels>;
     /** The failed-read state, shown before (never instead of) the pager. Copy is the app's. */
     renderError: (state: NotificationListErrorState) => ReactNode;
     /**
@@ -420,14 +366,10 @@ export interface NotificationHistoryListProps {
     config: NotificationSystemConfig;
     userId: string;
     category: string;
-    /** The app's cache keys (see {@link NotificationQueryKeys}); the package's own when omitted. */
-    queryKeys?: NotificationQueryKeys;
     pageSize?: number;
     staleTime?: number;
     /** Empty-state text, shown only for an answered, empty first page. */
     emptyText?: string;
-    /** The list's own words (only `loading` applies here); an omitted key keeps its English default. */
-    labels?: Partial<Pick<NotificationListLabels, 'loading'>>;
     /** The failed-read state, shown before (never instead of) the pager. Copy is the app's. */
     renderError: (state: NotificationListErrorState) => ReactNode;
     /** Left-aligned title for the read-only archived-list header. */
@@ -446,8 +388,6 @@ export interface NotificationUnreadBadgeProps {
     config: NotificationSystemConfig;
     userId: string;
     category: string;
-    /** The app's cache keys (see {@link NotificationQueryKeys}); the package's own when omitted. */
-    queryKeys?: NotificationQueryKeys;
     refetchInterval?: number;
 }
 //# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG","sourcesContent":["/**\n * @ttt-productions/notification-core — Type definitions\n *\n * Two-tier notification system: active (unread) → history (archived).\n * No `isRead` flag — existence in the active collection means unread.\n */\n\n// Type-only import: erased at compile time, so this does not force React into\n// the server-safe main entry's runtime graph (the `react` peer dep stays optional).\nimport type { ReactNode } from 'react';\n\n// ============================================================================\n// DOCUMENT TYPES\n// ============================================================================\n\n/**\n * Active notification document stored in Firestore.\n * Same shape for both user and admin collections.\n */\nexport interface NotificationDoc {\n  /** Firestore doc ID */\n  id: string;\n  /** Notification type (e.g. 'content_report', 'entity_invite') */\n  type: string;\n  /** Dedup key (e.g. 'report_entityXYZ') — same key = same notification */\n  dedupKey: string;\n  /** Category: 'user' | 'admin' (extensible) */\n  category: string;\n\n  // Targeting\n  /** userId for 'user' category, null for 'admin' (shared) */\n  targetUserId: string | null;\n\n  // Display\n  /** Notification title */\n  title: string;\n  /** Notification body */\n  message: string;\n\n  // Dedup aggregation\n  /** Incremented on duplicates */\n  count: number;\n  /**\n   * Last N actor user IDs (capped). Identity is stored id-only — display names\n   * are resolved at read time by the consuming app (e.g. from publicUsers), so\n   * they never drift in the persisted doc.\n   */\n  latestActorIds: string[];\n\n  // Navigation\n  /**\n   * Route path when clicked (e.g. '/admin' or '/entities/abc'). ABSENT when the\n   * type declares no `defaultTargetPath` — a linkless, informational-only\n   * notification (the consumer renders no \"go to\" affordance for it).\n   */\n  targetPath?: string;\n  /** Type-specific metadata (e.g. { entityId, reason }) */\n  metadata: Record<string, unknown>;\n\n  // Seen state (personal notifications)\n  /**\n   * Epoch ms the recipient last marked this notification seen, or `0` when\n   * unseen. Generic field — no domain knowledge. Always present (initialized\n   * to `0` on creation and reset to `0` on dedup-increment) so the unread\n   * `count()` aggregation can match it with a `seenAt == 0` equality predicate.\n   * On a shared card it is the members' one shared seen state when the category\n   * declares `sharedSeenState`; otherwise the shared unread indicator is\n   * existence-based and ignores it.\n   */\n  seenAt: number;\n\n  /**\n   * Opaque per-generation token (uuid), minted FRESH whenever the active doc is\n   * created or materially re-lit. The SEEN/ARCHIVE precondition compares against\n   * THIS, not a restartable integer: the active doc id is deterministic, so a\n   * delete+recreate would restart an integer and let a stale tab's \"version 1\"\n   * match a different card it never saw (ABA). An opaque token cannot repeat.\n   * Optional on the legacy active doc shape; the ledger materializer always sets it.\n   */\n  activityGeneration?: string;\n  /** The `activityGeneration` observed at the time `seenAt` was last set. */\n  seenAtGeneration?: string;\n\n  // Timestamps (epoch ms)\n  /** First occurrence */\n  createdAt: number;\n  /** Latest occurrence */\n  updatedAt: number;\n}\n\n// Archived history docs are persisted as an untyped wrapper by the server archive\n// helper (server/observed-generation.ts) — `archivedSnapshot` (the full active doc)\n// plus archive metadata + a native-TTL `expireAt` Timestamp. There is no consumer-\n// facing TS type for that shape; the canonical registry schema lives in the\n// consuming app's core package (doc-schemas/notifications.ts → NotificationHistoryDocSchema).\n\n/**\n * Pending notification — queue item for the batch processor.\n */\nexport interface PendingNotification {\n  id: string;\n  /** Notification type */\n  type: string;\n  /** Target category */\n  category: string;\n  /** Target userId (null for admin/shared) */\n  targetUserId: string | null;\n  /** Who triggered this (id-only; display name resolved at read time) */\n  actorId: string;\n  /** Type-specific data for building the notification */\n  metadata: Record<string, unknown>;\n  /** Epoch ms */\n  createdAt: number;\n}\n\n// ============================================================================\n// CONFIGURATION TYPES\n// ============================================================================\n\n/**\n * Per-category configuration (user vs admin).\n */\nexport interface NotificationCategoryConfig {\n  /** Firestore collection path for active notifications */\n  activePath: string;\n  /** Function that returns the history collection path */\n  historyPath: (userId?: string) => string;\n  /** 'personal' requires targetUserId, 'shared' = all members see everything */\n  audienceType: 'personal' | 'shared';\n  /**\n   * Shared categories only: the members share one seen state, so a card any member marked seen\n   * (`seenAt` set) is seen for every member, and the unread count counts the cards no member has\n   * seen (`seenAt == 0`). Omitted, a shared category's unread indicator is existence-based: every\n   * active card counts. A personal category always counts its recipient's unseen cards.\n   */\n  sharedSeenState?: boolean;\n}\n\n/**\n * Per-type configuration for a notification type.\n */\nexport interface NotificationTypeConfig {\n  /** Which category this type belongs to */\n  category: string;\n  /** Delivery mode */\n  delivery: 'realtime' | 'queued';\n  /** Function to build the dedupKey from metadata */\n  dedupKeyPattern: (metadata: Record<string, unknown>) => string;\n  /** Function to build the title from metadata */\n  titlePattern: (metadata: Record<string, unknown>) => string;\n  /** Function to build the message from metadata + count */\n  messagePattern: (metadata: Record<string, unknown>, count: number) => string;\n  /**\n   * Default target path, or function to build from metadata. OMIT to declare a\n   * linkless type: the written doc carries no `targetPath` and the consumer\n   * renders no \"go to\" affordance (clear-only rows).\n   */\n  defaultTargetPath?: string | ((metadata: Record<string, unknown>) => string);\n  /** Max count value (default 5000) */\n  countCap?: number;\n  /** Max latestActorIds array length (default 5) */\n  actorCap?: number;\n  /** Icon text (e.g. an emoji) shown on the type's rows; rows of a type without one show the package's bell. */\n  icon?: string;\n}\n\n/**\n * Full notification system configuration — provided by each app.\n */\nexport interface NotificationSystemConfig {\n  /** Category definitions */\n  categories: Record<string, NotificationCategoryConfig>;\n  /** Type definitions */\n  types: Record<string, NotificationTypeConfig>;\n  /** Batch processor interval in minutes (default 10) */\n  batchIntervalMinutes?: number;\n  /** Firestore collection for pending notifications (default 'pendingNotifications') */\n  pendingCollectionPath?: string;\n  /** Firestore collection for the delivery ledger (default 'notificationDeliveries'). */\n  deliveriesCollectionPath?: string;\n  /**\n   * Factory that converts epoch-ms to the app's Firestore `Timestamp` instance.\n   * REQUIRED for the delivery ledger: Firestore native TTL acts ONLY on\n   * `Timestamp` fields, so `expireAt` must be a real Timestamp (never a number).\n   * The generic package never imports firebase-admin, so the app injects this\n   * (e.g. `(ms) => admin.firestore.Timestamp.fromMillis(ms)`).\n   */\n  timestampFromMillis?: (ms: number) => unknown;\n  /** Delivery-row TTL after materialization, in ms (default 90 days). */\n  deliveryTtlMs?: number;\n  /** Max delivery attempts before a row dead-letters (default 8). */\n  maxDeliveryAttempts?: number;\n}\n\n// ============================================================================\n// HOOK OPTION TYPES\n// ============================================================================\n\n/**\n * The cache keys the notification hooks read and refresh under, so an app names them from its\n * own key scope. Each method returns the key for one category and viewer: the active and history\n * lists read beneath theirs (each page size under it) and an archive refreshes everything beneath\n * all three. Omitted, the hooks use their own `['notifications', 'active' | 'history' |\n * 'unread-count', category, userId]` keys.\n */\nexport interface NotificationQueryKeys {\n  active: (category: string, userId: string) => readonly unknown[];\n  history: (category: string, userId: string) => readonly unknown[];\n  unreadCount: (category: string, userId: string) => readonly unknown[];\n}\n\nexport interface UseActiveNotificationsOptions {\n  config: NotificationSystemConfig;\n  userId: string;\n  category: string;\n  enabled?: boolean;\n  /** The app's cache keys (see {@link NotificationQueryKeys}); the package's own when omitted. */\n  queryKeys?: NotificationQueryKeys;\n  pageSize?: number;\n  /** Re-read the displayed page every `refetchInterval` ms while mounted (default 30s). */\n  refetchInterval?: number;\n  /** How long a read page counts as fresh, in ms (default 30s). */\n  staleTime?: number;\n}\n\n/**\n * A flattened archived-history item for the read surface. The history doc is a\n * wrapper (`archivedSnapshot` + archive metadata + TTL); this shape lifts the\n * snapshot's display fields to the top level so the history list renders exactly\n * like the active list, plus `archivedAt` for ordering/display and\n * `archiveOccurrenceId` as the stable React key.\n */\nexport interface NotificationHistoryItem extends NotificationDoc {\n  /** The history doc id (stable key — the `archiveOccurrenceId`). */\n  archiveOccurrenceId: string;\n  /** Epoch ms the notification was archived (history docs order by this). */\n  archivedAt: number;\n}\n\nexport interface UseNotificationHistoryOptions {\n  config: NotificationSystemConfig;\n  userId: string;\n  category: string;\n  enabled?: boolean;\n  /** The app's cache keys (see {@link NotificationQueryKeys}); the package's own when omitted. */\n  queryKeys?: NotificationQueryKeys;\n  pageSize?: number;\n  /** Read-freshness stale time in ms (archived rows are immutable; default 60s). */\n  staleTime?: number;\n}\n\nexport interface UseUnreadCountOptions {\n  config: NotificationSystemConfig;\n  userId: string;\n  category: string;\n  enabled?: boolean;\n  /** The app's cache keys (see {@link NotificationQueryKeys}); the package's own when omitted. */\n  queryKeys?: NotificationQueryKeys;\n  refetchInterval?: number;\n  countLimit?: number;\n}\n\n/**\n * What an archive adapter answers: whether the card was archived. `false` means the\n * server archived nothing (for example the card gained new activity after it was\n * rendered); the row stays active and is not shown as clearing.\n */\nexport interface NotificationArchiveResult {\n  archived: boolean;\n}\n\n/**\n * App-supplied adapter that archives one rendered notification (active → history).\n * It receives the row exactly as the list rendered it, so the app can send what it\n * observed (e.g. the row's activity generation). It rejects on failure and resolves\n * whether the card was archived.\n */\nexport type NotificationArchiveFn = (notification: NotificationDoc) => Promise<NotificationArchiveResult>;\n\nexport interface UseArchiveNotificationOptions {\n  userId: string;\n  category: string;\n  /**\n   * Performs the archive through the app's callable. The hook performs no client\n   * Firestore writes; it only invalidates the read keys on success.\n   */\n  archiveFn: NotificationArchiveFn;\n  /** The app's cache keys (see {@link NotificationQueryKeys}); the package's own when omitted. */\n  queryKeys?: NotificationQueryKeys;\n  /** Keys to refresh after an archive in place of the category's three keys. */\n  invalidateKeys?: readonly unknown[][];\n}\n\n// ----------------------------------------------------------------------------\n// Archive-all — server-owned job + thin client status poller\n// ----------------------------------------------------------------------------\n//\n// Archive-all is NOT a browser loop. The client enqueues ONE server-owned\n// archive-all job (scoped to a single notification category/tab), then polls its\n// status until the job reaches a terminal state. All paging + ownership-checked\n// per-card deletion happen server-side in a bounded scheduled/queued worker; the\n// hook never touches Firestore and never chains archive calls. The generic\n// package hardcodes NO callable name — the app injects both adapters below.\n\n/**\n * Terminal + transient states of a server-owned archive-all job, as surfaced to the UI.\n *\n * - `idle`        — nothing enqueued yet (initial / reset state).\n * - `enqueuing`   — the enqueue adapter is in flight (job not yet acknowledged).\n * - `in-progress` — the job is enqueued/running; the worker is still draining the category.\n * - `complete`    — TERMINAL: the worker fully drained the category's active set.\n * - `incomplete`  — TERMINAL: the job stopped without draining everything (e.g. hit its own\n *                   bound / a non-advanceable card). The tray keeps a \"some remain — try again\"\n *                   affordance, mirroring the old loop's incomplete result.\n * - `failed`      — TERMINAL: the enqueue call threw, or the job dead-lettered / reported failure.\n */\nexport type ArchiveAllJobStatus =\n  | 'idle'\n  | 'enqueuing'\n  | 'in-progress'\n  | 'complete'\n  | 'incomplete'\n  | 'failed';\n\n/**\n * Result of the INJECTED enqueue adapter — triggers exactly one server-owned archive-all job for\n * the given category and returns immediately with the job's id (idempotent per user+category+request\n * on the app side). The app wires this to its `httpsCallable(functions, 'enqueueArchiveAll')`\n * (or equivalent); the generic package never names the callable.\n */\nexport interface EnqueueArchiveAllResult {\n  /** Server job id the poller then polls via the status adapter. */\n  jobId: string;\n}\n\n/**\n * Snapshot of a server-owned archive-all job, returned by the INJECTED status-query adapter.\n * The poller maps `state` → {@link ArchiveAllJobStatus} and stops polling on any terminal state.\n * `category` echoes the tab/category the job was enqueued for so the UI can assert per-tab scoping.\n */\nexport interface ArchiveAllJobSnapshot {\n  /** Job lifecycle state as owned by the server worker. */\n  state: 'in-progress' | 'complete' | 'incomplete' | 'failed';\n  /** The notification category/tab this job is scoped to (must match the enqueue category). */\n  category: string;\n  /** Cards archived so far (monotonic); optional progress for the UI. */\n  archived?: number;\n  /** Human-readable failure reason when `state === 'failed'` (optional). */\n  error?: string;\n}\n\n/**\n * Aggregate result the poller resolves with once the job reaches a terminal state.\n * `complete` is the load-bearing completion contract (true ONLY when the whole category was\n * drained), preserved from the old loop so callers gate side effects the same way.\n */\nexport interface ArchiveAllPollResult {\n  status: Extract<ArchiveAllJobStatus, 'complete' | 'incomplete' | 'failed'>;\n  category: string;\n  archived: number;\n  complete: boolean;\n  error?: string;\n}\n\nexport interface UseArchiveAllNotificationsOptions {\n  userId: string;\n  category: string;\n  /**\n   * App-supplied adapter that ENQUEUES one server-owned archive-all job scoped to `category` and\n   * returns its `jobId`. The `category` is passed so the app callable can carry the tab/source into\n   * the job (per-tab scoping is REQUIRED — the worker archives only that category's active cards).\n   * Typically `(category) => enqueueArchiveAll({ category })` over an `httpsCallable`.\n   */\n  enqueueArchiveAllFn: (category: string) => Promise<EnqueueArchiveAllResult>;\n  /**\n   * App-supplied adapter that returns the current {@link ArchiveAllJobSnapshot} for a job id — the\n   * hook polls it until the job reaches a terminal state. Typically\n   * `(jobId) => getArchiveAllStatus({ jobId })` over an `httpsCallable`, or a Firestore read of the\n   * job doc. No client Firestore writes.\n   */\n  getArchiveAllStatusFn: (jobId: string) => Promise<ArchiveAllJobSnapshot>;\n  /** Poll interval in ms while the job is in-progress (default 1500). */\n  pollIntervalMs?: number;\n  /**\n   * Max number of status polls before the poller gives up and resolves `incomplete` (guards a job\n   * that never reaches a terminal state — default 120, i.e. ~3 min at the default interval).\n   */\n  maxPolls?: number;\n  /** The app's cache keys (see {@link NotificationQueryKeys}); the package's own when omitted. */\n  queryKeys?: NotificationQueryKeys;\n  /** Keys to refresh after an archive-all in place of the category's three keys. */\n  invalidateKeys?: readonly unknown[][];\n}\n\n// ============================================================================\n// COMPONENT PROP TYPES\n// ============================================================================\n\n/**\n * Per-row actions the list hands to `renderRowAction`. The row itself is inert\n * — every affordance lives in the controls the consumer\n * renders in the slot. `archive` performs the active→history archive for that\n * row; it is present ONLY on the active list (archived history rows cannot be\n * re-archived, so it is absent there).\n */\nexport interface NotificationRowActions {\n  /**\n   * Archives this row and resolves the server's answer: `{ archived: false }` when it archived\n   * nothing (the card changed after it was rendered), so the app can say why the row stayed.\n   * Rejects when the archive fails.\n   */\n  archive?: () => Promise<NotificationArchiveResult>;\n  /**\n   * True while this row is archiving, including a category-wide Clear All. After an\n   * archive the server confirmed, it stays true until the row leaves the active list.\n   */\n  isArchivePending?: boolean;\n}\n\n/**\n * What a list hands its `renderError` slot when its read failed. `hasRows` is true when\n * rows from an earlier read are still on screen above the slot (a failed refresh);\n * `retry` re-reads the displayed page and `retrying` is that read's pending flag.\n */\nexport interface NotificationListErrorState {\n  error: Error;\n  retry: () => void;\n  retrying: boolean;\n  hasRows: boolean;\n}\n\n/**\n * The words a list shows of its own. Every key is optional; an omitted one keeps the package's\n * English default.\n */\nexport interface NotificationListLabels {\n  /** The Clear All control (default \"Clear All\"). */\n  clearAll: string;\n  /** The Clear All control while its job runs (default \"Clearing...\"). */\n  clearing: string;\n  /** Shown when a Clear All ended with cards left (default \"Some notifications remain — try again.\"). */\n  clearIncomplete: string;\n  /** The loading spinner's announced label (default \"Loading notifications\"). */\n  loading: string;\n}\n\nexport interface NotificationListProps {\n  config: NotificationSystemConfig;\n  userId: string;\n  category: string;\n  /**\n   * Archives one rendered notification. Passed straight through to\n   * `useArchiveNotification`; the app wires it to its callable.\n   */\n  archiveFn: NotificationArchiveFn;\n  /**\n   * Adapter that ENQUEUES one server-owned archive-all job scoped to `category` and returns its\n   * `jobId`. Passed straight through to `useArchiveAllNotifications`; the app wires it to its\n   * enqueue callable. Per-tab scoping: the category flows through to the job.\n   */\n  enqueueArchiveAllFn: (category: string) => Promise<EnqueueArchiveAllResult>;\n  /**\n   * Adapter that returns the current status snapshot for an archive-all `jobId`. Passed straight\n   * through to `useArchiveAllNotifications`, which polls it until the job is terminal; the app wires\n   * it to its status callable / job-doc read.\n   */\n  getArchiveAllStatusFn: (jobId: string) => Promise<ArchiveAllJobSnapshot>;\n  /** The app's cache keys (see {@link NotificationQueryKeys}); the package's own when omitted. */\n  queryKeys?: NotificationQueryKeys;\n  /** Left-aligned title for the active-list header. */\n  title?: ReactNode;\n  onClearAll?: () => void;\n  /** Re-read the displayed page every `refetchInterval` ms while mounted (default 30s). */\n  refetchInterval?: number;\n  /** How long a read page counts as fresh, in ms (default 30s). */\n  staleTime?: number;\n  /** Empty-state text, shown only for an answered, empty first page. */\n  emptyText?: string;\n  /** The list's own words; any omitted key keeps its English default. */\n  labels?: Partial<NotificationListLabels>;\n  /** The failed-read state, shown before (never instead of) the pager. Copy is the app's. */\n  renderError: (state: NotificationListErrorState) => ReactNode;\n  /**\n   * Called with the rows on screen each time the displayed page's answered rows change\n   * (not while a page is loading or failed with nothing shown) — the rows to mark seen.\n   */\n  onRenderedRowsChange?: (rows: readonly NotificationDoc[]) => void;\n  /**\n   * Per-row control slot. The row itself is inert; the consumer renders the row's\n   * controls here — typically an ArrowRight \"go to\" (which may call `actions.archive`\n   * then navigate) plus a clear/archive button (calls `actions.archive`). Omit to render\n   * a row with no controls.\n   */\n  renderRowAction?: (notification: NotificationDoc, actions: NotificationRowActions) => ReactNode;\n}\n\nexport interface NotificationHistoryListProps {\n  config: NotificationSystemConfig;\n  userId: string;\n  category: string;\n  /** The app's cache keys (see {@link NotificationQueryKeys}); the package's own when omitted. */\n  queryKeys?: NotificationQueryKeys;\n  pageSize?: number;\n  staleTime?: number;\n  /** Empty-state text, shown only for an answered, empty first page. */\n  emptyText?: string;\n  /** The list's own words (only `loading` applies here); an omitted key keeps its English default. */\n  labels?: Partial<Pick<NotificationListLabels, 'loading'>>;\n  /** The failed-read state, shown before (never instead of) the pager. Copy is the app's. */\n  renderError: (state: NotificationListErrorState) => ReactNode;\n  /** Left-aligned title for the read-only archived-list header. */\n  title?: ReactNode;\n  /**\n   * Per-row control slot for archived rows. The row is inert; archived rows are\n   * read-only (no re-archive), so `actions.archive` is absent — the consumer\n   * typically renders only an ArrowRight \"go to\". Omit for a row with no controls.\n   */\n  renderRowAction?: (notification: NotificationHistoryItem, actions: NotificationRowActions) => ReactNode;\n}\n\nexport interface NotificationEmptyStateProps {\n  text?: string;\n}\n\nexport interface NotificationUnreadBadgeProps {\n  config: NotificationSystemConfig;\n  userId: string;\n  category: string;\n  /** The app's cache keys (see {@link NotificationQueryKeys}); the package's own when omitted. */\n  queryKeys?: NotificationQueryKeys;\n  refetchInterval?: number;\n}\n"]}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG","sourcesContent":["/**\n * @ttt-productions/notification-core — Type definitions\n *\n * Two-tier notification system: active (unread) → history (archived).\n * No `isRead` flag — existence in the active collection means unread.\n */\n\n// Type-only import: erased at compile time, so this does not force React into\n// the server-safe main entry's runtime graph (the `react` peer dep stays optional).\nimport type { ReactNode } from 'react';\n\n// ============================================================================\n// DOCUMENT TYPES\n// ============================================================================\n\n/**\n * Active notification document stored in Firestore.\n * Same shape for both user and admin collections.\n */\nexport interface NotificationDoc {\n  /** Firestore doc ID */\n  id: string;\n  /** Notification type (e.g. 'content_report', 'entity_invite') */\n  type: string;\n  /** Dedup key (e.g. 'report_entityXYZ') — same key = same notification */\n  dedupKey: string;\n  /** Category: 'user' | 'admin' (extensible) */\n  category: string;\n\n  // Targeting\n  /** userId for 'user' category, null for 'admin' (shared) */\n  targetUserId: string | null;\n\n  // Display\n  /** Notification title */\n  title: string;\n  /** Notification body */\n  message: string;\n\n  // Dedup aggregation\n  /** Incremented on duplicates */\n  count: number;\n  /**\n   * Last N actor user IDs (capped). Identity is stored id-only — display names\n   * are resolved at read time by the consuming app (e.g. from publicUsers), so\n   * they never drift in the persisted doc.\n   */\n  latestActorIds: string[];\n\n  // Navigation\n  /**\n   * Route path when clicked (e.g. '/admin' or '/entities/abc'). ABSENT when the\n   * type declares no `defaultTargetPath` — a linkless, informational-only\n   * notification (the consumer renders no \"go to\" affordance for it).\n   */\n  targetPath?: string;\n  /** Type-specific metadata (e.g. { entityId, reason }) */\n  metadata: Record<string, unknown>;\n\n  // Seen state (personal notifications)\n  /**\n   * Epoch ms the recipient last marked this notification seen, or `0` when\n   * unseen. Generic field — no domain knowledge. Always present (initialized\n   * to `0` on creation and reset to `0` on dedup-increment) so the unread\n   * `count()` aggregation can match it with a `seenAt == 0` equality predicate.\n   * `seenAt` is a personal concept; shared notifications carry it for shape\n   * uniformity but their unread indicator is existence-based and ignores it.\n   */\n  seenAt: number;\n\n  /**\n   * Opaque per-generation token (uuid), minted FRESH whenever the active doc is\n   * created or materially re-lit. The SEEN/ARCHIVE precondition compares against\n   * THIS, not a restartable integer: the active doc id is deterministic, so a\n   * delete+recreate would restart an integer and let a stale tab's \"version 1\"\n   * match a different card it never saw (ABA). An opaque token cannot repeat.\n   * Optional on the legacy active doc shape; the ledger materializer always sets it.\n   */\n  activityGeneration?: string;\n  /** The `activityGeneration` observed at the time `seenAt` was last set. */\n  seenAtGeneration?: string;\n\n  // Timestamps (epoch ms)\n  /** First occurrence */\n  createdAt: number;\n  /** Latest occurrence */\n  updatedAt: number;\n}\n\n// Archived history docs are persisted as an untyped wrapper by the server archive\n// helper (server/observed-generation.ts) — `archivedSnapshot` (the full active doc)\n// plus archive metadata + a native-TTL `expireAt` Timestamp. There is no consumer-\n// facing TS type for that shape; the canonical registry schema lives in the\n// consuming app's core package (doc-schemas/notifications.ts → NotificationHistoryDocSchema).\n\n/**\n * Pending notification — queue item for the batch processor.\n */\nexport interface PendingNotification {\n  id: string;\n  /** Notification type */\n  type: string;\n  /** Target category */\n  category: string;\n  /** Target userId (null for admin/shared) */\n  targetUserId: string | null;\n  /** Who triggered this (id-only; display name resolved at read time) */\n  actorId: string;\n  /** Type-specific data for building the notification */\n  metadata: Record<string, unknown>;\n  /** Epoch ms */\n  createdAt: number;\n}\n\n// ============================================================================\n// CONFIGURATION TYPES\n// ============================================================================\n\n/**\n * Per-category configuration (user vs admin).\n */\nexport interface NotificationCategoryConfig {\n  /** Firestore collection path for active notifications */\n  activePath: string;\n  /** Function that returns the history collection path */\n  historyPath: (userId?: string) => string;\n  /** 'personal' requires targetUserId, 'shared' = all members see everything */\n  audienceType: 'personal' | 'shared';\n}\n\n/**\n * Per-type configuration for a notification type.\n */\nexport interface NotificationTypeConfig {\n  /** Which category this type belongs to */\n  category: string;\n  /** Delivery mode */\n  delivery: 'realtime' | 'queued';\n  /** Function to build the dedupKey from metadata */\n  dedupKeyPattern: (metadata: Record<string, unknown>) => string;\n  /** Function to build the title from metadata */\n  titlePattern: (metadata: Record<string, unknown>) => string;\n  /** Function to build the message from metadata + count */\n  messagePattern: (metadata: Record<string, unknown>, count: number) => string;\n  /**\n   * Default target path, or function to build from metadata. OMIT to declare a\n   * linkless type: the written doc carries no `targetPath` and the consumer\n   * renders no \"go to\" affordance (clear-only rows).\n   */\n  defaultTargetPath?: string | ((metadata: Record<string, unknown>) => string);\n  /** Max count value (default 5000) */\n  countCap?: number;\n  /** Max latestActorIds array length (default 5) */\n  actorCap?: number;\n  /** Icon/emoji for display (optional) */\n  icon?: string;\n}\n\n/**\n * Full notification system configuration — provided by each app.\n */\nexport interface NotificationSystemConfig {\n  /** Category definitions */\n  categories: Record<string, NotificationCategoryConfig>;\n  /** Type definitions */\n  types: Record<string, NotificationTypeConfig>;\n  /** Batch processor interval in minutes (default 10) */\n  batchIntervalMinutes?: number;\n  /** Firestore collection for pending notifications (default 'pendingNotifications') */\n  pendingCollectionPath?: string;\n  /** Firestore collection for the delivery ledger (default 'notificationDeliveries'). */\n  deliveriesCollectionPath?: string;\n  /**\n   * Factory that converts epoch-ms to the app's Firestore `Timestamp` instance.\n   * REQUIRED for the delivery ledger: Firestore native TTL acts ONLY on\n   * `Timestamp` fields, so `expireAt` must be a real Timestamp (never a number).\n   * The generic package never imports firebase-admin, so the app injects this\n   * (e.g. `(ms) => admin.firestore.Timestamp.fromMillis(ms)`).\n   */\n  timestampFromMillis?: (ms: number) => unknown;\n  /** Delivery-row TTL after materialization, in ms (default 90 days). */\n  deliveryTtlMs?: number;\n  /** Max delivery attempts before a row dead-letters (default 8). */\n  maxDeliveryAttempts?: number;\n}\n\n// ============================================================================\n// HOOK OPTION TYPES\n// ============================================================================\n\nexport interface UseActiveNotificationsOptions {\n  config: NotificationSystemConfig;\n  userId: string;\n  category: string;\n  enabled?: boolean;\n  pageSize?: number;\n  /** Re-read the displayed page every `refetchInterval` ms while mounted (default 30s). */\n  refetchInterval?: number;\n  /** How long a read page counts as fresh, in ms (default 30s). */\n  staleTime?: number;\n}\n\n/**\n * A flattened archived-history item for the read surface. The history doc is a\n * wrapper (`archivedSnapshot` + archive metadata + TTL); this shape lifts the\n * snapshot's display fields to the top level so the history list renders exactly\n * like the active list, plus `archivedAt` for ordering/display and\n * `archiveOccurrenceId` as the stable React key.\n */\nexport interface NotificationHistoryItem extends NotificationDoc {\n  /** The history doc id (stable key — the `archiveOccurrenceId`). */\n  archiveOccurrenceId: string;\n  /** Epoch ms the notification was archived (history docs order by this). */\n  archivedAt: number;\n}\n\nexport interface UseNotificationHistoryOptions {\n  config: NotificationSystemConfig;\n  userId: string;\n  category: string;\n  enabled?: boolean;\n  pageSize?: number;\n  /** Read-freshness stale time in ms (archived rows are immutable; default 60s). */\n  staleTime?: number;\n}\n\nexport interface UseUnreadCountOptions {\n  config: NotificationSystemConfig;\n  userId: string;\n  category: string;\n  enabled?: boolean;\n  refetchInterval?: number;\n  countLimit?: number;\n}\n\n/**\n * What an archive adapter answers: whether the card was archived. `false` means the\n * server archived nothing (for example the card gained new activity after it was\n * rendered); the row stays active and is not shown as clearing.\n */\nexport interface NotificationArchiveResult {\n  archived: boolean;\n}\n\n/**\n * App-supplied adapter that archives one rendered notification (active → history).\n * It receives the row exactly as the list rendered it, so the app can send what it\n * observed (e.g. the row's activity generation). It rejects on failure and resolves\n * whether the card was archived.\n */\nexport type NotificationArchiveFn = (notification: NotificationDoc) => Promise<NotificationArchiveResult>;\n\nexport interface UseArchiveNotificationOptions {\n  userId: string;\n  category: string;\n  /**\n   * Performs the archive through the app's callable. The hook performs no client\n   * Firestore writes; it only invalidates the read keys on success.\n   */\n  archiveFn: NotificationArchiveFn;\n  invalidateKeys?: readonly unknown[][];\n}\n\n// ----------------------------------------------------------------------------\n// Archive-all — server-owned job + thin client status poller\n// ----------------------------------------------------------------------------\n//\n// Archive-all is NOT a browser loop. The client enqueues ONE server-owned\n// archive-all job (scoped to a single notification category/tab), then polls its\n// status until the job reaches a terminal state. All paging + ownership-checked\n// per-card deletion happen server-side in a bounded scheduled/queued worker; the\n// hook never touches Firestore and never chains archive calls. The generic\n// package hardcodes NO callable name — the app injects both adapters below.\n\n/**\n * Terminal + transient states of a server-owned archive-all job, as surfaced to the UI.\n *\n * - `idle`        — nothing enqueued yet (initial / reset state).\n * - `enqueuing`   — the enqueue adapter is in flight (job not yet acknowledged).\n * - `in-progress` — the job is enqueued/running; the worker is still draining the category.\n * - `complete`    — TERMINAL: the worker fully drained the category's active set.\n * - `incomplete`  — TERMINAL: the job stopped without draining everything (e.g. hit its own\n *                   bound / a non-advanceable card). The tray keeps a \"some remain — try again\"\n *                   affordance, mirroring the old loop's incomplete result.\n * - `failed`      — TERMINAL: the enqueue call threw, or the job dead-lettered / reported failure.\n */\nexport type ArchiveAllJobStatus =\n  | 'idle'\n  | 'enqueuing'\n  | 'in-progress'\n  | 'complete'\n  | 'incomplete'\n  | 'failed';\n\n/**\n * Result of the INJECTED enqueue adapter — triggers exactly one server-owned archive-all job for\n * the given category and returns immediately with the job's id (idempotent per user+category+request\n * on the app side). The app wires this to its `httpsCallable(functions, 'enqueueArchiveAll')`\n * (or equivalent); the generic package never names the callable.\n */\nexport interface EnqueueArchiveAllResult {\n  /** Server job id the poller then polls via the status adapter. */\n  jobId: string;\n}\n\n/**\n * Snapshot of a server-owned archive-all job, returned by the INJECTED status-query adapter.\n * The poller maps `state` → {@link ArchiveAllJobStatus} and stops polling on any terminal state.\n * `category` echoes the tab/category the job was enqueued for so the UI can assert per-tab scoping.\n */\nexport interface ArchiveAllJobSnapshot {\n  /** Job lifecycle state as owned by the server worker. */\n  state: 'in-progress' | 'complete' | 'incomplete' | 'failed';\n  /** The notification category/tab this job is scoped to (must match the enqueue category). */\n  category: string;\n  /** Cards archived so far (monotonic); optional progress for the UI. */\n  archived?: number;\n  /** Human-readable failure reason when `state === 'failed'` (optional). */\n  error?: string;\n}\n\n/**\n * Aggregate result the poller resolves with once the job reaches a terminal state.\n * `complete` is the load-bearing completion contract (true ONLY when the whole category was\n * drained), preserved from the old loop so callers gate side effects the same way.\n */\nexport interface ArchiveAllPollResult {\n  status: Extract<ArchiveAllJobStatus, 'complete' | 'incomplete' | 'failed'>;\n  category: string;\n  archived: number;\n  complete: boolean;\n  error?: string;\n}\n\nexport interface UseArchiveAllNotificationsOptions {\n  userId: string;\n  category: string;\n  /**\n   * App-supplied adapter that ENQUEUES one server-owned archive-all job scoped to `category` and\n   * returns its `jobId`. The `category` is passed so the app callable can carry the tab/source into\n   * the job (per-tab scoping is REQUIRED — the worker archives only that category's active cards).\n   * Typically `(category) => enqueueArchiveAll({ category })` over an `httpsCallable`.\n   */\n  enqueueArchiveAllFn: (category: string) => Promise<EnqueueArchiveAllResult>;\n  /**\n   * App-supplied adapter that returns the current {@link ArchiveAllJobSnapshot} for a job id — the\n   * hook polls it until the job reaches a terminal state. Typically\n   * `(jobId) => getArchiveAllStatus({ jobId })` over an `httpsCallable`, or a Firestore read of the\n   * job doc. No client Firestore writes.\n   */\n  getArchiveAllStatusFn: (jobId: string) => Promise<ArchiveAllJobSnapshot>;\n  /** Poll interval in ms while the job is in-progress (default 1500). */\n  pollIntervalMs?: number;\n  /**\n   * Max number of status polls before the poller gives up and resolves `incomplete` (guards a job\n   * that never reaches a terminal state — default 120, i.e. ~3 min at the default interval).\n   */\n  maxPolls?: number;\n  invalidateKeys?: readonly unknown[][];\n}\n\n// ============================================================================\n// COMPONENT PROP TYPES\n// ============================================================================\n\n/**\n * Per-row actions the list hands to `renderRowAction`. The row itself is inert\n * — every affordance lives in the controls the consumer\n * renders in the slot. `archive` performs the active→history archive for that\n * row; it is present ONLY on the active list (archived history rows cannot be\n * re-archived, so it is absent there).\n */\nexport interface NotificationRowActions {\n  /** Archives this row; rejects when the archive fails. */\n  archive?: () => Promise<void>;\n  /**\n   * True while this row is archiving, including a category-wide Clear All. After an\n   * archive the server confirmed, it stays true until the row leaves the active list.\n   */\n  isArchivePending?: boolean;\n}\n\n/**\n * What a list hands its `renderError` slot when its read failed. `hasRows` is true when\n * rows from an earlier read are still on screen above the slot (a failed refresh);\n * `retry` re-reads the displayed page and `retrying` is that read's pending flag.\n */\nexport interface NotificationListErrorState {\n  error: Error;\n  retry: () => void;\n  retrying: boolean;\n  hasRows: boolean;\n}\n\nexport interface NotificationListProps {\n  config: NotificationSystemConfig;\n  userId: string;\n  category: string;\n  /**\n   * Archives one rendered notification. Passed straight through to\n   * `useArchiveNotification`; the app wires it to its callable.\n   */\n  archiveFn: NotificationArchiveFn;\n  /**\n   * Adapter that ENQUEUES one server-owned archive-all job scoped to `category` and returns its\n   * `jobId`. Passed straight through to `useArchiveAllNotifications`; the app wires it to its\n   * enqueue callable. Per-tab scoping: the category flows through to the job.\n   */\n  enqueueArchiveAllFn: (category: string) => Promise<EnqueueArchiveAllResult>;\n  /**\n   * Adapter that returns the current status snapshot for an archive-all `jobId`. Passed straight\n   * through to `useArchiveAllNotifications`, which polls it until the job is terminal; the app wires\n   * it to its status callable / job-doc read.\n   */\n  getArchiveAllStatusFn: (jobId: string) => Promise<ArchiveAllJobSnapshot>;\n  /** Left-aligned title for the active-list header. */\n  title?: ReactNode;\n  onClearAll?: () => void;\n  /** Re-read the displayed page every `refetchInterval` ms while mounted (default 30s). */\n  refetchInterval?: number;\n  /** How long a read page counts as fresh, in ms (default 30s). */\n  staleTime?: number;\n  /** Empty-state text, shown only for an answered, empty first page. */\n  emptyText?: string;\n  /** The failed-read state, shown before (never instead of) the pager. Copy is the app's. */\n  renderError: (state: NotificationListErrorState) => ReactNode;\n  /**\n   * Called with the rows on screen each time the displayed page's answered rows change\n   * (not while a page is loading or failed with nothing shown) — the rows to mark seen.\n   */\n  onRenderedRowsChange?: (rows: readonly NotificationDoc[]) => void;\n  /**\n   * Per-row control slot. The row itself is inert; the consumer renders the row's\n   * controls here — typically an ArrowRight \"go to\" (which may call `actions.archive`\n   * then navigate) plus a clear/archive button (calls `actions.archive`). Omit to render\n   * a row with no controls.\n   */\n  renderRowAction?: (notification: NotificationDoc, actions: NotificationRowActions) => ReactNode;\n}\n\nexport interface NotificationHistoryListProps {\n  config: NotificationSystemConfig;\n  userId: string;\n  category: string;\n  pageSize?: number;\n  staleTime?: number;\n  /** Empty-state text, shown only for an answered, empty first page. */\n  emptyText?: string;\n  /** The failed-read state, shown before (never instead of) the pager. Copy is the app's. */\n  renderError: (state: NotificationListErrorState) => ReactNode;\n  /** Left-aligned title for the read-only archived-list header. */\n  title?: ReactNode;\n  /**\n   * Per-row control slot for archived rows. The row is inert; archived rows are\n   * read-only (no re-archive), so `actions.archive` is absent — the consumer\n   * typically renders only an ArrowRight \"go to\". Omit for a row with no controls.\n   */\n  renderRowAction?: (notification: NotificationHistoryItem, actions: NotificationRowActions) => ReactNode;\n}\n\nexport interface NotificationEmptyStateProps {\n  text?: string;\n}\n\nexport interface NotificationUnreadBadgeProps {\n  config: NotificationSystemConfig;\n  userId: string;\n  category: string;\n  refetchInterval?: number;\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ttt-productions/notification-core",
-  "version": "0.15.10",
+  "version": "0.15.12",
   "description": "Shared notification system for TTT Productions apps — active/history two-tier architecture with dedup, batch processing, and themed UI components",
   "repository": {
     "type": "git",
@@ -42,7 +42,7 @@
   },
   "peerDependencies": {
     "@tanstack/react-query": ">=5.0.0",
-    "@ttt-productions/query-core": "^0.14.9",
+    "@ttt-productions/query-core": "^0.14.10",
     "@ttt-productions/ui-core": "^0.11.25",
     "firebase": ">=12.0.0",
     "react": ">=19.0.0",
@@ -70,7 +70,7 @@
   },
   "devDependencies": {
     "@tanstack/react-query": "^5.0.0",
-    "@ttt-productions/query-core": "^0.14.9",
+    "@ttt-productions/query-core": "^0.14.10",
     "@ttt-productions/ui-core": "^0.11.25",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",

package/src/styles/notifications.css

@@ -127,13 +127,11 @@
   align-self: center;
 }
 
-/* The consumer's controls from `renderRowAction`. The slot may shrink beside the row's copy, up
- * to half the row, so long control content (a subject link) clips inside it rather than widening
- * the row; the consumer's node supplies its own visual treatment. */
+/* Sibling action slot next to the archive control — consumer-supplied via
+ * `renderRowAction`. Purely a layout/isolation wrapper; the consumer's node
+ * supplies its own visual treatment. */
 .ntf-item-row-action {
-  flex-shrink: 1;
-  min-width: 0;
-  max-width: 50%;
+  flex-shrink: 0;
   align-self: center;
 }
 

package/dist/react/components/notification-type-icon.d.ts

@@ -1,11 +0,0 @@
-import type { NotificationSystemConfig } from '../../types.js';
-/**
- * A row's type icon: the type's own `icon` text, or a bell drawn in `currentColor`, so the
- * row's icon class colors and sizes it like any other glyph. Decorative — the row's title says
- * what it is.
- */
-export declare function NotificationTypeIcon({ config, type }: {
-    config: NotificationSystemConfig;
-    type: string;
-}): import("react").JSX.Element;
-//# sourceMappingURL=notification-type-icon.d.ts.map

package/dist/react/components/notification-type-icon.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"notification-type-icon.d.ts","sourceRoot":"","sources":["../../../src/react/components/notification-type-icon.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,gBAAgB,CAAC;AAE/D;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE;IAAE,MAAM,EAAE,wBAAwB,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,+BAuBxG"}

package/dist/react/components/notification-type-icon.js

@@ -1,12 +0,0 @@
-'use client';
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-/**
- * A row's type icon: the type's own `icon` text, or a bell drawn in `currentColor`, so the
- * row's icon class colors and sizes it like any other glyph. Decorative — the row's title says
- * what it is.
- */
-export function NotificationTypeIcon({ config, type }) {
-    const icon = config.types[type]?.icon;
-    return (_jsx("div", { className: "ntf-item-icon", "aria-hidden": "true", children: icon ?? (_jsxs("svg", { className: "ntf-item-icon-glyph", xmlns: "http://www.w3.org/2000/svg", width: "16", height: "16", viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: "2", strokeLinecap: "round", strokeLinejoin: "round", children: [_jsx("path", { d: "M6 8a6 6 0 0 1 12 0c0 7 3 9 3 9H3s3-2 3-9" }), _jsx("path", { d: "M10.3 21a1.94 1.94 0 0 0 3.4 0" })] })) }));
-}
-//# sourceMappingURL=notification-type-icon.js.map

package/dist/react/components/notification-type-icon.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"notification-type-icon.js","sourceRoot":"","sources":["../../../src/react/components/notification-type-icon.tsx"],"names":[],"mappings":"AAAA,YAAY,CAAC;;AAIb;;;;GAIG;AACH,MAAM,UAAU,oBAAoB,CAAC,EAAE,MAAM,EAAE,IAAI,EAAsD;IACvG,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC;IACtC,OAAO,CACL,cAAK,SAAS,EAAC,eAAe,iBAAa,MAAM,YAC9C,IAAI,IAAI,CACP,eACE,SAAS,EAAC,qBAAqB,EAC/B,KAAK,EAAC,4BAA4B,EAClC,KAAK,EAAC,IAAI,EACV,MAAM,EAAC,IAAI,EACX,OAAO,EAAC,WAAW,EACnB,IAAI,EAAC,MAAM,EACX,MAAM,EAAC,cAAc,EACrB,WAAW,EAAC,GAAG,EACf,aAAa,EAAC,OAAO,EACrB,cAAc,EAAC,OAAO,aAEtB,eAAM,CAAC,EAAC,2CAA2C,GAAG,EACtD,eAAM,CAAC,EAAC,gCAAgC,GAAG,IACvC,CACP,GACG,CACP,CAAC;AACJ,CAAC","sourcesContent":["'use client';\n\nimport type { NotificationSystemConfig } from '../../types.js';\n\n/**\n * A row's type icon: the type's own `icon` text, or a bell drawn in `currentColor`, so the\n * row's icon class colors and sizes it like any other glyph. Decorative — the row's title says\n * what it is.\n */\nexport function NotificationTypeIcon({ config, type }: { config: NotificationSystemConfig; type: string }) {\n  const icon = config.types[type]?.icon;\n  return (\n    <div className=\"ntf-item-icon\" aria-hidden=\"true\">\n      {icon ?? (\n        <svg\n          className=\"ntf-item-icon-glyph\"\n          xmlns=\"http://www.w3.org/2000/svg\"\n          width=\"16\"\n          height=\"16\"\n          viewBox=\"0 0 24 24\"\n          fill=\"none\"\n          stroke=\"currentColor\"\n          strokeWidth=\"2\"\n          strokeLinecap=\"round\"\n          strokeLinejoin=\"round\"\n        >\n          <path d=\"M6 8a6 6 0 0 1 12 0c0 7 3 9 3 9H3s3-2 3-9\" />\n          <path d=\"M10.3 21a1.94 1.94 0 0 0 3.4 0\" />\n        </svg>\n      )}\n    </div>\n  );\n}\n"]}

package/dist/react/query-keys.d.ts

@@ -1,5 +0,0 @@
-import type { NotificationQueryKeys } from '../types.js';
-export declare function resolveNotificationQueryKeys(queryKeys: NotificationQueryKeys | undefined): NotificationQueryKeys;
-/** The three keys an archive or an archive-all refreshes for one category and viewer. */
-export declare function archiveRefreshKeys(queryKeys: NotificationQueryKeys | undefined, category: string, userId: string): readonly (readonly unknown[])[];
-//# sourceMappingURL=query-keys.d.ts.map

package/dist/react/query-keys.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"query-keys.d.ts","sourceRoot":"","sources":["../../src/react/query-keys.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AASzD,wBAAgB,4BAA4B,CAAC,SAAS,EAAE,qBAAqB,GAAG,SAAS,GAAG,qBAAqB,CAEhH;AAED,yFAAyF;AACzF,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,qBAAqB,GAAG,SAAS,EAC5C,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,GACb,SAAS,CAAC,SAAS,OAAO,EAAE,CAAC,EAAE,CAGjC"}

package/dist/react/query-keys.js

@@ -1,15 +0,0 @@
-/** The keys the hooks use when the app supplies none. */
-const DEFAULT_NOTIFICATION_QUERY_KEYS = {
-    active: (category, userId) => ['notifications', 'active', category, userId],
-    history: (category, userId) => ['notifications', 'history', category, userId],
-    unreadCount: (category, userId) => ['notifications', 'unread-count', category, userId],
-};
-export function resolveNotificationQueryKeys(queryKeys) {
-    return queryKeys ?? DEFAULT_NOTIFICATION_QUERY_KEYS;
-}
-/** The three keys an archive or an archive-all refreshes for one category and viewer. */
-export function archiveRefreshKeys(queryKeys, category, userId) {
-    const keys = resolveNotificationQueryKeys(queryKeys);
-    return [keys.active(category, userId), keys.unreadCount(category, userId), keys.history(category, userId)];
-}
-//# sourceMappingURL=query-keys.js.map

package/dist/react/query-keys.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"query-keys.js","sourceRoot":"","sources":["../../src/react/query-keys.ts"],"names":[],"mappings":"AAEA,yDAAyD;AACzD,MAAM,+BAA+B,GAA0B;IAC7D,MAAM,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,CAAC,CAAC,eAAe,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,CAAC;IAC3E,OAAO,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,CAAC,CAAC,eAAe,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,CAAC;IAC7E,WAAW,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,CAAC,CAAC,eAAe,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,CAAC;CACvF,CAAC;AAEF,MAAM,UAAU,4BAA4B,CAAC,SAA4C;IACvF,OAAO,SAAS,IAAI,+BAA+B,CAAC;AACtD,CAAC;AAED,yFAAyF;AACzF,MAAM,UAAU,kBAAkB,CAChC,SAA4C,EAC5C,QAAgB,EAChB,MAAc;IAEd,MAAM,IAAI,GAAG,4BAA4B,CAAC,SAAS,CAAC,CAAC;IACrD,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,EAAE,IAAI,CAAC,WAAW,CAAC,QAAQ,EAAE,MAAM,CAAC,EAAE,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC,CAAC;AAC7G,CAAC","sourcesContent":["import type { NotificationQueryKeys } from '../types.js';\n\n/** The keys the hooks use when the app supplies none. */\nconst DEFAULT_NOTIFICATION_QUERY_KEYS: NotificationQueryKeys = {\n  active: (category, userId) => ['notifications', 'active', category, userId],\n  history: (category, userId) => ['notifications', 'history', category, userId],\n  unreadCount: (category, userId) => ['notifications', 'unread-count', category, userId],\n};\n\nexport function resolveNotificationQueryKeys(queryKeys: NotificationQueryKeys | undefined): NotificationQueryKeys {\n  return queryKeys ?? DEFAULT_NOTIFICATION_QUERY_KEYS;\n}\n\n/** The three keys an archive or an archive-all refreshes for one category and viewer. */\nexport function archiveRefreshKeys(\n  queryKeys: NotificationQueryKeys | undefined,\n  category: string,\n  userId: string,\n): readonly (readonly unknown[])[] {\n  const keys = resolveNotificationQueryKeys(queryKeys);\n  return [keys.active(category, userId), keys.unreadCount(category, userId), keys.history(category, userId)];\n}\n"]}