kybik44 · April 24, 2026 11:03
diff --git a/CALL-REFACTOR-PLAN.md b/CALL-REFACTOR-PLAN.md
diff --git a/nf-call.service.ts b/nf-call.service.ts
 // Call Service — Layer 1
 // Business logic layer. Owns CallState, coordinates WebRTC Service + Media Manager.
 // This is what WebRTCPipeline.ts becomes after refactoring.

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

 // These already exist and stay as-is:
 // import { WebRTCSession } from './core/WebRTCSession';
 // import { PeerConnectionManager } from './core/PeerConnectionManager';
 // import { MediaCaptureService } from './core/MediaCaptureService';
 // import { CloudflareCallsClient } from './signaling/CloudflareCallsClient';

 // These are new extracted classes:
 // import { CallStateMachine } from './core/CallStateMachine';
 // import { CombinedAudioPlayback } from './core/CombinedAudioPlayback';
 // import { RemoteParticipantManager } from './core/RemoteParticipantManager';

 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>;

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

  // private stateMachine: CallStateMachine;
  // private audioPlayback: CombinedAudioPlayback;
  // private remoteParticipants: RemoteParticipantManager;
  // private session: WebRTCSession | null = null;
  // private peer: PeerConnectionManager | null = null;
  // private capture: MediaCaptureService | null = null;
  // private callsClient: SFUAdapter | null = null;

  private cameraStream: MediaStream | undefined;
  private micStream: MediaStream | undefined;
  private hasPublished = false;

  constructor() {
    // 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;

    // Extracted classes own their own signals
    // this.stateMachine = new CallStateMachine();
    // this.callState = this.stateMachine.state;
    // this.remoteParticipants = new RemoteParticipantManager();
    // this.participants = this.remoteParticipants.participants;
    // this.audioPlayback = new CombinedAudioPlayback();

    this.participants = createSignal<CallParticipant[]>([])[0]; // placeholder
  }

  // ── Call Lifecycle ─────────────────────────────────────────
  // The hook (useSessionConnection) 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> {
    // this.stateMachine.transition({ status: 'connected', hostID: params.guestId }, 'connect');
    // 1. Create callsClient (CloudflareCallsClient)
    // 2. Create peer (PeerConnectionManager) with callbacks
    // 3. Create session (WebRTCSession) with callbacks:
    //    - onNetworkStats → this.handleStats()
    //    - onRemoteVideoActive → this.remoteParticipants.setVideoReceiving()
    //    - onRemoteVideoStale → this.handleStaleVideo()
    //    - onBeforeNewSubscriptions → this.clearRemoteParticipant()
    // 4. session.connect({ sessionId, guestId })
    // 5. Create silent placeholder
    // 6. Ensure peer session
  }

  async disconnect(): Promise<void> {
    // SAFETY: if status is 'reconnecting', wait for reconnect to finish first.
    // Reconnect owns the teardown/rebuild cycle — disconnect must not race it.
    // if (this.stateMachine.state().status === 'reconnecting') return;
    //
    // this.stateMachine.transition({ status: 'idle' }, 'disconnect');
    // 1. this.clearRemoteParticipant()
    // 2. this.audioPlayback.teardown()
    // 3. Stop camera/mic streams
    // 4. session.disconnect()
    // 5. peer.closeConnection()
    // 6. Reset all state
  }

  async reconnect(): Promise<void> {
    // this.stateMachine.transition({ status: 'reconnecting', sessionID }, 'reconnect');
    // SAFETY: reconnect() does its own teardown before rebuilding.
    // disconnect() is blocked while status is 'reconnecting'.
    // If reconnect fails → transition to 'error', then caller decides:
    //   retry (→ reconnect again) or give up (→ disconnect).
    // Re-run connect() with last params
  }

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

  async publish(): Promise<void> {
    // this.stateMachine.transition({ status: 'joining', sessionID }, 'publish');
    // Delegates to session.publishTracks()
    // On success: hasPublished = true
    // On failure: retry with session recreation
  }

  async subscribe(params?: SubscribeParams): Promise<void> {
    // Delegates to session.subscribeTracks()
    // On success: stateMachine.transition({ status: 'call', sessionID }, 'subscribed')
  }

  clearPublisherSubscription(publisherGuestId: string): void {
    // session.clearPublisherSubscription(publisherGuestId)
  }

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

  async enableCamera(existingStream?: MediaStream): Promise<void> {
    // 1. Ensure peer session
    // 2. Capture camera (or use existingStream)
    // 3. Attach to peer via negotiation queue
    // 4. Apply camera sending params
    // 5. Set isCameraEnabled(true)
    // 6. Refresh local preview
    // 7. Re-publish if already in a call
  }

  async disableCamera(): Promise<void> {
    // 1. Disable camera track on peer
    // 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. Ensure peer session
    // 2. Capture mic (or use existingStream)
    // 3. Enforce echo cancellation / noise suppression
    // 4. Attach to peer via negotiation queue
    // 5. Set isMicEnabled(true)
    // 6. Refresh local preview + audio playback
    // 7. Re-publish if needed
  }

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

  async setCameraQuality(quality: string, fps?: number): Promise<void> {
    // Apply camera sending params to peer (resolution, framerate)
  }

  // ── 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.remoteParticipants.update(...)
  }

  // ── 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.remoteParticipants.update({ remoteStream: stream, ... })
  }

  private clearRemoteParticipant(): void {
    // Coordinates BOTH extracted classes:
    // 1. this.audioPlayback.teardown()
    // 2. this.remoteParticipants.clear()
  }

  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 handleStats(networkStats: NetworkStats | null): void {
    // Receive raw stats from WebRTCSession
    // Enrich with render diagnostics from remoteParticipants.sampleRenderDiagnostics()
    // 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 'call' 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
 // ═══════════════════════════════════════════════════════════


 // ── Call State ────────────────────────────────────────────
 // Where the call is in its lifecycle. 6 states.
 // Error can happen from ANY state.

 export type CallState =
  | { status: 'idle' }
  | { status: 'connected'; hostID: string }
  | { status: 'joining'; sessionID: string }
  | { status: 'call'; sessionID: string }
  | { status: 'reconnecting'; sessionID: string }
  | { status: 'error'; message: string; previousStatus?: CallStatus };

 export type CallStatus = CallState['status'];


 // ── Media State ──────────────────────────────────────────
 // What devices are active right now.

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


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

 export type CallParticipant = {
  id: string;
  name: string;
  isLocal: boolean;
  hasVideo: boolean;
  hasAudio: boolean;
  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         (Layer 1 — business logic)
 // WebRTCSession         → RTCSessionManager   (Layer 2 — SDP, signaling)
 // PeerConnectionManager → RTCConnectionManager(Layer 2 — RTCPeerConnection)
 // MediaCaptureService   → MediaManager        (Layer 3 — getUserMedia)
 // RemoteParticipantManager → ParticipantManager
 // ═══════════════════════════════════════════════════════════
diff --git a/nf-useCall.ts b/nf-useCall.ts
 // useCall hook — SolidJS
 // Adapted from useWebRTC.ts (RTC-FRONTEND), rewritten for SolidJS + SFU.
 // This is what useSessionConnection.ts becomes — much simpler.

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

 export function useCall(callService: CallService) {

  // ── Reactive effects on callState ──────────────────────────

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

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

      case 'connected':
        // Show "ready" state, clear previous errors
        break;

      case 'joining':
        // Show progress indicator
        break;

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

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

      case 'error':
        // Show error: state.message
        // Offer reconnect button
        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 pipeline
    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 ───────────────────────
  // Called reactively when participant routes change.

  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();
    // Re-enable camera/mic if they were on
    // Re-publish
    // Re-subscribe
  }

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

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

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

  return {
    // State (reactive signals, read in templates)
    callState: callService.callState,
    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),
  };
 }
	// Call Service — Layer 1
	// Business logic layer. Owns CallState, coordinates WebRTC Service + Media Manager.
	// This is what WebRTCPipeline.ts becomes after refactoring.

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

	// These already exist and stay as-is:
	// import { WebRTCSession } from './core/WebRTCSession';
	// import { PeerConnectionManager } from './core/PeerConnectionManager';
	// import { MediaCaptureService } from './core/MediaCaptureService';
	// import { CloudflareCallsClient } from './signaling/CloudflareCallsClient';

	// These are new extracted classes:
	// import { CallStateMachine } from './core/CallStateMachine';
	// import { CombinedAudioPlayback } from './core/CombinedAudioPlayback';
	// import { RemoteParticipantManager } from './core/RemoteParticipantManager';

	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>;

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

	// private stateMachine: CallStateMachine;
	// private audioPlayback: CombinedAudioPlayback;
	// private remoteParticipants: RemoteParticipantManager;
	// private session: WebRTCSession \| null = null;
	// private peer: PeerConnectionManager \| null = null;
	// private capture: MediaCaptureService \| null = null;
	// private callsClient: SFUAdapter \| null = null;

	private cameraStream: MediaStream \| undefined;
	private micStream: MediaStream \| undefined;
	private hasPublished = false;

	constructor() {
	// 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;

	// Extracted classes own their own signals
	// this.stateMachine = new CallStateMachine();
	// this.callState = this.stateMachine.state;
	// this.remoteParticipants = new RemoteParticipantManager();
	// this.participants = this.remoteParticipants.participants;
	// this.audioPlayback = new CombinedAudioPlayback();

	this.participants = createSignal<CallParticipant[]>([])[0]; // placeholder
	}

	// ── Call Lifecycle ─────────────────────────────────────────
	// The hook (useSessionConnection) 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> {
	// this.stateMachine.transition({ status: 'connected', hostID: params.guestId }, 'connect');
	// 1. Create callsClient (CloudflareCallsClient)
	// 2. Create peer (PeerConnectionManager) with callbacks
	// 3. Create session (WebRTCSession) with callbacks:
	// - onNetworkStats → this.handleStats()
	// - onRemoteVideoActive → this.remoteParticipants.setVideoReceiving()
	// - onRemoteVideoStale → this.handleStaleVideo()
	// - onBeforeNewSubscriptions → this.clearRemoteParticipant()
	// 4. session.connect({ sessionId, guestId })
	// 5. Create silent placeholder
	// 6. Ensure peer session
	}

	async disconnect(): Promise<void> {
	// SAFETY: if status is 'reconnecting', wait for reconnect to finish first.
	// Reconnect owns the teardown/rebuild cycle — disconnect must not race it.
	// if (this.stateMachine.state().status === 'reconnecting') return;
	//
	// this.stateMachine.transition({ status: 'idle' }, 'disconnect');
	// 1. this.clearRemoteParticipant()
	// 2. this.audioPlayback.teardown()
	// 3. Stop camera/mic streams
	// 4. session.disconnect()
	// 5. peer.closeConnection()
	// 6. Reset all state
	}

	async reconnect(): Promise<void> {
	// this.stateMachine.transition({ status: 'reconnecting', sessionID }, 'reconnect');
	// SAFETY: reconnect() does its own teardown before rebuilding.
	// disconnect() is blocked while status is 'reconnecting'.
	// If reconnect fails → transition to 'error', then caller decides:
	// retry (→ reconnect again) or give up (→ disconnect).
	// Re-run connect() with last params
	}

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

	async publish(): Promise<void> {
	// this.stateMachine.transition({ status: 'joining', sessionID }, 'publish');
	// Delegates to session.publishTracks()
	// On success: hasPublished = true
	// On failure: retry with session recreation
	}

	async subscribe(params?: SubscribeParams): Promise<void> {
	// Delegates to session.subscribeTracks()
	// On success: stateMachine.transition({ status: 'call', sessionID }, 'subscribed')
	}

	clearPublisherSubscription(publisherGuestId: string): void {
	// session.clearPublisherSubscription(publisherGuestId)
	}

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

	async enableCamera(existingStream?: MediaStream): Promise<void> {
	// 1. Ensure peer session
	// 2. Capture camera (or use existingStream)
	// 3. Attach to peer via negotiation queue
	// 4. Apply camera sending params
	// 5. Set isCameraEnabled(true)
	// 6. Refresh local preview
	// 7. Re-publish if already in a call
	}

	async disableCamera(): Promise<void> {
	// 1. Disable camera track on peer
	// 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. Ensure peer session
	// 2. Capture mic (or use existingStream)
	// 3. Enforce echo cancellation / noise suppression
	// 4. Attach to peer via negotiation queue
	// 5. Set isMicEnabled(true)
	// 6. Refresh local preview + audio playback
	// 7. Re-publish if needed
	}

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

	async setCameraQuality(quality: string, fps?: number): Promise<void> {
	// Apply camera sending params to peer (resolution, framerate)
	}

	// ── 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.remoteParticipants.update(...)
	}

	// ── 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.remoteParticipants.update({ remoteStream: stream, ... })
	}

	private clearRemoteParticipant(): void {
	// Coordinates BOTH extracted classes:
	// 1. this.audioPlayback.teardown()
	// 2. this.remoteParticipants.clear()
	}

	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 handleStats(networkStats: NetworkStats \| null): void {
	// Receive raw stats from WebRTCSession
	// Enrich with render diagnostics from remoteParticipants.sampleRenderDiagnostics()
	// 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 'call' or 'joining' state and force=true.
	}
	}
	// ═══════════════════════════════════════════════════════════
	// Call Types — single source of truth for the call system
	// ═══════════════════════════════════════════════════════════


	// ── Call State ────────────────────────────────────────────
	// Where the call is in its lifecycle. 6 states.
	// Error can happen from ANY state.

	export type CallState =
	\| { status: 'idle' }
	\| { status: 'connected'; hostID: string }
	\| { status: 'joining'; sessionID: string }
	\| { status: 'call'; sessionID: string }
	\| { status: 'reconnecting'; sessionID: string }
	\| { status: 'error'; message: string; previousStatus?: CallStatus };

	export type CallStatus = CallState['status'];


	// ── Media State ──────────────────────────────────────────
	// What devices are active right now.

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


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

	export type CallParticipant = {
	id: string;
	name: string;
	isLocal: boolean;
	hasVideo: boolean;
	hasAudio: boolean;
	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 (Layer 1 — business logic)
	// WebRTCSession → RTCSessionManager (Layer 2 — SDP, signaling)
	// PeerConnectionManager → RTCConnectionManager(Layer 2 — RTCPeerConnection)
	// MediaCaptureService → MediaManager (Layer 3 — getUserMedia)
	// RemoteParticipantManager → ParticipantManager
	// ═══════════════════════════════════════════════════════════
	// useCall hook — SolidJS
	// Adapted from useWebRTC.ts (RTC-FRONTEND), rewritten for SolidJS + SFU.
	// This is what useSessionConnection.ts becomes — much simpler.

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

	export function useCall(callService: CallService) {

	// ── Reactive effects on callState ──────────────────────────

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

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

	case 'connected':
	// Show "ready" state, clear previous errors
	break;

	case 'joining':
	// Show progress indicator
	break;

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

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

	case 'error':
	// Show error: state.message
	// Offer reconnect button
	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 pipeline
	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 ───────────────────────
	// Called reactively when participant routes change.

	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();
	// Re-enable camera/mic if they were on
	// Re-publish
	// Re-subscribe
	}

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

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

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

	return {
	// State (reactive signals, read in templates)
	callState: callService.callState,
	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),
	};
	}