peachsim 0.1.1625 → 0.1.1640

package/cli/commands/record.ts

@@ -1,5 +1,5 @@
 // peach record — drives the engine's built-in canvas recorder over
-// the WS bridge. no playwright, no ffmpeg. encoding happens in the
+// the WS bridge. scene export opens an isolated viewer; encoding happens in the
 // running peach page (webm via MediaRecorder, mp4 via WebCodecs, gif
 // via gifenc, raw png frames via a shared bitmap sampler).
 
@@ -76,18 +76,41 @@ const STORE_RECORD_START_TIMEOUT_MS = 90_000
 // (bitmap-capture.ts), so recovery is simply to retry.
 const CAPTURE_STEP_ENCODE_BUDGET_MS = 30_000
 
+// waits out a recording's duration as an in-flight bridge command. the host
+// closes a cli socket that sends nothing for 60s, but never one with a command
+// awaiting its sim, so a client-side sleep through a long capture dropped the
+// connection before the encode/flush step could use it.
+async function holdCapture(bridge: WsBridge, durationMs: number) {
+  await bridge.send(
+    { type: 'evaluate', code: `new Promise((r) => setTimeout(r, ${durationMs}))` },
+    { timeoutMs: durationMs + CAPTURE_STEP_ENCODE_BUDGET_MS },
+  )
+}
+
+// an explicit --timeout is the step's budget. a step that records for the
+// whole duration (a gif) gets that duration on top of it.
+function captureStepTimeoutMs(
+  parsed: ParsedBridgeCliArgs,
+  durationMs: number,
+  spansCapture: boolean,
+): number {
+  if (!parsed.explicitTimeout)
+    return Math.max(20_000, durationMs + CAPTURE_STEP_ENCODE_BUDGET_MS)
+  return spansCapture ? durationMs + parsed.commandTimeoutMs : parsed.commandTimeoutMs
+}
+
 async function evalCaptureStep<T>(
   bridge: WsBridge,
   code: string,
   step: string,
   durationMs: number,
+  timeoutMs: number,
 ): Promise<T> {
-  const timeoutMs = Math.max(20_000, durationMs + CAPTURE_STEP_ENCODE_BUDGET_MS)
   try {
     return (await bridge.send({ type: 'evaluate', code }, { timeoutMs })) as T
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err)
-    if (/^command timed out after \d+s$/.test(msg)) {
+    if (/^command timed out after \d+(?:\.\d+)?s$/.test(msg)) {
       console.error(
         `  ${step} stalled — the render host did not finish within ` +
           `${Math.round(timeoutMs / 1000)}s; it is likely contended or wedged.\n` +
@@ -143,6 +166,8 @@ const RECORD_VALUE_FLAGS = new Set([
   '--origin',
   '--owner',
   '--repo',
+  '--scene',
+  '--shell-url',
 ])
 const RECORD_SUBCOMMANDS = new Set([
   'start',
@@ -151,6 +176,7 @@ const RECORD_SUBCOMMANDS = new Set([
   'status',
   'prelude-start',
   'upload',
+  'render',
 ])
 
 // the record subcommand (start/stop/cancel/status) is the first non-flag
@@ -195,6 +221,23 @@ export async function runRecord(args: string[], opts: RecordOptions) {
     // drop the subcommand token; the rest (incl. any --sim/--port) flows on
     // to the subcommand handlers, which parse bridge flags themselves.
     const rest = [...args.slice(0, sub.index), ...args.slice(sub.index + 1)]
+    if (sub.name === 'render') {
+      const scene = valueOf(rest, '--scene')
+      const shellUrl = valueOf(rest, '--shell-url')
+      const output = valueOf(rest, '--output')
+      if (!scene || !shellUrl || !output)
+        throw new Error('record render requires --scene, --shell-url and --output')
+      const { renderSceneToVideo } = await import('../scene-video')
+      const result = await renderSceneToVideo({
+        scene: readFileSync(scene),
+        shellUrl,
+        output,
+      })
+      console.log(
+        `  video: ${resolve(output)} (${result.frameCount} frames at 60 fps, ${result.sizeBytes} bytes, rendered in ${(result.renderTimeMs / 1000).toFixed(1)}s)`,
+      )
+      return
+    }
     if (sub.name === 'start') {
       await recordStart(rest, opts)
       return
@@ -222,6 +265,8 @@ export async function runRecord(args: string[], opts: RecordOptions) {
 
   const parsed = parseBridgeCliArgs(args, {
     port: opts.port,
+    // an explicit --timeout wins over the default
+    commandTimeoutMs: 60_000,
     stripBooleanFlags: ['--no-shell', '--shell-only', '--open', '--lockstep'],
     stripValueFlags: [
       '--mode',
@@ -336,7 +381,7 @@ export async function runRecord(args: string[], opts: RecordOptions) {
       originOverride,
       allowGitHubAuth: true,
     })
-    const bridge = createBridgeFromParsed({ ...parsed, commandTimeoutMs: 60_000 })
+    const bridge = createBridgeFromParsed(parsed)
     try {
       await assertStoreBridgesAvailable(bridge)
       await assertGuestBundleLoaded(bridge, mode)
@@ -356,7 +401,7 @@ export async function runRecord(args: string[], opts: RecordOptions) {
         peachExit(1)
       }
       console.log(`  recording ${mode} for ${durationSec}s`)
-      await new Promise((r) => setTimeout(r, durationMs))
+      await holdCapture(bridge, durationMs)
       await evalStoreStop(bridge)
       const result = await pollStoreUpload(bridge)
       handleStoreUploadResult(result, openAfter, mode)
@@ -378,7 +423,7 @@ export async function runRecord(args: string[], opts: RecordOptions) {
     )
   }
 
-  const bridge = createBridgeFromParsed({ ...parsed, commandTimeoutMs: 60_000 })
+  const bridge = createBridgeFromParsed(parsed)
   try {
     await assertRecorderAvailable(bridge)
     await assertTabVisibleForCapture(bridge)
@@ -414,7 +459,7 @@ export async function runRecord(args: string[], opts: RecordOptions) {
         console.error(`  frame capture start failed: ${start.error ?? 'unknown error'}`)
         peachExit(1)
       }
-      await new Promise((r) => setTimeout(r, durationMs))
+      await holdCapture(bridge, durationMs)
       const deadline = Date.now() + Math.max(5_000, durationMs)
       // frames come back a few at a time: one message holding every base64 png
       // exceeds the bridge socket's message cap and closes it.
@@ -470,6 +515,7 @@ export async function runRecord(args: string[], opts: RecordOptions) {
         }${layers ? `, layers: ${JSON.stringify(layers)}` : ''} })`,
         'gif encode',
         durationMs,
+        captureStepTimeoutMs(parsed, durationMs, true),
       )
       if (!result) {
         console.error('  gif capture returned no frames')
@@ -503,6 +549,7 @@ export async function runRecord(args: string[], opts: RecordOptions) {
         `window.__sootsimRecorder.start(${JSON.stringify(startOpts)})`,
         `${format} start`,
         durationMs,
+        captureStepTimeoutMs(parsed, durationMs, false),
       )
     if (!startResult.ok) {
       console.error(`  start failed: ${startResult.error ?? 'unknown error'}`)
@@ -523,7 +570,7 @@ export async function runRecord(args: string[], opts: RecordOptions) {
     }
 
     console.log(`  recording ${format} for ${durationSec}s → ${out}`)
-    await new Promise((r) => setTimeout(r, durationMs))
+    await holdCapture(bridge, durationMs)
 
     const stopResult: {
       ok: boolean
@@ -537,6 +584,7 @@ export async function runRecord(args: string[], opts: RecordOptions) {
       `window.__sootsimRecorder.stop()`,
       `${format} encode/flush`,
       durationMs,
+      captureStepTimeoutMs(parsed, durationMs, false),
     )
     if (!stopResult.ok) {
       console.error(`  stop failed: ${stopResult.error ?? 'unknown error'}`)
@@ -570,11 +618,11 @@ async function probeSim(bridge: WsBridge, code: string): Promise<boolean> {
   try {
     return await bridge.send(
       { type: 'evaluate', code },
-      { timeoutMs: SIM_PROBE_TIMEOUT_MS },
+      { defaultTimeoutMs: SIM_PROBE_TIMEOUT_MS },
     )
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err)
-    if (/^command timed out after \d+s$/.test(msg)) {
+    if (/^command timed out after \d+(?:\.\d+)?s$/.test(msg)) {
       console.error(
         '  sim did not respond — it is connected to the bridge but has not\n' +
           '  loaded an app (or its page is unresponsive). run `peach list`\n' +
@@ -766,7 +814,7 @@ async function refuseLiveRecording(parsed: ParsedBridgeCliArgs) {
     ...parsed,
     simId: existing.simId ?? parsed.simId,
     simIdSource: existing.simId ? 'saved' : parsed.simIdSource,
-    commandTimeoutMs: 8_000,
+    commandTimeoutMs: parsed.explicitTimeout ? parsed.commandTimeoutMs : 8_000,
   })
   try {
     const sims = await bridge.listSims()
@@ -788,8 +836,12 @@ async function refuseLiveRecording(parsed: ParsedBridgeCliArgs) {
 }
 
 async function recordStart(args: string[], opts: RecordOptions) {
+  const mode = parseMode(valueOf(args, '--mode'))
   const parsed = parseBridgeCliArgs(args, {
     port: opts.port,
+    // an explicit --timeout wins over the per-mode default
+    commandTimeoutMs:
+      mode === 'live' || mode === 'combined' ? STORE_RECORD_START_TIMEOUT_MS : 15_000,
     stripBooleanFlags: ['--no-shell', '--shell-only', '--lockstep'],
     stripValueFlags: [
       '--mode',
@@ -803,7 +855,6 @@ async function recordStart(args: string[], opts: RecordOptions) {
     ],
   })
   await refuseLiveRecording(parsed)
-  const mode = parseMode(valueOf(args, '--mode'))
   const layers: 'tenant' | 'shell' | undefined = args.includes('--shell-only')
     ? 'shell'
     : args.includes('--no-shell')
@@ -820,11 +871,19 @@ async function recordStart(args: string[], opts: RecordOptions) {
   const fps = Number(valueOf(args, '--fps') ?? '30')
   const repoScope = readRepoScope(args)
 
-  const bridge = createBridgeFromParsed({
-    ...parsed,
-    commandTimeoutMs:
-      mode === 'live' || mode === 'combined' ? STORE_RECORD_START_TIMEOUT_MS : 15_000,
-  })
+  // the session is recorded before the engine is asked to start, so a start
+  // that times out on this side while the engine records stays stoppable. a
+  // refusal clears it.
+  const session: RecordingState = {
+    simId: parsed.simId ?? null,
+    mode,
+    format,
+    fps,
+    layers,
+    startedAt: new Date().toISOString(),
+  }
+
+  const bridge = createBridgeFromParsed(parsed)
   try {
     if (mode === 'live' || mode === 'combined') {
       // live mode captures events only — --no-shell / --shell-only have no
@@ -849,6 +908,7 @@ async function recordStart(args: string[], opts: RecordOptions) {
       await assertGuestBundleLoaded(bridge, mode)
       if (mode === 'combined') await assertTabVisibleForCapture(bridge)
       await injectPreviewSessionAuth(bridge, valueOf(args, '--origin'), repoScope)
+      writeRecordingState(session)
       const started = await evalStoreStart(
         bridge,
         mode,
@@ -856,6 +916,7 @@ async function recordStart(args: string[], opts: RecordOptions) {
         mode === 'combined' ? layers : undefined,
       )
       if (!started.ok) {
+        clearRecordingState()
         console.error(
           `  start failed: recording store refused to start (${mode})` +
             (started.error ? `: ${started.error}` : ''),
@@ -878,23 +939,17 @@ async function recordStart(args: string[], opts: RecordOptions) {
       } = { format, fps }
       if (layers) startOpts.layers = layers
       if (lockstep) startOpts.lockstep = true
+      writeRecordingState(session)
       const result: { ok: boolean; error?: string } = await bridge.send({
         type: 'evaluate',
         code: `window.__sootsimRecorder.start(${JSON.stringify(startOpts)})`,
       })
       if (!result.ok) {
+        clearRecordingState()
         console.error(`  start failed: ${result.error ?? 'unknown error'}`)
         peachExit(1)
       }
     }
-    writeRecordingState({
-      simId: parsed.simId ?? null,
-      mode,
-      format,
-      fps,
-      layers,
-      startedAt: new Date().toISOString(),
-    })
     if (mode === 'video') {
       console.log(
         `  recording ${format} @ ${fps}fps${layers ? ` (${layers})` : ''} — run \`peach record stop --output <path>\` when done`,
@@ -916,7 +971,7 @@ async function recordPreludeStart(args: string[], opts: RecordOptions) {
     stripValueFlags: ['--origin'],
   })
   await refuseLiveRecording(parsed)
-  const bridge = createBridgeFromParsed({ ...parsed, commandTimeoutMs: 15_000 })
+  const bridge = createBridgeFromParsed(parsed)
   try {
     await assertStoreBridgesAvailable(bridge)
     await assertTabVisibleForCapture(bridge)
@@ -1049,8 +1104,8 @@ async function recordStatus(args: string[], opts: RecordOptions) {
   }
   // no `record start` session — but an atomic run or the rail button may
   // still be recording. ask the engine before claiming nothing is happening.
-  const parsed = parseBridgeCliArgs(args, { port: opts.port })
-  const bridge = createBridgeFromParsed({ ...parsed, commandTimeoutMs: 8_000 })
+  const parsed = parseBridgeCliArgs(args, { port: opts.port, commandTimeoutMs: 8_000 })
+  const bridge = createBridgeFromParsed(parsed)
   try {
     const engineState = await probeEngineRecordingState(bridge)
     if (
@@ -1091,11 +1146,11 @@ async function recordCancel(args: string[], opts: RecordOptions) {
   if (!state) {
     // no `record start` session to cancel — but check the engine so we
     // don't falsely claim nothing is happening while an atomic run records.
-    const probeParsed = parseBridgeCliArgs(args, { port: opts.port })
-    const probeBridge = createBridgeFromParsed({
-      ...probeParsed,
+    const probeParsed = parseBridgeCliArgs(args, {
+      port: opts.port,
       commandTimeoutMs: 8_000,
     })
+    const probeBridge = createBridgeFromParsed(probeParsed)
     try {
       const engineState = await probeEngineRecordingState(probeBridge)
       if (
@@ -1132,18 +1187,14 @@ async function recordCancel(args: string[], opts: RecordOptions) {
     }
     return
   }
-  const parsed = parseBridgeCliArgs(args, { port: opts.port })
+  const parsed = parseBridgeCliArgs(args, { port: opts.port, commandTimeoutMs: 15_000 })
   noteSimMismatch(parsed.simId, state)
   // the recorder (and its buffered blob) lives in the page of the sim the
   // recording was *started* on — `state.simId` wins over the requested
   // --sim, otherwise cancel would stop an idle recorder on the wrong sim
   // and leave the real recording running (F11-1).
   const simId = state.simId ?? parsed.simId ?? undefined
-  const bridge = createBridgeFromParsed({
-    ...parsed,
-    simId,
-    commandTimeoutMs: 15_000,
-  })
+  const bridge = createBridgeFromParsed({ ...parsed, simId })
   try {
     if (state.mode === 'live' || state.mode === 'combined') {
       await bridge.send({
@@ -1174,6 +1225,9 @@ async function recordStop(args: string[], opts: RecordOptions) {
 
   const parsed = parseBridgeCliArgs(args, {
     port: opts.port,
+    // an explicit --timeout wins over the per-mode default
+    commandTimeoutMs:
+      state.mode === 'live' || state.mode === 'combined' ? UPLOAD_TIMEOUT_MS : 60_000,
     stripBooleanFlags: ['--open'],
     stripValueFlags: ['--output'],
   })
@@ -1184,15 +1238,17 @@ async function recordStop(args: string[], opts: RecordOptions) {
   const simId = state.simId ?? parsed.simId ?? undefined
   const openAfter = args.includes('--open')
 
-  const bridge = createBridgeFromParsed({
-    ...parsed,
-    simId,
-    commandTimeoutMs:
-      state.mode === 'live' || state.mode === 'combined' ? UPLOAD_TIMEOUT_MS : 60_000,
-  })
+  const bridge = createBridgeFromParsed({ ...parsed, simId })
   try {
     if (state.mode === 'live' || state.mode === 'combined') {
-      await evalStoreStop(bridge)
+      if (!(await evalStoreStop(bridge))) {
+        clearRecordingState()
+        console.error(
+          `  stop failed: the ${state.mode} start still in flight never began a take, so there is nothing to upload.\n` +
+            '  run `peach record start` again.',
+        )
+        peachExit(1)
+      }
       const result = await pollStoreUpload(bridge)
       clearRecordingState()
       handleStoreUploadResult(result, openAfter, state.mode)
@@ -1215,7 +1271,17 @@ async function recordStop(args: string[], opts: RecordOptions) {
     })
     if (!stopResult.ok) {
       console.error(`  stop failed: ${stopResult.error ?? 'unknown error'}`)
-      clearRecordingState()
+      // a start that timed out on the client can still be on its way to the
+      // engine. keep the state so a later stop finds the recording instead of
+      // leaving it running with nothing to stop it.
+      if (stopResult.error === 'not recording') {
+        console.error(
+          '  the start may not have reached the engine yet. retry `peach record stop`,\n' +
+            '  or run `peach record cancel` to give up on it.',
+        )
+      } else {
+        clearRecordingState()
+      }
       peachExit(1)
     }
     if (!stopResult.size) {
@@ -1376,11 +1442,15 @@ async function evalStoreStart(
   return { ok: false, error: error ?? null }
 }
 
-async function evalStoreStop(bridge: WsBridge): Promise<void> {
-  await bridge.send({
+// the engine stop waits for a start still in flight. false means that start
+// never began a take, so no upload will come and the store's last one belongs
+// to an earlier take.
+async function evalStoreStop(bridge: WsBridge): Promise<boolean> {
+  const stopped: boolean | null = await bridge.send({
     type: 'evaluate',
-    code: `void window.SootSim.bridges.stopRecording()`,
+    code: `window.SootSim.bridges.stopRecording()`,
   })
+  return stopped !== false
 }
 
 interface StoreUploadResult {

package/cli/commands/screenshot.ts

@@ -140,7 +140,15 @@ examples:
     // --id / --text, missing device model). surface them as a one-line
     // failure instead of an uncaught internal stack trace.
     try {
-      await captureViaBridge(parsed, outputArg, rect, withFrame, layers, allowLoading)
+      await captureViaBridge(
+        parsed,
+        outputArg,
+        rect,
+        withFrame,
+        layers,
+        allowLoading,
+        opts.verbose === true || args.includes('--verbose') || args.includes('-v'),
+      )
     } catch (err) {
       console.error(
         `  screenshot failed: ${err instanceof Error ? err.message : String(err)}`,
@@ -206,7 +214,16 @@ async function captureViaBridge(
   withFrame: boolean,
   layers: 'full' | 'tenant' | 'shell' | undefined,
   allowLoading: boolean,
+  verbose: boolean,
 ) {
+  // --verbose names the phase a slow capture spent its time in.
+  const phases: string[] = []
+  let phaseStart = Date.now()
+  const phase = (name: string) => {
+    const now = Date.now()
+    phases.push(`${name} ${now - phaseStart}ms`)
+    phaseStart = now
+  }
   // 45s, not 10s: a first-paint capture on a headless CI runner with software
   // GL (SwiftShader) is bounded but slow. forceRenderAll caps at ~6s (two
   // 3s-bounded passes) and the WebGL→2D drawImage readback + PNG encode of a
@@ -225,6 +242,7 @@ async function captureViaBridge(
     // affects screenshot fidelity directly, so call it out explicitly so the
     // user doesn't accept a stale frame as ground truth.
     const health = await checkSimHealth(bridge)
+    phase('health')
     if (health.hidden) {
       process.stderr.write(
         '  ⚠ screenshot will capture the LAST PAINTED canvas — likely stale.\n' +
@@ -267,6 +285,7 @@ async function captureViaBridge(
       }
     }
 
+    phase('ready')
     let resolvedRect: SampleRect | null = rect
     const matcher = (rect as { __matcher?: { id?: string; text?: string } })?.__matcher
     if (matcher) {
@@ -297,6 +316,7 @@ async function captureViaBridge(
     if (layers) request.layers = layers
     if (cropRect) request.crop = cropRect
     const dataUrl: string = await bridge.send(request)
+    phase('capture')
     const pngPrefix = 'data:image/png;base64,'
     // never write a 0-byte "saved" file from an empty or malformed payload —
     // the sim may be alive but not painting (check `peach get errors`)
@@ -326,6 +346,8 @@ async function captureViaBridge(
     } else {
       await writeScreenshotOutput(outputPath, rawBuffer)
     }
+    phase('write')
+    if (verbose) console.log(`  timing: ${phases.join(', ')}`)
     console.log(`  saved: ${outputPath}`)
   } finally {
     bridge.close()

package/cli/commands/serve.ts

@@ -8,7 +8,10 @@
 // run in the foreground (ctrl-c to stop). the persistent launchd/systemd
 // daemon installation is handled by `peach daemon install`.
 
-import { DEFAULT_SOOTSIM_BRIDGE_PORT } from '../../src/bridge-constants'
+import {
+  assertPeachPortEnvironment,
+  DEFAULT_SOOTSIM_BRIDGE_PORT,
+} from '../../src/bridge-constants'
 import {
   ensureRnxHome,
   isDaemonLockfileFresh,
@@ -58,6 +61,7 @@ examples:
     peachExit(0)
   }
 
+  assertPeachPortEnvironment(process.env)
   const portArgIdx = args.indexOf('--port')
   const port =
     portArgIdx >= 0 && args[portArgIdx + 1]
@@ -147,7 +151,8 @@ examples:
     if (sims.length > 0) lastUsedAt = Date.now()
     else if (
       starterGoneAt &&
-      Date.now() - Math.max(starterGoneAt, lastUsedAt, host.lastRequestAt) >= UNUSED_EXIT_MS
+      Date.now() - Math.max(starterGoneAt, lastUsedAt, host.lastRequestAt) >=
+        UNUSED_EXIT_MS
     ) {
       void shutdown('unused')
       return

package/cli/commands/setup.ts

@@ -17,7 +17,7 @@ import {
   writePrivacyPreferences,
 } from '../../src/home-paths'
 import { rnxRuntime } from '../../src/runtime-delivery'
-import { findDesktopCompanion } from '../desktop-companion'
+import { findDesktopCompanion, nativeDesktopIsDefault } from '../desktop-companion'
 import { isCi, PRIVACY_NOTICE } from '../privacy'
 import { confirm, select } from '../prompt'
 import {
@@ -155,12 +155,7 @@ export async function runSetup(
       serviceInstalled = true
     }
 
-    if (
-      simulatorDriver !== 'playwright' &&
-      process.platform !== 'darwin' &&
-      !options.dryRun &&
-      (simulatorDriver === 'desktop' || !findDesktopCompanion({ native: false }))
-    ) {
+    if (simulatorDriver !== 'playwright' && !options.dryRun && !findDesktopCompanion()) {
       await runInstallDesktop(
         simulatorDriver === 'desktop' ? ['--yes'] : ['--yes', '--electron'],
       )
@@ -272,7 +267,7 @@ function readSimulatorDriverFlag(args: string[]): SimulatorDriverPreference | un
   if (desktop && browser) {
     throw new Error('--desktop and --browser cannot be used together')
   }
-  if (desktop) return desktopHostPlatform() === 'mac-arm64' ? 'desktop' : 'electron'
+  if (desktop) return desktopHostPlatform() ? 'desktop' : 'electron'
   if (browser) return 'playwright'
   return undefined
 }
@@ -331,46 +326,29 @@ async function decideService(
   return confirm('Enable the background service?', true)
 }
 
+// the native app is the simulator window wherever it ships, and setup installs
+// it without asking. Windows chooses between the browser and its Electron app.
 async function decideSimulatorDriver(
   options: SetupOptions,
 ): Promise<SimulatorDriverPreference> {
-  if (process.platform === 'darwin' && !findDesktopCompanion()) {
-    if (options.simulatorDriver && options.simulatorDriver !== 'playwright') {
-      throw new Error('install the Mac app with `peach desktop install --native` first')
-    }
-    return 'playwright'
-  }
   if (options.simulatorDriver) return options.simulatorDriver
   const current = readSimulatorDriverPreference()
   if (current) return current
+  if (isCi()) return 'playwright'
+  if (nativeDesktopIsDefault()) return 'desktop'
+  if (process.platform !== 'win32') return 'playwright'
   if (options.ci || options.yes || options.dryRun) return 'playwright'
   requireInteractive(options, '--desktop or --browser')
-  const desktopDescription =
-    process.platform === 'darwin'
-      ? 'Desktop opens your installed native runtime (beta).'
-      : process.platform === 'win32'
-        ? 'Desktop downloads and runs the peach installer.'
-        : 'Desktop installs the native .deb with sudo apt-get and needs a desktop session.'
-  const desktopChoice =
-    process.platform === 'darwin'
-      ? 'Native app (beta)      Faster, may have more issues'
-      : process.platform === 'win32'
-        ? 'Desktop app            Runs the peach installer'
-        : 'Native app (beta)      Faster, may have more issues'
   printPromptBlock('Simulator window', [
     'Browser opens immediately in an isolated Chrome window.',
-    desktopDescription,
-    'The Desktop app opens in a dedicated native window.',
+    'Desktop downloads and runs the peach installer.',
+    'The Desktop app opens in a dedicated window.',
   ])
   const choice = await select('Where should peach open?', [
     'Browser (default)      No additional download',
-    desktopChoice,
+    'Desktop app            Runs the peach installer',
   ])
-  return choice === 0
-    ? 'playwright'
-    : process.platform === 'darwin'
-      ? 'desktop'
-      : 'electron'
+  return choice === 0 ? 'playwright' : 'electron'
 }
 
 // diagnostics and crash reports are on unless turned off; setup says so once
@@ -433,15 +411,14 @@ function printIntro(options: SetupOptions): void {
   if (options.json) return
   printBrand('Run any React Native app in a local simulator. No project setup required.')
   if (desktopHostPlatform()) {
-    printPromptBlock('Optional native runtime (beta)', [
-      'Try the native runtime for faster simulation. It is beta, so you may run into more issues.',
-      'Install the app: peach desktop install',
-      'Open your app: peach open <port> --driver desktop',
-      'Open a browser window: peach open <port> --driver playwright --headed',
+    printPromptBlock('Native desktop app', [
+      'peach opens your app in its native desktop app, which is faster than the browser.',
+      'Setup installs it, and peach open <port> uses it.',
+      'Open a browser window instead: peach open <port> --driver playwright --headed',
       ...(process.platform === 'linux'
-        ? ['Linux desktop installation uses sudo apt-get and needs a desktop session.']
+        ? ['On Linux the app installs with sudo apt-get and needs a desktop session.']
         : []),
-      'The background service is a separate choice that keeps the bridge ready for either runtime.',
+      'The background service is a separate choice that keeps the bridge ready for either window.',
     ])
   }
 }
@@ -451,7 +428,7 @@ function printHelp(): void {
 peach setup - configure optional local conveniences
 
 peach works without project setup. This command can enable the faster background
-service, choose Browser or Desktop, configure private diagnostics, and optionally
+service, install the native desktop app, configure private diagnostics, and optionally
 add an exact peachsim dependency plus a peach script for teammates.
 
 usage:

package/cli/commands/swift.ts

@@ -5,6 +5,7 @@ import { WebSocket, WebSocketServer } from 'ws'
 import { resolveContrastBackendOrigin } from '../../src/backend-origin'
 import { produceConfiguredBundle } from '../../src/configured-bundle-producer'
 import { swiftGuestBundle } from '../../src/guest-bundle'
+import { insertNativeAppIdentityFooter } from '../../src/native-app-identity'
 import {
   resolveSwiftModule,
   SWIFT_ENDPOINT_ENV,
@@ -73,6 +74,11 @@ export async function runSwift(
     } else if (arg === '--scheme') {
       scheme = input[++index]
       if (!scheme || scheme.startsWith('-')) throw new Error('--scheme requires a value')
+    } else if (arg === '--swift-sdks-path') {
+      const value = input[++index]
+      if (!value || value.startsWith('-'))
+        throw new Error('--swift-sdks-path requires a value')
+      process.env.PEACH_SWIFT_SDKS_PATH = path.resolve(value)
     } else if (arg === '--host-port' || valueFlags.has(arg)) {
       const value = input[++index]
       if (!value || value.startsWith('-')) throw new Error(`${arg} requires a value`)
@@ -163,7 +169,9 @@ export async function runSwift(
   const packageName = path.basename(packagePath)
   const appInfo = host.swiftProjectAppInfo(packagePath)
   const guestSource = swiftGuestBundle(packageName)
-  let guest = guestSource
+  const withIdentity = (source: string) =>
+    appInfo.identity ? insertNativeAppIdentityFooter(source, appInfo.identity) : source
+  let guest = withIdentity(guestSource)
   const controller = new AbortController()
   const resources: OpenCommandResources = {}
   let metadata: (SwiftEntryModuleArgs & { hmrPath: string }) | null = null
@@ -187,7 +195,9 @@ export async function runSwift(
         try {
           const config = await loadRNXAppConfig(appProject)
           host.configureSwiftStandinBehavior(packagePath, config)
-          guest = await produceConfiguredBundle(guestSource, config, new Set())
+          guest = withIdentity(
+            await produceConfiguredBundle(guestSource, config, new Set()),
+          )
           const next = await host.swiftPackageMetadata(
             packagePath,
             packageName,
@@ -343,7 +353,8 @@ export async function runSwift(
     console.log(`  Swift preview host: ${origin}`)
     await refresh()
     controller.signal.throwIfAborted()
-    if (!metadata || compileError) throw new Error(compileError)
+    // refresh already printed the error
+    if (!metadata || compileError) throw new Error('Swift compilation failed, see above')
     if (opts.device) openArgs.push('--device', opts.device)
     if (opts.driver) openArgs.push('--driver', opts.driver)
     if (opts.headless) openArgs.push('--headless')