peachsim 0.1.1481 → 0.1.1619

package/README.md

@@ -12,7 +12,8 @@ drivers, and library exports; its only command, `npx peachsim`, runs that same
 installer from the copy of `install.sh` it ships.
 
 The executable updates itself with `peach upgrade`, which then restarts a running
-background daemon onto the new executable and runtime. Successful interactive human
+background daemon onto the new executable. A new runtime needs no restart: the
+next new sim opens on it while open sims keep theirs. Successful interactive human
 commands refresh a cached stable CLI version in a detached process at most once
 every 20 hours. A newer version produces one short notice on stderr, once per
 version and no more than weekly. CI, agents, JSON output, pipes, and
@@ -162,6 +163,11 @@ a local foreground bridge when no daemon is reachable, then opens a `WsBridge`
 `cli/commands/inspect/*` and are re-exported as the programmatic `peachsim/sdk`;
 the Maestro runner is `cli/bridge-flow-runner.ts`; the Detox compat driver
 is in `detox/`. Test and screenshot paths additionally use `cli/drivers/*`.
+Opening a simulator and waiting for reconnection share one app-tree readiness
+poller. Its nominal wait budget includes WebSocket handshakes, target lookup,
+evaluation and poll pauses; unanswered commands do not restart the deadline.
+A timeout reports the last node count, missing test hook or bridge error and
+elapsed time. Registering a simulator alone does not satisfy readiness.
 Browser sims launch in an isolated Playwright Chrome for Testing profile.
 An explicit `--base-url` keeps that shell's origin and uses its assets without
 installing an active runtime. A bridge started for that shell skips automatic
@@ -185,6 +191,12 @@ config dictionary is empty and the app can select its own public defaults.
 Preserve failures from those endpoints rather than remapping them to a successful
 local response. The same flag is available on `peach flow`.
 
+A project with several Xcode application targets names the one to run, as an
+Xcode scheme does: `peach open <app-port> --ios-target <name>` (also on
+`peach flow` and `peach maestro test`) reads that target's version, build,
+bundle id and display name. Without it, such an app served by a plain Metro
+reads the runtime defaults.
+
 **The daemon is one process** — `SootSimBridgeHost` (`src/host/bridge-host.ts`).
 `peach serve` runs it in the foreground; the background daemon is the *same
 process* wrapped with autostart and the `~/.peach/daemon.json` lockfile. It is
@@ -196,6 +208,14 @@ guest-app fetch/WebSocket traffic so the cross-origin tenant worker can reach
 localhost. The `AgentHost` extension owns one FIFO reader per agent session and
 fans agent events out to every subscriber.
 
+`peach open` auto-installs a published runtime only when the runtime directory
+is empty and no live bridge already owns the runtime. When a live bridge is
+performing its first download, `open` waits for that bridge's bootstrap state
+to finish, then uses its installed runtime. Without a live bridge, runtime
+files without a selected runtime containing `index.html` still cause a refusal.
+Finish copying the runtime, then select it with `peach runtime use <version>`.
+Write the active marker after staging is complete when preparing an isolated home.
+
 During source development, each Vite bridge owns one
 `~/.peach/dev-bridges/<port>.json` heartbeat record. CLI defaults select the
 current `PORT_OFFSET`, then the current checkout, then the canonical `:7668`
@@ -203,12 +223,13 @@ bridge, so concurrent worktrees cannot replace or delete one another's address.
 Each Vite shell also publishes its exact bridge at `/__sootsim/bridge`, so a
 launcher that reuses a shell from another isolated `PEACH_HOME` stays in that
 shell's bridge world without reading the other process's lockfile directory.
-An explicit `--port` also participates in `--sim` ownership discovery even
-without a local heartbeat record. The bridge must report that simulator as
-open; a port that names another simulator's world is rejected.
-SDK `connect({ sim })` and batched `do --then` actions use that same ownership
-discovery. An inferred default port does not override the named sim's world;
-an explicit SDK port or CLI `--port` retains the ownership check.
+An explicit CLI `--port` or SDK port connects directly to that bridge without
+scanning other worlds or requiring a local heartbeat record. That bridge handles
+the named sim and reports an error if it is absent.
+Without an explicit port, `--sim`, SDK `connect({ sim })`, and batched `do --then`
+actions discover the sim's owning world. Each world probe has one two-second
+wall deadline covering both connection and response. An inferred default port
+does not override the named sim's world.
 
 **The sim** is a browser/Electron *page* launched by a CLI driver. Inside that
 page run three workers: the **shell worker** owns device and native state, the
@@ -267,6 +288,7 @@ therefore runs before assertions in each flow.
 curl -fsSL https://peachsim.com/install.sh | sh   # or: npx peachsim
 peach                 # open ConnectRN and choose a running app in the simulator
 peach open /settings  # dispatch a React Native deep link into that app
+peach open /settings --no-describe --quiet  # keep open options with deep links
 ```
 
 Start Metro, Expo, One, or another supported React Native development server
@@ -389,6 +411,8 @@ outside `node_modules`, `dist`, and `build`. Keep it before
 `react-native-worklets/plugin` in a custom Babel stack that lists both plugins.
 Apps using `babel-preset-expo` omit the explicit Worklets plugin because the
 preset configures it automatically.
+Runtime Fragment aliases are excluded before element creation. Component tag
+expressions are evaluated once, and ordinary components retain their locations.
 
 For One's Rolldown native bundler, use the native transform in `vite.config.ts`:
 
@@ -421,13 +445,14 @@ peach open 8081         # load a running metro/expo dev server
 peach open /settings    # route via React Native Linking
 peach describe          # dump UI tree
 peach get errors 5      # recent runtime failures
-peach compat            # scan native package compatibility
+peach doctor            # check what of this app Peach runs
 peach support report "…"  # preview an opt-in compatibility report
 peach find --testid cta # inspect one node deeply
 peach debug enable animated,layout
 peach debug trace shell on 240
 peach do tap-text "..." # interact
 peach do tap email --then type user@example.com --then tap submit
+peach shell window --x 120 --y 140 --scale fit # place/scale desktop sim window
 peach debug snapshot before
 peach debug snapshot after
 peach debug diff before after
@@ -499,6 +524,11 @@ options and enables two integrations:
 The URL helpers request ordinary Metro graphs: `dev=false&minify=true` for
 production and `dev=true&minify=false` for development.
 
+Metro registration readers retain the original factory bytes and module IDs.
+Empty dependencies may be an empty array, an omitted production argument, or a
+null development argument before the module name. Identity validation and
+fingerprinting treat each as zero dependencies and reject malformed arguments.
+
 ```js
 const {
   toPeachProductionBundleUrl,
@@ -531,6 +561,16 @@ peach detox            # auto-discovers e2e/ tests and launches a shell
 peach detox init       # scaffold a config + sample test
 ```
 
+`device.launchApp()` reuses a running guest by default. With a URL,
+`device.launchApp({ url })` and `device.openURL({ url })` deliver a Linking
+URL event to the running guest through the shell's deep-link bridge. Warm `launchApp` brings the guest forward; `openURL` retains its
+foreground or background state. Both retain its browser session and app state.
+`sourceApp` does not add fields to React Native's `{ url }` event. A
+stopped guest rejects URL delivery. Explicit `newInstance: true`, deletion,
+and video recording create a new browser context; cold launches still use the
+supplied shell URL. When synchronization is enabled, URL delivery waits for
+existing work before dispatch and for navigation and painting afterward.
+
 See `../../docs/migrating-from-detox.md` for details.
 
 ## Coming from Maestro
@@ -584,6 +624,9 @@ the framed export inline without changing Maestro syntax:
 native content, a populated node tree, or a live-frame channel whose publish
 count advances across probes. Canvas-only GL, WebGPU, and video surfaces can
 therefore prove that they are painting without weakening the boot-card guard.
+A confirmed guest launch error ends readiness immediately, including waits longer
+than one bridge request. Loading and suppressed entry errors keep their existing
+readiness rules.
 
 ```yaml
 - takeScreenshot: hero
@@ -695,11 +738,11 @@ serves its selected version from a version-specific localhost origin, so a
 background activation cannot mix an already loaded shell with chunks from the
 next runtime. Without config, each new open selects the active stable version.
 When `peach.config.ts` sets `runtimeVersion`, `peach open` installs that
-version without changing the machine default. The same file replaces an app's own
-native modules (`nativeModules`, `turboModules`) and native views
-(`nativeViews`, keyed by the `requireNativeComponent` name or an Expo view's
-`Module_View` name) with project-local files; the configuration guide in the
-docs lists every slot. App config, native-linked fonts,
+version without changing the machine default. The same file answers native code Peach does
+not know under `packages`, keyed by the package and then its native module
+and view names, and an installed `peach-stub-<package>` package answers in the
+same shape with no config line; the configuration guide in the docs lists
+every slot. App config, native-linked fonts,
 and splash assets resolve from the local directory named by `--project-root`
 when supplied, otherwise the project root advertised by the selected development
 server. Hosted recorders pass their checked-out repository explicitly because

package/cli/app-catalog.ts

@@ -3,6 +3,7 @@ import path from 'node:path'
 import {
   enumerateBundleColors,
   enumerateBundleImages,
+  enumerateBundleSymbols,
 } from '../../sootsim-swift/src/bundleAssets'
 import type { AppCatalog } from 'peach-engine/engine/app-catalog-wire'
 
@@ -36,7 +37,7 @@ function catalogFiles(dir: string, found: string[]) {
   }
 }
 
-// the app's asset-catalog colors and images and its declared accent, read off
+// the app's asset-catalog colors, images, symbols and declared accent, read off
 // the ios project a prebuild or a bare app keeps on disk: the app target is
 // the folder holding the AppDelegate, the catalogs are its .xcassets, and the
 // accent is what its Info.plist or project build settings name. metro serves
@@ -65,9 +66,9 @@ export function discoverAppCatalog(
   const relative = files.map((file) =>
     path.relative(targetDir, file).split(path.sep).join(path.posix.sep),
   )
-  const readContents = (candidate: string) =>
-    candidate.endsWith('Contents.json') ? readText(path.join(targetDir, candidate)) : null
+  const readContents = (candidate: string) => readText(path.join(targetDir, candidate))
   const colors = enumerateBundleColors(relative, readContents)
+  const symbols = enumerateBundleSymbols(relative, readContents, () => '.')
   const served = path.relative(appDir, targetDir).split(path.sep).join(path.posix.sep)
   const images: AppCatalog['images'] = {}
   for (const { name, file, scale } of enumerateBundleImages(relative, readContents)) {
@@ -85,8 +86,9 @@ export function discoverAppCatalog(
   if (
     accentName === null &&
     Object.keys(colors).length === 0 &&
-    Object.keys(images).length === 0
+    Object.keys(images).length === 0 &&
+    Object.keys(symbols).length === 0
   )
     return null
-  return { colors, images, accentName }
+  return { colors, images, symbols, accentName }
 }

package/cli/app-config.ts

@@ -4,6 +4,7 @@ import * as peachConfigModule from '../src/config'
 import { isPeachConfig, type PeachConfig } from '../src/config'
 import { rnxPublicBrand } from '../src/public-brand'
 import { resolveAppProject, type ResolvedAppProject } from './app-project'
+import { resolveAppStubs, wireSlotMigration, type AppStubs } from './app-stubs'
 
 // `{ file }` entries are relative to the config file; the engine loads them by
 // absolute path from the runtime's replacement-module endpoint.
@@ -33,16 +34,42 @@ function resolveConfigReplacementFiles(
   return {
     ...config,
     modules: resolveFileEntries(config.modules, configDir),
-    turboModules: resolveFileEntries(config.turboModules, configDir),
-    nativeModules: resolveFileEntries(config.nativeModules, configDir),
-    nativeViews: resolveFileEntries(config.nativeViews, configDir),
   }
 }
 
+// the engine's wire slots; an app names native stubs by package instead
+const WIRE_SLOTS = ['nativeModules', 'turboModules', 'nativeViews'] as const
+
+// the app's config with every native stub lowered into the engine's wire slots:
+// its own `packages` and the installed stub packages, applied with or without
+// a peach.config.ts.
 export async function loadRNXAppConfig(
   project: ResolvedAppProject | null,
 ): Promise<PeachConfig | undefined> {
-  if (!project?.configPath) return undefined
+  return (await loadRNXAppStubs(project)).config
+}
+
+export async function loadRNXAppStubs(
+  project: ResolvedAppProject | null,
+): Promise<{ config: PeachConfig | undefined; stubs: AppStubs }> {
+  if (!project) return { config: undefined, stubs: { applied: [], skipped: [] } }
+  const config = await loadConfigFile(project)
+  try {
+    return resolveAppStubs(
+      project.appDir,
+      config,
+      project.configPath ? path.dirname(project.configPath) : project.appDir,
+    )
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error)
+    throw new Error(`could not load the native stubs of ${project.appDir}: ${message}`)
+  }
+}
+
+async function loadConfigFile(
+  project: ResolvedAppProject,
+): Promise<PeachConfig | undefined> {
+  if (!project.configPath) return undefined
   try {
     const jiti = createJiti(import.meta.url, {
       interopDefault: true,
@@ -57,6 +84,16 @@ export async function loadRNXAppConfig(
     if (!isPeachConfig(loaded)) {
       throw new Error('the default export must be a peach config object')
     }
+    const wire = WIRE_SLOTS.filter((slot) => loaded[slot] !== undefined)
+    if (wire.length > 0) {
+      const migration = wireSlotMigration(project.appDir, {
+        modules: { ...loaded.turboModules, ...loaded.nativeModules },
+        views: { ...loaded.nativeViews },
+      })
+      throw new Error(
+        `${wire.join(', ')} moved under packages, keyed by the package whose native side they answer. replace them with:\n${migration}`,
+      )
+    }
     return resolveConfigReplacementFiles(loaded, project.configPath)
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error)
@@ -64,9 +101,11 @@ export async function loadRNXAppConfig(
   }
 }
 
-export async function resolveRNXAppConfig(
-  startDir: string = process.cwd(),
-): Promise<{ project: ResolvedAppProject | null; config: PeachConfig | undefined }> {
+export async function resolveRNXAppConfig(startDir: string = process.cwd()): Promise<{
+  project: ResolvedAppProject | null
+  config: PeachConfig | undefined
+  stubs: AppStubs
+}> {
   const project = resolveAppProject(startDir)
-  return { project, config: await loadRNXAppConfig(project) }
+  return { project, ...(await loadRNXAppStubs(project)) }
 }

package/cli/app-fonts.ts

@@ -3,16 +3,24 @@ import fs from 'node:fs'
 import { createRequire } from 'node:module'
 import path from 'node:path'
 import {
+  encodeAppFontsWire,
   expoFontPathsFromPlugins,
   nativeLinkedFontSpecsFromPaths,
   metroFontSpecsFromPaths,
+  appFontAssetUrlsFromWire,
   type ConfigPluginFontSpec,
+  type FontPlatform,
 } from 'peach-engine/engine/config-plugin-fonts'
 import { resolveListeningPid, resolveProcessCwd } from '../scripts/dev-server-scanner'
 import { loopbackOriginOf } from '../src/backend-origin'
 import { MANIFEST_PROBE_TIMEOUT_MS } from '../src/dev-bundle-resolution'
+import { stageHostFile } from '../src/host/staged-host-files'
 import { parsePlistSource } from '../src/plist.ts'
 import { resolveAppProject } from './app-project'
+import {
+  materialSymbolFontPaths,
+  materialSymbolFontAssets,
+} from './material-symbol-fonts'
 
 const require = createRequire(import.meta.url)
 
@@ -31,24 +39,62 @@ export function discoverNativeLinkedAppFonts(opts: {
   bundleUrl: string
   projectDir: string
   platform?: string
+  nativeAssetOrigin: string
 }): DiscoveredAppFontSpec[] {
   const metroOrigin = loopbackOriginOf(opts.bundleUrl)
   if (!metroOrigin) return []
+  const { paths, materialSymbols } = discoverNativeLinkedAppFontAssets(opts)
   const specs = metroFontSpecsFromPaths(
-    projectRelativeFontPaths(opts.projectDir, discoverNativeLinkedAppFontPaths(opts)),
+    projectRelativeFontPaths(opts.projectDir, paths),
     metroOrigin,
+    nativeFontPlatform(opts.platform),
+  )
+  attachMaterialSymbolMetadata(specs, materialSymbols, (asset) =>
+    stageHostFile(asset, opts.nativeAssetOrigin),
   )
-  // a family linked from more than one file keeps the first declaration.
-  const byFamily = new Map<string, DiscoveredAppFontSpec>()
-  for (const spec of specs)
-    if (!byFamily.has(spec.family)) byFamily.set(spec.family, spec)
-  return [...byFamily.values()]
+  return specs
 }
 
-function projectRelativeFontPaths(projectDir: string, fontPaths: string[]): string[] {
-  return fontPaths.map((fontPath) =>
-    path.relative(path.resolve(projectDir), fontPath).split(path.sep).join('/'),
+function nativeFontPlatform(platform: string | undefined): FontPlatform {
+  return (platform || process.env.CONTRAST_PLATFORM || 'ios').toLowerCase() === 'android'
+    ? 'android'
+    : 'ios'
+}
+
+function attachMaterialSymbolMetadata(
+  specs: ConfigPluginFontSpec[],
+  files: ReturnType<typeof materialSymbolFontAssets>,
+  assetUrl: (filePath: string) => string,
+): void {
+  const first = specs.find(
+    (spec) =>
+      spec.family !== undefined &&
+      /^MaterialSymbols(?:Outlined|Rounded|Sharp)_/.test(spec.family),
   )
+  if (first && files)
+    first.materialSymbols = {
+      hash: files.hash,
+      codepointsUrl: assetUrl(files.codepointsPath),
+      mirroredUrl: assetUrl(files.mirroredPath),
+    }
+}
+
+function projectRelativeFontPaths(projectDir: string, fontPaths: string[]): string[] {
+  // metro resolves an asset path lexically against its project root and reads
+  // through symlinks, so a font declared inside the project keeps its declared
+  // path even when node_modules is a symlink to a shared install. a font that
+  // node resolved outside the project (a hoisted workspace or pnpm store) is
+  // named through its real location, in the namespace of the real project root.
+  const projectRoot = path.resolve(projectDir)
+  const realProjectRoot = fs.realpathSync(projectDir)
+  return fontPaths.map((fontPath) => {
+    const lexical = path.relative(projectRoot, fontPath)
+    const relative =
+      lexical.startsWith('..') || path.isAbsolute(lexical)
+        ? path.relative(realProjectRoot, fs.realpathSync(fontPath))
+        : lexical
+    return relative.split(path.sep).join('/')
+  })
 }
 
 function isFile(filePath: string): boolean {
@@ -60,15 +106,15 @@ function isFile(filePath: string): boolean {
 }
 
 // absolute paths of every existing font file the native app links.
-function discoverNativeLinkedAppFontPaths(opts: {
+function discoverNativeLinkedAppFontAssets(opts: {
   projectDir: string
   platform?: string
-}): string[] {
+}): { paths: string[]; materialSymbols?: ReturnType<typeof materialSymbolFontAssets> } {
   const project = resolveAppProject(opts.projectDir)
   const selectedAppDir = project?.appDir ?? null
-  if (!selectedAppDir) return []
+  if (!selectedAppDir) return { paths: [] }
 
-  const platform = (opts.platform || process.env.CONTRAST_PLATFORM || 'ios').toLowerCase()
+  const platform = nativeFontPlatform(opts.platform)
 
   let getConfig: ExpoConfigGetter | null = null
   // resolve from the exact app root advertised by the development server.
@@ -97,13 +143,13 @@ function discoverNativeLinkedAppFontPaths(opts: {
   }
 
   // a declared path with no file behind it links nothing natively.
-  const fontPaths = expoFontPathsFromPlugins(
-    plugins,
-    platform === 'android' ? 'android' : 'ios',
-  )
+  const fontPaths = expoFontPathsFromPlugins(plugins, platform)
     .slice(0, 256)
     .map((fontPath) => path.resolve(selectedAppDir, fontPath))
     .filter(isFile)
+  const materialFonts =
+    platform === 'android' ? materialSymbolFontPaths(selectedAppDir) : []
+  fontPaths.push(...materialFonts)
   // the walk is bounded by WORK, not by a clock: at most 64 readdirs, at most 64
   // queued dirs, 4 levels deep, 256 paths. those ceilings are what keep a stray
   // node_modules from being crawled, and no machine can blow through them. a
@@ -270,7 +316,10 @@ function discoverNativeLinkedAppFontPaths(opts: {
     } catch {}
   }
 
-  return [...new Set(fontPaths)]
+  return {
+    paths: [...new Set(fontPaths)],
+    materialSymbols: materialSymbolFontAssets(materialFonts),
+  }
 }
 
 // prebuilt guests cannot discover files linked into their native binary.
@@ -282,15 +331,23 @@ export function readNativeLinkedAppFontsWire(opts: {
   if (!resolveAppProject(opts.projectDir)) {
     throw new Error(`native font project is unavailable: ${opts.projectDir}`)
   }
-  return encodeAppFontsWire(
-    nativeLinkedFontSpecsFromPaths(
-      projectRelativeFontPaths(opts.projectDir, discoverNativeLinkedAppFontPaths(opts)),
-      (fontPath) => {
-        const bytes = fs.readFileSync(path.resolve(opts.projectDir, fontPath))
-        return `data:${fontContentType(fontPath)};base64,${bytes.toString('base64')}`
-      },
-    ),
+  const projectDir = fs.realpathSync(opts.projectDir)
+  const { paths, materialSymbols } = discoverNativeLinkedAppFontAssets(opts)
+  const specs = nativeLinkedFontSpecsFromPaths(
+    projectRelativeFontPaths(projectDir, paths),
+    nativeFontPlatform(opts.platform),
+    (fontPath) => {
+      const bytes = fs.readFileSync(path.resolve(projectDir, fontPath))
+      return `data:${fontContentType(fontPath)};base64,${bytes.toString('base64')}`
+    },
+  )
+  attachMaterialSymbolMetadata(
+    specs,
+    materialSymbols,
+    (filePath) =>
+      `data:application/octet-stream;base64,${fs.readFileSync(filePath).toString('base64')}`,
   )
+  return encodeAppFontsWire(specs)
 }
 
 // resolve a metro dev server's project root. Expo's middleware advertises it
@@ -355,28 +412,6 @@ export async function resolveMetroProjectRoot(bundleUrl: string): Promise<string
   return pid === null ? null : resolveProcessCwd(pid)
 }
 
-export function encodeAppFontsWire(specs: DiscoveredAppFontSpec[]): string {
-  return specs
-    .map((spec) => `${encodeURIComponent(spec.url)}::${encodeURIComponent(spec.family)}`)
-    .join(',')
-}
-
-export function parseAppFontUrls(wire: string): string[] {
-  const urls: string[] = []
-  for (const entry of wire.split(',')) {
-    const trimmed = entry.trim()
-    if (!trimmed) continue
-    const sep = trimmed.indexOf('::')
-    const urlPart = sep === -1 ? trimmed : trimmed.slice(0, sep)
-    try {
-      urls.push(decodeURIComponent(urlPart))
-    } catch {
-      urls.push(urlPart)
-    }
-  }
-  return urls.filter(Boolean)
-}
-
 // content type for a config-plugin font url, by extension. config fonts only
 // ever ship as ttf/otf/woff(2); fall back to octet-stream for anything else
 // so R2 still serves bytes the engine can register.
@@ -413,7 +448,7 @@ export async function fetchAppFontFiles(
 ): Promise<FetchedAppFont[]> {
   const out: FetchedAppFont[] = []
   const seen = new Set<string>()
-  for (const url of parseAppFontUrls(wire)) {
+  for (const url of appFontAssetUrlsFromWire(wire)) {
     const urlhash = createHash('sha256').update(url).digest('hex')
     if (seen.has(urlhash)) continue
     seen.add(urlhash)