rnxsim 0.1.431 → 0.1.433

package/cli/commands/maestro-generate.ts

@@ -7,6 +7,15 @@ import yaml from 'yaml'
 import { authHeaderValue, resolveCliAuth } from '../auth'
 import { registerRun, stepSummaryFromTrace } from '../run-registry'
 import { createBridgeFromParsed, parseBridgeCliArgs } from '../ws-bridge'
+import {
+  findUnexpectedFlowArgs,
+  FLOW_ARG_VALUE_FLAGS,
+  FLOW_BRIDGE_ARG_OPTIONS,
+  getLastFlowPreviewUploadResult,
+  getLastFlowTraceSteps,
+  runFlowPlayback,
+  type UnexpectedFlowArg,
+} from './flow'
 import { inspectDescribe } from './inspect/core'
 import { resolveDefaultUploadOrigin } from './upload'
 
@@ -27,24 +36,17 @@ function flagValueAny(args: string[], names: string[]): string | undefined {
   return undefined
 }
 
-const VALUE_FLAGS = new Set([
-  '--origin',
-  '--preview-origin',
-  '--public-origin',
-  '--preview-public-origin',
-  '--owner',
-  '--repo',
-  '--url',
-  '--driver',
-  '--sim',
-  '--device',
-  '--slow',
-  '--tail-wait',
-  '--remap',
-  '--replace',
-])
+// generate is a front-end for runFlowPlayback: it inspects the sim, asks the
+// model for a flow, then hands the argv down. these are the only flags it reads
+// itself; everything else belongs to the runner and is forwarded verbatim. this
+// file used to keep its own allowlist of what to forward, which silently
+// dropped --proof, --record, --profile, --screenshots, --out and --base-url
+// while `maestro test` honoured all six.
+const GENERATE_VALUE_FLAGS = ['--origin', '--preview-origin', '--public-origin']
 
-function findPrompt(args: string[]): { prompt: string; index: number } | null {
+const VALUE_FLAGS = new Set([...GENERATE_VALUE_FLAGS, ...FLOW_ARG_VALUE_FLAGS])
+
+export function findPrompt(args: string[]): { prompt: string; index: number } | null {
   for (let i = 0; i < args.length; i++) {
     const arg = args[i]
     if (!arg) continue
@@ -65,14 +67,11 @@ function stripPromptForBridge(args: string[], promptIndex: number): string[] {
 async function describeCurrentSim(args: string[], promptIndex: number): Promise<string> {
   const bridgeArgs = stripPromptForBridge(args, promptIndex)
   const parsedBridgeArgs = parseBridgeCliArgs(bridgeArgs, {
-    stripBooleanFlags: [
-      '--new',
-      '--headless',
-      '--headed',
-      '--electron',
-      '--preview-open',
+    stripBooleanFlags: FLOW_BRIDGE_ARG_OPTIONS.stripBooleanFlags,
+    stripValueFlags: [
+      ...GENERATE_VALUE_FLAGS,
+      ...FLOW_BRIDGE_ARG_OPTIONS.stripValueFlags,
     ],
-    stripValueFlags: [...VALUE_FLAGS],
   })
   const bridge = createBridgeFromParsed(parsedBridgeArgs)
   try {
@@ -237,7 +236,7 @@ function parseGeneratedFlow(text: string): {
   return { summary, steps, yamlText: yaml.stringify(steps) }
 }
 
-function buildFlowArgs(
+export function buildFlowArgs(
   args: string[],
   promptIndex: number,
   flowPath: string,
@@ -251,32 +250,10 @@ function buildFlowArgs(
     '--billing-kind',
     'test_run',
   ]
-  const passthroughValues = new Set([
-    '--public-origin',
-    '--preview-public-origin',
-    '--owner',
-    '--repo',
-    '--url',
-    '--driver',
-    '--sim',
-    '--device',
-    '--slow',
-    '--tail-wait',
-    '--remap',
-    '--replace',
-  ])
-  const passthroughBooleans = new Set([
-    '--new',
-    '--headless',
-    '--headed',
-    '--electron',
-    '--preview-open',
-    '--no-shell',
-    '--shell-only',
-  ])
   for (let i = 0; i < args.length; i++) {
     if (i === promptIndex) continue
     const arg = args[i]
+    if (!arg) continue
     if (arg === '--origin' || arg === '--preview-origin') {
       i += 1
       continue
@@ -287,17 +264,50 @@ function buildFlowArgs(
       i += 1
       continue
     }
-    if (passthroughValues.has(arg)) {
+    out.push(arg)
+    if (VALUE_FLAGS.has(arg)) {
       const value = args[i + 1]
-      if (value) out.push(arg, value)
+      if (value !== undefined) out.push(value)
       i += 1
-      continue
     }
-    if (passthroughBooleans.has(arg)) out.push(arg)
   }
   return out
 }
 
+// an argument nothing reads is an argument that silently changes what the run
+// does, and generate hands its argv to runFlowPlayback, which is the end of the
+// line for argv. so whatever survives buildFlowArgs is checked against the
+// runner's own vocabulary, before the sim inspection and the model call rather
+// than after them.
+export function findUnexpectedGenerateArgs(
+  args: string[],
+  promptIndex: number,
+): UnexpectedFlowArg[] {
+  const problems: UnexpectedFlowArg[] = []
+  for (let i = 0; i < args.length; i++) {
+    if (i === promptIndex) continue
+    const arg = args[i]
+    if (!arg) continue
+    // generate writes --billing-kind onto the flow argv itself and getFlag
+    // takes the first occurrence, so a caller's value loses to it in silence.
+    if (arg === '--billing-kind') {
+      problems.push({ arg, message: `${arg} is set by rnx maestro generate` })
+      i += 1
+      continue
+    }
+    if (!GENERATE_VALUE_FLAGS.includes(arg)) continue
+    const value = args[i + 1]
+    if (value === undefined || value.startsWith('-')) {
+      problems.push({ arg, message: `${arg} expects a value` })
+    }
+    i += 1
+  }
+  return [
+    ...problems,
+    ...findUnexpectedFlowArgs(buildFlowArgs(args, promptIndex, '<flow>', '<origin>')),
+  ]
+}
+
 export async function runMaestroGenerate(args: string[]): Promise<number> {
   const promptArg = findPrompt(args)
   if (!promptArg) {
@@ -305,6 +315,14 @@ export async function runMaestroGenerate(args: string[]): Promise<number> {
     return 1
   }
   const { prompt, index: promptIndex } = promptArg
+  const unexpected = findUnexpectedGenerateArgs(args, promptIndex)
+  if (unexpected.length > 0) {
+    for (const problem of unexpected) {
+      console.error(`  error: ${problem.message}`)
+    }
+    console.error('\n  run `rnx maestro --help` for the flags this command accepts')
+    return 1
+  }
   const cliAuth = resolveCliAuth()
   if (!cliAuth || cliAuth.kind === 'github') {
     console.error('  rnx maestro generate "<goal>" needs a login or RNX_API_KEY.')
@@ -326,8 +344,6 @@ export async function runMaestroGenerate(args: string[]): Promise<number> {
   console.log(`  flow: ${flowPath}`)
 
   const startedAt = Date.now()
-  const { runFlowPlayback, getLastFlowPreviewUploadResult, getLastFlowTraceSteps } =
-    await import('./flow')
   const flowArgs = buildFlowArgs(args, promptIndex, flowPath, origin)
   const exitCode = await runFlowPlayback(flowArgs)
   const upload = getLastFlowPreviewUploadResult()

package/cli/commands/maestro.ts

@@ -12,7 +12,10 @@ import yaml from 'yaml'
 import { resolveCliAuth } from '../auth'
 import { parseFlowFile } from '../flow-file'
 import { registerRun, shouldRegisterRun, stepSummaryFromTrace } from '../run-registry'
+import { RnxExit } from '../run-rnx'
 import {
+  findUnexpectedFlowArgs,
+  FLOW_ARG_VALUE_FLAGS,
   getLastFlowPreviewUploadResult,
   getLastFlowTraceSteps,
   hoistLeadingSimFlag,
@@ -44,8 +47,9 @@ usage:
 
 options:
   --env KEY=VALUE        set env vars for \${KEY} interpolation (repeatable)
-  --continuous           re-run the flow on file changes (alias for --watch)
+  --continuous           accepted for maestro cli compat; rnx runs the flow once
   --format <fmt>         accepted for maestro cli compat (not used)
+  --device <model>       override the flow frontmatter device for this run
   --new                  force a fresh browser window for this run
   --headed               force a fresh, VISIBLE window (implies --new,
                          overrides --headless) — watch the flow run live
@@ -144,22 +148,35 @@ function applyEnvFlags(args: string[]): string[] {
   return out
 }
 
-// Remove Maestro-only flags that the shared runner does not know.
-// these are accepted so users can literally s/maestro/rnx maestro/ in
-// their scripts without edits.
-function stripUnknownMaestroFlags(args: string[]): string[] {
+// maestro-cli flags with no rnx equivalent, accepted so an existing script can
+// swap `maestro` for `rnx maestro` unedited. each one says out loud that it is
+// being ignored: an option that is quietly dropped is how a run reports success
+// while doing something other than what was asked. `--origin` is consumed here
+// because only this command reads it; everything else this function leaves
+// alone rides on to the flow runner, which rejects what it does not know.
+function stripMaestroCompatFlags(args: string[]): string[] {
   const out: string[] = []
   for (let i = 0; i < args.length; i++) {
     const a = args[i]
-    if (a === '--format' || a === '--output' || a === '--device' || a === '-d') {
+    if (a === '--format' || a === '--output') {
+      console.warn(`  warn: ${a} is accepted for maestro cli compatibility and ignored`)
       i += 1
       continue
     }
+    if (a === '--origin') {
+      // read above for the run-registration origin. the flow runner has no
+      // --origin, so it must not ride into playbackArgs.
+      i += 1
+      continue
+    }
+    if (a === '-d') {
+      // maestro's short form for --device. rnx's device flag names a device
+      // model, and the flow runner reads it under the long spelling only.
+      out.push('--device')
+      continue
+    }
     if (a === '--continuous') {
-      // map to --watch for runFlowPlayback's existing watch path if one
-      // exists; today runFlowPlayback has no watch mode, so we drop the
-      // flag and log a warning rather than silently changing behavior.
-      console.warn('  warn: --continuous is not yet implemented in rnx — running once')
+      console.warn('  warn: --continuous is not implemented in rnx — running once')
       continue
     }
     out.push(a)
@@ -317,21 +334,33 @@ export async function runMaestro(
   ) {
     return runMaestroAuthoring(remaining)
   }
-  remaining = stripUnknownMaestroFlags(remaining)
+  // `--origin` names the Contrast instance that hosts the run row. this command
+  // is its only reader, so read it before stripMaestroCompatFlags consumes it.
+  const originFlagIndex = remaining.indexOf('--origin')
+  const originFlagValue =
+    originFlagIndex >= 0 ? remaining[originFlagIndex + 1] : undefined
+  remaining = stripMaestroCompatFlags(remaining)
 
   // resolve the target flow file or directory.
   let target: string | null = null
   let forwardArgs: string[]
 
   if (sub === 'test') {
-    // `rnx maestro test <flow-or-dir> [flags...]`
-    const positional = remaining.slice(1).find((a) => !looksLikeFlag(a))
-    if (positional) {
-      target = path.resolve(cwd, positional)
-      forwardArgs = remaining.slice(1).filter((a) => a !== positional)
+    // `rnx maestro test <flow-or-dir> [flags...]`. the flow path is the first
+    // token that is neither a flag nor the value of one — without the second
+    // half, `test --sim a2 login.yaml` takes `a2` as the flow file. remove it
+    // by index, since a path can equal a flag value elsewhere in the argv.
+    const rest = remaining.slice(1)
+    const positionalIndex = rest.findIndex(
+      (a, i) =>
+        !looksLikeFlag(a) && !(i > 0 && FLOW_ARG_VALUE_FLAGS.includes(rest[i - 1])),
+    )
+    if (positionalIndex >= 0) {
+      target = path.resolve(cwd, rest[positionalIndex])
+      forwardArgs = rest.filter((_, i) => i !== positionalIndex)
     } else {
       target = findDefaultMaestroTarget(cwd)
-      forwardArgs = remaining.slice(1)
+      forwardArgs = rest
     }
   } else if (sub && !looksLikeFlag(sub)) {
     // `rnx maestro <flow-or-dir>` — tolerate the shorthand.
@@ -343,6 +372,19 @@ export async function runMaestro(
     forwardArgs = remaining
   }
 
+  // every flag here is forwarded to each flow, so check the vocabulary once,
+  // before anything opens a sim. runFlowPlayback checks again for its
+  // programmatic callers; doing it here keeps a directory run from printing
+  // the same rejection once per flow after it has already started work.
+  const unexpected = findUnexpectedFlowArgs(['<flow>', ...forwardArgs])
+  if (unexpected.length > 0) {
+    for (const problem of unexpected) {
+      console.error(`  error: ${problem.message}`)
+    }
+    console.error('\n  run `rnx maestro --help` for the flags this command accepts')
+    return 1
+  }
+
   if (!target) {
     console.error(`
   error: no maestro flows found.
@@ -390,7 +432,7 @@ export async function runMaestro(
   let registerOriginPromise: Promise<string> | null = null
   const registerOrigin = () =>
     (registerOriginPromise ??= resolveDefaultUploadOrigin(
-      flagValue('--preview-origin') ?? flagValue('--origin'),
+      flagValue('--preview-origin') ?? originFlagValue,
     ))
 
   let worstExit = 0
@@ -414,8 +456,15 @@ export async function runMaestro(
     try {
       exit = await runFlowPlayback(playbackArgs)
     } catch (err) {
-      console.error(`  x ${(err as Error).message}`)
-      exit = 1
+      // rnxExit is a deliberate exit that already printed its own reason.
+      // reporting the sentinel's own text on top of it reads like a second,
+      // unrelated failure.
+      if (err instanceof RnxExit) {
+        exit = err.code || 1
+      } else {
+        console.error(`  x ${(err as Error).message}`)
+        exit = 1
+      }
     }
     results.push({ file, exit })
     if (exit !== 0 && worstExit === 0) worstExit = exit

package/cli/commands/platform.ts

@@ -1,9 +1,9 @@
 // `rnx ios` and `rnx android` — start a simulator on that platform.
 //
 // the platform picks the device; the command context picks WHERE the sim runs
-// (host, local box, or cloud box). there is deliberately no per-place spelling
-// such as `rnx cloud ios`, so this file only resolves the device and hands the
-// rest to the normal open path.
+// (this machine, a local box, or `--remote`). there is deliberately no
+// per-place spelling such as `rnx remote ios`, so this file only resolves the
+// device and hands the rest to the normal open path.
 
 import {
   DEFAULT_DEVICE_BY_PLATFORM,
@@ -26,10 +26,10 @@ function isDeviceModel(value: string): value is DeviceModel {
   return value in devices
 }
 
-const CLOUD_USAGE =
-  'usage: rnx ios --nano <local bundle.js|https://bundle-url> [--assets <dir>] [--device <model>]'
+const REMOTE_USAGE =
+  'usage: rnx ios --remote <local bundle.js|https://bundle-url> [--assets <dir>] [--device <model>]'
 
-function cloudInputFromArgs(args: string[]): {
+function remoteInputFromArgs(args: string[]): {
   bundlePath: string
   assetsPath: string | null
 } {
@@ -37,19 +37,19 @@ function cloudInputFromArgs(args: string[]): {
   let assetsPath: string | null = null
   for (let index = 0; index < args.length; index++) {
     const arg = args[index]
-    if (arg === '--nano' || arg === '--cloud') continue
+    if (arg === '--remote') continue
     if (arg === '--device') {
       index++
       continue
     }
     if (arg === '--assets') {
       assetsPath = args[++index] ?? null
-      if (!assetsPath) throw new Error('rnx ios --nano --assets requires a directory')
+      if (!assetsPath) throw new Error('rnx ios --remote --assets requires a directory')
       continue
     }
     if (arg.startsWith('--assets=')) {
       assetsPath = arg.slice('--assets='.length) || null
-      if (!assetsPath) throw new Error('rnx ios --nano --assets requires a directory')
+      if (!assetsPath) throw new Error('rnx ios --remote --assets requires a directory')
       continue
     }
     if (
@@ -60,14 +60,14 @@ function cloudInputFromArgs(args: string[]): {
       arg.startsWith('--session=') ||
       arg.startsWith('--tab=')
     ) {
-      throw new Error('rnx ios --nano creates a new simulator and cannot target --sim')
+      throw new Error('rnx ios --remote creates a new simulator and cannot target --sim')
     }
     if (arg.startsWith('-')) {
-      throw new Error(`rnx ios --nano does not support ${arg}`)
+      throw new Error(`rnx ios --remote does not support ${arg}`)
     }
     positional.push(arg)
   }
-  if (positional.length !== 1 || !positional[0]) throw new Error(CLOUD_USAGE)
+  if (positional.length !== 1 || !positional[0]) throw new Error(REMOTE_USAGE)
   return { bundlePath: positional[0], assetsPath }
 }
 
@@ -76,13 +76,6 @@ export async function runPlatformCommand(
   args: string[],
   opts: { port?: number } = {},
 ): Promise<number | undefined> {
-  if (args.includes('--micro')) {
-    console.error(
-      `  ${rnxPublicBrand.commandName} ${platform} --micro is not implemented`,
-    )
-    return 1
-  }
-
   // `--device` is applied to the settings store before dispatch, so a
   // contradiction shows up here as a platform mismatch. refuse it by name
   // rather than silently overriding whichever one the user meant.
@@ -121,33 +114,34 @@ export async function runPlatformCommand(
     }
   }
 
-  if (args.includes('--nano') || args.includes('--cloud')) {
+  if (args.includes('--remote')) {
     if (platform !== 'ios') {
       console.error(
-        `  ${rnxPublicBrand.commandName} android --nano is not available; RNX Cloud currently supports iOS`,
+        `  ${rnxPublicBrand.commandName} android --remote is not available; remote simulators are iOS only`,
       )
       return 1
     }
     try {
-      const input = cloudInputFromArgs(args)
+      const input = remoteInputFromArgs(args)
       const {
         publishCloudSessionToShell,
         readCloudSession,
         requireCloudSessionShellUpdate,
       } = await import('../cloud-session')
       const descriptor = requireCloudSessionShellUpdate()
-      const { authHeaderOrExit } = await import('../auth')
-      const { header } = authHeaderOrExit('ios --nano')
+      const { authHeaderOrExit, cloudAccountIdOrExit } = await import('../auth')
+      const { auth, header } = authHeaderOrExit('ios --remote')
+      const accountId = cloudAccountIdOrExit(auth)
       const existingSession = readCloudSession()
       if (existingSession) {
         const { addCloudSimulator } = await import('../cloud-client')
         const added = await addCloudSimulator(existingSession, {
           device: selectedDevice,
           authorization: header,
+          accountId,
         })
         publishCloudSessionToShell(added.session, descriptor)
-        console.log(`  cloud box: ${existingSession.boxId} (nano)`)
-        console.log(`  simulator: ${added.receipt.simId}`)
+        console.log(`  remote simulator: ${added.receipt.simId}`)
         console.log(`  claim expires: ${added.receipt.claim.expiresAt}`)
         console.log(
           '  commands: describe, find, get tree|node|count|memory, wait ready|selector, do, reset, logs, state, screenshot',
@@ -160,6 +154,7 @@ export async function runPlatformCommand(
         assetsPath: input.assetsPath ?? undefined,
         device: selectedDevice,
         authorization: header,
+        accountId,
       })
       try {
         publishCloudSessionToShell(created.session, descriptor)
@@ -169,8 +164,7 @@ export async function runPlatformCommand(
       }
       const receipt = created.receipt
       const produced = created.artifact
-      console.log(`  cloud box: ${receipt.boxId} (nano)`)
-      console.log(`  simulator: ${receipt.simulator.simId}`)
+      console.log(`  remote simulator: ${receipt.simulator.simId}`)
       console.log(`  artifact: ${receipt.artifact.id} (${receipt.artifact.bytes} bytes)`)
       console.log(
         `  source bundle: sha256:${produced.source.sha256} (${produced.source.bytes} bytes)`,
@@ -181,15 +175,21 @@ export async function runPlatformCommand(
       console.log(
         `  embedded assets: ${produced.assets.descriptors} descriptors, ${produced.assets.variants} scales, ${produced.assets.bytes} bytes (${produced.assets.encodedBytes} encoded)`,
       )
+      // the dest directory was chosen by resolving this bundle's descriptors
+      // against it, so say which one won rather than leaving it invisible.
+      if (created.assetsDirectory) {
+        console.log(`  asset dest: ${created.assetsDirectory}`)
+      }
       console.log(`  claim expires: ${receipt.simulator.claim.expiresAt}`)
       console.log(
         '  commands: describe, find, get tree|node|count|memory, wait ready|selector, do, reset, logs, state, screenshot',
       )
+      for (const warning of created.warnings) console.warn(`  warning: ${warning}`)
       return 0
     } catch (error) {
       rethrowIfExit(error)
       console.error(
-        `  ${rnxPublicBrand.commandName} ios --nano failed: ${
+        `  ${rnxPublicBrand.commandName} ios --remote failed: ${
           error instanceof Error ? error.message : String(error)
         }`,
       )
@@ -211,9 +211,7 @@ export async function runPlatformCommand(
       '--no-hmr',
       '--no-describe',
       '--quiet',
-      '--nano',
-      '--cloud',
-      '--micro',
+      '--remote',
     ],
     stripValueFlags: [
       '--base-url',

package/cli/commands/screenshot.ts

@@ -127,12 +127,13 @@ examples:
       const dataUrl: unknown = await cloudBridge.send({ type: 'screenshot' })
       const pngPrefix = 'data:image/png;base64,'
       if (typeof dataUrl !== 'string' || !dataUrl.startsWith(pngPrefix)) {
-        throw new Error('RNX Cloud screenshot returned invalid image data')
+        throw new Error('remote simulator screenshot returned invalid image data')
       }
       const outputPath = resolve(process.cwd(), outputArg || '/tmp/rnx-inspect.png')
       mkdirSync(dirname(outputPath), { recursive: true })
       const png = Buffer.from(dataUrl.slice(pngPrefix.length), 'base64')
-      if (png.length === 0) throw new Error('RNX Cloud screenshot returned no image data')
+      if (png.length === 0)
+        throw new Error('remote simulator screenshot returned no image data')
       writeFileSync(outputPath, png)
       console.log(`  saved: ${outputPath}`)
     } catch (error) {

package/cli/commands/upload.ts

@@ -28,7 +28,12 @@ import { authHeaderValue, githubUploadIdentity, resolveCliAuth } from '../auth'
 import { openUrl } from '../open-url'
 import { resolveRunProvenance } from '../run-registry'
 import { rnxExit } from '../run-rnx'
-import { createBridgeFromParsed, evalInBridge, parseBridgeCliArgs } from '../ws-bridge'
+import {
+  callInBridge,
+  createBridgeFromParsed,
+  evalInBridge,
+  parseBridgeCliArgs,
+} from '../ws-bridge'
 import type { SootSimTimelineEvent } from '@rnx/globals'
 
 interface UploadOptions {
@@ -313,25 +318,38 @@ function forceInlineBundle(bundleUrl: string): string {
   }
 }
 
-// pull window.__sootsimLastTransformedBundle.text over the bridge in
-// slices. a single eval returning tens of MB of base64 hits the ws
-// message framing cap; stringly slicing lets us page it in safely.
+// 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_500_000 // ~1.5 MB of utf-16 source per call
-  const pieces: string[] = []
+  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 evalInBridge<string | null>(
+    const chunk = await callInBridge<string | null>(
       bridge,
-      `(window.__sootsimLastTransformedBundle?.text || "").slice(${offset}, ${end})`,
+      'SootSim.bridges.readTransformedBundleSlice',
+      offset,
+      end,
     )
     if (typeof chunk !== 'string') return null
-    pieces.push(chunk)
+    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 pieces.join('')
+  return new TextDecoder().decode(joined)
 }
 
 type RecordedEntry = {

package/cli/help-core.ts

@@ -38,10 +38,20 @@ function backendLabel(command: string, args: readonly string[]): string {
 }
 
 function renderPreviewHelp(command: 'web' | 'ios' | 'android'): string {
+  // `rnx ios --remote` is the one leaf here that is not a preview selector, so
+  // the help has to name it or the flag is reachable only from the website.
+  const remote =
+    command === 'ios'
+      ? `
+  rnx ios --remote <bundle.js|https://bundle-url> [--assets <dir>] [--device <model>]
+                              run the bundle on a headless remote simulator.
+                              its Metro assets are found for you; --assets
+                              overrides that search.`
+      : ''
   return `rnx ${command} — select or ensure the current branch's existing ${command} preview
 
 usage:
-  rnx ${command}
+  rnx ${command}${remote}
 
 The browser backend selects the Factory-owned ${command} iframe. It never launches a
 host process or Cloudflare runtime.`