# OpenSpec Change: enterprise-react-iphone

- **Change ID**: enterprise-react-iphone
- **Package**: `@suaveplan/react-iphone`
- **Category**: react
- **Target path**: `react/ui/react-iphone`
- **Status**: PROPOSED
- **Date**: 2026-04-24
- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/react-iphone.md`

---

## Summary

Deliver `@suaveplan/react-iphone` on genesis from scratch at enterprise quality. A React iPhone-simulator SDK for WebRTC voice/video calling: on-device UI screens (`IncomingCallScreen`, `OutgoingCallScreen`, `ActiveCallScreen`, `EndedCallScreen`), video containers, call controls, plus the service layer (`CallManager`, `HookManager`, `SignalingClient`, `SignalingChannelAdapter`, `WebRTCProvider`), and hooks (`useCallManager`, `useCallTimer`). Genesis re-enables the commented-out enhanced features (`CallManagerEnhanced`, `CallManagerWebRTC`, `PhoneStateSerializer`, `ServerStateManager`), fills the hardcoded TODO stubs, adds Storybook stories for every screen, and reaches 100% test coverage.

---

## Current-state audit (genesis)

Package does not exist on genesis — fresh build.

---

## Available workspace deps on genesis

| Package | Role |
|---|---|
| `@suaveplan/error` (`workspace:^`) | `CallError` base class |
| `@suaveplan/events` (`workspace:^`) | Event bus for call state changes |
| `@suaveplan/logger` (`workspace:^`) | Structured call logs |
| `@suaveplan/react-translate` (`workspace:^`) | i18n |
| `@suaveplan/react-ui` (`workspace:^`) | UI primitives |
| `zod` (`catalog:forms`) | Call config schemas |
| `@opentelemetry/api` (`catalog:observability`) | Call lifecycle spans |

External: `tslib catalog:build`. React 18 peer.

---

## Preserved public API surface

### Components

`CallButton`, call-state icons, `ActiveCallScreen`, `EndedCallScreen`, `IncomingCallScreen`, `OutgoingCallScreen`, `AudioOnlyContainer`, `CallVideoContainer`, `VideoStreamRenderer`

### Hooks

`useCallManager`, `useCallTimer`

### Services (all enabled — no commented exports)

`CallManager`, `CallManagerEnhanced`, `CallManagerWebRTC`, `HookManager`, `HookExecutionMode`, `SignalingChannelAdapter`, `SignalingClient`, `WebRTCProvider`, `PhoneStateSerializer`, `ServerStateManager`

---

## New additions for genesis

1. **Re-enable enhanced services** — `CallManagerEnhanced`, `CallManagerWebRTC`, `PhoneStateSerializer`, `ServerStateManager` all exported and fully implemented (no TODO stubs).
2. **`CallError`** — codes: `CALL_SIGNALING_FAILED`, `CALL_WEBRTC_FAILED`, `CALL_MANAGER_NOT_INITIALIZED`.
3. **OTel call lifecycle spans** — `call.incoming`, `call.outgoing`, `call.connected`, `call.ended`.
4. **Storybook** — every screen component with default + loading + error + playground stories.
5. **Playwright E2E** — mock WebRTC + signaling; verify call state transitions render correct screens.

---

## File layout

```text
react/ui/react-iphone/
  package.json
  tsconfig.json
  vitest.config.ts
  src/
    index.ts
    components/
      common/ (CallButton, icons)
      screens/ (ActiveCallScreen, EndedCallScreen, IncomingCallScreen, OutgoingCallScreen)
      video/ (VideoStreamRenderer, AudioOnlyContainer, CallVideoContainer)
    hooks/
      use-call-manager/ use-call-timer/
    services/
      call-manager/ call-manager-enhanced/
      call-manager-webrtc/ hook-manager/
      phone-state-serializer/ server-state-manager/
      signaling-channel-adapter/ signaling-client/
      webrtc-provider/
    types/
  e2e/
    call-flow.spec.ts
```