rnxsim 0.1.432 → 0.1.434

package/cli/cloud-client.ts

@@ -10,9 +10,13 @@ import {
 import { dirname, extname, join, resolve } from 'node:path'
 import {
   embedMetroAssetFiles,
+  extractAssetDescriptors,
+  metroAssetPlaceholderBytes,
   metroAssetScaleFilename,
   metroIosAssetDestRelatives,
-  resolveMetroIosAssetDestFile,
+  resolveMetroIosAssetDestFiles,
+  type MetroArtifactAssetSize,
+  type MetroAssetDescriptor,
 } from '../../contrast-bundler/src/metroAssetArtifact'
 import {
   buildRnxCloudArtifact,
@@ -20,6 +24,7 @@ import {
 } from '../../contrast-bundler/src/metroCloudArtifact'
 import { inferMetroModuleIdentity } from '../../sootsim-engine/src/metro-fingerprint'
 import { loadMetroFingerprintRegistry } from '../../sootsim-engine/src/metro-fingerprint-registry-client'
+import { isLoopbackHost } from '../src/backend-origin'
 import {
   isRnxCloudCommandType,
   RNX_CLOUD_MAX_ARTIFACT_BYTES,
@@ -31,12 +36,15 @@ import {
   type RNXMetroModuleIdentityMetadata,
 } from '../src/metro-production-bundle'
 import { rnxPublicBrand } from '../src/public-brand'
+import { CHOOSE_ACCOUNT_HINT } from './auth'
 import {
   createCloudSession,
   normalizeCloudOrigin,
   readCloudSession,
   type CloudSession,
 } from './cloud-session'
+import { detectProject, findProjectRoot } from './commands/detect'
+import type { StorageSnapshot } from '../../sootsim-engine/src/preview/storage-snapshot-contract'
 import type {
   BridgeClaimResult,
   BridgeSimInfo,
@@ -47,13 +55,35 @@ import type {
 export const DEFAULT_RNX_CLOUD_ORIGIN = rnxPublicBrand.origin
 export const MAX_RNX_CLOUD_BUNDLE_BYTES = RNX_CLOUD_MAX_ARTIFACT_BYTES
 
+// every message this module writes names the command through this constant.
+const REMOTE_COMMAND = 'rnx ios --remote'
+
+// an artifact this close to the ceiling is one asset away from being refused,
+// and the producer knows which assets it would be.
+const WARN_ARTIFACT_BYTES = Math.floor(MAX_RNX_CLOUD_BUNDLE_BYTES * 0.8)
+
+// a Metro asset dest is a shallow tree of images. a walk that runs past this
+// is pointed at something else entirely, and its extra entries cannot resolve
+// an asset anyway.
+const MAX_ASSET_DEST_FILES = 25_000
+
 interface CreateCloudBoxOptions {
   bundlePath: string
   device: string
   authorization: string
+  /** the account to bill when the authorization is a session token; an api key names its own */
+  accountId: string | null
   /** the `--assets-dest` directory Metro wrote beside the bundle. */
   assetsPath?: string
   apiOrigin?: string
+  /** the name this box carries in the account's box list. */
+  boxName?: string | null
+  /**
+   * the storage and route the first simulator boots with, captured from a
+   * running app. a snapshot reaches a megabyte, so a create that carries one
+   * is multipart rather than a bare artifact body.
+   */
+  storage?: StorageSnapshot | null
 }
 
 interface CloudCommandEnvelope {
@@ -66,18 +96,43 @@ function isRecord(value: unknown): value is Record<string, unknown> {
   return value !== null && typeof value === 'object' && !Array.isArray(value)
 }
 
-function responseError(status: number, text: string): Error {
-  if (text) {
-    try {
-      const parsed: unknown = JSON.parse(text)
-      const error = isRecord(parsed) ? parsed.error : null
-      if (isRecord(error) && typeof error.message === 'string') {
-        return new Error(`RNX Cloud request failed (${status}): ${error.message}`)
-      }
-    } catch {}
+// three services answer this client and each states a failure its own way:
+// the box service says { error: '<sentence>' }, the site's public api says
+// { error: '<code>', message: '<sentence>' }, and its service-to-service api
+// says { error: { code, message } }. all three carry one sentence meant for
+// the person at the terminal, so read whichever field holds it. without this
+// the sentence never reaches them and they get the raw json body instead.
+function failureSentence(text: string): string | null {
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(text)
+  } catch {
+    return null
+  }
+  if (!isRecord(parsed)) return null
+  if (isRecord(parsed.error) && typeof parsed.error.message === 'string') {
+    return parsed.error.message
   }
+  if (typeof parsed.message === 'string') return parsed.message
+  if (typeof parsed.error === 'string') return parsed.error
+  return null
+}
+
+// the account service says what it needs in its own words; the CLI says what
+// the person can do about it, which is choose the account at `rnx login`.
+const ACCOUNT_CHOICE_REFUSALS = new Set([
+  'accountId is required',
+  'you do not have access to this account',
+])
+
+function responseError(status: number, text: string): Error {
+  const parsed = text ? failureSentence(text) : null
+  const sentence =
+    parsed && ACCOUNT_CHOICE_REFUSALS.has(parsed) ? CHOOSE_ACCOUNT_HINT : parsed
   return new Error(
-    `RNX Cloud request failed (${status})${text.trim() ? `: ${text.trim()}` : ''}`,
+    `remote simulator request failed (${status})${
+      sentence ? `: ${sentence}` : text.trim() ? `: ${text.trim()}` : ''
+    }`,
   )
 }
 
@@ -90,16 +145,16 @@ function resolveCloudOrigin(value?: string): string {
 function readImmutableBundleSource(bundlePath: string): string {
   const filepath = resolve(bundlePath)
   if (extname(filepath) !== '.js') {
-    throw new Error('rnx ios --nano requires one local Metro .js bundle')
+    throw new Error(`${REMOTE_COMMAND} requires one local Metro .js bundle`)
   }
   const descriptor = openSync(filepath, 'r')
   try {
     const before = fstatSync(descriptor, { bigint: true })
     if (!before.isFile()) {
-      throw new Error('rnx ios --nano bundle must be a regular local file')
+      throw new Error(`${REMOTE_COMMAND} bundle must be a regular local file`)
     }
     if (before.size <= 0n) {
-      throw new Error('rnx ios --nano bundle is empty')
+      throw new Error(`${REMOTE_COMMAND} bundle is empty`)
     }
     const bytes = readFileSync(descriptor)
     const after = fstatSync(descriptor, { bigint: true })
@@ -110,16 +165,16 @@ function readImmutableBundleSource(bundlePath: string): string {
       before.mtimeNs !== after.mtimeNs ||
       bytes.length !== Number(before.size)
     ) {
-      throw new Error('rnx ios --nano bundle changed while it was being read')
+      throw new Error(`${REMOTE_COMMAND} bundle changed while it was being read`)
     }
     let source: string
     try {
       source = new TextDecoder('utf-8', { fatal: true }).decode(bytes)
     } catch {
-      throw new Error('rnx ios --nano bundle must be valid UTF-8 JavaScript')
+      throw new Error(`${REMOTE_COMMAND} bundle must be valid UTF-8 JavaScript`)
     }
     if (source.includes('\0') || !source.includes('__d(') || !source.includes('__r(')) {
-      throw new Error('rnx ios --nano requires a Metro JavaScript bundle')
+      throw new Error(`${REMOTE_COMMAND} requires a Metro JavaScript bundle`)
     }
     return source
   } finally {
@@ -133,33 +188,49 @@ async function fetchBundleSource(bundleUrl: string): Promise<string> {
     response = await fetch(bundleUrl)
   } catch (error) {
     throw new Error(
-      `rnx ios --nano could not fetch bundle from ${bundleUrl}: ${
+      `${REMOTE_COMMAND} could not fetch bundle from ${bundleUrl}: ${
         error instanceof Error ? error.message : String(error)
       }`,
     )
   }
   if (!response.ok) {
     throw new Error(
-      `rnx ios --nano could not fetch bundle from ${bundleUrl}: HTTP ${response.status}${
+      `${REMOTE_COMMAND} could not fetch bundle from ${bundleUrl}: HTTP ${response.status}${
         response.statusText ? ` ${response.statusText}` : ''
       }`,
     )
   }
   const text = await response.text()
   if (text.length === 0) {
-    throw new Error('rnx ios --nano bundle is empty')
+    throw new Error(`${REMOTE_COMMAND} bundle is empty`)
   }
   if (text.includes('\0') || !text.includes('__d(') || !text.includes('__r(')) {
-    throw new Error('rnx ios --nano requires a Metro JavaScript bundle')
+    throw new Error(`${REMOTE_COMMAND} requires a Metro JavaScript bundle`)
   }
   return text
 }
 
+// a bundle served over plain http is only trustworthy when it comes from this
+// machine, which is what "send to box" reads: the Metro dev server the app is
+// already running on.
+function isLoopbackBundleUrl(bundleInput: string): boolean {
+  if (!bundleInput.startsWith('http://')) return false
+  try {
+    return isLoopbackHost(new URL(bundleInput).hostname)
+  } catch {
+    return false
+  }
+}
+
+function isRemoteBundleInput(bundleInput: string): boolean {
+  return bundleInput.startsWith('https://') || bundleInput.startsWith('http://')
+}
+
 async function loadBundleSource(bundleInput: string): Promise<string> {
-  if (bundleInput.startsWith('http://')) {
-    throw new Error('rnx ios --nano bundle URL must use HTTPS')
+  if (bundleInput.startsWith('http://') && !isLoopbackBundleUrl(bundleInput)) {
+    throw new Error(`${REMOTE_COMMAND} bundle URL must use HTTPS`)
   }
-  if (bundleInput.startsWith('https://')) {
+  if (isRemoteBundleInput(bundleInput)) {
     return fetchBundleSource(bundleInput)
   }
   return readImmutableBundleSource(bundleInput)
@@ -168,10 +239,36 @@ async function loadBundleSource(bundleInput: string): Promise<string> {
 // `react-native bundle --assets-dest` dest paths are not always the JS
 // descriptor's httpServerLocation with `../` replaced by `_`. Metro 0.83 does
 // that (`__node_modules`); Metro 0.84 often dests `node_modules` and keeps the
-// project-root-relative app path. resolveMetroIosAssetDestFile matches both.
-function listMetroAssetDestFiles(assetsPath?: string): string[] {
-  if (!assetsPath || !existsSync(assetsPath)) return []
+// project-root-relative app path. resolveMetroIosAssetDestFiles matches both.
+interface MetroAssetDestListing {
+  directory: string
+  files: string[]
+  /** the walk stopped at the cap, so "not in this listing" proves nothing. */
+  truncated: boolean
+}
+
+// a Metro asset dest never holds these, but a project root does, and a
+// candidate can be either. `node_modules` is not in the list on purpose: a real
+// dest DOES carry one, because that is where `react-native bundle` copies the
+// assets that live inside packages. it is skipped only under a project root,
+// which is what a package.json at the candidate marks.
+const PROJECT_ONLY_DIRECTORIES = new Set([
+  'node_modules',
+  'Pods',
+  'DerivedData',
+  '.expo',
+  '.next',
+  '.turbo',
+  '.cache',
+  '.gradle',
+])
+
+function listMetroAssetDest(assetsPath: string): MetroAssetDestListing {
+  const directory = resolve(assetsPath)
+  if (!existsSync(directory)) return { directory, files: [], truncated: false }
+  const skipNested = existsSync(join(directory, 'package.json'))
   const files: string[] = []
+  let truncated = false
   const walk = (dir: string, prefix: string) => {
     let entries
     try {
@@ -180,13 +277,298 @@ function listMetroAssetDestFiles(assetsPath?: string): string[] {
       return
     }
     for (const entry of entries) {
-      const rel = prefix ? `${prefix}/${entry.name}` : entry.name
-      if (entry.isDirectory()) walk(join(dir, entry.name), rel)
-      else if (entry.isFile()) files.push(rel)
+      if (files.length >= MAX_ASSET_DEST_FILES) {
+        truncated = true
+        return
+      }
+      if (entry.isDirectory()) {
+        if (entry.name === '.git') continue
+        if (skipNested && PROJECT_ONLY_DIRECTORIES.has(entry.name)) continue
+        walk(join(dir, entry.name), prefix ? `${prefix}/${entry.name}` : entry.name)
+      } else if (entry.isFile()) {
+        files.push(prefix ? `${prefix}/${entry.name}` : entry.name)
+      }
+    }
+  }
+  walk(directory, '')
+  return { directory, files, truncated }
+}
+
+/**
+ * Metro's own identity for an asset. `getAbsoluteAssetInfo` in metro/src/Assets
+ * md5s every scale file's bytes into ONE digest, in the ascending scale order
+ * `buildAssetMap` keeps `scales` and `files` parallel in, and that digest is
+ * the descriptor's `hash`. so a directory can be asked whether it holds THIS
+ * asset instead of merely a file with the same name.
+ */
+function metroDescriptorHash(scaleBytes: readonly Buffer[]): string {
+  const hasher = createHash('md5')
+  for (const bytes of scaleBytes) hasher.update(bytes)
+  return hasher.digest('hex')
+}
+
+function metroAssetKey(descriptor: MetroAssetDescriptor): string {
+  return `${descriptor.httpServerLocation}/${descriptor.name}.${descriptor.type}`
+}
+
+/** where one descriptor's scales sit inside one candidate directory. */
+interface DescriptorPlacement {
+  /** the dest-relative file chosen for each declared scale that is present. */
+  files: Map<number, string>
+  /** files a scale matched that hold different images, so none was chosen. */
+  ambiguous: string[]
+  /** every declared scale is present and their bytes are Metro's `hash`. */
+  verified: boolean
+  /** every declared scale is present and their bytes are something else. */
+  mismatched: boolean
+}
+
+// an ambiguous scale is rare and its file count is small, so trying every
+// combination against the descriptor hash is cheap. the cap only stops a
+// pathological dest from turning identity into a search.
+const MAX_PLACEMENT_COMBINATIONS = 64
+
+function placementCombinations(perScale: readonly string[][]): string[][] {
+  let total = 1
+  for (const options of perScale) total *= options.length
+  if (total > MAX_PLACEMENT_COMBINATIONS) return []
+  let combinations: string[][] = [[]]
+  for (const options of perScale) {
+    combinations = combinations.flatMap((prefix) =>
+      options.map((option) => [...prefix, option]),
+    )
+  }
+  return combinations
+}
+
+/**
+ * one file per distinct image, out of the files a scale matched.
+ *
+ * two paths holding byte-identical images are not a choice to make, and the
+ * descriptor's hash could not separate them if they were.
+ */
+function distinctByContent(directory: string, options: readonly string[]): string[] {
+  if (options.length < 2) return [...options]
+  const byContent = new Map<string, string>()
+  for (const relative of options) {
+    let bytes: Buffer
+    try {
+      bytes = readFileSync(join(directory, relative))
+    } catch {
+      continue
     }
+    const digest = createHash('md5').update(bytes).digest('hex')
+    if (!byContent.has(digest)) byContent.set(digest, relative)
   }
-  walk(assetsPath, '')
-  return files
+  return [...byContent.values()]
+}
+
+/**
+ * decides what a candidate directory holds for one descriptor, by bytes.
+ *
+ * Metro hashes the asset's SOURCE files, and `react-native bundle` copies only
+ * @1x..@3x to an iOS dest while leaving `scales` unfiltered. so a descriptor
+ * that declares an Android rung such as @1.5x records a digest no iOS dest can
+ * reproduce, however complete that dest is. those come back neither verified
+ * nor mismatched, and the caller refuses when a whole bundle is like that
+ * rather than picking a directory it cannot check.
+ */
+function placeMetroDescriptor(
+  listing: MetroAssetDestListing,
+  descriptor: MetroAssetDescriptor,
+): DescriptorPlacement {
+  const perScale = descriptor.scales.map((scale) =>
+    distinctByContent(
+      listing.directory,
+      resolveMetroIosAssetDestFiles(listing.files, descriptor, scale),
+    ),
+  )
+  // a scale that resolved to one image names its file whatever the verdict
+  // below is. one that resolved to several is left for the hash to settle.
+  const files = new Map<number, string>()
+  const ambiguous: string[] = []
+  descriptor.scales.forEach((scale, index) => {
+    const options = perScale[index] ?? []
+    if (options.length === 1 && options[0]) files.set(scale, options[0])
+    else if (options.length > 1) ambiguous.push(...options)
+  })
+  if (perScale.length === 0 || perScale.some((options) => options.length === 0)) {
+    return { files, ambiguous, verified: false, mismatched: false }
+  }
+  for (const combination of placementCombinations(perScale)) {
+    let bytes: Buffer[]
+    try {
+      bytes = combination.map((relative) =>
+        readFileSync(join(listing.directory, relative)),
+      )
+    } catch {
+      continue
+    }
+    if (metroDescriptorHash(bytes) !== descriptor.hash) continue
+    const chosen = new Map<number, string>()
+    descriptor.scales.forEach((scale, index) => {
+      const relative = combination[index]
+      if (relative) chosen.set(scale, relative)
+    })
+    return { files: chosen, ambiguous: [], verified: true, mismatched: false }
+  }
+  // every declared scale is here and no arrangement of them is this asset, so
+  // the directory holds different images under these names.
+  return { files, ambiguous, verified: false, mismatched: true }
+}
+
+interface MetroAssetDest {
+  directory: string
+  /** the placement of each descriptor, in the order the bundle declares them. */
+  placements: DescriptorPlacement[]
+}
+
+interface MetroAssetSearch {
+  /** the directory the producer reads asset bytes from, or null if none held any. */
+  dest: MetroAssetDest | null
+  /** every directory the search considered, in order, for the warning text. */
+  searched: string[]
+  /** a walk stopped at the cap, so no directory can be called fully looked at. */
+  truncated: boolean
+}
+
+/**
+ * what two candidates could still disagree about.
+ *
+ * a verified placement's bytes reproduce Metro's own digest, so it is the right
+ * content wherever it was read from and two directories that both verified it
+ * are not in conflict. only the unverified files are a real fork, and they are
+ * keyed by absolute path because `<dir>/assets` and `<dir>` are both candidates
+ * and list the same files under different dest-relative names.
+ */
+function unverifiedFileKey(dest: MetroAssetDest): string {
+  return dest.placements
+    .filter((placement) => !placement.verified)
+    .flatMap((placement) =>
+      [...placement.files.values()].map((relative) => join(dest.directory, relative)),
+    )
+    .sort()
+    .join('\n')
+}
+
+/**
+ * finds the `--assets-dest` directory by RESOLVING the bundle's own asset
+ * descriptors against a short ordered list of the places Metro writes one, and
+ * CONFIRMING the bytes it finds against the md5 Metro recorded in each
+ * descriptor. name and layout alone are a popularity contest an unrelated build
+ * output can win; the hash makes it an identity check.
+ */
+function searchMetroAssetDest(
+  bundlePath: string,
+  descriptors: readonly MetroAssetDescriptor[],
+): MetroAssetSearch {
+  const bundleDirectory = dirname(resolve(bundlePath))
+  const candidates = [
+    join(bundleDirectory, 'assets'),
+    bundleDirectory,
+    resolve(bundleDirectory, '..', 'assets'),
+  ]
+  const cwd = process.cwd()
+  if (detectProject(cwd)?.hasMetroConfig) {
+    const root = findProjectRoot(cwd)
+    candidates.push(join(root, 'dist'), join(root, 'build'))
+  }
+  const searched: string[] = []
+  const holders: { dest: MetroAssetDest; verified: number }[] = []
+  const stale: string[] = []
+  let truncated = false
+  for (const candidate of candidates) {
+    const directory = resolve(candidate)
+    if (searched.includes(directory)) continue
+    searched.push(directory)
+    const listing = listMetroAssetDest(directory)
+    // a cut-short walk is remembered even when the candidate resolves nothing,
+    // because the reason it resolved nothing may be that it never finished.
+    if (listing.truncated) truncated = true
+    if (listing.files.length === 0) continue
+    const placements = descriptors.map((descriptor) =>
+      placeMetroDescriptor(listing, descriptor),
+    )
+    // one wrong asset is enough: a directory that provably holds different
+    // bytes under these names is a different build, not a partial dest.
+    if (placements.some((placement) => placement.mismatched)) {
+      stale.push(directory)
+      continue
+    }
+    const verified = placements.filter((placement) => placement.verified).length
+    if (verified === 0 && placements.every((placement) => placement.files.size === 0))
+      continue
+    holders.push({ dest: { directory, placements }, verified })
+  }
+  if (holders.length === 0) {
+    // every scale is on disk and none of it is this bundle's. saying the
+    // assets are missing would be false, and a stand-in over a stale image is
+    // the wrong repair for a dest that only needs rebuilding.
+    if (stale.length > 0) {
+      throw new Error(
+        `${REMOTE_COMMAND} found this bundle's assets in ${stale.join(', ')}, but their bytes are not the ones it was built against. Rebuild with \`react-native bundle --assets-dest ${stale[0]}\` so the bundle and the images match.`,
+      )
+    }
+    return { dest: null, searched, truncated }
+  }
+  const best = Math.max(...holders.map((holder) => holder.verified))
+  // a directory that confirmed nothing cannot outrank one that confirmed
+  // something, and when nothing anywhere confirmed, every claimant is a rival.
+  const rivals = holders.filter((holder) => holder.verified === best)
+  const distinct = new Set(rivals.map((rival) => unverifiedFileKey(rival.dest)))
+  const winner = rivals[0]
+  if (!winner) return { dest: null, searched, truncated }
+  if (distinct.size > 1) {
+    throw new Error(
+      `${REMOTE_COMMAND} found this bundle's assets in more than one directory and cannot tell which build wrote them: ${rivals
+        .map((rival) => rival.dest.directory)
+        .join(
+          ', ',
+        )}. Pass --assets <dir> to name the one \`react-native bundle --assets-dest\` wrote.`,
+    )
+  }
+  if (best === 0) {
+    // every descriptor declares a scale this directory does not hold, so not
+    // one of Metro's digests can be reproduced from it. that is ordinary for an
+    // asset carrying an Android rung such as @1.5x, and it is also exactly what
+    // a half-copied dest looks like, so there is nothing here to choose on.
+    throw new Error(
+      `${REMOTE_COMMAND} found images for this bundle in ${winner.dest.directory} but could not confirm a single one of them, so it will not guess that this is the build's own \`--assets-dest\`. Pass --assets <dir> to name the directory \`react-native bundle --assets-dest\` wrote.`,
+    )
+  }
+  return { dest: winner.dest, searched, truncated }
+}
+
+/**
+ * an explicitly named `--assets <dir>`. the caller promised this is the dest,
+ * so it is never ranked against anything, but its bytes are still checked
+ * against Metro's hashes so a stale dest is caught rather than shipped.
+ */
+function explicitMetroAssetDest(
+  directory: string,
+  descriptors: readonly MetroAssetDescriptor[],
+): MetroAssetSearch {
+  const listing = listMetroAssetDest(directory)
+  const placements = descriptors.map((descriptor) =>
+    placeMetroDescriptor(listing, descriptor),
+  )
+  return {
+    dest: { directory: listing.directory, placements },
+    searched: [listing.directory],
+    truncated: listing.truncated,
+  }
+}
+
+function largestEmbeddedAssets(
+  sizes: readonly MetroArtifactAssetSize[],
+  count: number,
+): string {
+  if (sizes.length === 0) return ''
+  const largest = sizes
+    .slice(0, count)
+    .map((entry) => `${entry.asset} ${entry.bytes} bytes`)
+    .join(', ')
+  return ` Largest embedded assets: ${largest}.`
 }
 
 async function inferCloudModuleIdentity(
@@ -197,9 +579,9 @@ async function inferCloudModuleIdentity(
     receipt = await loadMetroFingerprintRegistry()
   } catch (error) {
     throw new Error(
-      `rnx Cloud could not load the Metro fingerprint registry needed to identify this bundle: ${
+      `${REMOTE_COMMAND} could not load the Metro fingerprint registry needed to identify this bundle: ${
         error instanceof Error ? error.message : String(error)
-      }. Build it through the published Metro plugin: withRNX(config, { productionBundles: true }) for the production graph, or withRNX(config, { developmentBundles: true }) for the development graph.`,
+      }. Build it through the published Metro plugin: withRNX(config).`,
     )
   }
   try {
@@ -216,9 +598,9 @@ async function inferCloudModuleIdentity(
     }
   } catch (error) {
     throw new Error(
-      `rnx Cloud could not infer module identity for this Metro bundle: ${
+      `${REMOTE_COMMAND} could not infer module identity for this Metro bundle: ${
         error instanceof Error ? error.message : String(error)
-      }. Build it through the published Metro plugin: withRNX(config, { productionBundles: true }) for the production graph, or withRNX(config, { developmentBundles: true }) for the development graph.`,
+      }. Build it through the published Metro plugin: withRNX(config).`,
     )
   }
 }
@@ -230,27 +612,80 @@ async function inferCloudModuleIdentity(
  * an ordinary unannotated Metro production bundle is identified through the
  * published fingerprint registry; a withRNX footer remains the fast path.
  */
+export interface CloudArtifactProduction {
+  bytes: Buffer
+  sha256: string
+  receipt: RnxCloudArtifactReceipt
+  /** the asset dest directory the producer read, or null when it read none. */
+  assetsDirectory: string | null
+  /** what the CLI prints after the receipt. */
+  warnings: string[]
+}
+
 export async function produceCloudArtifact(
   bundlePath: string,
   assetsPath?: string,
-): Promise<{ bytes: Buffer; sha256: string; receipt: RnxCloudArtifactReceipt }> {
+): Promise<CloudArtifactProduction> {
   const source = await loadBundleSource(bundlePath)
-  const destFiles = assetsPath ? listMetroAssetDestFiles(assetsPath) : []
+  const descriptors = extractAssetDescriptors(source)
+  // an https bundle has no local tree to search, and a bundle with no assets
+  // has nothing to search for.
+  const search: MetroAssetSearch = assetsPath
+    ? explicitMetroAssetDest(resolve(assetsPath), descriptors)
+    : descriptors.length > 0 && !isRemoteBundleInput(bundlePath)
+      ? searchMetroAssetDest(bundlePath, descriptors)
+      : { dest: null, searched: [], truncated: false }
+  const dest = search.dest
+  // `embedMetroAssetFiles` re-parses the bundle, so its descriptors are equal
+  // to the ones the search placed but not the same objects.
+  const placements = new Map<string, DescriptorPlacement>()
+  descriptors.forEach((descriptor, index) => {
+    const placement = dest?.placements[index]
+    if (placement) placements.set(metroAssetKey(descriptor), placement)
+  })
+  const substituted: string[] = []
   const embedded = await embedMetroAssetFiles(source, async (variant) => {
-    const relative = resolveMetroIosAssetDestFile(
-      destFiles,
-      variant.descriptor,
-      variant.scale,
-    )
-    if (relative && assetsPath) return readFileSync(join(assetsPath, relative))
+    const label = metroAssetKey(variant.descriptor)
+    const placement = placements.get(label)
+    if (placement?.mismatched && dest) {
+      throw new Error(
+        `${REMOTE_COMMAND} found ${variant.descriptor.name}.${variant.descriptor.type} in ${dest.directory}, but its bytes are not the ones this bundle was built against. Rebuild with \`react-native bundle --assets-dest ${dest.directory}\` so the bundle and the images match.`,
+      )
+    }
+    const relative = placement?.files.get(variant.scale)
+    if (relative && dest) return readFileSync(join(dest.directory, relative))
     // iOS copies only @1x..@3x, so a declared scale with no file is ordinary
-    // and the producer narrows the descriptor. an asset with no file at any
-    // scale is the real failure, and this is where the dest path a customer
-    // should look for is still known.
-    const written = variant.descriptor.scales.some((scale) =>
-      resolveMetroIosAssetDestFile(destFiles, variant.descriptor, scale),
-    )
-    if (written) return null
+    // and the producer narrows the descriptor.
+    if (placement && placement.files.size > 0) return null
+    if (placement && placement.ambiguous.length > 0 && dest) {
+      throw new Error(
+        `${REMOTE_COMMAND} found more than one image for ${label} in ${dest.directory} and none of them is the one Metro hashed: ${placement.ambiguous.sort().join(', ')}. Pass --assets <dir> to name the directory \`react-native bundle --assets-dest\` wrote.`,
+      )
+    }
+    // a stand-in is only honest when the asset is genuinely absent from a
+    // directory we know is the right one. an explicitly named dest is a
+    // promise, not a guess, so a miss there is a typo, and a truncated walk
+    // never finished looking. both refuse instead of shipping bytes nobody
+    // chose.
+    if (assetsPath) {
+      throw new Error(
+        `${REMOTE_COMMAND} could not find ${label} under --assets ${dest?.directory ?? resolve(assetsPath)}. Point --assets at the directory \`react-native bundle --assets-dest\` wrote, or drop the flag to let ${REMOTE_COMMAND} find it.`,
+      )
+    }
+    if (search.truncated) {
+      throw new Error(
+        `${REMOTE_COMMAND} stopped listing ${search.searched.join(', ')} after ${MAX_ASSET_DEST_FILES} files and never reached ${label}, so it cannot tell a missing asset from an unread one. Pass --assets <dir> to name the directory \`react-native bundle --assets-dest\` wrote.`,
+      )
+    }
+    // no scale of this asset exists anywhere the search looked. an image can
+    // stand in visibly and let the app run; every declared scale gets the same
+    // stand-in, because narrowing to one would rewrite a `scales` list the
+    // descriptor may not even carry.
+    const placeholder = metroAssetPlaceholderBytes(variant.descriptor.type)
+    if (placeholder) {
+      if (!substituted.includes(label)) substituted.push(label)
+      return placeholder
+    }
     const filename = metroAssetScaleFilename(
       variant.descriptor.name,
       variant.descriptor.type,
@@ -259,24 +694,37 @@ export async function produceCloudArtifact(
     const classic =
       metroIosAssetDestRelatives(variant.descriptor.httpServerLocation, filename)[0] ??
       filename
-    const lookupPath = assetsPath ?? '.'
     throw new Error(
-      `rnx ios --nano could not read ${join(lookupPath, classic)} for ${variant.descriptor.name}.${variant.descriptor.type} at scale ${variant.scale}. Build the bundle with --assets-dest, or pass --assets <dir>.`,
+      `${REMOTE_COMMAND} could not read ${join(dest?.directory ?? '.', classic)} for ${variant.descriptor.name}.${variant.descriptor.type} at scale ${variant.scale}, and has no stand-in for a .${variant.descriptor.type} asset. Build the bundle with --assets-dest, or pass --assets <dir>.`,
     )
   })
   const artifact = await buildRnxCloudArtifact(embedded.code, {
     inferModuleIdentity: inferCloudModuleIdentity,
   })
   const bytes = Buffer.from(artifact.code, 'utf8')
+  const assets = artifact.receipt.assets
   if (bytes.length > MAX_RNX_CLOUD_BUNDLE_BYTES) {
     throw new Error(
-      `rnx ios --nano artifact is ${bytes.length} bytes and exceeds the ${MAX_RNX_CLOUD_BUNDLE_BYTES}-byte limit`,
+      `${REMOTE_COMMAND} artifact is ${bytes.length} bytes and exceeds the ${MAX_RNX_CLOUD_BUNDLE_BYTES}-byte limit. Embedded assets weigh ${assets.bytes} bytes on disk, and base64 embedding costs about a third on top of that, so the practical asset budget is roughly 15 MB.${largestEmbeddedAssets(assets.sizes, 10)}`,
+    )
+  }
+  const warnings: string[] = []
+  if (substituted.length > 0) {
+    warnings.push(
+      `${REMOTE_COMMAND} embedded a placeholder image for ${substituted.length} asset(s) no scale of which is in ${search.searched.join(', ') || 'any asset dest directory'}: ${substituted.join(', ')}. Build the bundle with --assets-dest, or pass --assets <dir>, to ship the real images.`,
+    )
+  }
+  if (bytes.length >= WARN_ARTIFACT_BYTES) {
+    warnings.push(
+      `${REMOTE_COMMAND} artifact is ${bytes.length} bytes, ${Math.round((bytes.length / MAX_RNX_CLOUD_BUNDLE_BYTES) * 100)}% of the ${MAX_RNX_CLOUD_BUNDLE_BYTES}-byte limit.${largestEmbeddedAssets(assets.sizes, 5)}`,
     )
   }
   return {
     bytes,
     sha256: createHash('sha256').update(bytes).digest('hex'),
     receipt: artifact.receipt,
+    assetsDirectory: dest?.directory ?? null,
+    warnings,
   }
 }
 
@@ -289,7 +737,7 @@ function readCreateResponse(
   boxToken: string
   simulatorToken: string
 } {
-  if (!isRecord(value)) throw new Error('RNX Cloud create returned invalid JSON')
+  if (!isRecord(value)) throw new Error('remote simulator create returned invalid JSON')
   const artifactId = `sha256:${expectedSha256}` as const
   const isExpectedArtifact = (artifact: unknown): artifact is { bytes: number } =>
     isRecord(artifact) &&
@@ -321,7 +769,7 @@ function readCreateResponse(
     typeof simulatorToken !== 'string' ||
     !simulatorToken
   ) {
-    throw new Error('RNX Cloud create returned an invalid box receipt')
+    throw new Error('remote simulator create returned an invalid receipt')
   }
   return {
     receipt: {
@@ -339,38 +787,51 @@ function readCreateResponse(
   }
 }
 
-// `rnx ios --nano <bundle>` creates a nano box around the artifact with its
-// first simulator in one request, and the shell then targets that box
+// `rnx ios --remote <bundle>` creates the remote host for the artifact and its
+// first simulator in one request, and the shell then targets that simulator
 export async function createCloudBox(options: CreateCloudBoxOptions): Promise<{
   receipt: RnxCloudBoxCreateReceipt
   session: CloudSession
   artifact: RnxCloudArtifactReceipt
+  assetsDirectory: string | null
+  warnings: string[]
 }> {
   const apiOrigin = resolveCloudOrigin(options.apiOrigin)
-  const isUrl = options.bundlePath.startsWith('https://')
-  const assetsPath = options.assetsPath
-    ? resolve(options.assetsPath)
-    : isUrl
-      ? undefined
-      : resolve(dirname(options.bundlePath))
-  const artifact = await produceCloudArtifact(options.bundlePath, assetsPath)
+  const artifact = await produceCloudArtifact(options.bundlePath, options.assetsPath)
+  const boxName = options.boxName?.trim()
+  const headers: Record<string, string> = {
+    authorization: options.authorization,
+    'x-rnx-box-size': 'nano',
+    'x-rnx-artifact-sha256': artifact.sha256,
+    'x-rnx-platform': 'ios',
+    'x-rnx-device': options.device,
+    ...(options.accountId ? { 'x-rnx-account-id': options.accountId } : null),
+    ...(boxName ? { 'x-rnx-box-name': boxName } : null),
+  }
+  let body: BodyInit
+  if (options.storage) {
+    const form = new FormData()
+    form.append(
+      'artifact',
+      new Blob([new Uint8Array(artifact.bytes)], { type: 'application/javascript' }),
+      'bundle.js',
+    )
+    form.append('storage', JSON.stringify(options.storage))
+    body = form
+  } else {
+    headers['content-type'] = 'application/javascript'
+    body = new Uint8Array(artifact.bytes)
+  }
   let response: Response
   try {
     response = await fetch(`${apiOrigin}/v1/boxes`, {
       method: 'POST',
-      headers: {
-        authorization: options.authorization,
-        'content-type': 'application/javascript',
-        'x-rnx-box-size': 'nano',
-        'x-rnx-artifact-sha256': artifact.sha256,
-        'x-rnx-platform': 'ios',
-        'x-rnx-device': options.device,
-      },
-      body: new Uint8Array(artifact.bytes),
+      headers,
+      body,
     })
   } catch (error) {
     throw new Error(
-      `could not reach RNX Cloud at ${apiOrigin}: ${
+      `${REMOTE_COMMAND} could not reach ${apiOrigin}: ${
         error instanceof Error ? error.message : String(error)
       }`,
     )
@@ -381,7 +842,7 @@ export async function createCloudBox(options: CreateCloudBoxOptions): Promise<{
   try {
     parsed = JSON.parse(responseText)
   } catch {
-    throw new Error('RNX Cloud create returned unreadable JSON')
+    throw new Error('remote simulator create returned unreadable JSON')
   }
   const created = readCreateResponse(parsed, artifact.bytes.length, artifact.sha256)
   const session = createCloudSession({
@@ -392,7 +853,13 @@ export async function createCloudBox(options: CreateCloudBoxOptions): Promise<{
     claimId: created.receipt.simulator.claim.id,
     token: created.simulatorToken,
   })
-  return { receipt: created.receipt, session, artifact: artifact.receipt }
+  return {
+    receipt: created.receipt,
+    session,
+    artifact: artifact.receipt,
+    assetsDirectory: artifact.assetsDirectory,
+    warnings: artifact.warnings,
+  }
 }
 
 export function resolveCloudSessionForParsed(
@@ -402,7 +869,7 @@ export function resolveCloudSessionForParsed(
   if (!session) return null
   if (parsed.simIdSource === 'flag' && parsed.simId !== session.simId) {
     throw new Error(
-      `this shell is connected to RNX Cloud simulator ${session.simId}; ${
+      `this shell is connected to remote simulator ${session.simId}; ${
         parsed.simId ? `--sim ${parsed.simId}` : 'the requested simulator'
       } is not available in this shell`,
     )
@@ -419,7 +886,9 @@ function cloudCommand(command: {
     if (key !== 'id' && key !== 'simId') clean[key] = value
   }
   if (isRnxCloudCommandType(command.type)) return clean
-  throw new Error(`RNX Cloud does not support bridge command type ${command.type}`)
+  throw new Error(
+    `a remote simulator does not support bridge command type ${command.type}`,
+  )
 }
 
 class CloudBridge implements WsBridge {
@@ -454,7 +923,7 @@ class CloudBridge implements WsBridge {
       )
     } catch (error) {
       throw new Error(
-        `could not reach RNX Cloud at ${this.session.apiOrigin}: ${
+        `could not reach the remote simulator at ${this.session.apiOrigin}: ${
           error instanceof Error ? error.message : String(error)
         }`,
       )
@@ -465,34 +934,38 @@ class CloudBridge implements WsBridge {
     try {
       parsed = JSON.parse(text)
     } catch {
-      throw new Error('RNX Cloud command returned unreadable JSON')
+      throw new Error('remote simulator command returned unreadable JSON')
     }
     if (!isRecord(parsed) || parsed.id !== body.id) {
-      throw new Error('RNX Cloud command returned an invalid command receipt')
+      throw new Error('remote simulator command returned an invalid command receipt')
     }
     if (typeof parsed.error === 'string' && parsed.error) throw new Error(parsed.error)
     if (!Object.hasOwn(parsed, 'result')) {
-      throw new Error('RNX Cloud command receipt has no result')
+      throw new Error('remote simulator command receipt has no result')
     }
     return parsed.result
   }
 
   listSims(): Promise<BridgeSimInfo[]> {
-    return Promise.reject(new Error('RNX Cloud does not expose a local simulator list'))
+    return Promise.reject(
+      new Error('a remote simulator does not expose a local simulator list'),
+    )
   }
 
   focusSim(): Promise<never> {
-    return Promise.reject(
-      new Error('RNX Cloud simulators have no browser window to focus'),
-    )
+    return Promise.reject(new Error('remote simulators have no browser window to focus'))
   }
 
   closeSim(): Promise<never> {
-    return Promise.reject(new Error('RNX Cloud close uses the simulator DELETE route'))
+    return Promise.reject(
+      new Error('remote simulator close uses the simulator DELETE route'),
+    )
   }
 
   claim(): Promise<BridgeClaimResult> {
-    return Promise.reject(new Error('RNX Cloud claim uses the simulator claim route'))
+    return Promise.reject(
+      new Error('remote simulator claim uses the simulator claim route'),
+    )
   }
 
   close(): void {}
@@ -511,7 +984,7 @@ function readClaimResponse(value: unknown): { id: string; expiresAt: number } {
     !claim.id ||
     typeof claim.expiresAt !== 'number'
   ) {
-    throw new Error('RNX Cloud claim returned an invalid receipt')
+    throw new Error('remote simulator claim returned an invalid receipt')
   }
   return { id: claim.id, expiresAt: claim.expiresAt }
 }
@@ -542,7 +1015,7 @@ export async function claimCloudSimulator(
   try {
     parsed = JSON.parse(text)
   } catch {
-    throw new Error('RNX Cloud claim returned unreadable JSON')
+    throw new Error('remote simulator claim returned unreadable JSON')
   }
   const claim = readClaimResponse(parsed)
   return {
@@ -554,7 +1027,7 @@ export async function claimCloudSimulator(
 export async function confirmCloudSimulator(session: CloudSession): Promise<void> {
   const confirmed = await claimCloudSimulator(session)
   if (confirmed.session.claimId !== session.claimId) {
-    throw new Error('RNX Cloud confirmation replaced the initial claim')
+    throw new Error('remote simulator confirmation replaced the initial claim')
   }
 }
 
@@ -576,6 +1049,7 @@ export async function closeCloudBox(session: CloudSession): Promise<void> {
 export interface AddCloudSimulatorOptions {
   device: string
   authorization: string
+  accountId: string | null
 }
 
 export async function addCloudSimulator(
@@ -595,13 +1069,14 @@ export async function addCloudSimulator(
           authorization: `Bearer ${session.boxToken}`,
           'x-rnx-account-authorization': options.authorization,
           'content-type': 'application/json',
+          ...(options.accountId ? { 'x-rnx-account-id': options.accountId } : {}),
         },
         body: JSON.stringify({ device: options.device }),
       },
     )
   } catch (error) {
     throw new Error(
-      `could not reach RNX Cloud at ${session.apiOrigin}: ${
+      `could not reach the remote simulator at ${session.apiOrigin}: ${
         error instanceof Error ? error.message : String(error)
       }`,
     )
@@ -617,16 +1092,19 @@ export async function addCloudSimulator(
             (isRecord(parsed.error) && parsed.error.code === 'unknown_artifact'))
         ) {
           throw new Error(
-            'this box does not hold a new bundle; run `rnx close` and create again',
+            'this remote simulator does not hold a new bundle; run `rnx close` and create again',
           )
         }
       } catch (err) {
-        if (err instanceof Error && err.message.startsWith('this box does not hold')) {
+        if (
+          err instanceof Error &&
+          err.message.startsWith('this remote simulator does not hold')
+        ) {
           throw err
         }
       }
       throw new Error(
-        'this box does not hold a new bundle; run `rnx close` and create again',
+        'this remote simulator does not hold a new bundle; run `rnx close` and create again',
       )
     }
     throw responseError(response.status, responseText)
@@ -635,10 +1113,10 @@ export async function addCloudSimulator(
   try {
     parsed = JSON.parse(responseText)
   } catch {
-    throw new Error('RNX Cloud simulator create returned unreadable JSON')
+    throw new Error('remote simulator create returned unreadable JSON')
   }
   if (!isRecord(parsed) || !isRecord(parsed.simulator)) {
-    throw new Error('RNX Cloud simulator create returned an invalid receipt')
+    throw new Error('remote simulator create returned an invalid receipt')
   }
   const simulator = parsed.simulator
   const simId = simulator.simId
@@ -658,7 +1136,7 @@ export async function addCloudSimulator(
     typeof artifact.id !== 'string' ||
     typeof artifact.bytes !== 'number'
   ) {
-    throw new Error('RNX Cloud simulator create returned an invalid receipt')
+    throw new Error('remote simulator create returned an invalid receipt')
   }
   const receipt: RnxCloudCreateReceipt = {
     simId,