kybik44 · April 24, 2026 13:17
diff --git a/CALL-REFACTOR-PLAN.md b/CALL-REFACTOR-PLAN.md
diff --git a/media-manager.ts b/media-manager.ts
 import type { CallType } from './call-state';

 export type CallMediaOptions = {
  type: CallType;
  audioEnabled?: boolean;
  videoEnabled?: boolean;
 };

 export async function getCallMediaStream(options: CallMediaOptions) {
  if (typeof navigator === 'undefined' || !navigator.mediaDevices?.getUserMedia) {
    throw new Error('WebRTC media capture is unavailable in this environment.');
  }

  const constraints: MediaStreamConstraints = {
    audio: options.audioEnabled ?? true,
    video: options.type === 'video' ? (options.videoEnabled ?? true) : false,
  };

  return navigator.mediaDevices.getUserMedia(constraints);
 }

 export function stopMediaStream(stream: MediaStream | null | undefined) {
  if (!stream) return;
  for (const track of stream.getTracks()) track.stop();
 }
diff --git a/nf-call.service.ts b/nf-call.service.ts
 // Call Service — upper layer
 // Business logic. Owns CallState, media control, participants, audio routing.
 // Uses RTCService for all WebRTC operations. Never touches SDP or ICE directly.
 // This is what WebRTCPipeline.ts becomes after refactoring.

 import { createSignal, type Accessor } from 'solid-js';
 import type {
  CallState,
  CallParticipant,
  CallStats,
  ConnectParams,
  SubscribeParams,
 } from './nf-call.types';
 import type { RTCService } from './nf-rtc.service';

 // Extracted classes (new):
 // import { CombinedAudioPlayback } from './CombinedAudioPlayback';
 // import { ParticipantManager } from './ParticipantManager';

 export class CallService {

  // ── State (read-only signals) ──────────────────────────────

  readonly callState: Accessor<CallState>;
  readonly participants: Accessor<CallParticipant[]>;
  readonly stats: Accessor<CallStats | null>;

  readonly isCameraEnabled: Accessor<boolean>;
  readonly isMicEnabled: Accessor<boolean>;
  readonly isGuestMuted: Accessor<boolean>;
  readonly localPreviewStream: Accessor<MediaStream | null>;

  // ── RTC layer (injected) ───────────────────────────────────

  private rtc: RTCService;

  // ── Private state ──────────────────────────────────────────

  // private audioPlayback: CombinedAudioPlayback;
  // private participantManager: ParticipantManager;
  private cameraStream: MediaStream | undefined;
  private micStream: MediaStream | undefined;
  private hasPublished = false;

  constructor(rtc: RTCService) {
    this.rtc = rtc;

    // Signals
    const [callState, setCallState] = createSignal<CallState>({ status: 'idle' });
    const [stats, setStats] = createSignal<CallStats | null>(null);
    const [isCameraEnabled, setIsCameraEnabled] = createSignal(false);
    const [isMicEnabled, setIsMicEnabled] = createSignal(false);
    const [isGuestMuted, setIsGuestMuted] = createSignal(false);
    const [localPreviewStream, setLocalPreviewStream] = createSignal<MediaStream | null>(null);

    this.callState = callState;
    this.stats = stats;
    this.isCameraEnabled = isCameraEnabled;
    this.isMicEnabled = isMicEnabled;
    this.isGuestMuted = isGuestMuted;
    this.localPreviewStream = localPreviewStream;
    this.participants = createSignal<CallParticipant[]>([])[0]; // placeholder

    // Wire RTC callbacks → Call layer handlers
    // rtc.onRemoteStream = (stream) => this.onRemoteStreamChanged(stream);
    // rtc.onRemoteVideoActive = () => this.participantManager.setVideoReceiving(true);
    // rtc.onRemoteVideoStale = () => this.handleStaleVideo();
    // rtc.onNetworkStats = (raw) => this.handleStats(raw);
    // rtc.onIceRestartExhausted = () => this.handleIceFailure();
  }

  // ── Call Lifecycle ─────────────────────────────────────────
  // The hook (useCall) calls these in sequence.
  // Connect/publish/subscribe stay separate because the hook
  // does app-level work between each step (API calls, stale-flow
  // detection, conditional camera/mic).

  async connect(params: ConnectParams): Promise<void> {
    // setCallState({ status: 'connecting', sessionID: params.sessionId })
    // Delegate to RTC layer:
    // await this.rtc.createSession({ sessionId, guestId })
    // Now RTCState is 'connected', CallState is 'connecting'
  }

  async disconnect(): Promise<void> {
    // SAFETY: if CallState is 'reconnecting', block.
    // Reconnect owns the teardown/rebuild cycle — disconnect must not race it.
    //
    // 1. this.participantManager.clear()
    // 2. this.audioPlayback.teardown()
    // 3. Stop camera/mic streams
    // 4. await this.rtc.closeSession()
    // 5. Reset all signals
    // setCallState({ status: 'idle' })
  }

  async reconnect(): Promise<void> {
    // setCallState({ status: 'reconnecting', sessionID })
    // SAFETY: reconnect() does its own teardown before rebuilding.
    // disconnect() is blocked while status is 'reconnecting'.
    // If reconnect fails → error, then caller decides: retry or give up.
    //
    // 1. await this.rtc.closeSession()
    // 2. await this.rtc.createSession(lastParams)
    // 3. Re-enable camera/mic if they were on
    // 4. Re-publish, re-subscribe
  }

  // ── Publish / Subscribe ────────────────────────────────────

  async publish(): Promise<void> {
    // setCallState({ status: 'joining', sessionID })
    // Collect current tracks (camera, mic, silent placeholder)
    // await this.rtc.publishTracks(tracks)
    // hasPublished = true
  }

  async subscribe(params?: SubscribeParams): Promise<void> {
    // await this.rtc.subscribeTracks(params)
    // setCallState({ status: 'active', sessionID })
  }

  clearPublisherSubscription(publisherGuestId: string): void {
    // this.rtc.clearPublisherSubscription(publisherGuestId)
  }

  // ── Media Control ──────────────────────────────────────────

  async enableCamera(existingStream?: MediaStream): Promise<void> {
    // 1. Capture camera (or use existingStream)
    // 2. await this.rtc.addTrack(videoTrack)
    // 3. this.rtc.applySendingParams(sender, cameraParams)
    // 4. Set isCameraEnabled(true)
    // 5. Refresh local preview
    // 6. Re-publish if already in a call
  }

  async disableCamera(): Promise<void> {
    // 1. this.rtc.removeTrack(cameraSender)
    // 2. Stop camera stream
    // 3. Set isCameraEnabled(false)
    // 4. Refresh local preview
    // 5. Re-publish to tell SFU to stop forwarding
  }

  async enableMic(existingStream?: MediaStream): Promise<void> {
    // 1. Capture mic (or use existingStream)
    // 2. Enforce echo cancellation / noise suppression
    // 3. await this.rtc.addTrack(audioTrack)
    // 4. Set isMicEnabled(true)
    // 5. Refresh local preview + audio playback
    // 6. Re-publish if needed
  }

  async disableMic(): Promise<void> {
    // 1. Replace mic with silent placeholder (maintain SFU presence)
    //    this.rtc.replaceTrack(micSender, silentTrack)
    // 2. Stop mic stream
    // 3. Set isMicEnabled(false)
    // 4. Refresh local preview + audio playback
  }

  async setCameraQuality(quality: string, fps?: number): Promise<void> {
    // this.rtc.applySendingParams(cameraSender, qualityParams)
  }

  // ── Audio Output ───────────────────────────────────────────

  async setSpeakerEnabled(enabled: boolean): Promise<void> {
    // Mute/unmute the remote audio element
    // this.audioPlayback.refresh(...)
  }

  async setSpeakerDevice(deviceId: string | null): Promise<void> {
    // this.audioPlayback.setSpeakerDevice(deviceId)
  }

  async setCombinedAudioPlayback(enabled: boolean): Promise<void> {
    // this.audioPlayback.setCombinedEnabled(enabled)
    // this.audioPlayback.refresh(...)
  }

  async setCombinedAudioLocalGain(gain: number): Promise<void> {
    // this.audioPlayback.setLocalGain(gain)
  }

  async setCombinedAudioRemoteGain(gain: number): Promise<void> {
    // this.audioPlayback.setRemoteGain(gain)
  }

  // ── Guest Control ──────────────────────────────────────────

  async setGuestMuted(muted: boolean): Promise<void> {
    // Set isGuestMuted signal
    // this.participantManager.applyGuestMuteState(muted)
  }

  // ── Internal: Coordination ─────────────────────────────────
  // These stay here because they coordinate across extracted classes.

  private onRemoteStreamChanged(stream: MediaStream | null): void {
    // Coordinates BOTH extracted classes:
    // 1. this.audioPlayback.refresh({ remoteStream: stream, ... })
    // 2. this.participantManager.update({ remoteStream: stream, ... })
  }

  private handleStaleVideo(): void {
    // Production-critical self-healing:
    // When StaleVideoDetector fires (no decoded frames for several polls),
    // clear subscription cache and re-subscribe to force SFU to resume.
    // this.subscribe(this.lastSubscribeParams)
  }

  private handleIceFailure(): void {
    // RTCState went to 'failed' → CallState goes to 'error'
    // setCallState({ status: 'error', message: 'Connection lost', previousStatus })
    // Caller (hook) decides: reconnect or disconnect
  }

  private handleStats(raw: unknown): void {
    // Receive raw stats from RTCService
    // Enrich with render diagnostics from participantManager
    // Emit via setStats()
  }

  private refreshLocalPreview(): void {
    // Combine live camera + mic tracks into a preview stream
    // Emit via setLocalPreviewStream()
  }

  private async publishIfNeeded(force: boolean): Promise<void> {
    // Re-publish after mid-call media changes (camera enable/disable).
    // Only runs if already in 'active' or 'joining' state and force=true.
  }
 }
diff --git a/nf-call.types.ts b/nf-call.types.ts
 // ═══════════════════════════════════════════════════════════
 // Call Types — single source of truth for the call system
 // Two independent layers, each with its own state.
 // ═══════════════════════════════════════════════════════════


 // ═══════════════════════════════════════════════════════════
 // RTC Layer — WebRTC connection state
 // Managed by RTCService. Call layer reads but does not write.
 // ═══════════════════════════════════════════════════════════

 export type RTCState =
  | { status: 'new' }                              // no connection yet
  | { status: 'connecting' }                       // ICE/DTLS in progress
  | { status: 'connected' }                        // ICE connected, media can flow
  | { status: 'disconnected' }                     // ICE disconnected, may recover
  | { status: 'failed'; reason: string }           // ICE failed, needs restart
  | { status: 'closed' };                          // peer connection closed

 export type RTCStatus = RTCState['status'];


 // ═══════════════════════════════════════════════════════════
 // Call Layer — call lifecycle state
 // Managed by CallService. Sits on top of RTC layer.
 // ═══════════════════════════════════════════════════════════

 export type CallState =
  | { status: 'idle' }                             // no call
  | { status: 'connecting'; sessionID: string }    // SFU session created, setting up
  | { status: 'joining'; sessionID: string }       // publishing/subscribing tracks
  | { status: 'active'; sessionID: string }        // in call, media flowing
  | { status: 'reconnecting'; sessionID: string }  // recovering from failure
  | { status: 'error'; message: string; previousStatus?: CallStatus };

 export type CallStatus = CallState['status'];


 // ── Media State ──────────────────────────────────────────
 // What devices are active right now. Owned by CallService.

 export type MediaState = {
  isCameraEnabled: boolean;
  isMicEnabled: boolean;
  isGuestMuted: boolean;
  localPreviewStream: MediaStream | null;
 };


 // ── Participants ─────────────────────────────────────────
 // Who is in the call. Separate from CallState.
 //
 // active + 0 participants = host waiting for guest
 // active + 1 participant  = active call
 // active + 0 after having 1 = other side dropped

 export type CallParticipant = {
  id: string;
  name: string;
  isLocal: boolean;
  hasVideo: boolean;
  hasAudio: boolean;
  isEmpty: boolean;           // joined with no media (silent placeholder only)
  video?: VideoSource;
 };

 export type VideoSource =
  | { kind: 'video-frame'; getFrame: () => VideoFrame | undefined }
  | { kind: 'media-element'; getElement: () => HTMLVideoElement | undefined };


 // ── Network Stats ────────────────────────────────────────

 export type CallStats = {
  rttMs?: number;
  packetLoss?: number;
  bitrateKbps?: number;
  status: 'live' | 'unavailable';
 };


 // ── Connect / Subscribe ─────────────────────────────────

 export type ConnectParams = {
  sessionId: string;
  visibleName: string;
  guestId: string;
  cameraQuality?: CameraQuality;
  cameraFrameRate?: number;
 };

 export type SubscribeParams = {
  publisherSessionId?: string;
  trackNames?: string[];
  targets?: SubscribeTarget[];
 };

 export type SubscribeTarget = {
  publisherGuestId: string;
  trackNames: string[];
 };


 // ── Quality ──────────────────────────────────────────────

 export type CameraQuality = 'low' | 'medium' | 'high' | 'hd';
 export type AudioQuality = 'low' | 'standard' | 'high';


 // ═══════════════════════════════════════════════════════════
 // Layer naming (current → refactored)
 //
 // WebRTCPipeline        → CallService         (Call layer — business logic)
 // WebRTCSession         → RTCService          (RTC layer — SDP, signaling, negotiation queue)
 // PeerConnectionManager → (merged into RTCService)
 // MediaCaptureService   → MediaManager        (Media — getUserMedia)
 // RemoteParticipantManager → ParticipantManager
 //
 // All files under src/callapp/
 //   types.ts, CallService.ts, RTCService.ts, CallStateMachine.ts,
 //   CombinedAudioPlayback.ts, ParticipantManager.ts, MediaManager.ts, ...
 // ═══════════════════════════════════════════════════════════
diff --git a/nf-rtc.service.ts b/nf-rtc.service.ts
 // RTC Service — lower layer
 // Owns RTCPeerConnection, SDP negotiation, ICE, signaling.
 // Has its own state (RTCState). CallService reads it but doesn't write it.
 // This is what WebRTCSession.ts + PeerConnectionManager.ts become.

 import { createSignal, type Accessor } from 'solid-js';
 import type { RTCState, SubscribeParams } from './nf-call.types';

 export class RTCService {

  // ── State (read-only) ─────────────────────────────────────

  readonly rtcState: Accessor<RTCState>;

  // ── Callbacks (set by CallService) ────────────────────────

  onRemoteStream: ((stream: MediaStream | null) => void) | null = null;
  onRemoteVideoActive: (() => void) | null = null;
  onRemoteVideoStale: (() => void) | null = null;
  onNetworkStats: ((stats: NetworkStats | null) => void) | null = null;
  onIceRestartExhausted: (() => void) | null = null;

  // ── Private ───────────────────────────────────────────────

  // private peer: RTCPeerConnection | null = null;
  // private callsClient: SFUAdapter | null = null;
  // private negotiationQueue: NegotiationQueue;
  // private staleVideoDetector: StaleVideoDetector;

  constructor() {
    const [rtcState, setRtcState] = createSignal<RTCState>({ status: 'new' });
    this.rtcState = rtcState;
  }

  // ── Connection ────────────────────────────────────────────

  async createSession(params: { sessionId: string; guestId: string }): Promise<void> {
    // setRtcState({ status: 'connecting' })
    // 1. Create SFU adapter (CloudflareCallsClient)
    // 2. Create RTCPeerConnection with ICE callbacks:
    //    - oniceconnectionstatechange → update RTCState
    //    - ontrack → fire onRemoteStream
    // 3. Join SFU session
    // 4. Create silent placeholder track
    // 5. Ensure peer session (initial SDP exchange)
    // setRtcState({ status: 'connected' })
  }

  async closeSession(): Promise<void> {
    // 1. Close peer connection
    // 2. Stop stale video detector
    // setRtcState({ status: 'closed' })
  }

  // ── Publish / Subscribe ───────────────────────────────────
  // All SDP operations go through the negotiation queue.
  // CallService never touches SDP directly.

  async publishTracks(tracks: MediaStreamTrack[]): Promise<void> {
    // Enqueue SDP negotiation:
    // 1. Create offer with tracks
    // 2. SDP surgery (strip inactive m-sections, patch extmap, strip orphaned RTX)
    // 3. Send to SFU
    // 4. Apply answer
  }

  async subscribeTracks(params?: SubscribeParams): Promise<void> {
    // Enqueue SDP negotiation:
    // 1. Request tracks from SFU
    // 2. Apply remote SDP
    // 3. Fire onRemoteStream when tracks arrive
  }

  clearPublisherSubscription(publisherGuestId: string): void {
    // Remove subscription for specific publisher
  }

  // ── Track Management ──────────────────────────────────────

  async addTrack(track: MediaStreamTrack): Promise<RTCRtpSender> {
    // Add track to peer connection via negotiation queue
    return {} as RTCRtpSender; // placeholder
  }

  async replaceTrack(sender: RTCRtpSender, track: MediaStreamTrack | null): Promise<void> {
    // Replace track on existing sender (no renegotiation needed)
  }

  async removeTrack(sender: RTCRtpSender): Promise<void> {
    // Remove track from peer connection
  }

  applySendingParams(sender: RTCRtpSender, params: RTCRtpSendParameters): void {
    // Apply encoding parameters (resolution, framerate, bitrate)
  }

  // ── ICE ───────────────────────────────────────────────────

  async restartIce(): Promise<void> {
    // Trigger ICE restart
    // If exhausted → fire onIceRestartExhausted
  }

  // ── Stats ─────────────────────────────────────────────────

  async getStats(): Promise<RTCStatsReport | null> {
    // Return raw stats from peer connection
    return null;
  }
 }

 // Placeholder — actual type lives in networkStatsBuilder.ts
 type NetworkStats = {
  rttMs?: number;
  packetLoss?: number;
  bitrateKbps?: number;
 };
diff --git a/nf-useCall.ts b/nf-useCall.ts
 // useCall hook — SolidJS
 // Orchestrates CallService + RTCService for the UI.
 // Reads both layers' state independently.

 import { createEffect, onCleanup } from 'solid-js';
 import type { RTCService } from './nf-rtc.service';
 import type { CallService } from './nf-call.service';
 import type { CallState, RTCState } from './nf-call.types';

 export function useCall(callService: CallService, rtcService: RTCService) {

  // ── React to Call layer state ─────────────────────────────

  createEffect(() => {
    const state: CallState = callService.callState();

    switch (state.status) {
      case 'idle':
        // Clear errors, reset UI
        break;

      case 'connecting':
        // Show "connecting to session..."
        break;

      case 'joining':
        // Show progress indicator (publishing/subscribing)
        break;

      case 'active':
        // Active call — start heartbeat, show call UI
        break;

      case 'reconnecting':
        // Show "reconnecting..." notification
        break;

      case 'error':
        // Show error: state.message
        // Offer reconnect button
        break;
    }
  });

  // ── React to RTC layer state (independently) ──────────────

  createEffect(() => {
    const rtc: RTCState = rtcService.rtcState();

    switch (rtc.status) {
      case 'new':
        break;

      case 'connecting':
        // Optional: show ICE progress indicator
        break;

      case 'connected':
        // ICE connected — media can flow
        break;

      case 'disconnected':
        // ICE temporarily lost — may auto-recover
        // Show subtle "connection unstable" indicator
        break;

      case 'failed':
        // ICE failed — rtc.reason has details
        // CallService handles this via onIceRestartExhausted callback
        break;

      case 'closed':
        break;
    }
  });

  // ── Join flow (called by UI on "Join" button) ──────────────
  // The hook sequences these calls with app-level logic between
  // each step. This orchestration stays here, not in CallService,
  // because it depends on sessionStore, backend API, and
  // stale-flow detection.

  async function joinCall(params: {
    sessionId: string;
    guestId: string;
    visibleName: string;
    videoStream?: MediaStream;
    audioStream?: MediaStream;
  }) {
    // 1. Backend API: register with SFU
    // await api.app.JoinCfSfuSession({ sessionId, guestId })

    // 2. Connect (creates RTC session under the hood)
    await callService.connect({
      sessionId: params.sessionId,
      visibleName: params.visibleName,
      guestId: params.guestId,
    });

    // 3. Enable camera (if user wants video)
    if (params.videoStream) {
      await callService.enableCamera(params.videoStream);
    }

    // 4. Enable mic (if user wants audio)
    if (params.audioStream) {
      await callService.enableMic(params.audioStream);
    }

    // 5. Publish local tracks to SFU
    await callService.publish();

    // 6. Start heartbeat
    // startSessionHeartbeat(sessionId, guestId)
  }

  // ── Leave ──────────────────────────────────────────────────

  async function leaveCall() {
    // stopSessionHeartbeat()
    await callService.disconnect();
    // api.app.LeaveSession({ sessionId, guestId })
  }

  // ── Subscribe to remote participants ───────────────────────

  async function subscribeToParticipants(targets: Array<{
    publisherGuestId: string;
    trackNames: string[];
  }>) {
    await callService.subscribe({ targets });
  }

  // ── Reconnect ──────────────────────────────────────────────

  async function reconnect() {
    // Re-join SFU
    // await api.app.JoinCfSfuSession({ sessionId, guestId })
    await callService.reconnect();
  }

  // ── Cleanup on unmount ─────────────────────────────────────

  onCleanup(() => {
    const state = callService.callState();
    if (state.status !== 'idle') {
      callService.disconnect();
    }
  });

  // ── Return ─────────────────────────────────────────────────

  return {
    // State — two independent layers
    callState: callService.callState,
    rtcState: rtcService.rtcState,
    participants: callService.participants,
    stats: callService.stats,
    isCameraEnabled: callService.isCameraEnabled,
    isMicEnabled: callService.isMicEnabled,
    isGuestMuted: callService.isGuestMuted,
    localPreviewStream: callService.localPreviewStream,

    // Actions
    joinCall,
    leaveCall,
    reconnect,
    subscribeToParticipants,

    // Media controls (pass-through)
    enableCamera: (s?: MediaStream) => callService.enableCamera(s),
    disableCamera: () => callService.disableCamera(),
    enableMic: (s?: MediaStream) => callService.enableMic(s),
    disableMic: () => callService.disableMic(),
    setCameraQuality: (q: string, fps?: number) => callService.setCameraQuality(q, fps),

    // Audio output (pass-through)
    setSpeakerEnabled: (e: boolean) => callService.setSpeakerEnabled(e),
    setSpeakerDevice: (d: string | null) => callService.setSpeakerDevice(d),
    setCombinedAudioPlayback: (e: boolean) => callService.setCombinedAudioPlayback(e),

    // Guest control
    setGuestMuted: (m: boolean) => callService.setGuestMuted(m),
  };
 }
	import type { CallType } from './call-state';

	export type CallMediaOptions = {
	type: CallType;
	audioEnabled?: boolean;
	videoEnabled?: boolean;
	};

	export async function getCallMediaStream(options: CallMediaOptions) {
	if (typeof navigator === 'undefined' \|\| !navigator.mediaDevices?.getUserMedia) {
	throw new Error('WebRTC media capture is unavailable in this environment.');
	}

	const constraints: MediaStreamConstraints = {
	audio: options.audioEnabled ?? true,
	video: options.type === 'video' ? (options.videoEnabled ?? true) : false,
	};

	return navigator.mediaDevices.getUserMedia(constraints);
	}

	export function stopMediaStream(stream: MediaStream \| null \| undefined) {
	if (!stream) return;
	for (const track of stream.getTracks()) track.stop();
	}
	// Call Service — upper layer
	// Business logic. Owns CallState, media control, participants, audio routing.
	// Uses RTCService for all WebRTC operations. Never touches SDP or ICE directly.
	// This is what WebRTCPipeline.ts becomes after refactoring.

	import { createSignal, type Accessor } from 'solid-js';
	import type {
	CallState,
	CallParticipant,
	CallStats,
	ConnectParams,
	SubscribeParams,
	} from './nf-call.types';
	import type { RTCService } from './nf-rtc.service';

	// Extracted classes (new):
	// import { CombinedAudioPlayback } from './CombinedAudioPlayback';
	// import { ParticipantManager } from './ParticipantManager';

	export class CallService {

	// ── State (read-only signals) ──────────────────────────────

	readonly callState: Accessor<CallState>;
	readonly participants: Accessor<CallParticipant[]>;
	readonly stats: Accessor<CallStats \| null>;

	readonly isCameraEnabled: Accessor<boolean>;
	readonly isMicEnabled: Accessor<boolean>;
	readonly isGuestMuted: Accessor<boolean>;
	readonly localPreviewStream: Accessor<MediaStream \| null>;

	// ── RTC layer (injected) ───────────────────────────────────

	private rtc: RTCService;

	// ── Private state ──────────────────────────────────────────

	// private audioPlayback: CombinedAudioPlayback;
	// private participantManager: ParticipantManager;
	private cameraStream: MediaStream \| undefined;
	private micStream: MediaStream \| undefined;
	private hasPublished = false;

	constructor(rtc: RTCService) {
	this.rtc = rtc;

	// Signals
	const [callState, setCallState] = createSignal<CallState>({ status: 'idle' });
	const [stats, setStats] = createSignal<CallStats \| null>(null);
	const [isCameraEnabled, setIsCameraEnabled] = createSignal(false);
	const [isMicEnabled, setIsMicEnabled] = createSignal(false);
	const [isGuestMuted, setIsGuestMuted] = createSignal(false);
	const [localPreviewStream, setLocalPreviewStream] = createSignal<MediaStream \| null>(null);

	this.callState = callState;
	this.stats = stats;
	this.isCameraEnabled = isCameraEnabled;
	this.isMicEnabled = isMicEnabled;
	this.isGuestMuted = isGuestMuted;
	this.localPreviewStream = localPreviewStream;
	this.participants = createSignal<CallParticipant[]>([])[0]; // placeholder

	// Wire RTC callbacks → Call layer handlers
	// rtc.onRemoteStream = (stream) => this.onRemoteStreamChanged(stream);
	// rtc.onRemoteVideoActive = () => this.participantManager.setVideoReceiving(true);
	// rtc.onRemoteVideoStale = () => this.handleStaleVideo();
	// rtc.onNetworkStats = (raw) => this.handleStats(raw);
	// rtc.onIceRestartExhausted = () => this.handleIceFailure();
	}

	// ── Call Lifecycle ─────────────────────────────────────────
	// The hook (useCall) calls these in sequence.
	// Connect/publish/subscribe stay separate because the hook
	// does app-level work between each step (API calls, stale-flow
	// detection, conditional camera/mic).

	async connect(params: ConnectParams): Promise<void> {
	// setCallState({ status: 'connecting', sessionID: params.sessionId })
	// Delegate to RTC layer:
	// await this.rtc.createSession({ sessionId, guestId })
	// Now RTCState is 'connected', CallState is 'connecting'
	}

	async disconnect(): Promise<void> {
	// SAFETY: if CallState is 'reconnecting', block.
	// Reconnect owns the teardown/rebuild cycle — disconnect must not race it.
	//
	// 1. this.participantManager.clear()
	// 2. this.audioPlayback.teardown()
	// 3. Stop camera/mic streams
	// 4. await this.rtc.closeSession()
	// 5. Reset all signals
	// setCallState({ status: 'idle' })
	}

	async reconnect(): Promise<void> {
	// setCallState({ status: 'reconnecting', sessionID })
	// SAFETY: reconnect() does its own teardown before rebuilding.
	// disconnect() is blocked while status is 'reconnecting'.
	// If reconnect fails → error, then caller decides: retry or give up.
	//
	// 1. await this.rtc.closeSession()
	// 2. await this.rtc.createSession(lastParams)
	// 3. Re-enable camera/mic if they were on
	// 4. Re-publish, re-subscribe
	}

	// ── Publish / Subscribe ────────────────────────────────────

	async publish(): Promise<void> {
	// setCallState({ status: 'joining', sessionID })
	// Collect current tracks (camera, mic, silent placeholder)
	// await this.rtc.publishTracks(tracks)
	// hasPublished = true
	}

	async subscribe(params?: SubscribeParams): Promise<void> {
	// await this.rtc.subscribeTracks(params)
	// setCallState({ status: 'active', sessionID })
	}

	clearPublisherSubscription(publisherGuestId: string): void {
	// this.rtc.clearPublisherSubscription(publisherGuestId)
	}

	// ── Media Control ──────────────────────────────────────────

	async enableCamera(existingStream?: MediaStream): Promise<void> {
	// 1. Capture camera (or use existingStream)
	// 2. await this.rtc.addTrack(videoTrack)
	// 3. this.rtc.applySendingParams(sender, cameraParams)
	// 4. Set isCameraEnabled(true)
	// 5. Refresh local preview
	// 6. Re-publish if already in a call
	}

	async disableCamera(): Promise<void> {
	// 1. this.rtc.removeTrack(cameraSender)
	// 2. Stop camera stream
	// 3. Set isCameraEnabled(false)
	// 4. Refresh local preview
	// 5. Re-publish to tell SFU to stop forwarding
	}

	async enableMic(existingStream?: MediaStream): Promise<void> {
	// 1. Capture mic (or use existingStream)
	// 2. Enforce echo cancellation / noise suppression
	// 3. await this.rtc.addTrack(audioTrack)
	// 4. Set isMicEnabled(true)
	// 5. Refresh local preview + audio playback
	// 6. Re-publish if needed
	}

	async disableMic(): Promise<void> {
	// 1. Replace mic with silent placeholder (maintain SFU presence)
	// this.rtc.replaceTrack(micSender, silentTrack)
	// 2. Stop mic stream
	// 3. Set isMicEnabled(false)
	// 4. Refresh local preview + audio playback
	}

	async setCameraQuality(quality: string, fps?: number): Promise<void> {
	// this.rtc.applySendingParams(cameraSender, qualityParams)
	}

	// ── Audio Output ───────────────────────────────────────────

	async setSpeakerEnabled(enabled: boolean): Promise<void> {
	// Mute/unmute the remote audio element
	// this.audioPlayback.refresh(...)
	}

	async setSpeakerDevice(deviceId: string \| null): Promise<void> {
	// this.audioPlayback.setSpeakerDevice(deviceId)
	}

	async setCombinedAudioPlayback(enabled: boolean): Promise<void> {
	// this.audioPlayback.setCombinedEnabled(enabled)
	// this.audioPlayback.refresh(...)
	}

	async setCombinedAudioLocalGain(gain: number): Promise<void> {
	// this.audioPlayback.setLocalGain(gain)
	}

	async setCombinedAudioRemoteGain(gain: number): Promise<void> {
	// this.audioPlayback.setRemoteGain(gain)
	}

	// ── Guest Control ──────────────────────────────────────────

	async setGuestMuted(muted: boolean): Promise<void> {
	// Set isGuestMuted signal
	// this.participantManager.applyGuestMuteState(muted)
	}

	// ── Internal: Coordination ─────────────────────────────────
	// These stay here because they coordinate across extracted classes.

	private onRemoteStreamChanged(stream: MediaStream \| null): void {
	// Coordinates BOTH extracted classes:
	// 1. this.audioPlayback.refresh({ remoteStream: stream, ... })
	// 2. this.participantManager.update({ remoteStream: stream, ... })
	}

	private handleStaleVideo(): void {
	// Production-critical self-healing:
	// When StaleVideoDetector fires (no decoded frames for several polls),
	// clear subscription cache and re-subscribe to force SFU to resume.
	// this.subscribe(this.lastSubscribeParams)
	}

	private handleIceFailure(): void {
	// RTCState went to 'failed' → CallState goes to 'error'
	// setCallState({ status: 'error', message: 'Connection lost', previousStatus })
	// Caller (hook) decides: reconnect or disconnect
	}

	private handleStats(raw: unknown): void {
	// Receive raw stats from RTCService
	// Enrich with render diagnostics from participantManager
	// Emit via setStats()
	}

	private refreshLocalPreview(): void {
	// Combine live camera + mic tracks into a preview stream
	// Emit via setLocalPreviewStream()
	}

	private async publishIfNeeded(force: boolean): Promise<void> {
	// Re-publish after mid-call media changes (camera enable/disable).
	// Only runs if already in 'active' or 'joining' state and force=true.
	}
	}
	// ═══════════════════════════════════════════════════════════
	// Call Types — single source of truth for the call system
	// Two independent layers, each with its own state.
	// ═══════════════════════════════════════════════════════════


	// ═══════════════════════════════════════════════════════════
	// RTC Layer — WebRTC connection state
	// Managed by RTCService. Call layer reads but does not write.
	// ═══════════════════════════════════════════════════════════

	export type RTCState =
	\| { status: 'new' } // no connection yet
	\| { status: 'connecting' } // ICE/DTLS in progress
	\| { status: 'connected' } // ICE connected, media can flow
	\| { status: 'disconnected' } // ICE disconnected, may recover
	\| { status: 'failed'; reason: string } // ICE failed, needs restart
	\| { status: 'closed' }; // peer connection closed

	export type RTCStatus = RTCState['status'];


	// ═══════════════════════════════════════════════════════════
	// Call Layer — call lifecycle state
	// Managed by CallService. Sits on top of RTC layer.
	// ═══════════════════════════════════════════════════════════

	export type CallState =
	\| { status: 'idle' } // no call
	\| { status: 'connecting'; sessionID: string } // SFU session created, setting up
	\| { status: 'joining'; sessionID: string } // publishing/subscribing tracks
	\| { status: 'active'; sessionID: string } // in call, media flowing
	\| { status: 'reconnecting'; sessionID: string } // recovering from failure
	\| { status: 'error'; message: string; previousStatus?: CallStatus };

	export type CallStatus = CallState['status'];


	// ── Media State ──────────────────────────────────────────
	// What devices are active right now. Owned by CallService.

	export type MediaState = {
	isCameraEnabled: boolean;
	isMicEnabled: boolean;
	isGuestMuted: boolean;
	localPreviewStream: MediaStream \| null;
	};


	// ── Participants ─────────────────────────────────────────
	// Who is in the call. Separate from CallState.
	//
	// active + 0 participants = host waiting for guest
	// active + 1 participant = active call
	// active + 0 after having 1 = other side dropped

	export type CallParticipant = {
	id: string;
	name: string;
	isLocal: boolean;
	hasVideo: boolean;
	hasAudio: boolean;
	isEmpty: boolean; // joined with no media (silent placeholder only)
	video?: VideoSource;
	};

	export type VideoSource =
	\| { kind: 'video-frame'; getFrame: () => VideoFrame \| undefined }
	\| { kind: 'media-element'; getElement: () => HTMLVideoElement \| undefined };


	// ── Network Stats ────────────────────────────────────────

	export type CallStats = {
	rttMs?: number;
	packetLoss?: number;
	bitrateKbps?: number;
	status: 'live' \| 'unavailable';
	};


	// ── Connect / Subscribe ─────────────────────────────────

	export type ConnectParams = {
	sessionId: string;
	visibleName: string;
	guestId: string;
	cameraQuality?: CameraQuality;
	cameraFrameRate?: number;
	};

	export type SubscribeParams = {
	publisherSessionId?: string;
	trackNames?: string[];
	targets?: SubscribeTarget[];
	};

	export type SubscribeTarget = {
	publisherGuestId: string;
	trackNames: string[];
	};


	// ── Quality ──────────────────────────────────────────────

	export type CameraQuality = 'low' \| 'medium' \| 'high' \| 'hd';
	export type AudioQuality = 'low' \| 'standard' \| 'high';


	// ═══════════════════════════════════════════════════════════
	// Layer naming (current → refactored)
	//
	// WebRTCPipeline → CallService (Call layer — business logic)
	// WebRTCSession → RTCService (RTC layer — SDP, signaling, negotiation queue)
	// PeerConnectionManager → (merged into RTCService)
	// MediaCaptureService → MediaManager (Media — getUserMedia)
	// RemoteParticipantManager → ParticipantManager
	//
	// All files under src/callapp/
	// types.ts, CallService.ts, RTCService.ts, CallStateMachine.ts,
	// CombinedAudioPlayback.ts, ParticipantManager.ts, MediaManager.ts, ...
	// ═══════════════════════════════════════════════════════════
	// RTC Service — lower layer
	// Owns RTCPeerConnection, SDP negotiation, ICE, signaling.
	// Has its own state (RTCState). CallService reads it but doesn't write it.
	// This is what WebRTCSession.ts + PeerConnectionManager.ts become.

	import { createSignal, type Accessor } from 'solid-js';
	import type { RTCState, SubscribeParams } from './nf-call.types';

	export class RTCService {

	// ── State (read-only) ─────────────────────────────────────

	readonly rtcState: Accessor<RTCState>;

	// ── Callbacks (set by CallService) ────────────────────────

	onRemoteStream: ((stream: MediaStream \| null) => void) \| null = null;
	onRemoteVideoActive: (() => void) \| null = null;
	onRemoteVideoStale: (() => void) \| null = null;
	onNetworkStats: ((stats: NetworkStats \| null) => void) \| null = null;
	onIceRestartExhausted: (() => void) \| null = null;

	// ── Private ───────────────────────────────────────────────

	// private peer: RTCPeerConnection \| null = null;
	// private callsClient: SFUAdapter \| null = null;
	// private negotiationQueue: NegotiationQueue;
	// private staleVideoDetector: StaleVideoDetector;

	constructor() {
	const [rtcState, setRtcState] = createSignal<RTCState>({ status: 'new' });
	this.rtcState = rtcState;
	}

	// ── Connection ────────────────────────────────────────────

	async createSession(params: { sessionId: string; guestId: string }): Promise<void> {
	// setRtcState({ status: 'connecting' })
	// 1. Create SFU adapter (CloudflareCallsClient)
	// 2. Create RTCPeerConnection with ICE callbacks:
	// - oniceconnectionstatechange → update RTCState
	// - ontrack → fire onRemoteStream
	// 3. Join SFU session
	// 4. Create silent placeholder track
	// 5. Ensure peer session (initial SDP exchange)
	// setRtcState({ status: 'connected' })
	}

	async closeSession(): Promise<void> {
	// 1. Close peer connection
	// 2. Stop stale video detector
	// setRtcState({ status: 'closed' })
	}

	// ── Publish / Subscribe ───────────────────────────────────
	// All SDP operations go through the negotiation queue.
	// CallService never touches SDP directly.

	async publishTracks(tracks: MediaStreamTrack[]): Promise<void> {
	// Enqueue SDP negotiation:
	// 1. Create offer with tracks
	// 2. SDP surgery (strip inactive m-sections, patch extmap, strip orphaned RTX)
	// 3. Send to SFU
	// 4. Apply answer
	}

	async subscribeTracks(params?: SubscribeParams): Promise<void> {
	// Enqueue SDP negotiation:
	// 1. Request tracks from SFU
	// 2. Apply remote SDP
	// 3. Fire onRemoteStream when tracks arrive
	}

	clearPublisherSubscription(publisherGuestId: string): void {
	// Remove subscription for specific publisher
	}

	// ── Track Management ──────────────────────────────────────

	async addTrack(track: MediaStreamTrack): Promise<RTCRtpSender> {
	// Add track to peer connection via negotiation queue
	return {} as RTCRtpSender; // placeholder
	}

	async replaceTrack(sender: RTCRtpSender, track: MediaStreamTrack \| null): Promise<void> {
	// Replace track on existing sender (no renegotiation needed)
	}

	async removeTrack(sender: RTCRtpSender): Promise<void> {
	// Remove track from peer connection
	}

	applySendingParams(sender: RTCRtpSender, params: RTCRtpSendParameters): void {
	// Apply encoding parameters (resolution, framerate, bitrate)
	}

	// ── ICE ───────────────────────────────────────────────────

	async restartIce(): Promise<void> {
	// Trigger ICE restart
	// If exhausted → fire onIceRestartExhausted
	}

	// ── Stats ─────────────────────────────────────────────────

	async getStats(): Promise<RTCStatsReport \| null> {
	// Return raw stats from peer connection
	return null;
	}
	}

	// Placeholder — actual type lives in networkStatsBuilder.ts
	type NetworkStats = {
	rttMs?: number;
	packetLoss?: number;
	bitrateKbps?: number;
	};
	// useCall hook — SolidJS
	// Orchestrates CallService + RTCService for the UI.
	// Reads both layers' state independently.

	import { createEffect, onCleanup } from 'solid-js';
	import type { RTCService } from './nf-rtc.service';
	import type { CallService } from './nf-call.service';
	import type { CallState, RTCState } from './nf-call.types';

	export function useCall(callService: CallService, rtcService: RTCService) {

	// ── React to Call layer state ─────────────────────────────

	createEffect(() => {
	const state: CallState = callService.callState();

	switch (state.status) {
	case 'idle':
	// Clear errors, reset UI
	break;

	case 'connecting':
	// Show "connecting to session..."
	break;

	case 'joining':
	// Show progress indicator (publishing/subscribing)
	break;

	case 'active':
	// Active call — start heartbeat, show call UI
	break;

	case 'reconnecting':
	// Show "reconnecting..." notification
	break;

	case 'error':
	// Show error: state.message
	// Offer reconnect button
	break;
	}
	});

	// ── React to RTC layer state (independently) ──────────────

	createEffect(() => {
	const rtc: RTCState = rtcService.rtcState();

	switch (rtc.status) {
	case 'new':
	break;

	case 'connecting':
	// Optional: show ICE progress indicator
	break;

	case 'connected':
	// ICE connected — media can flow
	break;

	case 'disconnected':
	// ICE temporarily lost — may auto-recover
	// Show subtle "connection unstable" indicator
	break;

	case 'failed':
	// ICE failed — rtc.reason has details
	// CallService handles this via onIceRestartExhausted callback
	break;

	case 'closed':
	break;
	}
	});

	// ── Join flow (called by UI on "Join" button) ──────────────
	// The hook sequences these calls with app-level logic between
	// each step. This orchestration stays here, not in CallService,
	// because it depends on sessionStore, backend API, and
	// stale-flow detection.

	async function joinCall(params: {
	sessionId: string;
	guestId: string;
	visibleName: string;
	videoStream?: MediaStream;
	audioStream?: MediaStream;
	}) {
	// 1. Backend API: register with SFU
	// await api.app.JoinCfSfuSession({ sessionId, guestId })

	// 2. Connect (creates RTC session under the hood)
	await callService.connect({
	sessionId: params.sessionId,
	visibleName: params.visibleName,
	guestId: params.guestId,
	});

	// 3. Enable camera (if user wants video)
	if (params.videoStream) {
	await callService.enableCamera(params.videoStream);
	}

	// 4. Enable mic (if user wants audio)
	if (params.audioStream) {
	await callService.enableMic(params.audioStream);
	}

	// 5. Publish local tracks to SFU
	await callService.publish();

	// 6. Start heartbeat
	// startSessionHeartbeat(sessionId, guestId)
	}

	// ── Leave ──────────────────────────────────────────────────

	async function leaveCall() {
	// stopSessionHeartbeat()
	await callService.disconnect();
	// api.app.LeaveSession({ sessionId, guestId })
	}

	// ── Subscribe to remote participants ───────────────────────

	async function subscribeToParticipants(targets: Array<{
	publisherGuestId: string;
	trackNames: string[];
	}>) {
	await callService.subscribe({ targets });
	}

	// ── Reconnect ──────────────────────────────────────────────

	async function reconnect() {
	// Re-join SFU
	// await api.app.JoinCfSfuSession({ sessionId, guestId })
	await callService.reconnect();
	}

	// ── Cleanup on unmount ─────────────────────────────────────

	onCleanup(() => {
	const state = callService.callState();
	if (state.status !== 'idle') {
	callService.disconnect();
	}
	});

	// ── Return ─────────────────────────────────────────────────

	return {
	// State — two independent layers
	callState: callService.callState,
	rtcState: rtcService.rtcState,
	participants: callService.participants,
	stats: callService.stats,
	isCameraEnabled: callService.isCameraEnabled,
	isMicEnabled: callService.isMicEnabled,
	isGuestMuted: callService.isGuestMuted,
	localPreviewStream: callService.localPreviewStream,

	// Actions
	joinCall,
	leaveCall,
	reconnect,
	subscribeToParticipants,

	// Media controls (pass-through)
	enableCamera: (s?: MediaStream) => callService.enableCamera(s),
	disableCamera: () => callService.disableCamera(),
	enableMic: (s?: MediaStream) => callService.enableMic(s),
	disableMic: () => callService.disableMic(),
	setCameraQuality: (q: string, fps?: number) => callService.setCameraQuality(q, fps),

	// Audio output (pass-through)
	setSpeakerEnabled: (e: boolean) => callService.setSpeakerEnabled(e),
	setSpeakerDevice: (d: string \| null) => callService.setSpeakerDevice(d),
	setCombinedAudioPlayback: (e: boolean) => callService.setCombinedAudioPlayback(e),

	// Guest control
	setGuestMuted: (m: boolean) => callService.setGuestMuted(m),
	};
	}