@mentra/miniapp 3.2.1-beta.319 → 3.2.1-beta.354

package/src/react/stream-preview/creditLoop.ts

@@ -0,0 +1,189 @@
+/**
+ * Consumer side of the one-frame credit scheme.
+ *
+ * The native sender holds exactly one frame in flight and will not send the next until this side
+ * acknowledges the last, so there is no queue anywhere and a slow consumer shows up as a lower
+ * frame rate rather than as growing latency. This module is the half that makes that true: parse,
+ * draw, ack — and never hold a reference to a frame after its ack.
+ *
+ * Durations here would be `performance.now()` and describe JavaScript only; the header's
+ * `timestampNs` / `sentAtNs` are a native monotonic clock with a different epoch. End-to-end
+ * latency is measured natively (it sees both the send and the ack on one clock).
+ */
+
+import {parsePreviewFrame, type ParsedFrame, type PreviewParseErrorReason} from "./protocol"
+
+export interface CreditLoopFrameSummary {
+  gen: number
+  seq: number
+  width: number
+  height: number
+  pixelFormat: string
+  rotationQuarters: number
+}
+
+export interface CreditLoopStats {
+  framesReceived: number
+  drawsSubmitted: number
+  acksSent: number
+  parseErrors: number
+  parseErrorsByReason: Partial<Record<PreviewParseErrorReason, number>>
+  /**
+   * Frames that arrived while another was still being processed. Native guarantees one at a time,
+   * so any value above zero means the credit scheme is broken.
+   */
+  overlapped: number
+  /** Frames the sender skipped, counted from gaps in the header sequence. */
+  sequenceGaps: number
+  skippedBySender: number
+  lastError: string | null
+  lastFrame: CreditLoopFrameSummary | null
+}
+
+export interface CreditLoopOptions {
+  sendAck: (gen: number, seq: number) => void
+  /**
+   * Submit the frame. Returns the submit duration in ms, or null when there is no renderer (the
+   * component is unmounted or its GL context is lost). The frame is acked either way.
+   */
+  draw?: (frame: ParsedFrame) => number | null
+  /** Called once per rejected frame, before anything else happens to it. */
+  onParseError?: (reason: PreviewParseErrorReason, detail?: string) => void
+}
+
+export class CreditLoop {
+  private readonly errorsByReason = new Map<PreviewParseErrorReason, number>()
+  private idleWaiters: Array<() => void> = []
+  private inFlightCount = 0
+  private framesReceived = 0
+  private drawsSubmitted = 0
+  private acksSent = 0
+  private parseErrors = 0
+  private overlapped = 0
+  private sequenceGaps = 0
+  private skippedBySender = 0
+  private lastSeq: number | null = null
+  private lastGen: number | null = null
+  private lastError: string | null = null
+  private lastFrame: CreditLoopFrameSummary | null = null
+  private draw: CreditLoopOptions["draw"]
+
+  constructor(private readonly options: CreditLoopOptions) {
+    this.draw = options.draw
+  }
+
+  /** Swap the renderer without touching the credit state. Null means frames are acked undrawn. */
+  setDraw(draw: CreditLoopOptions["draw"] | null): void {
+    this.draw = draw ?? undefined
+  }
+
+  /** Frames currently being processed. The credit scheme means this is 0 or 1. */
+  get inFlight(): number {
+    return this.inFlightCount
+  }
+
+  /** Entry point for the transport. Deliberately not awaited: the transport must not block. */
+  handleBinary(buffer: ArrayBuffer): void {
+    if (this.inFlightCount > 0) this.overlapped += 1
+    this.inFlightCount += 1
+    void this.process(buffer).finally(() => {
+      this.inFlightCount -= 1
+      if (this.inFlightCount === 0) {
+        const waiters = this.idleWaiters
+        this.idleWaiters = []
+        for (const resolve of waiters) resolve()
+      }
+    })
+  }
+
+  /** Resolves once nothing is being processed. */
+  idle(): Promise<void> {
+    if (this.inFlightCount === 0) return Promise.resolve()
+    return new Promise((resolve) => this.idleWaiters.push(resolve))
+  }
+
+  recordError(reason: string): void {
+    this.lastError = reason
+  }
+
+  snapshot(): CreditLoopStats {
+    const parseErrorsByReason: Partial<Record<PreviewParseErrorReason, number>> = {}
+    for (const [reason, count] of this.errorsByReason) parseErrorsByReason[reason] = count
+    return {
+      framesReceived: this.framesReceived,
+      drawsSubmitted: this.drawsSubmitted,
+      acksSent: this.acksSent,
+      parseErrors: this.parseErrors,
+      parseErrorsByReason,
+      overlapped: this.overlapped,
+      sequenceGaps: this.sequenceGaps,
+      skippedBySender: this.skippedBySender,
+      lastError: this.lastError,
+      lastFrame: this.lastFrame,
+    }
+  }
+
+  reset(): void {
+    this.framesReceived = 0
+    this.drawsSubmitted = 0
+    this.acksSent = 0
+    this.parseErrors = 0
+    this.overlapped = 0
+    this.sequenceGaps = 0
+    this.skippedBySender = 0
+    this.lastSeq = null
+    this.lastGen = null
+    this.lastError = null
+    this.lastFrame = null
+    this.errorsByReason.clear()
+  }
+
+  private async process(buffer: ArrayBuffer): Promise<void> {
+    this.framesReceived += 1
+    const parsed = parsePreviewFrame(buffer)
+    if (!parsed.ok) {
+      // No ack: a frame this side could not read is not a frame it consumed, and acking it would
+      // hide the fault behind a healthy-looking rate.
+      this.parseErrors += 1
+      this.errorsByReason.set(parsed.reason, (this.errorsByReason.get(parsed.reason) ?? 0) + 1)
+      this.lastError = parsed.detail ? `${parsed.reason} (${parsed.detail})` : parsed.reason
+      this.options.onParseError?.(parsed.reason, parsed.detail)
+      return
+    }
+    this.trackSequence(parsed)
+    this.lastFrame = {
+      gen: parsed.sessionGen,
+      seq: parsed.frameSeq,
+      width: parsed.width,
+      height: parsed.height,
+      pixelFormat: parsed.pixelFormat,
+      rotationQuarters: parsed.rotationQuarters,
+    }
+    if (this.draw) {
+      const submitMs = this.draw(parsed)
+      if (submitMs === null) this.lastError = "draw_failed"
+      else this.drawsSubmitted += 1
+    }
+    // Ack last, after the draw has been submitted, so the credit the sender gets back means "this
+    // side is done with that frame" rather than "this side received some bytes". A dead canvas
+    // still acks: withholding credit would stall the sender on top of it.
+    this.options.sendAck(parsed.sessionGen, parsed.frameSeq)
+    this.acksSent += 1
+  }
+
+  private trackSequence(parsed: ParsedFrame): void {
+    if (this.lastGen !== parsed.sessionGen) {
+      this.lastGen = parsed.sessionGen
+      this.lastSeq = parsed.frameSeq
+      return
+    }
+    if (this.lastSeq !== null) {
+      const delta = parsed.frameSeq - this.lastSeq
+      if (delta > 1) {
+        this.sequenceGaps += 1
+        this.skippedBySender += delta - 1
+      }
+    }
+    this.lastSeq = parsed.frameSeq
+  }
+}

package/src/react/stream-preview/protocol.ts

@@ -0,0 +1,227 @@
+/**
+ * Wire format for raw decoded-frame preview (`MFPV`): a 64-byte little-endian header followed by
+ * a tightly packed 8-bit YUV payload.
+ *
+ * Nothing in this module may copy the payload. `parsePreviewFrame` returns `Uint8Array` views onto
+ * the caller's ArrayBuffer and the renderer uploads those views straight to WebGL; a `.slice()`
+ * anywhere in this path turns a zero-copy preview into a per-frame memcpy.
+ *
+ * Bad input is expected — a truncated or stale frame is a measurement, not an exception — so the
+ * parser returns a discriminated union and never throws.
+ *
+ *   offset  size  field
+ *        0     4  magic "MFPV"
+ *        4     2  version u16
+ *        6     2  headerLen u16
+ *        8     4  payloadLen u32
+ *       12     4  sessionGen u32
+ *       16     4  frameSeq u32
+ *       20     2  width u16
+ *       22     2  height u16
+ *       24     1  pixelFormat u8 (1 = I420, 2 = NV12)
+ *       25     1  rotation u8 (quarter turns clockwise)
+ *       26     1  colorMatrix u8 (0 unknown, 1 BT.601, 2 BT.709)
+ *       27     1  colorRange u8 (0 unknown, 1 limited, 2 full)
+ *       28     2  flags u16 (bit 0: the sender fell back on default colour metadata)
+ *       30     2  reserved u16
+ *       32     8  timestampNs i64 (native monotonic decode time, 0 when unknown)
+ *       40     8  sentAtNs i64 (native monotonic at the send call)
+ *       48    16  reserved
+ */
+
+/** Fixed header size. A sender that disagrees is rejected rather than guessed at. */
+export const PREVIEW_FRAME_HEADER_BYTES = 64
+export const PREVIEW_FRAME_VERSION = 1
+/** ASCII "MFPV". */
+export const PREVIEW_FRAME_MAGIC = [0x4d, 0x46, 0x50, 0x56] as const
+/** Neither the glasses nor a phone camera reaches this; anything above it is a corrupt header. */
+export const PREVIEW_FRAME_MAX_DIMENSION = 4096
+
+export const PIXEL_FORMAT_I420 = 1
+export const PIXEL_FORMAT_NV12 = 2
+
+export type PreviewPixelFormat = "i420" | "nv12"
+export type PreviewColorMatrix = "bt601" | "bt709"
+export type PreviewColorRange = "limited" | "full"
+
+/**
+ * One code per rejected frame, because "the frame was bad" is not a finding. A run that drops
+ * frames on `truncated-payload` and one that drops them on `payload-size-mismatch` point at
+ * different halves of the native sender.
+ */
+export type PreviewParseErrorReason =
+  | "short-buffer"
+  | "bad-magic"
+  | "unsupported-version"
+  | "bad-header-length"
+  | "bad-dimensions"
+  | "unknown-pixel-format"
+  | "payload-size-mismatch"
+  | "truncated-payload"
+
+export const PREVIEW_PARSE_ERROR_REASONS: readonly PreviewParseErrorReason[] = [
+  "short-buffer",
+  "bad-magic",
+  "unsupported-version",
+  "bad-header-length",
+  "bad-dimensions",
+  "unknown-pixel-format",
+  "payload-size-mismatch",
+  "truncated-payload",
+]
+
+interface ParsedFrameBase {
+  ok: true
+  sessionGen: number
+  frameSeq: number
+  width: number
+  height: number
+  /** Quarter turns clockwise, normalized to 0..3. */
+  rotationQuarters: number
+  colorMatrix: PreviewColorMatrix
+  colorRange: PreviewColorRange
+  /** The header said "unknown" and BT.601 was assumed. */
+  colorMatrixAssumed: boolean
+  /** The header said "unknown" and limited range was assumed. */
+  colorRangeAssumed: boolean
+  /** Header flag bit 0: the native sender itself had to fall back on default colour metadata. */
+  senderColorFallback: boolean
+  /**
+   * Native monotonic clock, nanoseconds. Never subtract a `performance.now()` value from these:
+   * the two clocks share no epoch. Only native-to-native differences mean anything.
+   */
+  timestampNs: bigint
+  sentAtNs: bigint
+  yStride: number
+  chromaWidth: number
+  chromaHeight: number
+  chromaStride: number
+  payloadLen: number
+}
+
+export interface ParsedI420Frame extends ParsedFrameBase {
+  pixelFormat: "i420"
+  y: Uint8Array
+  u: Uint8Array
+  v: Uint8Array
+}
+
+export interface ParsedNv12Frame extends ParsedFrameBase {
+  pixelFormat: "nv12"
+  y: Uint8Array
+  /** Interleaved U,V pairs: `chromaStride` is 2 × `chromaWidth` bytes. */
+  uv: Uint8Array
+}
+
+export type ParsedFrame = ParsedI420Frame | ParsedNv12Frame
+
+export interface PreviewParseError {
+  ok: false
+  reason: PreviewParseErrorReason
+  /** Numbers the reason alone does not carry, for the log line. */
+  detail?: string
+}
+
+export type PreviewParseResult = ParsedFrame | PreviewParseError
+
+/** Chroma plane dimensions for 4:2:0, which both supported formats are. */
+export function chromaDimensions(width: number, height: number): {width: number; height: number} {
+  return {width: Math.ceil(width / 2), height: Math.ceil(height / 2)}
+}
+
+/** Bytes a tightly packed I420 or NV12 frame occupies. Both layouts are the same size. */
+export function packedPayloadBytes(width: number, height: number): number {
+  const chroma = chromaDimensions(width, height)
+  return width * height + 2 * chroma.width * chroma.height
+}
+
+function fail(reason: PreviewParseErrorReason, detail?: string): PreviewParseError {
+  return detail === undefined ? {ok: false, reason} : {ok: false, reason, detail}
+}
+
+/**
+ * Validate a frame and expose its planes.
+ *
+ * The plane fields are views onto `buffer`, so they stay valid only as long as the caller holds
+ * that buffer and nothing else writes into it.
+ */
+export function parsePreviewFrame(buffer: ArrayBuffer): PreviewParseResult {
+  if (buffer.byteLength < PREVIEW_FRAME_HEADER_BYTES) {
+    return fail("short-buffer", `${buffer.byteLength} bytes`)
+  }
+  const header = new DataView(buffer, 0, PREVIEW_FRAME_HEADER_BYTES)
+  const magic = new Uint8Array(buffer, 0, PREVIEW_FRAME_MAGIC.length)
+  if (PREVIEW_FRAME_MAGIC.some((byte, index) => magic[index] !== byte)) {
+    return fail("bad-magic", Array.from(magic, (byte) => byte.toString(16).padStart(2, "0")).join(" "))
+  }
+  const version = header.getUint16(4, true)
+  if (version !== PREVIEW_FRAME_VERSION) return fail("unsupported-version", `v${version}`)
+  const headerLen = header.getUint16(6, true)
+  if (headerLen !== PREVIEW_FRAME_HEADER_BYTES) return fail("bad-header-length", `${headerLen} bytes`)
+  const payloadLen = header.getUint32(8, true)
+  const sessionGen = header.getUint32(12, true)
+  const frameSeq = header.getUint32(16, true)
+  const width = header.getUint16(20, true)
+  const height = header.getUint16(22, true)
+  if (width === 0 || height === 0 || width > PREVIEW_FRAME_MAX_DIMENSION || height > PREVIEW_FRAME_MAX_DIMENSION) {
+    return fail("bad-dimensions", `${width}x${height}`)
+  }
+  const formatCode = header.getUint8(24)
+  if (formatCode !== PIXEL_FORMAT_I420 && formatCode !== PIXEL_FORMAT_NV12) {
+    return fail("unknown-pixel-format", `code ${formatCode}`)
+  }
+  const expectedPayload = packedPayloadBytes(width, height)
+  if (payloadLen !== expectedPayload) {
+    return fail("payload-size-mismatch", `${payloadLen} bytes, expected ${expectedPayload}`)
+  }
+  if (buffer.byteLength < headerLen + payloadLen) {
+    return fail("truncated-payload", `${buffer.byteLength - headerLen} of ${payloadLen} bytes`)
+  }
+
+  const matrixCode = header.getUint8(26)
+  const rangeCode = header.getUint8(27)
+  const flags = header.getUint16(28, true)
+  const chroma = chromaDimensions(width, height)
+  const luma = width * height
+  const base: ParsedFrameBase = {
+    ok: true,
+    sessionGen,
+    frameSeq,
+    width,
+    height,
+    rotationQuarters: header.getUint8(25) % 4,
+    // Unknown metadata is not a rejection: BT.601 limited is what an untagged 8-bit camera frame
+    // almost always is. The assumption is surfaced so a wrong-looking picture can be traced to it
+    // instead of to the shader.
+    colorMatrix: matrixCode === 2 ? "bt709" : "bt601",
+    colorRange: rangeCode === 2 ? "full" : "limited",
+    colorMatrixAssumed: matrixCode !== 1 && matrixCode !== 2,
+    colorRangeAssumed: rangeCode !== 1 && rangeCode !== 2,
+    senderColorFallback: (flags & 0x0001) !== 0,
+    timestampNs: header.getBigInt64(32, true),
+    sentAtNs: header.getBigInt64(40, true),
+    yStride: width,
+    chromaWidth: chroma.width,
+    chromaHeight: chroma.height,
+    chromaStride: formatCode === PIXEL_FORMAT_NV12 ? chroma.width * 2 : chroma.width,
+    payloadLen,
+  }
+
+  // Subviews, never copies.
+  if (formatCode === PIXEL_FORMAT_NV12) {
+    return {
+      ...base,
+      pixelFormat: "nv12",
+      y: new Uint8Array(buffer, headerLen, luma),
+      uv: new Uint8Array(buffer, headerLen + luma, 2 * chroma.width * chroma.height),
+    }
+  }
+  const chromaPlane = chroma.width * chroma.height
+  return {
+    ...base,
+    pixelFormat: "i420",
+    y: new Uint8Array(buffer, headerLen, luma),
+    u: new Uint8Array(buffer, headerLen + luma, chromaPlane),
+    v: new Uint8Array(buffer, headerLen + luma + chromaPlane, chromaPlane),
+  }
+}

package/src/react/stream-preview/resizeCoalescer.ts

@@ -0,0 +1,88 @@
+/**
+ * Collapse a stream of box measurements into the few that matter.
+ *
+ * A layout animation fires ResizeObserver every frame. Bursts inside one frame are merged with
+ * `requestAnimationFrame`, and a size is only applied once it has held still for the settle
+ * window. Hiding (a zero box) and the first measurement apply at once: the first so the preview
+ * starts without a delay, hiding so production stops as soon as nobody can see it.
+ */
+
+export interface PreviewBox {
+  width: number
+  height: number
+}
+
+export interface ResizeCoalescerOptions {
+  apply: (box: PreviewBox) => void
+  settleMs?: number
+  requestFrame?: (cb: () => void) => unknown
+  setTimer?: (cb: () => void, ms: number) => unknown
+  clearTimer?: (handle: unknown) => void
+}
+
+export const RESIZE_SETTLE_MS = 250
+
+function isZero(box: PreviewBox): boolean {
+  return !(box.width > 0) || !(box.height > 0)
+}
+
+export class ResizeCoalescer {
+  private latest: PreviewBox | null = null
+  private lastApplied: PreviewBox | null = null
+  private framePending = false
+  private timer: unknown = null
+  private cancelled = false
+  private readonly settleMs: number
+  private readonly requestFrame: (cb: () => void) => unknown
+  private readonly setTimer: (cb: () => void, ms: number) => unknown
+  private readonly clearTimer: (handle: unknown) => void
+
+  constructor(private readonly options: ResizeCoalescerOptions) {
+    this.settleMs = options.settleMs ?? RESIZE_SETTLE_MS
+    this.requestFrame =
+      options.requestFrame ??
+      ((cb) => (typeof requestAnimationFrame === "function" ? requestAnimationFrame(() => cb()) : setTimeout(cb, 16)))
+    this.setTimer = options.setTimer ?? ((cb, ms) => setTimeout(cb, ms))
+    this.clearTimer = options.clearTimer ?? ((handle) => clearTimeout(handle as ReturnType<typeof setTimeout>))
+  }
+
+  push(box: PreviewBox): void {
+    if (this.cancelled) return
+    this.latest = box
+    if (!this.lastApplied || isZero(box) || isZero(this.lastApplied)) {
+      this.clearSettle()
+      this.applyLatest()
+      return
+    }
+    if (this.framePending) return
+    this.framePending = true
+    this.requestFrame(() => {
+      this.framePending = false
+      if (this.cancelled) return
+      this.clearSettle()
+      this.timer = this.setTimer(() => {
+        this.timer = null
+        this.applyLatest()
+      }, this.settleMs)
+    })
+  }
+
+  cancel(): void {
+    this.cancelled = true
+    this.clearSettle()
+  }
+
+  private applyLatest(): void {
+    const box = this.latest
+    if (!box || this.cancelled) return
+    if (this.lastApplied && this.lastApplied.width === box.width && this.lastApplied.height === box.height) return
+    this.lastApplied = box
+    this.options.apply(box)
+  }
+
+  private clearSettle(): void {
+    if (this.timer === null) return
+    this.clearTimer(this.timer)
+    this.timer = null
+  }
+}

package/src/react/stream-preview/testFrames.ts

@@ -0,0 +1,86 @@
+/**
+ * Build `MFPV` frames for tests. Lives beside the parser so the golden-bytes test and the parser
+ * cannot drift apart silently. Not exported from the package entry.
+ */
+
+import {
+  chromaDimensions,
+  packedPayloadBytes,
+  PIXEL_FORMAT_I420,
+  PIXEL_FORMAT_NV12,
+  PREVIEW_FRAME_HEADER_BYTES,
+  PREVIEW_FRAME_MAGIC,
+  PREVIEW_FRAME_VERSION,
+  type PreviewPixelFormat,
+} from "./protocol"
+
+export interface BuildPreviewFrameOptions {
+  width?: number
+  height?: number
+  pixelFormat?: PreviewPixelFormat
+  sessionGen?: number
+  frameSeq?: number
+  rotationQuarters?: number
+  /** Raw header codes so a test can send "unknown" (0) and check the fallback. */
+  colorMatrixCode?: number
+  colorRangeCode?: number
+  flags?: number
+  timestampNs?: bigint
+  sentAtNs?: bigint
+  /** Byte written into every sample of each plane, so plane views can be told apart. */
+  fill?: {y?: number; u?: number; v?: number}
+  /** Deliberate corruption, for the rejection tests. Every field overrides what would be written. */
+  corrupt?: {
+    magic?: readonly number[]
+    version?: number
+    headerLen?: number
+    payloadLen?: number
+    /** Payload bytes actually appended, independent of the declared `payloadLen`. */
+    payloadBytes?: number
+    pixelFormatCode?: number
+  }
+}
+
+/** Build a wire-format frame. */
+export function buildPreviewFrame(options: BuildPreviewFrameOptions = {}): ArrayBuffer {
+  const width = options.width ?? 1280
+  const height = options.height ?? 720
+  const pixelFormat = options.pixelFormat ?? "i420"
+  const corrupt = options.corrupt ?? {}
+  const chroma = chromaDimensions(width, height)
+  const declaredPayload = corrupt.payloadLen ?? packedPayloadBytes(width, height)
+  const actualPayload = corrupt.payloadBytes ?? packedPayloadBytes(width, height)
+  const buffer = new ArrayBuffer(PREVIEW_FRAME_HEADER_BYTES + actualPayload)
+  const header = new DataView(buffer, 0, PREVIEW_FRAME_HEADER_BYTES)
+  const magic = corrupt.magic ?? PREVIEW_FRAME_MAGIC
+  for (let index = 0; index < 4; index += 1) header.setUint8(index, magic[index] ?? 0)
+  header.setUint16(4, corrupt.version ?? PREVIEW_FRAME_VERSION, true)
+  header.setUint16(6, corrupt.headerLen ?? PREVIEW_FRAME_HEADER_BYTES, true)
+  header.setUint32(8, declaredPayload, true)
+  header.setUint32(12, options.sessionGen ?? 1, true)
+  header.setUint32(16, options.frameSeq ?? 1, true)
+  header.setUint16(20, width, true)
+  header.setUint16(22, height, true)
+  header.setUint8(24, corrupt.pixelFormatCode ?? (pixelFormat === "nv12" ? PIXEL_FORMAT_NV12 : PIXEL_FORMAT_I420))
+  header.setUint8(25, options.rotationQuarters ?? 0)
+  header.setUint8(26, options.colorMatrixCode ?? 1)
+  header.setUint8(27, options.colorRangeCode ?? 1)
+  header.setUint16(28, options.flags ?? 0, true)
+  header.setBigInt64(32, options.timestampNs ?? 0n, true)
+  header.setBigInt64(40, options.sentAtNs ?? 0n, true)
+
+  const payload = new Uint8Array(buffer, PREVIEW_FRAME_HEADER_BYTES)
+  const luma = Math.min(width * height, payload.length)
+  const chromaPlane = chroma.width * chroma.height
+  payload.fill(options.fill?.y ?? 0x80, 0, luma)
+  if (pixelFormat === "nv12") {
+    for (let index = luma; index + 1 < payload.length; index += 2) {
+      payload[index] = options.fill?.u ?? 0x40
+      payload[index + 1] = options.fill?.v ?? 0xc0
+    }
+  } else {
+    payload.fill(options.fill?.u ?? 0x40, luma, Math.min(luma + chromaPlane, payload.length))
+    payload.fill(options.fill?.v ?? 0xc0, Math.min(luma + chromaPlane, payload.length))
+  }
+  return buffer
+}

package/src/react/stream-preview/tiers.ts

@@ -0,0 +1,37 @@
+/**
+ * Preview sizing tiers.
+ *
+ * The page measures its box (CSS pixels × devicePixelRatio, after rotation) and only tells the
+ * host when the quantized tier changes, so a resize storm costs at most one reconfigure per tier.
+ * The host quantizes again with the same table and is the authority; native never upscales.
+ */
+
+export interface PreviewTier {
+  width: number
+  height: number
+  maxFps: number
+}
+
+/** Smallest first. The last entry is the ceiling until measurements justify raising it. */
+export const PREVIEW_TIERS: readonly PreviewTier[] = [
+  {width: 320, height: 180, maxFps: 15},
+  {width: 640, height: 360, maxFps: 15},
+]
+
+/**
+ * The smallest tier that covers the box, capped at the ceiling. A zero-area box means the preview
+ * is hidden and returns null.
+ */
+export function quantizePreviewTier(boxWidth: number, boxHeight: number): PreviewTier | null {
+  if (!(boxWidth > 0) || !(boxHeight > 0)) return null
+  for (const tier of PREVIEW_TIERS) {
+    if (tier.width >= boxWidth && tier.height >= boxHeight) return tier
+  }
+  return PREVIEW_TIERS[PREVIEW_TIERS.length - 1]!
+}
+
+export function sameTier(a: PreviewTier | null, b: PreviewTier | null): boolean {
+  if (a === b) return true
+  if (!a || !b) return false
+  return a.width === b.width && a.height === b.height && a.maxFps === b.maxFps
+}