Collaboration Package

@prox-os/collaboration is the shared collaboration primitive package for Prox OS apps. It defines participant, presence, comment, thread, mention, sharing, review, approval, and collaboration event contracts, plus React primitives and mock data for Storybook.

It is not a chat app, realtime editing engine, notification center, search index, activity feed, permission system, or backend transport. Apps and runtime layers own persistence, realtime providers, routing, notifications, audit, and execution.

Package Scope

The package provides:

collaboration resource references for apps, windows, documents, media, maps, data tables, charts, files, workflows, AI sessions, workspaces, and system resources;
participant, role, status, and presence contracts;
comment, thread, anchor, mention, reaction, share, review, and event types;
helpers for participant labels, presence labels, mention tokens, thread counts, thread filtering, and lightweight role checks;
adapters that map collaboration events into @prox-os/actions intents;
adapter helpers for editor selections, block anchors, routes, files, and data table cells;
mock data covering OS docs, editor selections, media review, Madrid map places, data table cells, founder workflows, AI collaborators, share states, and approval flows;
React primitives for avatars, presence, comments, threads, mentions, sharing, assignees, review approval, and collaboration panels.

Non-Goals

No Slack or team chat product.
No Notion or Figma clone.
No realtime backend, WebSocket, Yjs server, Liveblocks, Convex, Firebase, Supabase Realtime, or Durable Objects integration in Phase 1.
No editor implementation. Editor comments use anchors, not editor internals.
No action execution. The package emits action intent through @prox-os/actions.
No notification, search, activity, security, files, or workspace management replacement.
No OS Shell private imports.

Core Concepts

Concept	Type	Responsibility
Participant	`OsParticipant`	User, guest, team, agent, or system actor metadata.
Presence	`OsPresenceEntry`	Who is viewing, editing, commenting, reviewing, idle, typing, or presenting.
Resource ref	`OsCollaborationResourceRef`	OS-native resource identity without importing app runtime code.
Comment	`OsComment`	Published, draft, edited, deleted, or resolved comment body.
Thread	`OsCommentThread`	Anchored conversation for a resource, text selection, block, media region, map coordinate, data cell, or chart point.
Mention	`OsMention` component and `getMentionTokens`	Lightweight mention display and parsing helpers.
Share state	`OsShareState`	Visibility, targets, permissions, and current-user share capabilities.
Review request	`OsReviewRequest`	Review status, reviewers, checklist, due date, and related threads.
Event	`OsCollaborationEvent`	UI-level collaboration event emitted to app/runtime layers.

The comment thread component is named OsCommentThreadView to avoid a TypeScript export collision with the OsCommentThread data type.

React Primitives

OsAvatar
OsAvatarGroup
OsPresenceDot
OsPresenceList
OsCollaboratorCard
OsMention
OsMentionList
OsCommentComposer
OsCommentItem
OsCommentThreadView
OsThreadList
OsReviewStatusBadge
OsReviewChecklist
OsApprovalCard
OsSharePanel
OsAssigneePicker
OsCollaborationPanel
OsCollaborationEmptyState

Storybook

Open UI Workshop and browse:

Collaboration / Overview
Collaboration / Presence
Collaboration / Comments
Collaboration / Threads
Collaboration / Mentions
Collaboration / Share Panel
Collaboration / Review Approval
Collaboration / Resource Collaboration
Collaboration / Editor Integration
Collaboration / Actions Integration

The stories use mock data only. Buttons log or emit callbacks; they do not persist, route, notify, approve, or execute backend work.

Package Relationships

Package	Relationship
`@prox-os/actions`	Collaboration actions such as resolve thread, share resource, request review, approve review, and open resource are action intents.
`@prox-os/command`	Future command providers can expose "mentioned me", "unresolved comments", and "open review requests" commands.
`@prox-os/forms`	Comment composers, share invites, and review requests may later use form primitives, but Phase 1 stays lightweight.
`@prox-os/editor`	Editor selections and blocks map to `OsThreadAnchor`; this package does not import editor components.
Future notifications	Mentions, review requests, comment replies, and resolved threads can create notification events.
Future search	Comments, participants, threads, reviews, and activity can become searchable resources.
Future activity	Collaboration events can feed an OS-level activity timeline.
Future security UI	Share states and access review can be displayed with security and audit surfaces.

Phase Roadmap

Phase 1: Contracts, Mock Data, React Primitives

TypeScript contracts.
Mock data.
React primitives.
Storybook examples.
Docs.
Action, editor, and resource adapter examples.
No real backend.

Phase 2: Provider Adapters

Define OsCollaborationProvider.
Add mock and local storage providers.
Evaluate Yjs, Liveblocks, Supabase Realtime, Cloudflare Durable Objects, and local-first sync as adapters.
Add optimistic updates and conflict handling only behind provider boundaries.

Phase 3: OS Runtime Integration

App runtime collaboration context.
Window-level presence.
Workspace-level permissions.
Notification, activity, search, and AI summary integration.

Phase 4: Community And Multi-Home Collaboration

Creator resource collaboration under future public paths.
Public and moderated comments.
App, dataset, document, and community workflow reviews.

Acceptance Checklist

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

Collaboration Package

On this page