// rnx record upload — capture the currently-loaded bundle + device spec from
// a running rnx sim and POST it to the Contrast upload endpoint. returns a
// /preview/<id> url that anyone can open to load this bundle in a frame.
//
// uploads are unlisted-public (unguessable id) but require a signed-in
// desktop session so the share is associated with the user's account.

import { createHash } from 'crypto'
import { readFileSync } from 'fs'
import path from 'path'
import { gzipSync, gunzipSync } from 'zlib'
import { shouldCompress } from 'sootsim-engine/preview/compress'
import { brotliBundle } from 'sootsim-engine/preview/compress-node'
import {
  runPresignedUpload,
  type InitRequestBody,
} from 'sootsim-engine/preview/presigned-upload'
import {
  TRACE_CAPTURE_POSTROLL_MS,
  TRACE_CAPTURE_PREROLL_MS,
  isTraceTimelineEvent,
  parseTraceTimelineJsonl,
} from 'sootsim-engine/preview/trace'
import { rnxPublicBrand } from '../../src/public-brand'
import { fetchAppFontFiles } from '../app-fonts'
import { fetchAppSplashImages } from '../app-splash'
import { authHeaderValue, githubUploadIdentity, resolveCliAuth } from '../auth'
import { openUrl } from '../open-url'
import { resolveRunProvenance } from '../run-registry'
import { rnxExit } from '../run-rnx'
import {
  callInBridge,
  createBridgeFromParsed,
  evalInBridge,
  parseBridgeCliArgs,
} from '../ws-bridge'
import type { SootSimTimelineEvent } from '@rnx/globals'

interface UploadOptions {
  port?: number
  verbose?: boolean
}

export type UploadResult = {
  previewUrl: string
  shareId: string
}

// pull the server's human-readable `message` out of a JSON error body so the
// CLI can print it directly instead of dumping the raw `{"error":...}` blob.
function parseServerMessage(responseText?: string): string | null {
  if (!responseText) return null
  try {
    const body = JSON.parse(responseText) as { message?: unknown }
    return typeof body.message === 'string' && body.message ? body.message : null
  } catch {
    return null
  }
}

type BundleSnapshot = {
  bundleUrl: string | null
  entry: string | null
  deviceSpec: InitRequestBody['deviceSpec']
  runtimeVersion: string | null
  pageHref: string
  transformedBundle: {
    url: string
    byteLength: number
    timestamp: number
  } | null
}

type AttachedInteractionSnapshot = {
  meta: NonNullable<InitRequestBody['snapshots']>[number] & { id: string }
  bytes: Uint8Array
}

function readSnapshotManifest(manifestPath: string): AttachedInteractionSnapshot[] {
  const parsed: unknown = JSON.parse(readFileSync(manifestPath, 'utf8'))
  if (!Array.isArray(parsed)) throw new Error('snapshot manifest must be an array')
  const seen = new Set<string>()
  return parsed.map((entry, index) => {
    if (entry === null || typeof entry !== 'object') {
      throw new Error(`snapshot manifest entry ${index} must be an object`)
    }
    const id = Reflect.get(entry, 'id')
    const label = Reflect.get(entry, 'label')
    const filePath = Reflect.get(entry, 'path')
    const t = Reflect.get(entry, 't')
    if (typeof id !== 'string' || !id || seen.has(id)) {
      throw new Error(`snapshot manifest entry ${index} has an invalid or duplicate id`)
    }
    if (typeof filePath !== 'string' || !filePath) {
      throw new Error(`snapshot manifest entry ${index} has no PNG path`)
    }
    if (typeof t !== 'number' || !Number.isFinite(t) || t < 0) {
      throw new Error(`snapshot manifest entry ${index} has an invalid capture time`)
    }
    seen.add(id)
    const bytes = readFileSync(filePath)
    return {
      meta: {
        id,
        label: typeof label === 'string' && label ? label : id,
        kind: 'interaction',
        t: Math.round(t),
        contentType: 'image/png',
        sizeBytes: bytes.byteLength,
      },
      bytes,
    }
  })
}

const REMOTE_DEFAULT_ORIGIN = process.env.RNX_UPLOAD_ORIGIN || 'https://contrast.dev'
// the canonical public preview link. Uploads go to the contrast backend, but
// reviewers/users open rnx preview pages on rnxsim.com.
const REMOTE_DEFAULT_PUBLIC_PREVIEW_ORIGIN =
  process.env.RNX_PREVIEW_ORIGIN || rnxPublicBrand.origin
export async function resolveDefaultUploadOrigin(
  explicitOrigin?: string,
): Promise<string> {
  if (explicitOrigin) return explicitOrigin
  if (process.env.RNX_UPLOAD_ORIGIN) return process.env.RNX_UPLOAD_ORIGIN
  return REMOTE_DEFAULT_ORIGIN
}

function normalizeOrigin(origin: string): string {
  return origin.replace(/\/$/, '')
}

function isLoopbackOrigin(origin: string): boolean {
  try {
    const parsed = new URL(origin)
    const hostname = parsed.hostname.replace(/^\[|\]$/g, '').toLowerCase()
    return (
      hostname === 'localhost' ||
      hostname.endsWith('.localhost') ||
      hostname === '0.0.0.0' ||
      hostname === '::1' ||
      /^127(?:\.\d{1,3}){3}$/.test(hostname)
    )
  } catch {
    return false
  }
}

function isContrastOrigin(origin: string): boolean {
  try {
    const hostname = new URL(origin).hostname.toLowerCase()
    return hostname === 'contrast.dev' || hostname.endsWith('.contrast.dev')
  } catch {
    return false
  }
}

export function resolvePublicPreviewOrigin(
  uploadOrigin: string,
  explicitOrigin?: string,
): string {
  if (explicitOrigin) return normalizeOrigin(explicitOrigin)
  if (process.env.RNX_PREVIEW_ORIGIN) {
    return normalizeOrigin(process.env.RNX_PREVIEW_ORIGIN)
  }
  if (isLoopbackOrigin(uploadOrigin)) return normalizeOrigin(uploadOrigin)
  if (isContrastOrigin(uploadOrigin)) {
    return normalizeOrigin(REMOTE_DEFAULT_PUBLIC_PREVIEW_ORIGIN)
  }
  return normalizeOrigin(uploadOrigin)
}

function printHelp() {
  console.log(`
rnx record upload — publish the current recorded bundle as a /preview/<id> link

usage:
  rnx record upload [--origin <url>] [--public-origin <url>] (--events <path> | --video <path>) [--screenshot <path>] [--owner <org> --repo <repo>] [--sim <sim>] [--open] [--assets-only]

options:
  --origin <url>     upload target (default: ${REMOTE_DEFAULT_ORIGIN})
                     override with RNX_UPLOAD_ORIGIN env var
  --public-origin <url>
                     public /preview link origin (default: ${REMOTE_DEFAULT_PUBLIC_PREVIEW_ORIGIN}
                     for prod uploads, upload origin for localhost/custom origins).
                     override with RNX_PREVIEW_ORIGIN env var
  --events <path>    path to a gzipped events .jsonl.gz file to attach
                     required unless --video is present; previews must
                     have replay or recording playback data
  --screenshot <path>
                     path to a PNG thumbnail to attach to the share
  --snapshot-manifest <path>
                     JSON manifest of existing interaction PNGs to attach
  --video <path>     path to a mp4/gif flow recording. embedded inline
                     in the pr sticky comment served at
                     /api/preview/flow-video?id=<share-id>
  --video-duration-ms <ms>
                     duration hint for attached flow video
  --timeline-events <path>
                     extra trace timeline rows, JSONL or JSONL gz
  --trace-frame-stats <path>
                     frame stats JSON returned by the recorder bridge
  --failure-bundle <dir>
                     per-failure debug bundle dir written by the flow runner
                     (error.json, describe.json, a11y.txt, tree.txt,
                     console.json, screenshot.png). uploaded with the share
                     so failed CI runs are debuggable from the dashboard
  --owner <org>      associate a session upload with a linked org repo
  --repo <repo>      repo name for --owner; the signed-in user must belong
                     to the local/org team that owns the link
  --billing-kind test_run
                     meter this upload as a natural-language test run
  --sim <sim>        target a specific sim (see: rnx list)
  --open             open the resulting /preview/<id> url in the browser
  --assets-only      drop API/JSON/HTML records before upload; keep images,
                     fonts, css, js, and binary blobs. live-data demos hit
                     the real network at replay time instead of serving
                     recorded API snapshots
  -h, --help

examples:
  rnx record upload --events ./my-session.jsonl.gz
  rnx record upload --origin https://contrast.localhost:3000 --events ./my-session.jsonl.gz --open
  rnx record upload --video /tmp/rnx-flow.mp4 --video-duration-ms 12000
`)
}

function extractStringFlag(args: string[], name: string): string | undefined {
  const idx = args.findIndex((a) => a === name)
  if (idx < 0) return undefined
  const value = args[idx + 1]
  args.splice(idx, 2)
  return value
}

function extractBoolFlag(args: string[], name: string): boolean {
  const idx = args.findIndex((a) => a === name)
  if (idx < 0) return false
  args.splice(idx, 1)
  return true
}

function parsePositiveMs(raw: string | undefined, name: string): number | undefined {
  if (!raw) return undefined
  const value = Number(raw)
  if (!Number.isFinite(value) || value <= 0) {
    console.error(`  invalid ${name}: ${raw}`)
    rnxExit(1)
  }
  return Math.round(value)
}

// mirrors fetch-recorder.ts#isAssetContentType — kept in sync manually.
// applied when --assets-only is set so the client-side filter matches what
// the recorder would have captured in assets-only mode.
function isAssetContentType(rawContentType: string): boolean {
  const ct = (rawContentType || '').toLowerCase().split(';')[0].trim()
  if (!ct) return false
  if (
    ct.startsWith('image/') ||
    ct.startsWith('font/') ||
    ct.startsWith('video/') ||
    ct.startsWith('audio/') ||
    ct.startsWith('model/')
  )
    return true
  if (ct === 'text/css') return true
  if (ct === 'application/javascript' || ct === 'text/javascript') return true
  if (ct === 'application/wasm') return true
  if (ct === 'application/font-woff' || ct === 'application/font-woff2') return true
  if (ct === 'application/octet-stream') return true
  return false
}

async function fetchBytes(url: string): Promise<Uint8Array> {
  const res = await fetch(url)
  if (!res.ok) {
    throw new Error(`fetch ${url} -> ${res.status} ${res.statusText}`)
  }
  return new Uint8Array(await res.arrayBuffer())
}

function guessBundleContentType(url: string): string {
  if (/\.bundle($|\?)/.test(url)) return 'application/javascript'
  if (/\.js($|\?)/.test(url)) return 'application/javascript'
  if (/\.zip($|\?)/.test(url)) return 'application/zip'
  return 'application/javascript'
}

function appFontsWireFromPageHref(pageHref: string): string {
  try {
    return new URL(pageHref).searchParams.get('appFonts') || ''
  } catch {
    return ''
  }
}

function appSplashWireFromPageHref(pageHref: string): string {
  try {
    return new URL(pageHref).searchParams.get('appSplash') || ''
  } catch {
    return ''
  }
}

// metro serves a self-contained bundle when lazy=false. rewrite the
// bundle URL to force that so the captured JS has every chunk inlined.
function forceInlineBundle(bundleUrl: string): string {
  try {
    const u = new URL(bundleUrl)
    if (u.searchParams.get('lazy') === 'true') {
      u.searchParams.set('lazy', 'false')
      return u.toString()
    }
    return bundleUrl
  } catch {
    return bundleUrl
  }
}

// pull the retained transformed bundle over the bridge in slices. a single
// message carrying tens of MB hits the ws framing cap, so this pages the
// bytes in. the page holds the bundle as a Blob, so the slices are byte
// ranges: collect the bytes and decode once at the end, because decoding
// each slice on its own would split multi-byte characters at the seams.
async function pullTransformedBundle(
  bridge: ReturnType<typeof createBridgeFromParsed>,
  byteLength: number,
): Promise<string | null> {
  const CHUNK = 1_000_000 // ~1.33 MB of base64 per call
  const pieces: Uint8Array[] = []
  let total = 0
  for (let offset = 0; offset < byteLength; offset += CHUNK) {
    const end = Math.min(offset + CHUNK, byteLength)
    const chunk = await callInBridge<string | null>(
      bridge,
      'SootSim.bridges.readTransformedBundleSlice',
      offset,
      end,
    )
    if (typeof chunk !== 'string') return null
    const bytes = Uint8Array.from(atob(chunk), (c) => c.charCodeAt(0))
    pieces.push(bytes)
    total += bytes.length
  }
  const joined = new Uint8Array(total)
  let at = 0
  for (const piece of pieces) {
    joined.set(piece, at)
    at += piece.length
  }
  return new TextDecoder().decode(joined)
}

type RecordedEntry = {
  url: string
  urlhash: string
  method?: string
  bodyHash?: string
  requestVaryHash?: string
  status: number
  contentType: string
  responseHeaders?: Array<{ name: string; value: string }>
  size: number
}

type RecordedFetch = RecordedEntry & {
  bodyBase64: string
}

function traceTimelineQuery(args: {
  recordedDurationMs?: number
  recordingStartedAtMs?: number
}): { since?: number; until?: number; limit: number } {
  if (args.recordedDurationMs && args.recordingStartedAtMs) {
    return {
      since: args.recordingStartedAtMs - TRACE_CAPTURE_PREROLL_MS,
      until:
        args.recordingStartedAtMs + args.recordedDurationMs + TRACE_CAPTURE_POSTROLL_MS,
      limit: 2000,
    }
  }
  return { limit: 2000 }
}

function readTraceTimelineEventsFile(filePath: string): SootSimTimelineEvent[] {
  const bytes = readFileSync(filePath)
  const isGzip = bytes[0] === 0x1f && bytes[1] === 0x8b
  const text = (isGzip ? gunzipSync(bytes) : bytes).toString('utf8')
  return parseTraceTimelineJsonl(text)
}

function readTraceFrameStatsFile(filePath: string): unknown {
  return JSON.parse(readFileSync(filePath, 'utf8'))
}

function frameRowsFromStats(frameStats: unknown): SootSimTimelineEvent[] {
  if (frameStats === null || typeof frameStats !== 'object') return []
  const record = frameStats as { startedAtEpochMs?: unknown; samples?: unknown }
  const startedAt =
    typeof record.startedAtEpochMs === 'number' && record.startedAtEpochMs > 0
      ? record.startedAtEpochMs
      : null
  if (startedAt === null || !Array.isArray(record.samples)) return []
  const rows: SootSimTimelineEvent[] = []
  for (const sample of record.samples) {
    if (!Array.isArray(sample) || typeof sample[0] !== 'number') continue
    const num = (value: unknown) =>
      typeof value === 'number' && Number.isFinite(value)
        ? Math.round(value * 100) / 100
        : 0
    rows.push({
      schemaVersion: 1,
      t: startedAt + Math.round(sample[0]),
      seq: rows.length + 1,
      context: 'tenant',
      kind: 'frame',
      data: {
        totalMs: num(sample[1]),
        layoutMs: num(sample[2]),
        renderMs: num(sample[3]),
        copyMs: num(sample[4]),
      },
    })
  }
  return rows
}

function frameStatsMeta(frameStats: unknown): unknown {
  if (frameStats === null || typeof frameStats !== 'object') return frameStats
  const { samples: _samples, ...aggregates } = frameStats as {
    samples?: unknown
    [key: string]: unknown
  }
  return aggregates
}

function mergeRecordedEntries<T extends { url: string; urlhash?: string }>(
  entries: T[],
): T[] {
  const merged = new Map<string, T>()
  for (const entry of entries) {
    merged.set(entry.urlhash || entry.url, entry)
  }
  return Array.from(merged.values())
}

export async function runUpload(
  args: string[],
  _opts: UploadOptions,
): Promise<UploadResult> {
  if (args.includes('--help') || args.includes('-h')) {
    printHelp()
    rnxExit(0)
  }

  const mutableArgs = [...args]
  const origin = await resolveDefaultUploadOrigin(
    extractStringFlag(mutableArgs, '--origin'),
  )
  const publicOrigin = resolvePublicPreviewOrigin(
    origin,
    extractStringFlag(mutableArgs, '--public-origin'),
  )
  const eventsPath = extractStringFlag(mutableArgs, '--events')
  const screenshotPath = extractStringFlag(mutableArgs, '--screenshot')
  const snapshotManifestPath = extractStringFlag(mutableArgs, '--snapshot-manifest')
  const videoPath = extractStringFlag(mutableArgs, '--video')
  const timelineEventsPath = extractStringFlag(mutableArgs, '--timeline-events')
  const traceFrameStatsPath = extractStringFlag(mutableArgs, '--trace-frame-stats')
  const failureBundleDir = extractStringFlag(mutableArgs, '--failure-bundle')
  const videoDurationMsRaw = extractStringFlag(mutableArgs, '--video-duration-ms')
  const recordedDurationMs = parsePositiveMs(
    extractStringFlag(mutableArgs, '--recorded-duration-ms'),
    '--recorded-duration-ms',
  )
  const recordingStartedAtMs = parsePositiveMs(
    extractStringFlag(mutableArgs, '--recording-started-at-ms'),
    '--recording-started-at-ms',
  )
  const owner = extractStringFlag(mutableArgs, '--owner')
  const repo = extractStringFlag(mutableArgs, '--repo')
  const billingKind = extractStringFlag(mutableArgs, '--billing-kind')
  const runScope = extractStringFlag(mutableArgs, '--run-scope')
  const openResult = extractBoolFlag(mutableArgs, '--open')
  if ((owner && !repo) || (!owner && repo)) {
    console.error('  --owner and --repo must be provided together')
    rnxExit(1)
  }
  if (billingKind && billingKind !== 'test_run') {
    console.error(`  invalid --billing-kind: ${billingKind}`)
    rnxExit(1)
  }
  if (!eventsPath && !videoPath) {
    console.error(
      '  preview uploads require playback data: pass --events or --video.\n' +
        '  for a normal local preview, use `rnx record --mode combined --open`\n' +
        '  or `rnx maestro test --preview` instead of uploading a bundle-only snapshot.',
    )
    rnxExit(1)
  }
  // assets-only filters captured cross-origin responses to just image/font/
  // css/js/binary records before upload — API responses (JSON, HTML) hit the
  // live network at replay time. used by the home demo-app capture so
  // demos stay fresh (token prices, feeds) instead of serving snapshots.
  const assetsOnly = extractBoolFlag(mutableArgs, '--assets-only')

  const parsed = parseBridgeCliArgs(mutableArgs, {
    stripBooleanFlags: [],
    stripValueFlags: [],
  })

  const bridge = createBridgeFromParsed(parsed)
  let snapshot: BundleSnapshot
  // bundle-origin manifest (no bodies) — CLI re-fetches these over http so
  // they can be large without blowing the ws frame cap. sibling bundle
  // chunks and static assets from the dev server.
  let manifest: RecordedEntry[] = []
  // cross-origin fetches with bodies already captured in-memory (clerk,
  // supabase, the app's api worker, etc.). the dev bundle's auth and
  // cookies were on *its* session; re-fetching those urls from a fresh
  // node process would fail or get different payloads. use the recorded
  // response so replay is deterministic and prod-viable.
  let recordedFetches: RecordedFetch[] = []
  let traceTimelineEvents: SootSimTimelineEvent[] = timelineEventsPath
    ? readTraceTimelineEventsFile(timelineEventsPath)
    : []
  const traceFrameStats = traceFrameStatsPath
    ? readTraceFrameStatsFile(traceFrameStatsPath)
    : null
  traceTimelineEvents.push(...frameRowsFromStats(traceFrameStats))
  const localTraceTimelineCount = traceTimelineEvents.length
  let transformedBundleText: string | null = null
  try {
    snapshot = await evalInBridge<BundleSnapshot>(
      bridge,
      '(typeof window.__sootsimCaptureBundle === "function") ? window.__sootsimCaptureBundle() : null',
    )
    if (snapshot?.bundleUrl) {
      const bundleOrigin = new URL(snapshot.bundleUrl).origin
      // manifest stays the body-less re-fetch path for bundle-origin static
      // assets (chunks, fonts, wasm). bundle-origin api endpoints would also
      // land here after the recorder's /__app-api unwrap, but re-fetching
      // them from the dev server fails (no session cookies) — they get
      // pulled with bodies via the recordedFetches dump below instead.
      const [mainManifest, workerManifest] = await Promise.all([
        evalInBridge<RecordedEntry[]>(
          bridge,
          `(async () => {
            const rec = window.__sootsimPreviewRecorder
            await rec?.flush?.()
            return rec?.list?.(${JSON.stringify(bundleOrigin)}) || []
          })()`,
        ),
        evalInBridge<RecordedEntry[]>(
          bridge,
          `(async () => {
            const list = window.__sootsimListWorkerFetchRecorder
            return typeof list === 'function'
              ? await list(${JSON.stringify(bundleOrigin)})
              : []
          })()`,
        ),
      ])
      manifest = mergeRecordedEntries([...mainManifest, ...workerManifest]).filter(
        (entry) => {
          try {
            return !new URL(entry.url).pathname.startsWith('/api/')
          } catch {
            return true
          }
        },
      )
      // dump everything recorded, filter to cross-origin. these carry
      // response bodies (base64), which can exceed the ws frame cap for
      // large responses — gate on count + size before pulling.
      const recorderLists = await evalInBridge<{
        main: RecordedEntry[]
        worker: RecordedEntry[]
      } | null>(
        bridge,
        `(async () => {
          const rec = window.__sootsimPreviewRecorder
          const workerList = window.__sootsimListWorkerFetchRecorder
          await rec?.flush?.()
          return {
            main: rec?.list ? rec.list() : [],
            worker: typeof workerList === 'function' ? await workerList() : [],
          }
        })()`,
      )
      const allRecordedEntries = recorderLists
        ? mergeRecordedEntries([...recorderLists.main, ...recorderLists.worker])
        : []
      const crossOriginEntries = allRecordedEntries.filter((entry) => {
        try {
          return new URL(entry.url).origin !== bundleOrigin
        } catch {
          return false
        }
      })
      const crossOriginStats =
        crossOriginEntries.length > 0
          ? {
              count: crossOriginEntries.length,
              totalBytes: crossOriginEntries.reduce((n, e) => n + (e.size || 0), 0),
            }
          : null
      if (crossOriginStats && crossOriginStats.count > 0) {
        console.log(
          `  ${crossOriginStats.count} recorded cross-origin responses ` +
            `(${(crossOriginStats.totalBytes / 1024).toFixed(1)} KiB)`,
        )
        // fetch the full records (with bodies). limit to ~20 MiB total —
        // if we're over, warn and truncate. most dev sessions are well
        // under this.
        // also pull bundle-origin-keyed api responses with bodies so the
        // upload can use them instead of re-fetching from the dev server
        // (which fails with 401 because the cli has no auth context). main
        // bundle + static assets stay on the manifest re-fetch path.
        const dumped = await evalInBridge<{
          main: RecordedFetch[]
          worker: RecordedFetch[]
        }>(
          bridge,
          `(async () => {
            const rec = window.__sootsimPreviewRecorder
            const workerDump = window.__sootsimDumpWorkerFetchRecorder
            const bundleUrl = ${JSON.stringify(snapshot.bundleUrl)}
            await rec?.flush?.()
            const keep = (r) => {
              try {
                const u = new URL(r.url)
                if (u.origin !== ${JSON.stringify(bundleOrigin)}) return true
                // bundle-origin api responses came from the rewritten
                // /__app-api proxy at record time (re-keyed by the
                // recorder's unwrap step). they need bodies attached the
                // same way as cross-origin records — direct re-fetch from
                // the dev server lacks the bundle's session cookies.
                if (r.url !== bundleUrl && u.pathname.startsWith('/api/')) return true
                return false
              } catch { return false }
            }
            return {
              main: rec?.dump ? rec.dump().filter(keep) : [],
              worker: typeof workerDump === 'function'
                ? (await workerDump()).filter(keep)
                : [],
            }
          })()`,
        )
        recordedFetches = mergeRecordedEntries([...dumped.main, ...dumped.worker])
        if (assetsOnly) {
          const before = recordedFetches.length
          recordedFetches = recordedFetches.filter((r) =>
            isAssetContentType(r.contentType),
          )
          const droppedBytes =
            crossOriginStats.totalBytes -
            recordedFetches.reduce((n, r) => n + (r.size || 0), 0)
          console.log(
            `  --assets-only: kept ${recordedFetches.length}/${before} records ` +
              `(dropped ${(droppedBytes / 1024).toFixed(1)} KiB of API responses)`,
          )
        }
      }
    }
    if (snapshot?.transformedBundle) {
      transformedBundleText = await pullTransformedBundle(
        bridge,
        snapshot.transformedBundle.byteLength,
      )
    }
    const timelineResult = await evalInBridge<{ events?: unknown[] } | null>(
      bridge,
      `(() => {
        const bridge = window.SootSim?.bridges?.timeline ?? window.__sootsimTimeline
        if (!bridge || typeof bridge.recent !== 'function') return null
        return bridge.recent(${JSON.stringify(
          traceTimelineQuery({ recordedDurationMs, recordingStartedAtMs }),
        )})
      })()`,
    ).catch((err: unknown) => {
      console.warn(
        `  warning: failed to capture trace timeline: ${
          err instanceof Error ? err.message : String(err)
        }`,
      )
      return null
    })
    const timelineEvents = Array.isArray(timelineResult?.events)
      ? timelineResult.events
      : []
    traceTimelineEvents = [
      ...traceTimelineEvents,
      ...timelineEvents.filter(isTraceTimelineEvent),
    ].sort((a, b) => a.t - b.t || a.seq - b.seq)
  } finally {
    bridge.close()
  }

  if (!snapshot) {
    console.error(
      '  could not read bundle snapshot — is rnx running and is the bundle loaded?',
    )
    rnxExit(2)
  }
  if (!snapshot.bundleUrl) {
    console.error(
      '  no ?bundle= URL on the current rnx tab.\n' +
        '  open the app you want to share first (e.g. rnx open 8082), then run upload.',
    )
    rnxExit(2)
  }

  // prefer the post-transform bundle captured from the running tab. this
  // is what actually evaluated — preview replay evaluates the same JS and
  // does not have to re-run sootsim's transforms. fall back to re-fetching
  // the raw metro URL + forcing lazy=false when the transform hasn't
  // published yet (e.g., tab was opened but bundle not finished loading).
  let bundleBytes: Uint8Array
  let isTransformed = false
  if (transformedBundleText !== null) {
    bundleBytes = new TextEncoder().encode(transformedBundleText)
    isTransformed = true
    console.log(
      `  using post-transform bundle: ${(bundleBytes.byteLength / 1024).toFixed(1)} KiB`,
    )
  } else {
    const fetchBundleUrl = forceInlineBundle(snapshot.bundleUrl)
    if (fetchBundleUrl !== snapshot.bundleUrl) {
      console.log(`  forcing lazy=false for self-contained bundle`)
    }
    console.log(`  capturing: ${fetchBundleUrl}`)
    bundleBytes = await fetchBytes(fetchBundleUrl)
    console.log(`  main bundle: ${(bundleBytes.byteLength / 1024).toFixed(1)} KiB`)
  }

  // everything else captured becomes a side file served from R2 via the
  // preview page's service worker. skip the main bundle (already sent).
  let extraEntries = manifest.filter((r) => r.url !== snapshot.bundleUrl)
  if (assetsOnly) {
    extraEntries = extraEntries.filter((r) => isAssetContentType(r.contentType))
  }
  console.log(`  fetching ${extraEntries.length} extra files…`)

  // fetch all extras in parallel (all localhost or proxy-passthrough).
  // each is small-to-medium; keep it simple, no concurrency cap needed
  // for typical v1 payloads.
  const extras = await Promise.all(
    extraEntries.map(async (entry) => {
      try {
        const bytes = await fetchBytes(entry.url)
        return { ...entry, bytes }
      } catch (err) {
        console.error(
          `  warning: failed to re-fetch ${entry.url}: ${err instanceof Error ? err.message : err}`,
        )
        return null
      }
    }),
  )
  const extrasOk = extras.filter((x): x is NonNullable<typeof x> => !!x)
  const totalExtrasBytes = extrasOk.reduce((n, r) => n + r.bytes.byteLength, 0)
  console.log(
    `  ${extrasOk.length} extra files: ${(totalExtrasBytes / 1024).toFixed(1)} KiB`,
  )

  let eventsGz: Uint8Array | undefined
  if (eventsPath) {
    // the CLI accepts a pre-gzipped .jsonl.gz (that's what the docstring
    // promises), so we pass the bytes straight through. if someone hands
    // us a plain jsonl, the server will still accept it but the preview
    // page's event replayer decodes via DecompressionStream — pre-gzip
    // stays the contract.
    eventsGz = readFileSync(eventsPath)
  }
  traceTimelineEvents.sort((a, b) => a.t - b.t || a.seq - b.seq)
  const traceTimelineJsonl = traceTimelineEvents
    .map((event) => JSON.stringify(event))
    .join('\n')
  const timelineGz = gzipSync(traceTimelineJsonl ? `${traceTimelineJsonl}\n` : '')
  console.log(
    `  trace timeline: ${traceTimelineEvents.length} events${
      localTraceTimelineCount ? ` (${localTraceTimelineCount} from runner sidecars)` : ''
    }`,
  )

  let screenshotBytes: Uint8Array | undefined
  if (screenshotPath) {
    screenshotBytes = readFileSync(screenshotPath)
    console.log(
      `  attaching screenshot: ${(screenshotBytes.byteLength / 1024).toFixed(1)} KiB`,
    )
  }
  const interactionSnapshots = snapshotManifestPath
    ? readSnapshotManifest(snapshotManifestPath)
    : []
  if (interactionSnapshots.length > 0) {
    console.log(`  attaching ${interactionSnapshots.length} interaction snapshots`)
  }

  // the flow runner's per-failure debug bundle: text artifacts fold into one
  // gzipped JSON envelope stored at the share's failure slot; screenshot.png
  // rides the snapshots channel as a 'failure' frame so the dashboard's run
  // rows can show the failing screen without fetching the whole envelope.
  let failureBundleGz: Uint8Array | undefined
  let failureScreenshotBytes: Uint8Array | undefined
  if (failureBundleDir) {
    const readText = (name: string): string | null => {
      try {
        return readFileSync(path.join(failureBundleDir, name), 'utf8')
      } catch {
        return null
      }
    }
    const readJson = (name: string): unknown => {
      const text = readText(name)
      if (text === null) return null
      try {
        return JSON.parse(text)
      } catch {
        return text
      }
    }
    const envelope = {
      error: readJson('error.json'),
      describe: readJson('describe.json'),
      console: readJson('console.json'),
      a11y: readText('a11y.txt'),
      tree: readText('tree.txt'),
    }
    if (Object.values(envelope).some((v) => v !== null)) {
      failureBundleGz = gzipSync(JSON.stringify(envelope))
      console.log(
        `  attaching failure bundle: ${(failureBundleGz.byteLength / 1024).toFixed(1)} KiB gz`,
      )
    }
    try {
      failureScreenshotBytes = readFileSync(path.join(failureBundleDir, 'screenshot.png'))
    } catch {
      // screenshot capture itself failed at the time — envelope still helps
    }
  }

  let videoBytes: Uint8Array | undefined
  let videoContentType: string | undefined
  let videoDurationMs: number | undefined
  if (videoPath) {
    videoBytes = readFileSync(videoPath)
    videoContentType = videoPath.endsWith('.mp4')
      ? 'video/mp4'
      : videoPath.endsWith('.gif')
        ? 'image/gif'
        : undefined
    if (!videoContentType) {
      console.error('  preview flow videos must be mp4 or gif')
      rnxExit(1)
    }
    if (videoDurationMsRaw) {
      const parsed = Number(videoDurationMsRaw)
      if (!Number.isFinite(parsed) || parsed <= 0) {
        console.error(`  invalid --video-duration-ms: ${videoDurationMsRaw}`)
        rnxExit(1)
      }
      videoDurationMs = Math.round(parsed)
    }
    console.log(
      `  attaching flow video: ${(videoBytes.byteLength / 1024).toFixed(1)} KiB (${videoContentType})`,
    )
  }

  // priority: RNX_API_KEY env → github runner token → saved credential
  // file → session token. github runner auth is what keeps installed PR
  // previews from requiring a new Contrast secret.
  const cliAuth = resolveCliAuth()
  const gitHubIdentity = githubUploadIdentity(cliAuth)
  const provenance = resolveRunProvenance()
  if (!cliAuth) {
    console.error('  preview uploads need auth.')
    console.error(
      '  set RNX_API_KEY=sk_rnx_..., run `rnx login`, or use the Contrast github runner.',
    )
    rnxExit(1)
  }
  const resolvedAuthHeader = authHeaderValue(cliAuth)

  const bundleOrigin = (() => {
    try {
      return new URL(snapshot.bundleUrl).origin
    } catch {
      return null
    }
  })()

  // compress the bundle (brotli, below) + compressible files (gzip).
  // bundle-origin extras + cross-origin recorded responses share one list —
  // the preview SW decides how to match each at replay time.
  type PreparedFile = {
    url: string
    urlhash: string
    method: string
    bodyHash: string
    requestVaryHash?: string
    contentType: string
    responseHeaders?: Array<{ name: string; value: string }>
    bytes: Uint8Array
    encoding: 'gzip' | undefined
  }
  const prepareFile = (
    raw: Uint8Array,
    url: string,
    urlhash: string,
    method: string,
    bodyHash: string,
    contentType: string,
    responseHeaders?: Array<{ name: string; value: string }>,
    requestVaryHash?: string,
  ): PreparedFile => {
    const compress = shouldCompress(contentType)
    const bytes = compress ? gzipSync(raw) : raw
    return {
      url,
      urlhash,
      method,
      bodyHash,
      requestVaryHash,
      contentType,
      responseHeaders,
      bytes,
      encoding: compress ? 'gzip' : undefined,
    }
  }
  // config-plugin app fonts (expo-font plugin etc.) are NOT in the metro
  // asset-registry and are fetched once at engine boot — before the recorder
  // starts — so neither the manifest re-fetch nor recordedFetches captures
  // them and the /preview replay 404s. backfill them here via the shared
  // fetcher (same code path as the build's `rnx app-fonts stage`) so both
  // pipelines store identical bytes keyed by sha256(url).
  const appFontFiles: PreparedFile[] = []
  const appFontsWire = appFontsWireFromPageHref(snapshot.pageHref) || ''
  if (appFontsWire) {
    const fonts = await fetchAppFontFiles(appFontsWire, {
      onStaged: ({ url, byteLength }) =>
        console.log(`  staged app font: ${url} (${(byteLength / 1024).toFixed(1)} KiB)`),
      onError: (url, err) =>
        console.error(
          `  warning: failed to fetch app font ${url}: ${err instanceof Error ? err.message : err}`,
        ),
    })
    for (const font of fonts) {
      appFontFiles.push(
        prepareFile(
          Buffer.from(font.bytes),
          font.url,
          font.urlhash,
          'GET',
          '-',
          font.contentType,
        ),
      )
    }
  }

  // stage the app's configured splash image(s) the same way: the metro asset
  // they reference is gone in a preview share, so re-fetch the bytes off the
  // still-live metro and persist them keyed by sha256(url). the engine's
  // <img src> resolves them through the share fetch proxy in preview mode.
  const appSplashFiles: PreparedFile[] = []
  const appSplashWire = appSplashWireFromPageHref(snapshot.pageHref) || ''
  if (appSplashWire) {
    const images = await fetchAppSplashImages(appSplashWire, {
      onStaged: ({ url, byteLength }) =>
        console.log(
          `  staged splash image: ${url} (${(byteLength / 1024).toFixed(1)} KiB)`,
        ),
      onError: (url, err) =>
        console.error(
          `  warning: failed to fetch splash image ${url}: ${err instanceof Error ? err.message : err}`,
        ),
    })
    for (const image of images) {
      appSplashFiles.push(
        prepareFile(
          Buffer.from(image.bytes),
          image.url,
          image.urlhash,
          'GET',
          '-',
          image.contentType,
        ),
      )
    }
  }

  const prepared: PreparedFile[] = [
    ...extrasOk.map((r) =>
      prepareFile(
        r.bytes,
        r.url,
        r.urlhash,
        'GET',
        '-',
        r.contentType,
        r.responseHeaders,
        r.requestVaryHash,
      ),
    ),
    ...recordedFetches.map((r) =>
      prepareFile(
        Buffer.from(r.bodyBase64, 'base64'),
        r.url,
        r.urlhash,
        r.method || 'GET',
        r.bodyHash || '-',
        r.contentType,
        r.responseHeaders,
        r.requestVaryHash,
      ),
    ),
    ...appFontFiles,
    ...appSplashFiles,
  ]

  // brotli source bytes for the upload. finalize verifies the source hash,
  // minifies in the node build container, and stores one canonical brotli
  // bundle. assets stay gzip below.
  const bundleBr = brotliBundle(bundleBytes)
  const bundleSha256 = createHash('sha256').update(bundleBytes).digest('hex')
  console.log(
    `  bundle raw=${(bundleBytes.byteLength / 1024).toFixed(1)} KiB br=${(bundleBr.byteLength / 1024).toFixed(1)} KiB`,
  )

  const initBody: InitRequestBody = {
    contentHash: bundleSha256,
    bundleSizeBytes: bundleBytes.byteLength,
    bundleContentType: guessBundleContentType(snapshot.bundleUrl),
    bundleEncoding: 'br',
    bundleMinified: false,
    bundleOrigin,
    runtimeVersion: snapshot.runtimeVersion ?? undefined,
    // config-only fonts resolved by `rnx open` and carried on the engine
    // URL. persist them onto the share meta so /preview/<id> re-applies
    // `?appFonts=` and registers the same typefaces.
    appFonts: appFontsWire || undefined,
    // configured splash (image + bg) resolved by `rnx open`. persist it so
    // /preview/<id> re-applies `?appSplash=` and paints the same splash; the
    // image bytes are staged above so the engine's <img> resolves in preview.
    appSplash: appSplashWire || undefined,
    entry: snapshot.entry,
    isTransformed,
    deviceSpec: snapshot.deviceSpec,
    installationId: gitHubIdentity?.installationId ?? undefined,
    repoId: gitHubIdentity?.repoId,
    owner: owner ?? gitHubIdentity?.owner ?? provenance.owner ?? undefined,
    repo: repo ?? gitHubIdentity?.repo ?? provenance.repo ?? undefined,
    branch: provenance.branch ?? undefined,
    commitSha: provenance.commitSha ?? undefined,
    githubUsername: provenance.githubUsername ?? undefined,
    pullRequestNumber: provenance.pullRequestNumber ?? undefined,
    pullRequestTitle: provenance.pullRequestTitle ?? undefined,
    billingKind: billingKind === 'test_run' ? 'test_run' : undefined,
    runScope: runScope || undefined,
    files: prepared.map((f) => ({
      url: f.url,
      urlhash: f.urlhash,
      method: f.method,
      bodyHash: f.bodyHash,
      contentType: f.contentType,
      responseHeaders: f.responseHeaders,
      requestVaryHash: f.requestVaryHash,
      encoding: f.encoding,
      sizeBytes: f.bytes.byteLength,
    })),
    events: eventsGz ? { sizeBytes: eventsGz.byteLength } : undefined,
    timeline: { sizeBytes: timelineGz.byteLength, encoding: 'gzip' },
    traceFrameStats: frameStatsMeta(traceFrameStats),
    recordedDurationMs,
    recordingStartedAtMs,
    failureBundle: failureBundleGz
      ? { sizeBytes: failureBundleGz.byteLength, encoding: 'gzip' }
      : undefined,
    snapshots: (() => {
      const entries: NonNullable<InitRequestBody['snapshots']> = []
      if (screenshotBytes) {
        entries.push({
          id: 'landing',
          label: 'Landing',
          kind: 'landing',
          t: 0,
          contentType: 'image/png',
          sizeBytes: screenshotBytes.byteLength,
        })
      }
      if (failureScreenshotBytes) {
        entries.push({
          id: 'failure',
          label: 'Failure',
          kind: 'failure',
          contentType: 'image/png',
          sizeBytes: failureScreenshotBytes.byteLength,
        })
      }
      for (const snapshot of interactionSnapshots) entries.push(snapshot.meta)
      return entries.length > 0 ? entries : undefined
    })(),
    flowVideo:
      videoBytes && videoContentType
        ? {
            sizeBytes: videoBytes.byteLength,
            contentType: videoContentType,
            durationMs: videoDurationMs,
          }
        : undefined,
  }

  const filesByHash = new Map<string, Uint8Array>()
  for (const f of prepared) filesByHash.set(f.urlhash, f.bytes)
  const snapshotBytes = new Map<string, Uint8Array>()
  if (screenshotBytes) snapshotBytes.set('landing', screenshotBytes)
  if (failureScreenshotBytes) snapshotBytes.set('failure', failureScreenshotBytes)
  for (const snapshot of interactionSnapshots) {
    snapshotBytes.set(snapshot.meta.id, snapshot.bytes)
  }

  const putT0 = Date.now()
  let putBytes = bundleBr.byteLength
  for (const f of prepared) putBytes += f.bytes.byteLength
  if (eventsGz) putBytes += eventsGz.byteLength
  putBytes += timelineGz.byteLength
  if (screenshotBytes) putBytes += screenshotBytes.byteLength
  if (failureScreenshotBytes) putBytes += failureScreenshotBytes.byteLength
  for (const snapshot of interactionSnapshots) putBytes += snapshot.bytes.byteLength
  if (failureBundleGz) putBytes += failureBundleGz.byteLength
  if (videoBytes) putBytes += videoBytes.byteLength

  const initUrl = `${normalizeOrigin(origin)}/api/preview/upload/init`
  console.log(`  init: ${initUrl}`)

  let finalize
  try {
    const result = await runPresignedUpload({
      originBase: origin,
      initBody,
      bundleBytes: bundleBr,
      filesByHash,
      extras: {
        eventsBytes: eventsGz,
        timelineBytes: timelineGz,
        videoBytes,
        failureBundleBytes: failureBundleGz,
        snapshotBytes,
      },
      authHeader: resolvedAuthHeader,
      concurrency: 16,
    })
    finalize = result.finalize
    const totalObjects =
      1 +
      result.init.files.length +
      (result.init.events ? 1 : 0) +
      (result.init.timeline ? 1 : 0) +
      result.init.snapshots.length +
      (result.init.flowVideo ? 1 : 0) +
      (result.init.failureBundle ? 1 : 0)
    console.log(
      `  PUT ${totalObjects} objects in ${Date.now() - putT0}ms (${(putBytes / 1024).toFixed(1)} KiB)`,
    )
  } catch (err: unknown) {
    const e = err as {
      phase?: 'init' | 'finalize'
      status?: number
      message?: string
      responseText?: string
    }
    if (e.phase === 'init' && e.status === 401) {
      console.error('  preview upload requires a valid login.')
      console.error('  run `rnx login` and retry.')
      rnxExit(1)
    }
    if (e.status === 402) {
      // billing gate — surface the server's own `message`, not raw JSON.
      console.error(
        `  ${parseServerMessage(e.responseText) ?? 'preview uploads require Personal, Team, or an active trial — upgrade from the billing dialog.'}`,
      )
      rnxExit(1)
    }
    // PresignedUploadError.message already carries the "<phase> failed:"
    // prefix — don't re-prefix it (that produced "init failed: init failed:").
    console.error(`  ${e.message ?? `${e.phase ?? 'upload'} failed: ${String(err)}`}`)
    rnxExit(1)
  }

  const previewUrl = `${publicOrigin}${finalize.url}`
  console.log(`\n  stored ${finalize.filesStored ?? 0} extra files`)
  console.log(`  preview: ${previewUrl}`)

  if (openResult) {
    await openUrl(previewUrl)
  }

  return { previewUrl, shareId: finalize.id }
}