Notifications Package

@prox-os/notifications is the shared OS-native notification primitives package for Prox OS apps. It defines notification, source, actor, target, action ref, group, digest, preference, and event contracts, plus React primitives and mock data for UI Workshop.

It is not a push service, delivery backend, email system, SMS system, service worker, notification daemon, activity feed, security dashboard, or global state store. Runtime, apps, and future backend packages own persistence, delivery, realtime subscriptions, browser permissions, routing, and execution.

Package Scope

The package provides:

serializable notification contracts for OS, app, resource, collaboration, mention, comment, review, approval, task, workflow, file, sync, AI, security, workspace, billing, and developer events;
notification source, actor, target, action ref, group, digest, state snapshot, preference, and event types;
helpers for labels, unread and urgent counts, filtering, sorting, grouping, reducers, snoozing, archiving, dismissal, expiration checks, relative time, and preference checks;
adapters that map action results, collaboration events, system events, AI events, security events, and workspace events into notification drafts;
mock data covering system updates, app updates, collaboration mentions, comments, review requests, approvals, AI runs, security warnings, workspace invites, file sync, billing, developer tooling, and digests;
React primitives for badges, bells, icons, priority/status badges, notification items, lists, grouped sections, filter tabs, toasts, toast stacks, notification center, digest cards, preference panels, permission hints, and empty states.

Non-Goals

No browser Notification API permission request.
No Service Worker registration.
No Web Push, email, SMS, webhook, Slack, Discord, or delivery SDK.
No backend queue, retry, cron digest, or notification persistence.
No global OS notification daemon or Zustand store.
No collaboration thread or review ownership. Collaboration objects stay in @prox-os/collaboration.
No action execution. Notifications carry action refs or action intent only.
No activity timeline, search index, security dashboard, or workspace management replacement.
No OS Shell private imports.

Core Concepts

Concept	Type	Responsibility
Notification	`OsNotification`	A single OS-native notification object.
Source	`OsNotificationSource`	OS, app, workspace, resource, integration, agent, or system origin.
Actor	`OsNotificationActor`	User, guest, team, agent, system, or integration that caused the event.
Target	`OsNotificationTarget`	App, window, route, document, thread, review, file, workspace, AI session, security event, billing account, developer tool, or external URL.
Action ref	`OsNotificationActionRef`	Serializable intent for opening, approving, retrying, archiving, or marking read.
Group	`OsNotificationGroup`	Grouped notification section with unread count and highest priority.
Digest	`OsNotificationDigest`	Daily, weekly, hourly, or custom summary.
Preferences	`OsNotificationPreferences`	Channel, delivery mode, quiet hours, muted kinds, and minimum priority intent.
Event	`OsNotificationEvent`	UI-level event emitted to app/runtime layers.

The grouped section component is named OsNotificationGroupView to avoid a TypeScript export collision with the OsNotificationGroup data type.

React Primitives

OsNotificationBadge
OsNotificationBell
OsNotificationPriorityBadge
OsNotificationStatusBadge
OsNotificationIcon
OsNotificationItem
OsNotificationList
OsNotificationGroupView
OsNotificationFilterTabs
OsNotificationToast
OsNotificationToastStack
OsNotificationCenter
OsNotificationDigestCard
OsNotificationPreferencePanel
OsNotificationEmptyState
OsNotificationPermissionHint

Storybook

Open UI Workshop and browse:

Notifications / Overview
Notifications / Badge & Bell
Notifications / Items
Notifications / List
Notifications / Center
Notifications / Toasts
Notifications / Preferences
Notifications / Digest
Notifications / Collaboration Notifications
Notifications / Actions Integration
Notifications / System Security AI

The stories use mock data and controlled callbacks only. They do not persist, request browser permissions, register service workers, deliver email, or execute backend work.

Package Relationships

Package	Relationship
`@prox-os/actions`	Notifications carry action refs or action intents for open target, mark read, archive, approve, retry, and open in OS.
`@prox-os/collaboration`	Mention, comment, review, approval, and resolved-thread events can map to notification drafts.
`@prox-os/command`	Future command providers can expose "unread notifications", "mentioned me", and "open notification center" commands.
`@prox-os/forms`	Preference panels may later use form primitives. Phase 1 keeps the package lightweight.
`@prox-os/editor`	Editor comments, review requests, and AI rewrite completion can create notifications.
Future search	Notification title, body, source, kind, actor, and target can be indexed.
Future activity	Notification events can feed an OS activity timeline without replacing it.
Future security UI	Security notifications can link to access review and audit surfaces.
Future workspace UI	Workspace notification preferences and workspace inboxes can consume these contracts.
Future AI UI	AI run completion, failures, approval requests, and agent comments can use notification objects.

Phase Roadmap

Phase 1: Contracts, Mock Data, React Primitives

TypeScript contracts.
Mock data.
React primitives.
Storybook examples.
Docs.
Action, collaboration, system, AI, security, and workspace adapter examples.
No real backend.
No browser notification permission request.
No Service Worker.

Phase 2: Local State And Provider Boundary

Define OsNotificationProvider.
Add mock and local storage providers.
Add preference persistence adapters.
Add optimistic mark-read, archive, dismiss, and snooze helpers.
Add digest generation helpers.

Phase 3: OS Runtime Integration

OS top bar notification bell.
OS notification center panel.
App, window, resource, and workspace scopes.
Command palette integration.
Activity, search, security, workspace, and AI package integration.

Phase 4: Delivery Infrastructure

Backend notification API.
Cloudflare Queue or Durable Object routing.
Web Push and Service Worker.
Email digest and webhook delivery.
Per-workspace notification rules.

Acceptance Checklist

Package exports contracts, helpers, adapters, mock data, and React primitives.
UI Workshop exposes all core notification stories.
No OS Shell private imports.
No real push, realtime, or delivery backend dependency.
Docs state Phase 1 boundaries and Phase 2+ provider direction.

Notifications Package

On this page