apiVersion: capsule.dev/v0.1
kind: Capsule
name: f4c-realtime-core
version: 0.1.0
type: subsystem
purpose:
  summary: 'Provides core real-time communication logic and generic UI components
    for audio/video calls and participant management using Cloudflare RealtimeKit.
    It encapsulates the integration with the RealtimeKit SDK and offers hooks and
    types for building real-time features.

    '
  owns:
  - RealtimeKit SDK integration and state management
  - Generic participant audio/video UI components (e.g., AudioVisualizer, UserCard)
  - Common types and utilities for real-time interactions
  does_not_own:
  - Specific chat UI components (e.g., TextChatCard)
  - Bot integration logic
  - Room creation and authentication APIs
  - Application-level branding or page layouts
interfaces:
  provides:
  - kind: library
    name: useChatRoom
    description: React hook for managing real-time chat room state and interactions.
  - kind: library
    name: UserInfo
    description: TypeScript interface for participant information.
  - kind: library
    name: Message
    description: TypeScript interface for chat messages.
  requires:
  - kind: http_api
    name: /api/token
    from_capsule: f4c-room-api
    description: Requires an authentication token from the room API to join a meeting.
  - kind: env
    name: NEXT_PUBLIC_WORKER_URL
    description: URL for the Cloudflare Worker, used by GET_WORKER_URL utility.
dependencies:
  capsules:
  - name: f4c-room-api
    version: '>=0.1.0'
agent:
  summary_for_ai: 'This capsule handles all RealtimeKit client-side interactions.
    Agents should focus on enhancing real-time features, improving audio/video quality,
    or extending participant UI. Ensure adherence to RealtimeKit API changes and maintain
    generic component design.

    '
  avoid:
  - Adding project-specific branding or hardcoded strings.
  - Introducing direct dependencies on other application-specific frontend capsules.
verification:
  invariants:
  - The `useChatRoom` hook must correctly manage RealtimeKit meeting state.
  - UserCard and AudioVisualizer components must remain generic and only depend on
    `UserInfo` and `MediaStream` types.
x-reuse:
  notes: 'app/src/common/consts.tsx: `LOCAL_PEER_ID` is a hardcoded string. `GET_WORKER_URL`
    assumes a Cloudflare Worker setup. app/src/common/utils.tsx: `umamiEvent` and
    `gtagEvent` are specific analytics calls that should be removed or replaced with
    a generic analytics interface. The `hashRoom` function is specific to FNV-1a hashing.

    '
x-reconstruct:
  install: install.json