peachsim 0.1.1406 → 0.1.1463

package/kotlin/tools/expo-types.main.kts

@@ -76,13 +76,25 @@ for (path in args) {
                 type.typeArgumentsAsTypes.singleOrNull()?.text ?: ""
             }
             if (composeView != null && !klass.hasModifier(KtTokens.ABSTRACT_KEYWORD)) {
-                views += "{\"name\":${quote(name)},\"hidden\":$isHidden,\"props\":${quote(composeView)}}"
+                views += "{\"name\":${quote(name)},\"hidden\":$isHidden,\"props\":${quote(composeView)},\"appContext\":true}"
                 return
             }
-            if (!klass.hasModifier(KtTokens.ABSTRACT_KEYWORD) && klass.superTypeListEntries.any {
-                (it.typeReference?.typeElement as? KtUserType)?.referencedName == "ExpoView"
-            }) {
-                views += "{\"name\":${quote(name)},\"hidden\":$isHidden,\"props\":\"\"}"
+            val isAndroidView = !klass.hasModifier(KtTokens.ABSTRACT_KEYWORD) && klass.superTypeListEntries.any {
+                val ref = it.typeReference?.text?.substringAfterLast('.')
+                ref == "ExpoView" || ref == "View" || ref == "FrameLayout" || ref == "LinearLayout" || ref == "ViewGroup"
+            }
+            if (isAndroidView) {
+                // native selects exact public constructor signatures, preferring Context/AppContext.
+                val constructors = listOfNotNull(klass.primaryConstructor) + klass.secondaryConstructors
+                val signatures = constructors.filter { !hidden(it) }.map { ctor ->
+                    ctor.valueParameters.map { it.typeReference?.text?.substringAfterLast('.') }
+                }
+                val takesAppContext = when {
+                    listOf("Context", "AppContext") in signatures -> true
+                    listOf("Context") in signatures -> false
+                    else -> return
+                }
+                views += "{\"name\":${quote(name)},\"hidden\":$isHidden,\"props\":\"\",\"appContext\":$takesAppContext}"
                 return
             }
             if (klass.superTypeListEntries.any { it.typeReference?.text?.substringAfterLast('.') == "ComposeProps" }) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "peachsim",
-  "version": "0.1.1406",
+  "version": "0.1.1463",
   "description": "Vite and Metro plugins, testing drivers, and SDK exports for peach.",
   "author": "Tamagui LLC",
   "license": "SEE LICENSE IN LICENSE",
@@ -370,6 +370,7 @@
     "pngjs": "catalog:",
     "rollup": "4.62.2",
     "systemjs": "6.15.1",
+    "tsconfck": "3.1.6",
     "typescript": "7.1.0-dev.20261003.1",
     "vite": "8.3.3",
     "yaml": "^2.8.3"

package/scripts/dev-server-scanner.ts

@@ -861,38 +861,48 @@ export async function probePort(
   // going through scanDevServers. wait for the optional in-repo registry here
   // too, or a cold CLI process can build the known app's bundle url before its
   // runtime config is available.
-  await loadOptionalDemoApps()
+  const demoApps = await loadOptionalDemoApps()
   const probeHostname = await tcpPing(port)
   if (!probeHostname) return null
 
+  // the owner lists a scanned server's project, and its cwd picks an in-repo
+  // demo app's runtime config. a direct probe on a published install has
+  // neither use, so it skips the lookups, which shell out to lsof on macOS.
+  // when they run, they overlap the http probes, which cost about as much.
   const suppliedPid = listeningProcess?.pid
-  const ownerPid =
-    suppliedPid && suppliedPid > 0 ? suppliedPid : await resolveListeningPid(port)
-  const ownerCwd = ownerPid ? await resolveProcessCwd(ownerPid) : null
-  const owner: Pick<DiscoveredServer, 'cwd' | 'pid'> = {
-    ...(ownerPid ? { pid: ownerPid } : {}),
-    ...(ownerCwd ? { cwd: ownerCwd } : {}),
-  }
+  const ownerPromise = (async (): Promise<Pick<DiscoveredServer, 'cwd' | 'pid'>> => {
+    if (!listeningProcess && demoApps.length === 0) return {}
+    const ownerPid =
+      suppliedPid && suppliedPid > 0 ? suppliedPid : await resolveListeningPid(port)
+    const ownerCwd = ownerPid ? await resolveProcessCwd(ownerPid) : null
+    return {
+      ...(ownerPid ? { pid: ownerPid } : {}),
+      ...(ownerCwd ? { cwd: ownerCwd } : {}),
+    }
+  })()
 
   const onePath = `/node_modules/one/metro-entry.bundle?platform=ios&dev=true`
 
   // wave 1 — safe parallel probes. none of these mutate metro state.
-  const [sootsimRes, statusRes, manifestRes, expoRes, swiftRes, oneScanRes] =
+  const [[sootsimRes, statusRes, manifestRes, expoRes, swiftRes, oneScanRes], owner] =
     await Promise.all([
-      knownNonPatched.has(port)
-        ? Promise.resolve(null)
-        : httpGet(probeHostname, port, '/__peachsim/'),
-      httpGet(probeHostname, port, '/status'),
-      knownOne.has(port)
-        ? Promise.resolve(null)
-        : httpGet(probeHostname, port, '/', 'GET', MANIFEST_TIMEOUT_MS, {
-            'expo-platform': 'ios',
-          }),
-      knownNonExpo.has(port)
-        ? Promise.resolve(null)
-        : httpGet(probeHostname, port, '/_expo/status'),
-      httpGet(probeHostname, port, SWIFT_DISCOVERY_PATH),
-      httpGet(probeHostname, port, '/__server-scan', 'GET', MANIFEST_TIMEOUT_MS),
+      Promise.all([
+        knownNonPatched.has(port)
+          ? Promise.resolve(null)
+          : httpGet(probeHostname, port, '/__peachsim/'),
+        httpGet(probeHostname, port, '/status'),
+        knownOne.has(port)
+          ? Promise.resolve(null)
+          : httpGet(probeHostname, port, '/', 'GET', MANIFEST_TIMEOUT_MS, {
+              'expo-platform': 'ios',
+            }),
+        knownNonExpo.has(port)
+          ? Promise.resolve(null)
+          : httpGet(probeHostname, port, '/_expo/status'),
+        httpGet(probeHostname, port, SWIFT_DISCOVERY_PATH),
+        httpGet(probeHostname, port, '/__server-scan', 'GET', MANIFEST_TIMEOUT_MS),
+      ]),
+      ownerPromise,
     ])
 
   // the One plugin advertises its exact native entry, including replacement

package/src/assetCatalogContract.ts

@@ -47,6 +47,13 @@ export type SwiftImageResources = Record<string, Record<string, SwiftImageVarian
 // an app catalog color resolves by appearance or names a system color.
 export type AppCatalogColor = { light: string; dark: string } | { system: string }
 
+// the premultiplied sRGB rendition SwiftUI passes to a shader image argument.
+export interface SfSymbolShaderImage {
+  readonly width: number
+  readonly height: number
+  readonly pixels: Uint8Array
+}
+
 // UIImage's ordered monochrome layers and unrounded content bearings.
 export interface SfSymbolImageDrawing {
   referencePointSize: number

package/src/bridge-contract.ts

@@ -351,8 +351,12 @@ export interface SemanticReadyProbe {
   flag: unknown
   at: number
   nodes: number
+  // ms the counted tree had held its shape when the count was read; 0 when
+  // the reader cannot tell
+  treeQuietMs: number
   targets: number
   liveFrameActive: boolean
+  paintedAppContent: boolean
   browserSurfaceCount: number
   liveFrameChannels: number
   liveFramePublishes: number
@@ -378,9 +382,15 @@ export const HEADLESS_TENANT_FETCH_HUNG_MARKER = 'headless tenant fetch hung'
 
 export function readyProbeHasContent(
   probe: Pick<SemanticReadyProbe, 'nodes' | 'targets'> &
-    Partial<Pick<SemanticReadyProbe, 'liveFrameActive' | 'browserSurfaceCount'>>,
+    Partial<
+      Pick<
+        SemanticReadyProbe,
+        'liveFrameActive' | 'browserSurfaceCount' | 'paintedAppContent'
+      >
+    >,
 ): boolean {
   return (
+    probe.paintedAppContent === true ||
     (probe.browserSurfaceCount ?? 0) > 0 ||
     probe.liveFrameActive ||
     probe.targets > 0 ||
@@ -390,10 +400,18 @@ export function readyProbeHasContent(
 
 export function readyProbeHasTargetContent(
   probe: Pick<SemanticReadyProbe, 'targets'> &
-    Partial<Pick<SemanticReadyProbe, 'liveFrameActive' | 'browserSurfaceCount'>>,
+    Partial<
+      Pick<
+        SemanticReadyProbe,
+        'liveFrameActive' | 'browserSurfaceCount' | 'paintedAppContent'
+      >
+    >,
 ): boolean {
   return (
-    (probe.browserSurfaceCount ?? 0) > 0 || probe.liveFrameActive || probe.targets > 0
+    probe.paintedAppContent === true ||
+    (probe.browserSurfaceCount ?? 0) > 0 ||
+    probe.liveFrameActive ||
+    probe.targets > 0
   )
 }
 

package/src/connect.ts

@@ -9,7 +9,13 @@ import {
   resolveCloudSessionForParsed,
 } from '../cli/cloud-client'
 import { readCurrentSimId } from '../cli/current-sim'
-import { createBridge, resolveBridgeWorld, type BridgeSimInfo } from '../cli/ws-bridge'
+import {
+  createBridge,
+  createBridgeFromParsed,
+  resolveBridgeWorld,
+  type BridgeSimInfo,
+  type ParsedBridgeCliArgs,
+} from '../cli/ws-bridge'
 import { SimClient, SimConnectError } from './sim-client'
 
 export interface ConnectOptions {
@@ -72,15 +78,22 @@ export async function connect(options: ConnectOptions = {}): Promise<SimClient>
     })
   }
 
-  const port = options.port ?? resolveBridgeWorld().bridgePort
   const commandTimeoutMs = options.timeoutMs ?? 15_000
+  const parsed = {
+    ...target,
+    wsPort: options.port ?? resolveBridgeWorld().bridgePort,
+    explicitPort: options.port !== undefined,
+    commandTimeoutMs,
+    positional: [],
+  } satisfies ParsedBridgeCliArgs
 
   // discovery socket: list sims and pick the target. closed before the pinned
   // client socket is opened so a failed connect never leaks a connection.
-  const discovery = createBridge(port, { commandTimeoutMs, cliLabel: 'sdk' })
+  const discovery = createBridgeFromParsed(parsed)
   let picked: BridgeSimInfo
   try {
-    picked = pickSim(await discovery.listSims(), options.sim, port)
+    const sims = await discovery.listSims()
+    picked = pickSim(sims, options.sim, parsed.wsPort)
   } catch (error) {
     discovery.close()
     if (error instanceof SimConnectError) throw error
@@ -91,7 +104,7 @@ export async function connect(options: ConnectOptions = {}): Promise<SimClient>
 
   // pinned socket: every command targets exactly the picked sim, immune to the
   // CLI's saved-pin re-resolution.
-  const bridge = createBridge(port, {
+  const bridge = createBridge(parsed.wsPort, {
     commandTimeoutMs,
     cliLabel: 'sdk',
     simId: picked.id,

package/src/desktop-host-delivery.ts

@@ -1,6 +1,6 @@
 // peach's binding of the shared runtime-delivery machinery for the native
 // desktop host. the host releases on its own (packages/peach-desktop's Native
-// Desktop Release workflow) and the CLI downloads and verifies each version
+// Desktop Release workflow) and explicit installs download and verify each version
 // into ~/.peach/desktop/versions/<version>/, exactly as `peach runtime install` manages
 // the engine runtime. on macOS the active version is at /Applications/Peach.app,
 // where Spotlight finds it and the CLI, the fleet installer and the app's own
@@ -9,6 +9,7 @@
 // its active version under ~/.peach and bundles node and software vulkan.
 
 import { spawnSync } from 'node:child_process'
+import { createHash } from 'node:crypto'
 import fs from 'node:fs'
 import os from 'node:os'
 import path from 'node:path'
@@ -185,6 +186,32 @@ export function activeDesktopHostApp(): string | null {
   return process.platform === 'darwin' && placedHostVersion() ? MAC_HOST_APP : null
 }
 
+/** protocol 2 binds port zero before publishing the host origin and evaluates
+ *  in its realms over node ipc for the process that started it. the receipt
+ *  travels inside the checksummed archive and signed mac bundle. bind its
+ *  declaration to the entry bytes so a receipt cannot bless another source. */
+export function hostEntrySupportsAutomaticPort(hostEntry: string): boolean {
+  try {
+    const contract: unknown = JSON.parse(
+      fs.readFileSync(
+        path.join(path.dirname(hostEntry), 'headless-contract.json'),
+        'utf8',
+      ),
+    )
+    return (
+      typeof contract === 'object' &&
+      contract !== null &&
+      'protocol' in contract &&
+      contract.protocol === 2 &&
+      'entrySha256' in contract &&
+      contract.entrySha256 ===
+        createHash('sha256').update(fs.readFileSync(hostEntry)).digest('hex')
+    )
+  } catch {
+    return false
+  }
+}
+
 /** the installed standalone host command; the driver appends its connection arguments. */
 export function headlessHostCommand(): string[] | null {
   const platform = desktopHostPlatform()
@@ -196,13 +223,16 @@ export function headlessHostCommand(): string[] | null {
     if (!app) return null
     const launcher = path.join(app, 'Contents/Frameworks/node')
     const host = path.join(app, 'Contents/Resources/node/host.mjs')
-    // releases before the bundled launcher have no headless host
-    if (!fs.existsSync(launcher) || !fs.existsSync(host)) return null
+    // releases before the bundled launcher have no headless host, and releases
+    // before the automatic-port bind cannot serve `--port 0`; use the browser
+    if (!fs.existsSync(launcher) || !hostEntrySupportsAutomaticPort(host)) return null
     return [launcher, '--experimental-vm-modules', host]
   }
   const version = placedHostVersion()
   if (!version) return null
   const dir = desktopHostDir(version)
+  // a placed host that predates the automatic-port bind upgrades like a missing one
+  if (!hostEntrySupportsAutomaticPort(path.join(dir, 'node/host.mjs'))) return null
   return [
     path.join(dir, 'bin/node'),
     '--experimental-vm-modules',

package/src/expo-swift-host.ts

@@ -353,14 +353,17 @@ export async function compileExpoSwiftModules(
             !(error instanceof SwiftMissingModulesError)
           )
             throw error
+          // a source error or a module peach does not provide holds until the
+          // stamp changes; retrying either relinks every namespace and rewrites
+          // the linked package, so no reload would ever reuse its artifact.
+          const missing = error instanceof SwiftMissingModulesError
           if (
-            sourceErrors.length &&
-            sourceErrors.length === errors.length &&
+            ((sourceErrors.length && sourceErrors.length === errors.length) || missing) &&
             sourceStamp(packagePath, module.root) === stamps.get(unit)
           ) {
             failedCompilations.set(packagePath, {
               stamp: stamps.get(unit)!,
-              diagnostic: sourceErrors.join('\n'),
+              diagnostic: missing ? diagnostic : sourceErrors.join('\n'),
             })
           }
           failures.set(

package/src/host/bridge-host.ts

@@ -16,6 +16,7 @@ import {
   SOOTSIM_BRIDGE_SIM_CLOSE_REASON,
 } from '../bridge-constants.ts'
 import { getCliVersion } from '../cli-version.ts'
+import { activeDesktopHostApp } from '../desktop-host-delivery.ts'
 import { handleExpoSwiftRequest } from '../expo-swift-host.ts'
 import {
   activeRuntimeDir as getActiveRuntimeDir,
@@ -361,6 +362,7 @@ export function injectSharedConfigIntoHtml(
     `<script>window.__sootsimSharedConfig=${payload};` +
     bridgePortTag +
     contrastOriginTag +
+    `window.__peachDesktopHostInstalled=${activeDesktopHostApp() !== null};` +
     `window.__sootsimCliVersion=${JSON.stringify(getCliVersion())};</script>`
   const html = data.toString('utf8')
   if (html.includes('<head>')) return html.replace('<head>', `<head>${tag}`)

package/src/host/fetch-proxy-transport.ts

@@ -82,10 +82,18 @@ async function createIdentity(): Promise<Omit<FetchTransportIdentity, 'port'>> {
 export async function startFetchProxyTransport(identityPath: string) {
   const identity = readIdentity(identityPath) ?? { ...(await createIdentity()), port: 0 }
   const sessions = new Set<ServerHttp2Session>()
+  // every open stream holds its queued response data against maxSessionMemory
+  // (megabytes), a few hundred kilobytes once a body outgrows the peer's
+  // window. past that cap bun answers new streams with GOAWAY
+  // ENHANCE_YOUR_CALM, failing every request on the session, or leaves them
+  // unanswered. the default 10 MB covers about 40 such streams, while the
+  // native host's undici adopts the advertised 256 as its own limit, so the cap
+  // covers a megabyte for each stream it admits.
   const server = createSecureServer(
     {
       cert: identity.cert,
       key: identity.key,
+      maxSessionMemory: 256,
       settings: { maxConcurrentStreams: 256 },
     },
     (req, res) => {

package/src/kotlin-host.ts

@@ -343,7 +343,7 @@ interface ExpoTypesFile {
     hiddenParameter: boolean
   }[]
   // Expo views; compose views also name their props class
-  views: { name: string; hidden: boolean; props: string }[]
+  views: { name: string; hidden: boolean; props: string; appContext: boolean }[]
   // ComposeProps classes with their public member properties
   props: { name: string; hidden: boolean; states: string[] }[]
 }
@@ -433,10 +433,16 @@ function readExpoTypes(output: string): ExpoTypesFile[] {
             !isRecord(view) ||
             typeof view.name !== 'string' ||
             typeof view.hidden !== 'boolean' ||
-            typeof view.props !== 'string'
+            typeof view.props !== 'string' ||
+            typeof view.appContext !== 'boolean'
           )
             throw new Error('expo-types printed an invalid view')
-          return { name: view.name, hidden: view.hidden, props: view.props }
+          return {
+            name: view.name,
+            hidden: view.hidden,
+            props: view.props,
+            appContext: view.appContext,
+          }
         }),
         props: row.props.map((entry: unknown) => {
           if (
@@ -463,7 +469,7 @@ function scanExpoTypes(
   sources: string[],
 ): Promise<ExpoTypesFile[]> {
   const candidates = sources.filter((file) =>
-    /\bRecord\b|\benum\s+class\b|\bExpoComposeView\b|\bExpoView\b|\bComposeProps\b/.test(
+    /\bRecord\b|\benum\s+class\b|\bExpoComposeView\b|\bExpoView\b|\bComposeProps\b|:\s*(?:[A-Za-z0-9_.]+\.)?(?:View|FrameLayout|LinearLayout|ViewGroup)\b/.test(
       fs.readFileSync(file, 'utf8'),
     ),
   )
@@ -560,7 +566,7 @@ function expoTypeSources(files: ExpoTypesFile[]): {
         .filter((view) => !view.hidden)
         .map(
           (view) =>
-            `    dev.peach.expo.PeachExpoTypes.view(${view.name}::class, ${view.props ? `${view.props}::class` : 'null'}) { context, appContext -> ${view.name}(context, appContext) }`,
+            `    dev.peach.expo.PeachExpoTypes.view(${view.name}::class, ${view.props ? `${view.props}::class` : 'null'}) { context, appContext -> ${view.name}(${view.appContext ? 'context, appContext' : 'context'}) }`,
         ),
       ...file.props
         .filter((entry) => !entry.hidden)

package/src/native-firebase-config.ts

@@ -1,6 +1,6 @@
 // read native default initialization inputs before the guest Firebase SDK starts.
 // expose only FirebaseOptions, never a partner-specific extra configuration.
-import { spawnSync } from 'node:child_process'
+import { spawn, spawnSync } from 'node:child_process'
 import fs from 'node:fs'
 import os from 'node:os'
 import path from 'node:path'
@@ -8,13 +8,18 @@ import { isRecord } from './is-record'
 import { parsePlistSource } from './plist'
 import { listXcodeAppTargets, readXcodeAppTarget } from './xcode-project'
 
-export function readNativeFirebaseConfig(
-  projectRoot: string,
-  platforms: readonly string[] = ['ios', 'android'],
-  iosTarget?: string,
-) {
-  const result: Record<string, unknown> = {}
-  let config: Record<string, unknown> = {}
+// expo's synchronous ESM/TypeScript loader requires Node's module evaluator.
+// a private result file keeps authored console output off the configuration wire.
+const EXPO_CONFIG_SCRIPT = `const { createRequire } = require('node:module');
+const { writeFileSync } = require('node:fs');
+const { join } = require('node:path');
+const root = process.argv[1];
+const { getConfig } = createRequire(join(root, 'package.json'))('@expo/config');
+const result = JSON.stringify(getConfig(root, { skipSDKVersionRequirement: true }).exp);
+if (Buffer.byteLength(result) > 1024 * 1024) throw new Error('Expo native configuration exceeds 1 MiB.');
+writeFileSync(process.argv[2], result, { mode: 0o600 });`
+
+function hasExpoConfig(projectRoot: string) {
   const appJsonPath = path.join(projectRoot, 'app.json')
   const appJson: unknown = fs.existsSync(appJsonPath)
     ? JSON.parse(fs.readFileSync(appJsonPath, 'utf8'))
@@ -25,53 +30,89 @@ export function readNativeFirebaseConfig(
       [appJson.ios, appJson.android].some(
         (value) => isRecord(value) && typeof value.googleServicesFile === 'string',
       ))
-  const dynamicExpo = [
-    'app.config.js',
-    'app.config.ts',
-    'app.config.cjs',
-    'app.config.mjs',
-  ].some((name) => fs.existsSync(path.join(projectRoot, name)))
-  if (staticExpo || dynamicExpo) {
-    // expo's synchronous ESM/TypeScript loader requires Node's module evaluator.
-    // a private result file keeps authored console output off the configuration wire.
-    const directory = fs.mkdtempSync(path.join(os.tmpdir(), 'peach-expo-config-'))
-    const resultPath = path.join(directory, 'config.json')
-    try {
-      const child = spawnSync(
-        'node',
-        [
-          '--input-type=commonjs',
-          '-e',
-          `const { createRequire } = require('node:module');
-const { writeFileSync } = require('node:fs');
-const { join } = require('node:path');
-const root = process.argv[1];
-const { getConfig } = createRequire(join(root, 'package.json'))('@expo/config');
-const result = JSON.stringify(getConfig(root, { skipSDKVersionRequirement: true }).exp);
-if (Buffer.byteLength(result) > 1024 * 1024) throw new Error('Expo native configuration exceeds 1 MiB.');
-writeFileSync(process.argv[2], result, { mode: 0o600 });`,
-          path.resolve(projectRoot),
-          resultPath,
-        ],
-        {
-          cwd: projectRoot,
-          encoding: 'utf8',
-          stdio: ['ignore', 'ignore', 'pipe'],
-          timeout: 30_000,
-          maxBuffer: 1024 * 1024,
-        },
-      )
-      if (child.error) throw child.error
-      if (child.status !== 0)
-        throw new Error(child.stderr || 'Expo native configuration evaluation failed.')
-      const resolved: unknown = JSON.parse(fs.readFileSync(resultPath, 'utf8'))
-      if (!isRecord(resolved))
-        throw new Error('Expo native configuration is unavailable.')
-      config = resolved
-    } finally {
-      fs.rmSync(directory, { recursive: true, force: true })
-    }
+  return (
+    staticExpo ||
+    ['app.config.js', 'app.config.ts', 'app.config.cjs', 'app.config.mjs'].some((name) =>
+      fs.existsSync(path.join(projectRoot, name)),
+    )
+  )
+}
+
+function expoConfigArgs(projectRoot: string, resultPath: string) {
+  return [
+    '--input-type=commonjs',
+    '-e',
+    EXPO_CONFIG_SCRIPT,
+    path.resolve(projectRoot),
+    resultPath,
+  ]
+}
+
+function readExpoConfigResult(resultPath: string, status: number | null, stderr: string) {
+  if (status !== 0)
+    throw new Error(stderr || 'Expo native configuration evaluation failed.')
+  const resolved: unknown = JSON.parse(fs.readFileSync(resultPath, 'utf8'))
+  if (!isRecord(resolved)) throw new Error('Expo native configuration is unavailable.')
+  return resolved
+}
+
+const resultDirectory = () => fs.mkdtempSync(path.join(os.tmpdir(), 'peach-expo-config-'))
+
+function readExpoConfig(projectRoot: string): Record<string, unknown> {
+  if (!hasExpoConfig(projectRoot)) return {}
+  const directory = resultDirectory()
+  const resultPath = path.join(directory, 'config.json')
+  try {
+    const child = spawnSync('node', expoConfigArgs(projectRoot, resultPath), {
+      cwd: projectRoot,
+      encoding: 'utf8',
+      stdio: ['ignore', 'ignore', 'pipe'],
+      timeout: 30_000,
+      maxBuffer: 1024 * 1024,
+    })
+    if (child.error) throw child.error
+    return readExpoConfigResult(resultPath, child.status, child.stderr)
+  } finally {
+    fs.rmSync(directory, { recursive: true, force: true })
+  }
+}
+
+// the same evaluation without blocking, so a caller can overlap it with other
+// startup work and hand the result to readNativeFirebaseConfig.
+export async function readExpoConfigAsync(
+  projectRoot: string,
+): Promise<Record<string, unknown>> {
+  if (!hasExpoConfig(projectRoot)) return {}
+  const directory = resultDirectory()
+  const resultPath = path.join(directory, 'config.json')
+  try {
+    const child = spawn('node', expoConfigArgs(projectRoot, resultPath), {
+      cwd: projectRoot,
+      stdio: ['ignore', 'ignore', 'pipe'],
+      timeout: 30_000,
+    })
+    let stderr = ''
+    child.stderr.setEncoding('utf8')
+    child.stderr.on('data', (chunk: string) => {
+      stderr += chunk
+    })
+    const status = await new Promise<number | null>((resolve, reject) => {
+      child.once('error', reject)
+      child.once('close', resolve)
+    })
+    return readExpoConfigResult(resultPath, status, stderr)
+  } finally {
+    fs.rmSync(directory, { recursive: true, force: true })
   }
+}
+
+export function readNativeFirebaseConfig(
+  projectRoot: string,
+  platforms: readonly string[] = ['ios', 'android'],
+  iosTarget?: string,
+  config: Record<string, unknown> = readExpoConfig(projectRoot),
+) {
+  const result: Record<string, unknown> = {}
   const ios = config.ios
   if (
     platforms.includes('ios') &&

package/src/process-output.ts

@@ -0,0 +1,16 @@
+// wait for both pipes before forcing an exit with live handles.
+// console writers must use these streams rather than a separate runtime sink.
+export async function exitWithFlushedOutput(code: number): Promise<never> {
+  await Promise.all(
+    [process.stdout, process.stderr].map(
+      (stream) =>
+        new Promise<void>((resolve, reject) => {
+          stream.end((error?: Error | null) => {
+            if (error) reject(error)
+            else resolve()
+          })
+        }),
+    ),
+  )
+  process.exit(code)
+}

package/src/sdk.ts

@@ -8,7 +8,12 @@
 export * from './sim-client'
 export * from '../cli/commands/inspect/core'
 export * from '../cli/commands/inspect/actions'
-export { waitForSootsimIdle, waitReadyAndSettle } from '../cli/commands/inspect/settling'
+export {
+  IdleObservationError,
+  RuntimeReadinessUnsupportedError,
+  waitForSootsimIdle,
+  waitReadyAndSettle,
+} from '../cli/commands/inspect/settling'
 export type {
   SettledWaitReady,
   WaitForSootsimIdleOptions,

package/src/sim-client.ts

@@ -358,7 +358,12 @@ export class SimClient implements WsBridge, InspectBridge {
     return status
   }
 
-  /** wait for layout/animation/transition settle after an interaction. */
+  /**
+   * wait for layout/animation/transition settle after an interaction.
+   * a still-busy guest returns settled false with its own elapsed time.
+   * a failed idle read throws IdleObservationError with the host elapsed
+   * time and the original failure.
+   */
   settle(
     opts: { maxMs?: number; strict?: boolean } = {},
   ): Promise<WaitForSootsimIdleResult> {