`@prox-os/activity`

What is @prox-os/activity?

@prox-os/activity is the OS-native activity timeline package for Prox OS. It defines cross-domain activity event contracts, timeline/feed primitives, event grouping, filters, digests, summaries, detail panels, related resources, mock data, and adapter examples.

Activity answers: who did what, when, to which app, workspace, file, AI run, security review, command, search result, notification, or collaboration thread?

Why Prox OS Needs Activity Primitives

Prox OS is a browser-based OS shell, not a single page app. Apps, workspaces, files, AI agents, security surfaces, notifications, search results, and collaboration objects all need a shared way to explain recent history without owning a backend event store.

Activity provides the shared foreground timeline layer for app context, workspace dashboards, resource history, developer tooling, Founder Suite workflows, and future community or creator spaces.

Package Scope

• Activity actor, target, object, event, feed, group, digest, stats, filter, query, action ref, related resource, visibility, sensitivity, and redaction contracts.
• Helpers for labels, filtering, sorting, grouping, digest generation, relative time, summaries, stats, related resources, redaction, and action refs.
• Adapter examples for actions, command, app manifests, workspace events, files, search, notifications, collaboration, AI UI, security UI, developer tooling, and generic resources.
• React primitives for activity icons, actor avatars, badges, items, lists, groups, timelines, feed panels, filters, scope pickers, digests, summaries, stats, detail panels, related resources, and states.
• Mock data for system, workspace, file, search, notification, collaboration, AI, security, developer, Founder Suite, and community activity.

Non-goals

• No real event store, event sourcing backend, or persistence.
• No analytics, telemetry, product tracking, or vendor SDKs.
• No PostHog, Segment, Amplitude, Sentry, Datadog, Logflare, queue, stream, or realtime provider integration.
• No WebSocket, SSE, or subscription runtime.
• No real notification delivery.
• No security audit compliance backend.
• No comments, reviews, file manager, search engine, AI runtime, workspace backend, command palette, or OS routing implementation.

Activity vs Notifications

Notifications are attention surfaces: badges, toasts, center rows, preferences, and delivery decisions.

Activity is a history and context surface: timeline items, related resources, digests, detail panels, and app or workspace context. A notification can become an activity event, but Activity does not own notification delivery or user attention policy.

Activity vs Security Audit

Security audit is a high-trust security/backend concern. It may require immutability, retention, compliance controls, and policy review.

Activity can display security-related events as product context, but it is not an audit backend and must not claim compliance guarantees.

Core Concepts

• Actor: user, guest, team, agent, app, integration, or system that caused an event.
• Target: app, workspace, file, AI session, notification, thread, review, security event, search query, developer tool, or external URL being acted on.
• Object: optional changed object such as an action, artifact, setting, permission, message, or integration.
• Activity event: normalized event with kind, verb, status, importance, source, tags, actions, related resources, visibility, sensitivity, and redaction state.
• Related resources: links to files, threads, reviews, AI artifacts, security reviews, notifications, search results, and workspace projects.
• Feed: scoped event collection for all, personal, workspace, app, resource, file, AI, security, collaboration, developer, or community views.
• Group: date, kind, actor, target, workspace, source, or importance bucket.
• Digest: generated highlight collection for daily, weekly, hourly, or custom summaries.
• Stats: event counts, actor counts, workspace/app counts, failed counts, and kind/verb breakdowns.

Core API

• Types: OsActivityActor, OsActivityTarget, OsActivityObject, OsActivityActionRef, OsActivityRelatedResource, OsActivityEvent, OsActivityFeed, OsActivityGroup, OsActivityDigest, OsActivityStats, OsActivityFilter, OsActivityQuery, OsActivityUiEvent.
• Helpers: getActivityKindLabel, getActivityVerbLabel, createActivityEvent, filterActivityEvents, sortActivityEvents, groupActivityEvents, createActivityDigest, summarizeActivityEvents, getActivityStats, redactActivityEvent, createActivityActionRefs.
• Components: OsActivityIcon, OsActivityActorAvatar, OsActivityKindBadge, OsActivityStatusBadge, OsActivityImportanceBadge, OsActivityItem, OsActivityList, OsActivityGroupView, OsActivityTimeline, OsActivityFeedPanel, OsActivityFilterTabs, OsActivityScopePicker, OsActivitySourceFilter, OsActivityDigestCard, OsActivitySummaryCard, OsActivityStatsGrid, OsActivityDetailPanel, OsActivityRelatedResources, OsActivityEmptyState, OsActivityLoadingState, OsActivityErrorState.

OsActivityGroup is the event group type. The React component is exported as OsActivityGroupView to keep the type/value names unambiguous across package exports.

React Primitives

The React primitives are intentionally controlled and runtime-agnostic. They render the supplied activity objects and call onOpen, onAction, onRelatedResourceOpen, or query callbacks. They do not fetch, persist, track, or stream data.

Mock Data

The package exports mock actors, targets, events, feeds, groups, digests, stats, Founder Suite activity, developer activity, and community activity. Examples cover OS startup, app openings, workspace switching, member and project updates, file sharing/export/sync conflicts, search, notification digests, comments, reviews, AI runs, AI approvals, security sessions, public link warnings, Storybook/typecheck events, package initialization, and creator app publishing.

Storybook Examples

Storybook stories live under apps/ui-workshop/src/stories/activity:

• Activity / Overview
• Activity / Items
• Activity / Timeline
• Activity / Feed Panel
• Activity / Filters & Groups
• Activity / Digest Summary Stats
• Activity / Detail & Related Resources
• Activity / Workspace File AI Activity
• Activity / Collaboration Notification Security Activity
• Activity / Developer Founder Community Activity
• Activity / Cross Package Adapters

Integrations

• @prox-os/actions: action requested, completed, failed, and retry metadata.
• @prox-os/command: command runs and command-open events.
• @prox-os/files: file opened, uploaded, exported, shared, deleted, restored, transfer failure, and sync conflict events.
• @prox-os/search: query submitted, result opened, saved search, and future activity indexing handoff.
• @prox-os/notifications: notification opened, marked read, action clicked, and digest generated events.
• @prox-os/collaboration: comments, mentions, thread resolution, review request, approval, rejection, and sharing events.
• @prox-os/ai-ui: AI message, run, tool call, approval, artifact, and context events.
• @prox-os/security-ui: security events, audit rows, access reviews, sessions, tokens, public link warnings, and restricted activity summaries.
• @prox-os/workspace-ui: workspace switch, member invite, role change, project milestone, integration status, and resource open events.

Phase 1

• TypeScript contracts.
• Mock activity actors, targets, events, feeds, groups, digests, and stats.
• Timeline, feed, digest, detail, summary, stats, filters, and state UI primitives.
• Helpers and cross-package adapters.
• Storybook examples and docs.
• No real event store, analytics, realtime streaming, or audit persistence.

Phase 2+

• Provider boundary: OsActivityProvider and OsActivityFeedProvider.
• Mock/local state provider, saved filters, redaction view model, digest generator, and search indexing adapter.
• OS runtime integration: activity center, app/window/resource context, command actions, workspace dashboard feeds, notification/security/search/AI/files/ collaboration handoff.
• Backend event store and realtime adapters.
• Community and creator activity surfaces with public/private boundaries.

Acceptance Checklist

• Workspace package is recognized as @prox-os/activity.
• Public entry exports types, helpers, adapters, mock data, and components.
• Components render in UI Workshop Storybook.
• Docs describe Activity versus Notifications and Security Audit.
• No deep import from apps/os-shell.
• No analytics, event store, audit backend, realtime, queue, or telemetry SDK.