@pickleball/expo-sdk 0.1.1

package/src/engine.ts

@@ -0,0 +1,1332 @@
+import type {
+  BootstrapInput,
+  EndReason,
+  LivestreamSessionProvider,
+  LivestreamState,
+  SdkRemoteConfig,
+  SdkSessionGrant,
+  SdkTelemetryCredentials,
+  SdkTelemetryEvent,
+  StartLivestreamInput,
+} from "./contracts";
+import {
+  ConsentRequiredError,
+  InvalidResponseError,
+  NetworkUnavailableError,
+  PermissionDeniedError,
+  PickleballExpoError,
+  SdkDisabledError,
+  SessionConflictError,
+  UnsupportedSdkError,
+  normalizeError,
+} from "./errors";
+import { isSdkRemoteConfig, isSdkVersionSupported } from "./contracts";
+
+export interface RoomConnection {
+  serverUrl: string;
+  participantToken: string;
+  microphoneEnabled: boolean;
+  /** false: vào phòng nhưng chưa publish track (trạng thái standby). */
+  publish?: boolean;
+}
+
+export type RoomEvent =
+  | { type: "reconnecting" }
+  | { type: "reconnected" }
+  | { type: "disconnected"; reason?: string }
+  | { type: "media-error"; error: unknown }
+  /** Lệnh điều khiển từ dashboard qua LiveKit data channel ({"type":"cmd"}). */
+  | { type: "command"; action: string };
+
+export interface RoomAdapter {
+  /** Bật/tắt publish track khi đã ở trong phòng (standby ↔ live). */
+  setPublishing?(enabled: boolean): Promise<void>;
+  setCaptureOrientation?(orientation: CaptureOrientation): Promise<void>;
+  listCameras?(): Promise<CameraDeviceInfo[]>;
+  selectCamera?(
+    deviceId: string,
+    facing: CameraDeviceInfo["facing"],
+  ): Promise<void>;
+  preparePreview(quality: 720 | 1080): Promise<unknown>;
+  connect(input: RoomConnection): Promise<void>;
+  disconnect(stopTracks?: boolean): Promise<void>;
+  switchCamera(): Promise<void>;
+  setMicrophoneEnabled(enabled: boolean): Promise<void>;
+  subscribe(listener: (event: RoomEvent) => void): () => void;
+  dispose(): Promise<void>;
+}
+
+export interface SdkRuntime {
+  assertSupported(): void;
+  requestPermissions(): Promise<boolean>;
+  activateKeepAwake(): void | Promise<void>;
+  deactivateKeepAwake(): void | Promise<void>;
+}
+
+export interface SdkStorage {
+  getItem(key: string): Promise<string | null>;
+  setItem(key: string, value: string): Promise<void>;
+  removeItem(key: string): Promise<void>;
+}
+
+export interface SdkNetwork {
+  isOnline(): boolean;
+  subscribe(listener: (online: boolean) => void): () => void;
+}
+
+export interface TelemetrySink {
+  send(
+    credentials: SdkTelemetryCredentials,
+    events: readonly SdkTelemetryEvent[],
+  ): Promise<void>;
+  dispose?(): void;
+}
+
+export interface EngineDependencies {
+  sessionProvider: LivestreamSessionProvider;
+  bootstrapInput: BootstrapInput;
+  roomFactory: () => RoomAdapter;
+  runtime: SdkRuntime;
+  storage: SdkStorage;
+  network: SdkNetwork;
+  telemetry?: TelemetrySink;
+  /** Thu chỉ số thiết bị; gọi mỗi nhịp heartbeat khi đang phát. */
+  deviceMetrics?: () => Promise<DeviceMetricsSample | null>;
+  now?: () => number;
+}
+
+export type CaptureOrientation = "portrait" | "landscape";
+
+export interface CameraDeviceInfo {
+  deviceId: string;
+  label: string;
+  facing: "front" | "environment" | "unknown";
+}
+
+/** Chỉ số thiết bị gửi kèm heartbeat (trường trùng schema deviceMetrics). */
+export interface DeviceMetricsSample {
+  batteryPct?: number;
+  batteryTempC?: number;
+  thermal?: number;
+  ramFreeMb?: number;
+  ramTotalMb?: number;
+  storageFreeGb?: number;
+  netType?: string;
+  linkMbps?: number;
+  rssi?: number;
+  connQuality?: string;
+  charging?: boolean;
+}
+
+export interface LivestreamSnapshot {
+  state: LivestreamState;
+  error: PickleballExpoError | null;
+  config: SdkRemoteConfig | null;
+  sessionId: string | null;
+  previewTrack: unknown;
+  isMicrophoneEnabled: boolean;
+  isCameraFront: boolean;
+  /** Explicit pre-live choice; null follows the window orientation. */
+  captureOrientation: CaptureOrientation | null;
+  /** Mẫu chỉ số thiết bị mới nhất (cập nhật mỗi heartbeat khi live). */
+  deviceMetrics: DeviceMetricsSample | null;
+  /** Cameras reported by the platform after preview was prepared. */
+  cameras: CameraDeviceInfo[];
+  /** Explicitly chosen camera; null when following facing (front/back). */
+  selectedCameraId: string | null;
+  elapsedMs: number;
+  isOnline: boolean;
+}
+
+const PENDING_END_KEY = "@pickleball/expo-sdk/pending-end";
+/** Standby không phát quá lâu → tự kết thúc (config.standbyTimeoutMs ghi đè). */
+const DEFAULT_STANDBY_TIMEOUT_MS = 15 * 60_000;
+const activeStates = new Set<LivestreamState>([
+  "standby",
+  "live",
+  "reconnecting",
+]);
+const inMemorySessionStates = new Set<LivestreamState>([
+  "connecting",
+  "standby",
+  "live",
+  "reconnecting",
+  "ending",
+]);
+
+interface PendingEndRecord {
+  sessionId: string;
+  pendingEnd: EndReason | null;
+}
+
+interface SessionTermination {
+  markerReady: Promise<void>;
+  completion: Promise<void>;
+}
+
+interface PendingTelemetry {
+  credentials: SdkTelemetryCredentials;
+  event: SdkTelemetryEvent;
+}
+
+class StaleOperationError extends Error {}
+
+export const LEGAL_LIVESTREAM_TRANSITIONS: Readonly<
+  Record<LivestreamState, readonly LivestreamState[]>
+> = {
+  idle: ["preparing"],
+  preparing: ["preview", "ending", "error"],
+  preview: ["connecting", "preparing", "ending", "error"],
+  connecting: ["standby", "live", "ending", "error"],
+  standby: ["live", "reconnecting", "ending", "error"],
+  live: ["standby", "reconnecting", "ending", "error"],
+  reconnecting: ["standby", "live", "ending", "error"],
+  ending: ["ended", "error"],
+  ended: ["preparing"],
+  error: ["preparing", "reconnecting", "ending", "ended"],
+};
+
+export class LivestreamEngine {
+  private room?: RoomAdapter;
+  private readonly now: () => number;
+  private snapshot: LivestreamSnapshot;
+  private listeners = new Set<() => void>();
+  private preparePromise?: Promise<void>;
+  private startPromise?: Promise<void>;
+  private stopPromise?: Promise<void>;
+  private retryPromise?: Promise<void>;
+  private credentialRefreshPromise?: Promise<void>;
+  private pendingReplayPromise?: Promise<void>;
+  private startupRecoveryPromise?: Promise<void>;
+  private startupRecovered = false;
+  private pendingReplayError?: unknown;
+  private ownedSessionId?: string;
+  private commandTail: Promise<void> = Promise.resolve();
+  private commandCount = 0;
+  private roomUnsubscribe: () => void = () => undefined;
+  private networkUnsubscribe: () => void = () => undefined;
+  private networkSubscribed = false;
+  private latestAppState: "active" | "background" | "inactive" = "active";
+  private backgroundTimer?: ReturnType<typeof setTimeout>;
+  private standbyTimer?: ReturnType<typeof setTimeout>;
+  private reconnectTimer?: ReturnType<typeof setTimeout>;
+  private heartbeatTimer?: ReturnType<typeof setInterval>;
+  private elapsedTimer?: ReturnType<typeof setInterval>;
+  private tokenRefreshTimer?: ReturnType<typeof setTimeout>;
+  private maxSessionTimer?: ReturnType<typeof setTimeout>;
+  private grant?: SdkSessionGrant;
+  private startedAt?: number;
+  /** Đang publish track (live) hay chỉ ngồi trong phòng (standby). */
+  private publishing = false;
+  /** Tổng thời gian đã phát trước lần tạm dừng gần nhất. */
+  private pausedElapsedMs = 0;
+  private sessionDeadline?: number;
+  private refreshRetryAttempt = 0;
+  private operationGeneration = 0;
+  private liveTimersStarted = false;
+  private keepAwakeActive = false;
+  private telemetryInFlight?: Promise<void>;
+  private pendingCriticalTelemetry?: PendingTelemetry;
+  private readonly sessionTerminations = new Map<string, SessionTermination>();
+  private disposePromise?: Promise<void>;
+  private disposed = false;
+
+  constructor(private readonly dependencies: EngineDependencies) {
+    this.now = dependencies.now ?? Date.now;
+    this.snapshot = {
+      state: "idle",
+      error: null,
+      config: null,
+      sessionId: null,
+      previewTrack: null,
+      isMicrophoneEnabled: true,
+      isCameraFront: true,
+      captureOrientation: null,
+      deviceMetrics: null,
+      cameras: [],
+      selectedCameraId: null,
+      elapsedMs: 0,
+      isOnline: dependencies.network.isOnline(),
+    };
+  }
+
+  getSnapshot = () => this.snapshot;
+
+  subscribe = (listener: () => void) => {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  };
+
+  async initialize() {
+    if (this.disposed) return;
+    this.ensureNetworkSubscription();
+    if (this.startupRecovered) {
+      try {
+        await this.replayPendingEnd();
+      } catch (error) {
+        this.pendingReplayError = error;
+      }
+      return;
+    }
+    if (!this.startupRecoveryPromise) {
+      this.startupRecoveryPromise = this.recoverStartupSession()
+        .catch((error) => {
+          this.pendingReplayError = error;
+        })
+        .finally(() => {
+          this.startupRecovered = true;
+          this.startupRecoveryPromise = undefined;
+        });
+    }
+    await this.startupRecoveryPromise;
+  }
+
+  prepare() {
+    if (this.preparePromise) return this.preparePromise;
+    if (this.snapshot.state === "preview") return Promise.resolve();
+    if (
+      ["connecting", "live", "reconnecting", "ending"].includes(
+        this.snapshot.state,
+      ) ||
+      (this.snapshot.state === "error" && this.snapshot.sessionId)
+    ) {
+      return Promise.reject(
+        new SessionConflictError("Cannot prepare while a session is active"),
+      );
+    }
+    this.preparePromise = this.enqueueLifecycle(() => this.doPrepare()).finally(() => {
+      this.preparePromise = undefined;
+    });
+    return this.preparePromise;
+  }
+
+  private async doPrepare() {
+    const generation = this.operationGeneration;
+    this.ensureNotDisposed();
+    this.transition("preparing");
+    try {
+      await this.ensurePendingEndResolved();
+      this.ensureOperation(generation);
+      this.dependencies.runtime.assertSupported();
+      const bootstrap = await this.dependencies.sessionProvider.bootstrap(
+        this.dependencies.bootstrapInput,
+      );
+      this.ensureOperation(generation);
+      if (!isSdkRemoteConfig(bootstrap.config)) {
+        throw new InvalidResponseError(
+          "The session provider returned invalid SDK config",
+        );
+      }
+      if (!bootstrap.config.enabled || !bootstrap.rolloutEnabled) {
+        throw new SdkDisabledError(bootstrap.message);
+      }
+      if (
+        !isSdkVersionSupported(
+          this.dependencies.bootstrapInput.sdkVersion,
+          bootstrap.config.minSdkVersion,
+        )
+      ) {
+        throw new UnsupportedSdkError();
+      }
+      this.update({ config: bootstrap.config });
+      const permitted = await this.dependencies.runtime.requestPermissions();
+      this.ensureOperation(generation);
+      if (!permitted) {
+        throw new PermissionDeniedError();
+      }
+      const room = this.ensureRoom();
+      if (this.snapshot.captureOrientation) {
+        await room.setCaptureOrientation?.(this.snapshot.captureOrientation);
+      }
+      const previewTrack = await room.preparePreview(
+        bootstrap.config.videoQuality,
+      );
+      if (!this.isOperationCurrent(generation)) {
+        await this.releaseRoom();
+        throw new StaleOperationError();
+      }
+      let cameras: CameraDeviceInfo[] = [];
+      try {
+        cameras = (await room.listCameras?.()) ?? [];
+      } catch {
+        // Danh sách camera chỉ phục vụ UI chọn ống kính; lỗi không chặn preview.
+      }
+      if (!this.isOperationCurrent(generation)) {
+        await this.releaseRoom();
+        throw new StaleOperationError();
+      }
+      this.update({ previewTrack, cameras });
+      this.transition("preview");
+    } catch (error) {
+      if (
+        !this.isOperationCurrent(generation) ||
+        error instanceof StaleOperationError
+      ) {
+        return;
+      }
+      this.fail(error);
+    }
+  }
+
+  start(
+    input: StartLivestreamInput,
+    options?: { autoPublish?: boolean },
+  ) {
+    if (this.startPromise) return this.startPromise;
+    if (this.snapshot.state === "live" || this.snapshot.state === "standby") {
+      return Promise.resolve();
+    }
+    if (this.snapshot.state !== "preview" && !this.preparePromise) {
+      return Promise.reject(
+        new SessionConflictError("Livestream preview is not ready"),
+      );
+    }
+    this.startPromise = this.enqueueLifecycle(() =>
+      this.doStart(input, options?.autoPublish ?? true),
+    ).finally(() => {
+      this.startPromise = undefined;
+    });
+    return this.startPromise;
+  }
+
+  private async doStart(input: StartLivestreamInput, autoPublish: boolean) {
+    const generation = this.operationGeneration;
+    let activeGrant: SdkSessionGrant | undefined;
+    this.ensureNotDisposed();
+    this.ensureState("preview");
+    if (!input.consentVersion.trim()) throw new ConsentRequiredError();
+    if (!input.externalSessionId.trim() || !input.title.trim()) {
+      const error = new ConsentRequiredError("Session ID and title are required");
+      this.fail(error);
+    }
+    if (!this.dependencies.network.isOnline()) {
+      this.fail(new NetworkUnavailableError());
+    }
+    this.transition("connecting");
+    this.ensureBackgroundGraceTimer();
+    try {
+      await this.ensurePendingEndResolved();
+      this.ensureOperation(generation);
+    } catch (error) {
+      if (
+        !this.isOperationCurrent(generation) ||
+        error instanceof StaleOperationError
+      ) {
+        return;
+      }
+      this.fail(error);
+    }
+    try {
+      // Cờ standby để server KHÔNG bật egress/goLive khi app chỉ vào chờ.
+      const grant = await this.dependencies.sessionProvider.start({
+        ...input,
+        standby: !autoPublish,
+      });
+      activeGrant = grant;
+      if (!this.isOperationCurrent(generation)) {
+        await this.abandonGrant(grant);
+        return;
+      }
+      if (!isSdkRemoteConfig(grant.config)) {
+        await this.abandonGrant(grant);
+        throw new InvalidResponseError(
+          "The session provider returned invalid SDK config",
+        );
+      }
+      this.ownedSessionId = grant.sessionId;
+      this.grant = grant;
+      this.liveTimersStarted = false;
+      this.keepAwakeActive = false;
+      // Ghi sớm ý định phát để retry/reconnect khôi phục đúng trạng thái.
+      this.publishing = autoPublish;
+      this.pausedElapsedMs = 0;
+      this.update({
+        config: grant.config,
+        sessionId: grant.sessionId,
+        elapsedMs: 0,
+      });
+      await this.dependencies.storage.setItem(
+        PENDING_END_KEY,
+        JSON.stringify({ sessionId: grant.sessionId, pendingEnd: null }),
+      );
+      if (!this.isOperationCurrent(generation)) {
+        await this.abandonGrant(grant);
+        return;
+      }
+      await this.requireRoom().connect({
+        serverUrl: grant.serverUrl,
+        participantToken: grant.participantToken,
+        microphoneEnabled: this.snapshot.isMicrophoneEnabled,
+        publish: autoPublish,
+      });
+      if (!this.isOperationCurrent(generation)) {
+        await this.abandonGrant(grant);
+        return;
+      }
+      await this.enterSession(generation, autoPublish);
+    } catch (error) {
+      if (
+        !this.isOperationCurrent(generation) ||
+        error instanceof StaleOperationError
+      ) {
+        if (activeGrant) await this.abandonGrant(activeGrant);
+        return;
+      }
+      this.fail(error);
+    }
+  }
+
+  stop(reason: EndReason = "user") {
+    if (this.stopPromise) return this.stopPromise;
+    if (this.snapshot.state === "ended" || this.snapshot.state === "idle") {
+      return Promise.resolve();
+    }
+    this.stopPromise = this.enqueueLifecycle(() => this.doStop(reason)).finally(() => {
+      this.stopPromise = undefined;
+    });
+    return this.stopPromise;
+  }
+
+  private async doStop(reason: EndReason) {
+    if (this.disposed) return;
+    const sessionId = this.ownedSessionId;
+    const termination = sessionId
+      ? this.ensureSessionTermination(sessionId, reason)
+      : undefined;
+    this.transition("ending");
+    this.clearTimers();
+    const roomCleanup = this.releaseRoom(termination?.markerReady);
+    await Promise.allSettled([
+      roomCleanup,
+      this.dependencies.runtime.deactivateKeepAwake(),
+    ]);
+    this.keepAwakeActive = false;
+    if (sessionId) {
+      await termination?.completion;
+      void this.sendTelemetry("session_ended", { reason });
+    }
+    this.grant = undefined;
+    this.ownedSessionId = undefined;
+    this.startedAt = undefined;
+    this.publishing = false;
+    this.pausedElapsedMs = 0;
+    this.update({ previewTrack: null, sessionId: null });
+    this.transition("ended");
+  }
+
+  retry() {
+    if (this.retryPromise) return this.retryPromise;
+    this.retryPromise = this.enqueueLifecycle(() => this.doRetry()).finally(() => {
+      this.retryPromise = undefined;
+    });
+    return this.retryPromise;
+  }
+
+  private async doRetry() {
+    const generation = this.operationGeneration;
+    this.ensureNotDisposed();
+    if (this.snapshot.state === "error" && !this.snapshot.sessionId) {
+      this.update({ error: null });
+      return this.prepare();
+    }
+    if (this.snapshot.state === "error" && this.snapshot.sessionId) {
+      this.transition("reconnecting");
+    }
+    this.ensureState("reconnecting");
+    const sessionId = this.snapshot.sessionId;
+    if (!sessionId || !this.grant) throw new Error("Missing session grant");
+    const activeGrant = this.grant;
+    try {
+      await this.refreshCredentials(generation);
+      this.ensureOperation(generation);
+      await this.requireRoom().connect({
+        serverUrl: this.grant.serverUrl,
+        participantToken: this.grant.participantToken,
+        microphoneEnabled: this.snapshot.isMicrophoneEnabled,
+        publish: this.publishing,
+      });
+      this.ensureOperation(generation);
+      this.clearReconnectTimer();
+      await this.enterSession(generation, this.publishing);
+    } catch (error) {
+      if (
+        !this.isOperationCurrent(generation) ||
+        error instanceof StaleOperationError
+      ) {
+        await this.abandonGrant(activeGrant);
+        return;
+      }
+      this.fail(error);
+    }
+  }
+
+  async switchCamera() {
+    if (!this.snapshot.previewTrack) return;
+    const generation = this.operationGeneration;
+    await this.requireRoom().switchCamera();
+    if (!this.isOperationCurrent(generation)) return;
+    this.update({
+      isCameraFront: !this.snapshot.isCameraFront,
+      selectedCameraId: null,
+    });
+  }
+
+  /** Chọn một ống kính cụ thể từ snapshot.cameras. */
+  async selectCamera(deviceId: string) {
+    if (!this.snapshot.previewTrack) return;
+    if (deviceId === this.snapshot.selectedCameraId) return;
+    const camera = this.snapshot.cameras.find(
+      (item) => item.deviceId === deviceId,
+    );
+    if (!camera) return;
+    const room = this.requireRoom();
+    if (!room.selectCamera) return;
+    const generation = this.operationGeneration;
+    await room.selectCamera(camera.deviceId, camera.facing);
+    if (!this.isOperationCurrent(generation)) return;
+    this.update({
+      selectedCameraId: camera.deviceId,
+      ...(camera.facing === "unknown"
+        ? {}
+        : { isCameraFront: camera.facing === "front" }),
+    });
+  }
+
+  /** Chọn kiểu quay trước khi live; không đổi khi phiên đang hoạt động. */
+  async setCaptureOrientation(orientation: CaptureOrientation) {
+    if (orientation === this.snapshot.captureOrientation) return;
+    if (this.snapshot.sessionId || activeStates.has(this.snapshot.state)) {
+      return;
+    }
+    const generation = this.operationGeneration;
+    if (this.snapshot.previewTrack) {
+      await this.requireRoom().setCaptureOrientation?.(orientation);
+      if (!this.isOperationCurrent(generation)) return;
+    }
+    this.update({ captureOrientation: orientation });
+  }
+
+  async setMicrophoneEnabled(enabled: boolean) {
+    const generation = this.operationGeneration;
+    await this.requireRoom().setMicrophoneEnabled(enabled);
+    if (!this.isOperationCurrent(generation)) return;
+    this.update({ isMicrophoneEnabled: enabled });
+  }
+
+  handleRoomEvent(event: RoomEvent) {
+    if (this.disposed) return;
+    // Lệnh từ dashboard (cùng giao thức với camera box): "start" bắt đầu
+    // phát, "stop" tạm dừng phát về standby — KHÔNG kết thúc phiên. Kết thúc
+    // phiên vẫn là hành động riêng (nút trên app / Kết thúc trên dashboard).
+    if (event.type === "command") {
+      if (event.action === "start") void this.startPublishing();
+      else if (event.action === "stop") void this.stopPublishing();
+      return;
+    }
+    if (
+      event.type === "reconnecting" &&
+      (this.snapshot.state === "live" || this.snapshot.state === "standby")
+    ) {
+      this.transition("reconnecting");
+      void this.sendTelemetry("reconnect", { phase: "started" });
+      const timeout = this.snapshot.config?.reconnectTimeoutMs ?? 30_000;
+      this.clearReconnectTimer();
+      this.reconnectTimer = setTimeout(() => {
+        void this.stop("network_timeout");
+      }, timeout);
+      return;
+    }
+    if (event.type === "reconnected" && this.snapshot.state === "reconnecting") {
+      this.clearReconnectTimer();
+      this.transition(this.publishing ? "live" : "standby");
+      void this.sendTelemetry("reconnect", { phase: "recovered" });
+      return;
+    }
+    if (event.type === "media-error") this.recordError(event.error);
+    if (
+      event.type === "disconnected" &&
+      activeStates.has(this.snapshot.state)
+    ) {
+      this.handleRoomEvent({ type: "reconnecting" });
+    }
+  }
+
+  handleAppState(state: "active" | "background" | "inactive") {
+    if (this.disposed) return;
+    this.latestAppState = state;
+    if (state === "active") {
+      if (this.backgroundTimer) clearTimeout(this.backgroundTimer);
+      this.backgroundTimer = undefined;
+      return;
+    }
+    this.ensureBackgroundGraceTimer();
+  }
+
+  private ensureBackgroundGraceTimer() {
+    if (
+      this.latestAppState === "active" ||
+      !["connecting", "standby", "live", "reconnecting"].includes(
+        this.snapshot.state,
+      ) ||
+      this.backgroundTimer
+    ) {
+      return;
+    }
+    const grace = this.snapshot.config?.backgroundGraceMs ?? 15_000;
+    this.backgroundTimer = setTimeout(() => {
+      this.backgroundTimer = undefined;
+      if (this.latestAppState !== "active") {
+        void this.stop("background_timeout");
+      }
+    }, grace);
+  }
+
+  dispose(): Promise<void> {
+    if (this.disposePromise) return this.disposePromise;
+    if (this.disposed) return Promise.resolve();
+    this.disposed = true;
+    this.operationGeneration += 1;
+    const sessionId = this.ownedSessionId;
+    let releaseEnd: () => void = () => undefined;
+    const endBarrier = new Promise<void>((resolve) => {
+      releaseEnd = resolve;
+    });
+    const termination = sessionId
+      ? this.ensureSessionTermination(sessionId, "error", endBarrier)
+      : undefined;
+    const roomCleanup = this.releaseRoom(termination?.markerReady);
+    this.clearTimers();
+    this.dependencies.telemetry?.dispose?.();
+    this.pendingCriticalTelemetry = undefined;
+    this.networkUnsubscribe();
+    this.listeners.clear();
+    this.keepAwakeActive = false;
+    this.grant = undefined;
+    this.ownedSessionId = undefined;
+    this.disposePromise = (async () => {
+      await termination?.markerReady;
+      await Promise.allSettled([
+        roomCleanup,
+        this.dependencies.runtime.deactivateKeepAwake(),
+      ]);
+      releaseEnd();
+      await termination?.completion;
+    })();
+    return this.disposePromise;
+  }
+
+  private async replayPendingEnd() {
+    if (this.ownsInMemorySession()) return;
+    if (this.pendingReplayPromise) return this.pendingReplayPromise;
+    this.pendingReplayPromise = this.doReplayPendingEnd().finally(() => {
+      this.pendingReplayPromise = undefined;
+    });
+    return this.pendingReplayPromise;
+  }
+
+  private async doReplayPendingEnd() {
+    const pending = await this.readPendingEnd();
+    if (!pending || pending.pendingEnd === null) return;
+    if (!this.dependencies.network.isOnline()) return;
+    await this.dependencies.sessionProvider.end({
+      sessionId: pending.sessionId,
+      reason: pending.pendingEnd ?? "error",
+    });
+    await this.dependencies.storage.removeItem(PENDING_END_KEY);
+    this.pendingReplayError = undefined;
+  }
+
+  private async recoverStartupSession() {
+    let pending = await this.readPendingEnd();
+    if (!pending || this.ownsInMemorySession()) return;
+    if (pending.pendingEnd === null) {
+      pending = { sessionId: pending.sessionId, pendingEnd: "error" };
+      await this.dependencies.storage.setItem(
+        PENDING_END_KEY,
+        JSON.stringify(pending),
+      );
+    }
+    if (!this.dependencies.network.isOnline()) return;
+    await this.dependencies.sessionProvider.end({
+      sessionId: pending.sessionId,
+      reason: pending.pendingEnd ?? "error",
+    });
+    await this.dependencies.storage.removeItem(PENDING_END_KEY);
+    this.pendingReplayError = undefined;
+  }
+
+  private async ensurePendingEndResolved() {
+    await this.initialize();
+    const pending = await this.readPendingEnd();
+    if (!pending) return;
+    if (!this.dependencies.network.isOnline()) {
+      throw new NetworkUnavailableError(
+        "Connect to the network to finish the previous livestream",
+      );
+    }
+    if (this.pendingReplayError instanceof TypeError) {
+      throw new NetworkUnavailableError(undefined, {
+        cause: this.pendingReplayError,
+      });
+    }
+    if (
+      this.snapshot.state === "connecting" &&
+      !this.ownedSessionId &&
+      pending.pendingEnd !== null
+    ) {
+      try {
+        await this.dependencies.sessionProvider.end({
+          sessionId: pending.sessionId,
+          reason: pending.pendingEnd,
+        });
+        await this.dependencies.storage.removeItem(PENDING_END_KEY);
+        this.pendingReplayError = undefined;
+        return;
+      } catch (error) {
+        this.pendingReplayError = error;
+        if (error instanceof TypeError) {
+          throw new NetworkUnavailableError(undefined, { cause: error });
+        }
+      }
+    }
+    throw new SessionConflictError(
+      pending.pendingEnd === null
+        ? "Another livestream session is still active"
+        : "The previous livestream is still pending end",
+    );
+  }
+
+  private async readPendingEnd(): Promise<PendingEndRecord | null> {
+    const raw = await this.dependencies.storage.getItem(PENDING_END_KEY);
+    if (!raw) return null;
+    try {
+      const value = JSON.parse(raw) as {
+        sessionId?: unknown;
+        pendingEnd?: unknown;
+      };
+      if (typeof value.sessionId !== "string") throw new TypeError();
+      if (value.pendingEnd === null) {
+        return { sessionId: value.sessionId, pendingEnd: null };
+      }
+      if (
+        [
+          "user",
+          "background_timeout",
+          "network_timeout",
+          "standby_timeout",
+          "error",
+        ].includes(String(value.pendingEnd))
+      ) {
+        return {
+          sessionId: value.sessionId,
+          pendingEnd: value.pendingEnd as EndReason,
+        };
+      }
+    } catch {
+      // Invalid bounded recovery data can be safely discarded.
+    }
+    await this.dependencies.storage.removeItem(PENDING_END_KEY);
+    return null;
+  }
+
+  private ownsInMemorySession() {
+    return Boolean(this.ownedSessionId) || inMemorySessionStates.has(this.snapshot.state);
+  }
+
+  private startTimers() {
+    if (this.liveTimersStarted) return;
+    this.liveTimersStarted = true;
+    const interval = Math.max(
+      10_000,
+      this.snapshot.config?.telemetryIntervalMs ?? 60_000,
+    );
+    this.heartbeatTimer = setInterval(() => {
+      void this.sendHeartbeat();
+    }, interval);
+    (this.heartbeatTimer as unknown as { unref?: () => void }).unref?.();
+    this.elapsedTimer = setInterval(() => {
+      if (this.startedAt !== undefined) {
+        this.update({ elapsedMs: this.now() - this.startedAt });
+      }
+    }, 1_000);
+    (this.elapsedTimer as unknown as { unref?: () => void }).unref?.();
+    this.scheduleTokenRefresh();
+    this.scheduleMaxSessionDuration();
+  }
+
+  private clearTimers() {
+    if (this.backgroundTimer) clearTimeout(this.backgroundTimer);
+    this.clearStandbyTimer();
+    if (this.heartbeatTimer) clearInterval(this.heartbeatTimer);
+    if (this.elapsedTimer) clearInterval(this.elapsedTimer);
+    if (this.tokenRefreshTimer) clearTimeout(this.tokenRefreshTimer);
+    if (this.maxSessionTimer) clearTimeout(this.maxSessionTimer);
+    this.clearReconnectTimer();
+    this.backgroundTimer = undefined;
+    this.heartbeatTimer = undefined;
+    this.elapsedTimer = undefined;
+    this.tokenRefreshTimer = undefined;
+    this.maxSessionTimer = undefined;
+    this.sessionDeadline = undefined;
+    this.liveTimersStarted = false;
+  }
+
+  private clearReconnectTimer() {
+    if (this.reconnectTimer) clearTimeout(this.reconnectTimer);
+    this.reconnectTimer = undefined;
+  }
+
+  /** Heartbeat kèm chỉ số thiết bị (nếu collector được cung cấp). */
+  private async sendHeartbeat() {
+    let metrics: DeviceMetricsSample | null = null;
+    try {
+      metrics = (await this.dependencies.deviceMetrics?.()) ?? null;
+    } catch {
+      metrics = null;
+    }
+    if (this.disposed) return;
+    if (metrics) this.update({ deviceMetrics: metrics });
+    return this.sendTelemetry(
+      "heartbeat",
+      metrics ? { ...metrics } : undefined,
+    );
+  }
+
+  private async sendTelemetry(
+    name: SdkTelemetryEvent["name"],
+    data?: Record<string, unknown>,
+  ) {
+    if (this.disposed || !this.dependencies.telemetry || !this.grant) return;
+    const grant = this.grant;
+    const pending: PendingTelemetry = {
+      credentials: grant.telemetry,
+      event: {
+        sessionId: grant.sessionId,
+        at: this.now(),
+        name,
+        ...(data ? { data } : {}),
+      },
+    };
+    if (this.telemetryInFlight) {
+      if (name === "session_ended" && !this.pendingCriticalTelemetry) {
+        this.pendingCriticalTelemetry = pending;
+      }
+      return this.telemetryInFlight;
+    }
+    return this.startTelemetrySend(pending);
+  }
+
+  private startTelemetrySend(pending: PendingTelemetry) {
+    const operation = (async () => {
+      try {
+        await this.dependencies.telemetry?.send(pending.credentials, [
+          pending.event,
+        ]);
+      } catch (error) {
+        if ((error as { status?: unknown })?.status === 401) {
+          try {
+            await this.refreshCredentials();
+            if (this.grant) {
+              await this.dependencies.telemetry?.send(this.grant.telemetry, [
+                pending.event,
+              ]);
+            }
+          } catch {
+            // Telemetry must never interrupt the livestream lifecycle.
+          }
+        }
+      }
+    })();
+    const tracked = operation.finally(() => {
+      if (this.telemetryInFlight !== tracked) return;
+      this.telemetryInFlight = undefined;
+      const critical = this.pendingCriticalTelemetry;
+      this.pendingCriticalTelemetry = undefined;
+      if (critical && !this.disposed) this.startTelemetrySend(critical);
+    });
+    this.telemetryInFlight = tracked;
+    return this.telemetryInFlight;
+  }
+
+  private refreshCredentials(generation = this.operationGeneration) {
+    if (this.credentialRefreshPromise) return this.credentialRefreshPromise;
+    const sessionId = this.snapshot.sessionId;
+    if (!sessionId || !this.grant) return Promise.resolve();
+    this.credentialRefreshPromise = this.dependencies.sessionProvider
+      .refresh(sessionId)
+      .then((refreshed) => {
+        this.ensureOperation(generation);
+        if (!isSdkRemoteConfig(refreshed.config)) {
+          throw new InvalidResponseError(
+            "The session provider returned invalid SDK config",
+          );
+        }
+        if (
+          !this.grant ||
+          this.snapshot.sessionId !== sessionId ||
+          !activeStates.has(this.snapshot.state)
+        ) {
+          return;
+        }
+        this.grant = {
+          ...this.grant,
+          participantToken:
+            refreshed.participantToken ?? this.grant.participantToken,
+          tokenExpiresAt: refreshed.tokenExpiresAt ?? this.grant.tokenExpiresAt,
+          telemetry: refreshed.telemetry ?? this.grant.telemetry,
+          config: refreshed.config,
+        };
+        this.update({ config: refreshed.config });
+        this.refreshRetryAttempt = 0;
+        if (this.liveTimersStarted) {
+          this.restartHeartbeat();
+          this.scheduleTokenRefresh();
+          this.scheduleMaxSessionDuration();
+        }
+      })
+      .finally(() => {
+        this.credentialRefreshPromise = undefined;
+      });
+    return this.credentialRefreshPromise;
+  }
+
+  private transition(state: LivestreamState) {
+    const previous = this.snapshot.state;
+    if (previous === state) return;
+    if (!LEGAL_LIVESTREAM_TRANSITIONS[previous].includes(state)) {
+      throw new SessionConflictError(
+        `Illegal livestream transition: ${previous} -> ${state}`,
+      );
+    }
+    this.update({ state, error: state === "error" ? this.snapshot.error : null });
+    // Ngồi standby quá lâu không phát → tự kết thúc để cắt participant
+    // minutes LiveKit + pin (timer reset mỗi lần rời/vào lại standby).
+    if (state === "standby") this.startStandbyTimer();
+    else this.clearStandbyTimer();
+    if (this.snapshot.sessionId) {
+      void this.sendTelemetry("state_changed", { from: previous, to: state });
+    }
+  }
+
+  private startStandbyTimer() {
+    this.clearStandbyTimer();
+    const timeout =
+      this.snapshot.config?.standbyTimeoutMs ?? DEFAULT_STANDBY_TIMEOUT_MS;
+    this.standbyTimer = setTimeout(() => {
+      this.standbyTimer = undefined;
+      if (this.snapshot.state === "standby") {
+        void this.stop("standby_timeout");
+      }
+    }, timeout);
+    (this.standbyTimer as unknown as { unref?: () => void }).unref?.();
+  }
+
+  private clearStandbyTimer() {
+    if (this.standbyTimer) clearTimeout(this.standbyTimer);
+    this.standbyTimer = undefined;
+  }
+
+  private fail(error: unknown): never {
+    const normalized = this.recordError(error);
+    throw normalized;
+  }
+
+  private recordError(error: unknown) {
+    const normalized = normalizeError(error);
+    const state = this.snapshot.state;
+    if (
+      state !== "error" &&
+      !LEGAL_LIVESTREAM_TRANSITIONS[state].includes("error")
+    ) {
+      return normalized;
+    }
+    this.update({ error: normalized });
+    this.transition("error");
+    void this.sendTelemetry("error", { code: normalized.code });
+    return normalized;
+  }
+
+  private update(patch: Partial<LivestreamSnapshot>) {
+    if (this.disposed) return;
+    this.snapshot = { ...this.snapshot, ...patch };
+    for (const listener of this.listeners) listener();
+  }
+
+  private ensureState(expected: LivestreamState) {
+    if (this.snapshot.state !== expected) {
+      throw new Error(`Expected livestream state ${expected}`);
+    }
+  }
+
+  private ensureNotDisposed() {
+    if (this.disposed) throw new Error("Livestream engine has been disposed");
+  }
+
+  private ensureRoom() {
+    if (!this.room) {
+      this.room = this.dependencies.roomFactory();
+      this.roomUnsubscribe = this.room.subscribe((event) =>
+        this.handleRoomEvent(event),
+      );
+    }
+    return this.room;
+  }
+
+  private ensureNetworkSubscription() {
+    if (this.networkSubscribed || this.disposed) return;
+    this.networkSubscribed = true;
+    this.networkUnsubscribe = this.dependencies.network.subscribe((online) => {
+      if (this.disposed) return;
+      this.update({ isOnline: online });
+      if (online && this.startupRecovered) {
+        void this.replayPendingEnd().catch((error) => {
+          this.pendingReplayError = error;
+        });
+      }
+    });
+  }
+
+  private requireRoom() {
+    if (!this.room) throw new Error("Livestream Room has not been prepared");
+    return this.room;
+  }
+
+  private releaseRoom(
+    beforeDispose: Promise<unknown> = Promise.resolve(),
+  ): Promise<void> {
+    const unsubscribe = this.roomUnsubscribe;
+    this.roomUnsubscribe = () => undefined;
+    const room = this.room;
+    this.room = undefined;
+    try {
+      unsubscribe();
+    } catch {
+      // A consumer listener must not prevent releasing native media resources.
+    }
+    if (!room) return Promise.resolve();
+    return beforeDispose.then(() => room.dispose());
+  }
+
+  private enqueueLifecycle<T>(command: () => Promise<T>): Promise<T> {
+    this.commandCount += 1;
+    let result: Promise<T>;
+    if (this.commandCount === 1) {
+      try {
+        result = Promise.resolve(command());
+      } catch (error) {
+        result = Promise.reject(error);
+      }
+    } else {
+      result = this.commandTail.then(command, command);
+    }
+    this.commandTail = result.then(
+      () => undefined,
+      () => undefined,
+    );
+    return result.finally(() => {
+      this.commandCount -= 1;
+    });
+  }
+
+  private scheduleTokenRefresh(delayOverride?: number) {
+    if (this.tokenRefreshTimer) clearTimeout(this.tokenRefreshTimer);
+    this.tokenRefreshTimer = undefined;
+    if (!this.grant || !this.snapshot.sessionId) return;
+    const delay =
+      delayOverride ??
+      Math.max(1_000, this.grant.tokenExpiresAt - this.now() - 60_000);
+    this.tokenRefreshTimer = setTimeout(() => {
+      void this.refreshCredentials().catch(() => {
+        if (this.disposed) return;
+        const retryDelay = Math.min(
+          30_000,
+          1_000 * 2 ** Math.min(this.refreshRetryAttempt, 5),
+        );
+        this.refreshRetryAttempt += 1;
+        this.scheduleTokenRefresh(retryDelay);
+      });
+    }, delay);
+    (this.tokenRefreshTimer as unknown as { unref?: () => void }).unref?.();
+  }
+
+  private scheduleMaxSessionDuration() {
+    if (this.startedAt === undefined || !this.snapshot.config) return;
+    const proposed =
+      this.startedAt + this.snapshot.config.maxSessionDurationMs;
+    this.sessionDeadline = Math.min(this.sessionDeadline ?? proposed, proposed);
+    if (this.maxSessionTimer) clearTimeout(this.maxSessionTimer);
+    const delay = Math.max(0, this.sessionDeadline - this.now());
+    this.maxSessionTimer = setTimeout(() => {
+      void this.stop("error");
+    }, delay);
+    (this.maxSessionTimer as unknown as { unref?: () => void }).unref?.();
+  }
+
+  private restartHeartbeat() {
+    if (this.heartbeatTimer) clearInterval(this.heartbeatTimer);
+    const interval = Math.max(
+      10_000,
+      this.snapshot.config?.telemetryIntervalMs ?? 60_000,
+    );
+    this.heartbeatTimer = setInterval(() => {
+      void this.sendHeartbeat();
+    }, interval);
+    (this.heartbeatTimer as unknown as { unref?: () => void }).unref?.();
+  }
+
+  private async enterSession(generation: number, publish: boolean) {
+    this.ensureOperation(generation);
+    if (!this.keepAwakeActive) {
+      await this.dependencies.runtime.activateKeepAwake();
+      if (!this.isOperationCurrent(generation)) {
+        await this.dependencies.runtime.deactivateKeepAwake();
+        throw new StaleOperationError();
+      }
+      this.keepAwakeActive = true;
+    }
+    this.publishing = publish;
+    if (publish && this.startedAt === undefined) {
+      // elapsedMs đếm thời gian PHÁT: cộng dồn qua các lần tạm dừng.
+      this.startedAt = this.now() - this.pausedElapsedMs;
+      this.sessionDeadline = undefined;
+      this.update({ elapsedMs: this.pausedElapsedMs });
+    }
+    this.startTimers();
+    this.transition(publish ? "live" : "standby");
+    this.ensureBackgroundGraceTimer();
+  }
+
+  /** Bắt đầu phát khi đang standby (từ nút trên app hoặc lệnh dashboard). */
+  async startPublishing() {
+    if (this.disposed || this.snapshot.state !== "standby") return;
+    const generation = this.operationGeneration;
+    try {
+      // Server bật recording egress + chuyển status live TRƯỚC khi publish
+      // track — phiên standby không được server provision sẵn egress nữa.
+      const grant = this.grant;
+      if (grant && this.dependencies.sessionProvider.publish) {
+        await this.dependencies.sessionProvider.publish(grant.sessionId);
+        if (
+          !this.isOperationCurrent(generation) ||
+          this.snapshot.state !== "standby"
+        ) {
+          return;
+        }
+      }
+      const room = this.requireRoom();
+      if (room.setPublishing) {
+        await room.setPublishing(true);
+      } else if (this.grant) {
+        await room.connect({
+          serverUrl: this.grant.serverUrl,
+          participantToken: this.grant.participantToken,
+          microphoneEnabled: this.snapshot.isMicrophoneEnabled,
+          publish: true,
+        });
+      }
+      if (!this.isOperationCurrent(generation)) return;
+      this.publishing = true;
+      this.startedAt = this.now() - this.pausedElapsedMs;
+      this.update({ elapsedMs: this.pausedElapsedMs });
+      this.transition("live");
+      void this.sendTelemetry("state_changed", { state: "live" });
+    } catch (error) {
+      if (
+        !this.isOperationCurrent(generation) ||
+        error instanceof StaleOperationError
+      ) {
+        return;
+      }
+      this.recordError(error);
+    }
+  }
+
+  /** Tạm dừng phát: ngắt kết nối LiveKit hoàn toàn về standby, KHÔNG kết thúc phiên. */
+  async stopPublishing() {
+    if (this.disposed || this.snapshot.state !== "live") return;
+    const generation = this.operationGeneration;
+    const room = this.requireRoom();
+    if (room.setPublishing) {
+      await room.setPublishing(false);
+    } else {
+      await room.disconnect(false);
+    }
+    if (!this.isOperationCurrent(generation)) return;
+    this.publishing = false;
+    this.pausedElapsedMs =
+      this.startedAt !== undefined ? this.now() - this.startedAt : 0;
+    this.startedAt = undefined;
+    this.update({ elapsedMs: this.pausedElapsedMs });
+    this.transition("standby");
+    void this.sendTelemetry("state_changed", { state: "standby" });
+    // Báo server dừng egress; lỗi mạng thì watchdog server tự dọn sau.
+    const grant = this.grant;
+    if (grant && this.dependencies.sessionProvider.unpublish) {
+      await this.dependencies.sessionProvider
+        .unpublish(grant.sessionId)
+        .catch(() => undefined);
+    }
+  }
+
+  private ensureSessionTermination(
+    sessionId: string,
+    reason: EndReason,
+    beforeEnd: Promise<unknown> = Promise.resolve(),
+  ): SessionTermination {
+    const existing = this.sessionTerminations.get(sessionId);
+    if (existing) return existing;
+    let markerReady: Promise<void>;
+    try {
+      markerReady = Promise.resolve(
+        this.dependencies.storage.setItem(
+          PENDING_END_KEY,
+          JSON.stringify({ sessionId, pendingEnd: reason }),
+        ),
+      ).catch(() => {
+        // Server-side termination is still useful if recovery storage fails.
+      });
+    } catch {
+      markerReady = Promise.resolve();
+    }
+    const completion = Promise.all([markerReady, beforeEnd]).then(async () => {
+      try {
+        await this.dependencies.sessionProvider.end({ sessionId, reason });
+        await this.dependencies.storage.removeItem(PENDING_END_KEY);
+      } catch {
+        // The pending-end marker remains for the next launch or online replay.
+      }
+    });
+    const termination = { markerReady, completion };
+    this.sessionTerminations.set(sessionId, termination);
+    return termination;
+  }
+
+  private async abandonGrant(grant: SdkSessionGrant) {
+    if (this.ownedSessionId === grant.sessionId) {
+      this.ownedSessionId = undefined;
+      this.grant = undefined;
+    }
+    const termination = this.ensureSessionTermination(grant.sessionId, "error");
+    const roomCleanup = this.releaseRoom(termination.markerReady);
+    await termination.markerReady;
+    if (this.disposed) {
+      await Promise.allSettled([roomCleanup, termination.completion]);
+      return;
+    }
+    await Promise.allSettled([
+      roomCleanup,
+      this.dependencies.runtime.deactivateKeepAwake(),
+      termination.completion,
+    ]);
+  }
+
+  private isOperationCurrent(generation: number) {
+    return !this.disposed && generation === this.operationGeneration;
+  }
+
+  private ensureOperation(generation: number) {
+    if (!this.isOperationCurrent(generation)) throw new StaleOperationError();
+  }
+}
+
+export { PENDING_END_KEY };