peachsim 0.1.1477 → 0.1.1481

package/cli/commands/control.ts

@@ -16,7 +16,7 @@ import {
   type DeviceModel,
 } from 'peach-engine/settings/devices'
 import { WebSocket } from 'ws'
-import { probePort } from '../../scripts/dev-server-scanner'
+import { pinSharedListenerScan, probePort } from '../../scripts/dev-server-scanner'
 import { isAppDeepLinkTarget, openAppUrl } from '../../src/app-url'
 import { isLoopbackHost, loopbackOriginOf } from '../../src/backend-origin'
 import { resolveSootsimShellBaseUrlForBridgePort } from '../../src/bridge-constants'
@@ -260,16 +260,12 @@ async function connectBridgeForOpen(
   // a closed port refuses at once, so this window only matters when something
   // listens: a live bridge on a loaded machine can take longer than 250 ms to
   // finish the handshake, and missing it spawned a second bridge.
-  if (
-    (explicitPort || preferredWorld !== null) &&
-    (await canConnectToBridge(preferredPort, 2_000))
-  ) {
+  const handshake = await bridgeHandshake(preferredPort, 2_000)
+  if ((explicitPort || preferredWorld !== null) && handshake === 'open') {
     return preferredPort
   }
   if (explicitPort && preferredWorld !== null) {
-    throw new Error(
-      `peach open: requested bridge port ${preferredPort} is not reachable.`,
-    )
+    throw new Error(unreachableBridgeMessage(preferredPort, handshake))
   }
   if (
     !explicitPort &&
@@ -404,23 +400,45 @@ async function ensureRuntimeForOpen() {
   await runRuntime(['install'], {})
 }
 
-function canConnectToBridge(port: number, timeoutMs: number): Promise<boolean> {
+type BridgeHandshake = 'open' | 'refused' | 'timeout'
+
+function bridgeHandshake(port: number, timeoutMs: number): Promise<BridgeHandshake> {
   return new Promise((resolve) => {
     const ws = new WebSocket(`ws://127.0.0.1:${port}`, { handshakeTimeout: timeoutMs })
     let settled = false
-    const finish = (ok: boolean) => {
+    const finish = (result: BridgeHandshake) => {
       if (settled) return
       settled = true
+      clearTimeout(timer)
       if (ws.readyState === WebSocket.OPEN) ws.close()
       else if (ws.readyState === WebSocket.CONNECTING) ws.terminate()
-      resolve(ok)
+      resolve(result)
     }
-    ws.once('open', () => finish(true))
-    ws.on('error', () => finish(false))
-    setTimeout(() => finish(false), timeoutMs)
+    const timer = setTimeout(() => finish('timeout'), timeoutMs)
+    ws.once('open', () => finish('open'))
+    ws.on('error', (err: NodeJS.ErrnoException) => {
+      finish(
+        err.code === 'ECONNREFUSED' || err.code === 'ENOTFOUND' ? 'refused' : 'timeout',
+      )
+    })
   })
 }
 
+function unreachableBridgeMessage(port: number, handshake: BridgeHandshake): string {
+  if (handshake === 'timeout') {
+    const cores = Math.max(1, os.cpus().length)
+    const load = os.loadavg()[0]
+    if (load >= cores) {
+      return `peach open: requested bridge port ${port} did not finish its handshake within 2s while load average was ${load.toFixed(1)} on ${cores} cores.`
+    }
+  }
+  return `peach open: requested bridge port ${port} is not reachable.`
+}
+
+function canConnectToBridge(port: number, timeoutMs: number): Promise<boolean> {
+  return bridgeHandshake(port, timeoutMs).then((result) => result === 'open')
+}
+
 function looksLikeSootsimUrl(target: string): boolean {
   try {
     const url = new URL(target)
@@ -531,39 +549,46 @@ async function resolveConnectionInputForCli(target: string): Promise<ResolvedDev
 
   console.log(`  resolving native bundle for ${normalized} (manifest timeout: 30s)…`)
   let lastError: Error | null = null
-  for (let attempt = 0; attempt < DEV_BUNDLE_RESOLVE_ATTEMPTS; attempt++) {
-    if (registeredPort && registeredPort > 0) {
-      const discovered = await probePort(registeredPort)
-      // a provisional bundle URL is enough to LIST the server but not to open
-      // it; fall through to resolveConnectionInput, which asks the manifest
-      // again with a budget that fits a real dev server.
-      if (discovered && !discovered.bundleUrlProvisional) {
-        return {
-          bundleUrl: discovered.bundleUrl,
-          port: discovered.port,
-          framework: discovered.framework,
-          projectName: discovered.projectName,
+  const releaseListenerScan = pinSharedListenerScan()
+  try {
+    for (let attempt = 0; attempt < DEV_BUNDLE_RESOLVE_ATTEMPTS; attempt++) {
+      if (registeredPort && registeredPort > 0) {
+        const discovered = await probePort(registeredPort)
+        // a provisional bundle URL is enough to LIST the server but not to open
+        // it; fall through to resolveConnectionInput, which asks the manifest
+        // again with a budget that fits a real dev server.
+        if (discovered && !discovered.bundleUrlProvisional) {
+          return {
+            bundleUrl: discovered.bundleUrl,
+            port: discovered.port,
+            framework: discovered.framework,
+            projectName: discovered.projectName,
+          }
         }
       }
-    }
 
-    try {
-      return await resolveConnectionInput(normalized)
-    } catch (error) {
-      if (
-        !(error instanceof Error) ||
-        !error.message.startsWith('could not resolve a native bundle')
-      ) {
-        throw error
+      try {
+        return await resolveConnectionInput(normalized)
+      } catch (error) {
+        if (
+          !(error instanceof Error) ||
+          !error.message.startsWith('could not resolve a native bundle')
+        ) {
+          throw error
+        }
+        lastError = error
       }
-      lastError = error
+      await sleep(DEV_BUNDLE_RESOLVE_INTERVAL_MS)
     }
-    await sleep(DEV_BUNDLE_RESOLVE_INTERVAL_MS)
+    throw (
+      lastError ??
+      new Error(
+        'could not resolve a native bundle for ' + normalized + ' after retrying.',
+      )
+    )
+  } finally {
+    releaseListenerScan()
   }
-  throw (
-    lastError ??
-    new Error('could not resolve a native bundle for ' + normalized + ' after retrying.')
-  )
 }
 
 // a dev server builds an app's graph on the first request for its bundle and
@@ -2132,7 +2157,8 @@ export async function runOpenCommand(
           const currentEphemeral = new URL(
             deriveCurrentSimBaseUrl(targetSim, baseUrl),
           ).searchParams.get('ephemeral')
-          if (currentEphemeral) navigationUrl.searchParams.set('ephemeral', currentEphemeral)
+          if (currentEphemeral)
+            navigationUrl.searchParams.set('ephemeral', currentEphemeral)
           navigatedShellUrl = navigationUrl.toString()
           navigationUrl.searchParams.set('inspectOpen', token)
           bridge

package/cli/commands/detox.ts

@@ -19,8 +19,8 @@ import { rnxPublicBrand } from '../../src/public-brand'
 import { resolveCliAuth } from '../auth'
 import { registerRun, shouldRegisterRun } from '../run-registry'
 import { peachExit } from '../run-rnx'
-import { buildShellUrl } from './control'
-import { discoverSootsimUrl } from './flow'
+import { resolveDefaultBridgePort } from '../ws-bridge'
+import { buildShellUrl, resolveShellBaseUrlForBridgePort } from './control'
 import { resolveDefaultUploadOrigin } from './upload'
 
 interface RunDetoxOpts {
@@ -35,7 +35,7 @@ usage:
   peach detox [testFiles...]        run all tests under e2e/, test/e2e/, or detox/
   peach detox --app <port|url>      the app each device.launchApp() opens
   peach detox --config <path>       use a specific jest config
-  peach detox --port, -p <port>     the peach shell port (default 5173)
+  peach detox --port, -p <port>     bridge port (defaults to the active local bridge)
   peach detox init                  scaffold peach-detox.config.cjs + sample test
   peach detox --watch               jest watch mode
   peach detox --headed              keep the peach shell window visible
@@ -77,7 +77,8 @@ export async function runDetox(args: string[], opts: RunDetoxOpts = {}): Promise
     Number(getFlag('--port') || getFlag('-p')) ||
     opts.port ||
     Number(process.env.SOOTSIM_PORT) ||
-    5173
+    resolveDefaultBridgePort()
+  const shellBaseUrl = process.env.PEACH_URL || resolveShellBaseUrlForBridgePort(port)
   if (getFlag('--sim')) {
     throw new Error(
       'Detox owns its browser context; pin its shell with PEACH_URL and --device instead of --sim',
@@ -169,7 +170,7 @@ export async function runDetox(args: string[], opts: RunDetoxOpts = {}): Promise
   // the driver navigates to a running peach shell; warn before jest starts
   // when none is reachable.
   if (!noLaunch) {
-    await ensureShellRunning(port)
+    await ensureShellRunning(shellBaseUrl)
   }
 
   // build the jest command. prefer the user's config if they passed --config
@@ -251,7 +252,6 @@ export async function runDetox(args: string[], opts: RunDetoxOpts = {}): Promise
   console.log(`    port:     ${port}${headed ? ' (headed)' : ''}`)
   if (localConfig) console.log(`    config:   ${localConfig}`)
 
-  const shellBaseUrl = process.env.PEACH_URL || `http://localhost:${port}`
   const app = getFlag('--app')
   const shellUrl = new URL(app ? await buildShellUrl(app, shellBaseUrl) : shellBaseUrl)
   const device = getFlag('--device')
@@ -447,12 +447,17 @@ function firstExisting(names: string[]): string | null {
   return null
 }
 
-async function ensureShellRunning(port: number): Promise<void> {
-  const shellUrl = await discoverSootsimUrl()
-  if (shellUrl) return
+async function ensureShellRunning(shellUrl: string): Promise<void> {
+  try {
+    const response = await fetch(shellUrl, { signal: AbortSignal.timeout(3000) })
+    await response.body?.cancel()
+    if (response.ok) return
+  } catch {
+    // an unreachable selected shell warns before jest owns its launch failure.
+  }
 
   console.warn(
-    `  warn: no peach shell reachable on :${port}. start your app, then run \`peach open <app-port>\`\n` +
+    `  warn: no peach shell reachable at ${shellUrl}. start your app, then run \`peach open <app-port>\`\n` +
       `  or pass --no-launch if you're managing the shell yourself.`,
   )
 }

package/cli/commands/flow.ts

@@ -197,8 +197,7 @@ export async function resolveAppFrontmatterTarget(
   return { target: trimmed }
 }
 
-// discover a peach shell URL — prefer patched servers, fall back to any match.
-// exported so `detox.ts` and `maestro.ts` can reuse the same discovery logic.
+// discover a peach shell URL from running dev servers, preferring patched ones.
 export async function discoverSootsimUrl(): Promise<string | null> {
   const servers = await scanDevServers()
   const patched = servers.find((s) => s.patched)

package/cli/commands/inspect/settling.ts

@@ -265,7 +265,11 @@ export async function waitForSootsimIdle({
             for (const n of hierarchy) {
               const layout = n && n.layout
               if (layout && layout.width > 0) {
-                const abs = (n && (n.absolute || n.absolutePosition)) || layout
+                // painted bounds catch a scroll fling. background playback
+                // keeps a view's painted bounds moving forever, so it and its
+                // subtree count by their own layout; the rest of the screen
+                // still catches the fling.
+                const abs = n.backgroundPlayback ? layout : n.absolute || n.absolutePosition || layout
                 nodes.push(Math.round(abs.x) + ',' + Math.round(abs.y) + ',' + Math.round(layout.width))
               }
               notePreviewProgress(

package/cli/commands/setup.ts

@@ -177,11 +177,9 @@ export async function runSetup(
     const productAnalytics = decidePrivacy(options, privacy)
     const crashReports = productAnalytics
 
-    const repositoryPlan = packageRoot
-      ? planRepositorySetup({ appDir: packageRoot, cliVersion })
-      : null
-    const repository = await decideRepository(options, repositoryPlan)
-    if (repository && repositoryPlan) {
+    const repositoryPlan = await decideRepository(options, packageRoot, cliVersion)
+    const repository = repositoryPlan !== null
+    if (repositoryPlan) {
       if (!options.json) {
         for (const operation of formatRepositoryOperations(repositoryPlan)) {
           console.log(`  ${muted(options.dryRun ? 'Would run' : 'Running')} ${operation}`)
@@ -376,22 +374,31 @@ function decidePrivacy(
 
 async function decideRepository(
   options: SetupOptions,
-  plan: RepositorySetupPlan | null,
-): Promise<boolean> {
-  if (!plan) {
+  appDir: string | null,
+  cliVersion: string,
+): Promise<RepositorySetupPlan | null> {
+  if (!appDir) {
     if (options.repository === true) {
       throw new Error('--repo requires a package.json inside a Git repository')
     }
-    return false
+    return null
+  }
+  if (options.repository === false) return null
+  if (
+    options.repository === undefined &&
+    (options.yes || options.ci || !process.stdin.isTTY)
+  ) {
+    return null
   }
-  if (plan.operations.length === 0) return true
-  if (options.repository !== undefined) return options.repository
-  if (options.yes || options.ci || !process.stdin.isTTY) return false
+  const plan = planRepositorySetup({ appDir, cliVersion })
+  if (plan.operations.length === 0 || options.repository === true) return plan
   printPromptBlock('Share peach with your team', [
     'peach already works here with no project setup.',
     'This only adds an exact peachsim dev dependency and a peach script for teammates.',
   ])
-  return confirm(`Add peach to ${path.basename(plan.appDir)}?`, false)
+  return (await confirm(`Add peach to ${path.basename(plan.appDir)}?`, false))
+    ? plan
+    : null
 }
 
 function requireInteractive(options: SetupOptions, flags: string): void {

package/cli/commands/test.ts

@@ -15,6 +15,7 @@ import {
   publishLiveDevStack,
 } from '../cloud-test-tunnel'
 import { parseFlowFile } from '../flow-file'
+import { resolveDefaultBridgePort } from '../ws-bridge'
 import { buildShellUrl, resolveShellBaseUrlForBridgePort } from './control'
 import { FLOW_ARG_VALUE_FLAGS, hoistLeadingSimFlag } from './flow'
 import { resolveDefaultUploadOrigin } from './upload'
@@ -1271,7 +1272,7 @@ export async function runTest(
       process.env.PEACH_URL = await buildShellUrl(
         appTarget.target,
         resolveShellBaseUrlForBridgePort(
-          opts.port ?? (Number(process.env.SOOTSIM_PORT) || 5173),
+          opts.port ?? (Number(process.env.SOOTSIM_PORT) || resolveDefaultBridgePort()),
         ),
       )
     }

package/cli/dev-build-freshness.ts

@@ -8,14 +8,11 @@
 // artifact mtimes per build route and reports which routes are stale, so
 // serve can refuse before binding instead of serving yesterday's engine.
 //
-// the route table mirrors scripts/dev/watch-peach-artifacts.ts ROUTES (the
-// authority on which sources feed which build). it is duplicated here rather
-// than imported because the watcher pulls chokidar plus engine/bundler
-// modules the CLI binary must not bundle — keep the two in sync: a source
-// the watch rebuilds on must appear below, or serve will call a stale build
-// fresh. deliberately omitted: the canvaskit binary inputs (resolved from a
-// manifest at watch time, never hand-edited) and the deps-web inputs (a
-// different served tree, not the engine serve() serves).
+// the watcher routes individual native inputs through its canonical providers.
+// this guard covers vendor glue/manifests and public assets as directories so
+// a native artifact update also refuses stale served workers. importing the
+// watcher would bundle chokidar and private engine/bundler modules into the cli.
+// deps-web belongs to a different served tree.
 
 import { readdirSync, statSync, type Dirent } from 'node:fs'
 import { join, relative, sep } from 'node:path'
@@ -53,8 +50,11 @@ const PEACHSIM_ENGINE_INPUTS = [
 const ENGINE_SOURCES = [
   'packages/peach-engine/src',
   'packages/peach-engine/public',
+  'packages/peach-engine/vendor',
   'packages/peach-engine/scripts/license-banner.ts',
   'packages/peach-engine/scripts/canvaskit-graphite-variant.ts',
+  'packages/peach-engine/scripts/canvaskit-ganesh-variant.ts',
+  'packages/peach-engine/scripts/canvaskit-kotlin-variant.ts',
   'packages/peach-engine/vite.build.config.ts',
   'packages/peach-engine/package.json',
   'packages/peach-compat/src',
@@ -176,7 +176,7 @@ export function findStaleDevBuildRoutes(monorepoRoot: string): StaleDevBuildRout
         newestSource = found
       }
     }
-    let newestArtifact: NewestFile | null = null
+    let oldestArtifact: NewestFile | null = null
     let artifactMissing = false
     for (const artifact of route.artifacts) {
       const found = newestForEntry(monorepoRoot, artifact)
@@ -184,20 +184,20 @@ export function findStaleDevBuildRoutes(monorepoRoot: string): StaleDevBuildRout
         artifactMissing = true
         continue
       }
-      if (!newestArtifact || found.mtimeMs > newestArtifact.mtimeMs) {
-        newestArtifact = found
+      if (!oldestArtifact || found.mtimeMs < oldestArtifact.mtimeMs) {
+        oldestArtifact = found
       }
     }
     if (!newestSource) continue
     if (
       artifactMissing ||
-      !newestArtifact ||
-      newestSource.mtimeMs > newestArtifact.mtimeMs
+      !oldestArtifact ||
+      newestSource.mtimeMs > oldestArtifact.mtimeMs
     ) {
       stale.push({
         route: route.id,
         newestSourcePath: toRepoPath(monorepoRoot, newestSource.absolutePath),
-        artifactMtimeMs: newestArtifact ? newestArtifact.mtimeMs : null,
+        artifactMtimeMs: oldestArtifact ? oldestArtifact.mtimeMs : null,
       })
     }
   }

package/cli/outbound-endpoints.ts

@@ -121,7 +121,7 @@ export const OUTBOUND_ENDPOINTS: Record<string, OutboundEndpointDeclaration> = {
     category: 'same-origin-runtime',
     destination: 'the origin already serving the peach runtime',
     preConsent: true,
-    payload: 'runtime assets and shared local settings',
+    payload: 'runtime assets, selected-shell reachability, and shared local settings',
   },
   guest_app_network: {
     category: 'guest-app-network',
@@ -552,12 +552,25 @@ export const DECLARED_OUTBOUND_CALLS: Record<string, OutboundCallDeclaration> =
     { category: 'same_origin_runtime', count: 1 },
   // the tenant build's built-in app chunk prefetch list and the chunk bodies
   // it names, resolved against the worker chunk's own url.
-  'packages/peach-engine/src/render-worker/app-in-worker.tsx :: fetch :: listUrl': {
+  'packages/peach-engine/src/render-worker/app-in-worker.tsx :: fetch-alias :: listUrl': {
     category: 'same_origin_runtime',
     count: 1,
   },
-  'packages/peach-engine/src/render-worker/app-in-worker.tsx :: fetch :: new URL(file, listUrl)':
+  'packages/peach-engine/src/render-worker/app-in-worker.tsx :: fetch-alias :: new URL(file, listUrl)':
     { category: 'same_origin_runtime', count: 1 },
+  // the tenant build's own chunks a dynamic import names, resolved against the
+  // importing chunk's url.
+  'packages/peach-engine/src/render-worker/module-preload.ts :: fetch-alias :: url': {
+    category: 'same_origin_runtime',
+    count: 1,
+  },
+  // guest fetch wrappers forward the guest's own request to the host fetch.
+  'packages/peach-engine/src/headless/tenant.ts :: fetch-alias :: activeInput as RequestInfo':
+    { category: 'guest_app_network', count: 1 },
+  'packages/peach-engine/src/render-worker/worker.ts :: fetch-alias :: input': {
+    category: 'guest_app_network',
+    count: 1,
+  },
   'packages/peach-engine/src/render-worker/rive-animation-clock.ts :: fetch :: wasmUrl': {
     category: 'same_origin_runtime',
     count: 1,
@@ -630,6 +643,10 @@ export const DECLARED_OUTBOUND_CALLS: Record<string, OutboundCallDeclaration> =
     category: 'local_development',
     count: 1,
   },
+  'packages/peachsim/cli/commands/detox.ts :: fetch :: shellUrl': {
+    category: 'same_origin_runtime',
+    count: 1,
+  },
   'packages/peachsim/cli/commands/cpu-profile.ts :: fetch :: `http://localhost:${cdpPort}/json/list`':
     { category: 'local_development', count: 1 },
   'packages/peachsim/cli/commands/cpu-profile.ts :: websocket :: wsUrl': {
@@ -821,7 +838,51 @@ interface NetworkNames {
   nodeGet: Set<string>
 }
 
-function networkNames(source: Program): NetworkNames {
+// `<owner>.fetch.bind(...)` captures the host fetch under another name
+function isFetchBinding(node: Expression): boolean {
+  return (
+    node.type === 'CallExpression' &&
+    node.callee.type === 'MemberExpression' &&
+    !node.callee.computed &&
+    node.callee.property.type === 'Identifier' &&
+    node.callee.property.name === 'bind' &&
+    node.callee.object.type === 'MemberExpression' &&
+    !node.callee.object.computed &&
+    node.callee.object.property.type === 'Identifier' &&
+    node.callee.object.property.name === 'fetch'
+  )
+}
+
+// names a relative module exports as fetch aliases, so a call through the
+// imported binding is declared like a direct fetch.
+const exportedFetchAliasCache = new Map<string, Set<string>>()
+function exportedFetchAliases(importer: string, specifier: string): Set<string> {
+  if (!specifier.startsWith('.')) return new Set()
+  const base = path.resolve(path.dirname(importer), specifier)
+  const file = [`${base}.ts`, `${base}.tsx`, base, path.join(base, 'index.ts')].find(
+    (candidate) => fs.existsSync(candidate) && fs.statSync(candidate).isFile(),
+  )
+  if (!file) return new Set()
+  const cached = exportedFetchAliasCache.get(file)
+  if (cached) return cached
+  const aliases = new Set<string>()
+  exportedFetchAliasCache.set(file, aliases)
+  const program = parseSync(file, fs.readFileSync(file, 'utf8'), {
+    lang: file.endsWith('.tsx') ? 'tsx' : 'ts',
+  }).program
+  const names = networkNames(program, file)
+  for (const statement of program.body) {
+    if (statement.type !== 'ExportNamedDeclaration') continue
+    if (statement.declaration?.type !== 'VariableDeclaration') continue
+    for (const declarator of statement.declaration.declarations) {
+      if (declarator.id.type === 'Identifier' && names.fetch.has(declarator.id.name))
+        aliases.add(declarator.id.name)
+    }
+  }
+  return aliases
+}
+
+function networkNames(source: Program, file: string): NetworkNames {
   const names: NetworkNames = {
     fetch: new Set(['fetch']),
     httpClient: new Set(['http', 'https']),
@@ -864,6 +925,16 @@ function networkNames(source: Program): NetworkNames {
     },
     ImportDeclaration(node) {
       const moduleName = node.source.value.replace(/^node:/, '')
+      const fetchAliases = exportedFetchAliases(file, node.source.value)
+      for (const specifier of node.specifiers) {
+        if (
+          specifier.type === 'ImportSpecifier' &&
+          specifier.imported.type === 'Identifier' &&
+          fetchAliases.has(specifier.imported.name)
+        ) {
+          names.fetch.add(specifier.local.name)
+        }
+      }
       if (moduleName === 'http' || moduleName === 'https') {
         for (const specifier of node.specifiers) {
           if (specifier.type === 'ImportSpecifier') {
@@ -895,7 +966,10 @@ function networkNames(source: Program): NetworkNames {
     },
     VariableDeclarator(node) {
       if (node.id.type !== 'Identifier' || !node.init) return
-      if (node.init.type === 'Identifier' && names.fetch.has(node.init.name)) {
+      if (
+        (node.init.type === 'Identifier' && names.fetch.has(node.init.name)) ||
+        isFetchBinding(node.init)
+      ) {
         names.fetch.add(node.id.name)
       }
       if (isClientExpression(node.init, names.httpClient)) {
@@ -1007,7 +1081,7 @@ export function detectOutboundCalls(repositoryRoot: string): DetectedOutboundCal
     const program = parseSync(file, source, {
       lang: file.endsWith('.tsx') ? 'tsx' : 'ts',
     }).program
-    const names = networkNames(program)
+    const names = networkNames(program, file)
     const relative = path.relative(repositoryRoot, file).split(path.sep).join('/')
     const recordCall = (node: CallExpression | NewExpression): void => {
       const kind = callKind(node, names, source)

package/detox/index.ts

@@ -657,10 +657,19 @@ export async function waitForSootsimIdle(
 // find a node in the sootsim tree matching a matcher descriptor
 async function findNodeByMatcher(matcher: Matcher): Promise<any> {
   const page = getPage()
-  if (matcher.index !== undefined || matcher.type === 'text') {
+  if (
+    matcher.regexFlags !== undefined ||
+    matcher.index !== undefined ||
+    matcher.type === 'text'
+  ) {
     return page.evaluate(async (indexedMatcher: Matcher) => {
-      const filter =
-        indexedMatcher.type === 'id'
+      const regex =
+        indexedMatcher.regexFlags !== undefined
+          ? new RegExp(indexedMatcher.value, indexedMatcher.regexFlags)
+          : null
+      const filter = regex
+        ? {}
+        : indexedMatcher.type === 'id'
           ? { hasId: indexedMatcher.value }
           : indexedMatcher.type === 'text'
             ? { hasText: indexedMatcher.value }
@@ -670,16 +679,18 @@ async function findNodeByMatcher(matcher: Matcher): Promise<any> {
                 ? { hasRole: indexedMatcher.value }
                 : { type: indexedMatcher.value }
       const results = await window.__sootsimTest!.queryAll(filter)
-      // detox by.text matches exact text elements, with or without an index.
-      // hasText also matches ancestors and substrings, which are not targets.
-      const indexed =
-        indexedMatcher.type === 'text'
-          ? results.filter(
-              (node) =>
-                (node.type === 'text' || node.nodeId < 0) &&
-                node.text === indexedMatcher.value,
-            )
-          : results
+      // text targets exclude ancestors; string values keep exact matching.
+      const indexed = results.filter((node) => {
+        if (indexedMatcher.type === 'text' && node.type !== 'text' && node.nodeId >= 0)
+          return false
+        if (!regex)
+          return indexedMatcher.type !== 'text' || node.text === indexedMatcher.value
+        const matches = (value: string | null) =>
+          typeof value === 'string' && regex.test(value)
+        if (indexedMatcher.type === 'id') return matches(node.testID) || matches(node.id)
+        if (indexedMatcher.type === 'text') return matches(node.text)
+        return matches(node.accessibilityLabel || (node.accessible ? node.text : null))
+      })
       return indexed[indexedMatcher.index ?? 0] ?? null
     }, matcher)
   }
@@ -1290,8 +1301,10 @@ function createSootSimElement(matcher: Matcher): SootSimElement {
     async replaceText(text: string) {
       const page = getPage()
       const node = await findNodeByMatcher(matcher)
+      const resolvedId = node?.testID ?? node?.id
       if (
         matcher.type === 'id' &&
+        typeof resolvedId === 'string' &&
         typeof node?.nodeId === 'number' &&
         node.nodeId >= 0x40000000
       ) {
@@ -1301,7 +1314,7 @@ function createSootSimElement(matcher: Matcher): SootSimElement {
             if (typeof mainShell?.callTestBridge !== 'function') return false
             return mainShell.callTestBridge('replaceTextByTestId', id, value)
           },
-          { id: matcher.value, value: text },
+          { id: resolvedId, value: text },
         )
         if (replaced === true) return
       }

package/detox/matchers.ts

@@ -4,20 +4,31 @@
 export interface Matcher {
   type: 'id' | 'text' | 'label' | 'type' | 'role'
   value: string
+  regexFlags?: string
   index?: number
 }
 
+function createMatcher(type: 'id' | 'text' | 'label', value: string | RegExp): Matcher {
+  if (typeof value === 'string') return { type, value }
+  // detox ignores global and sticky state and always uses unicode matching.
+  return {
+    type,
+    value: value.source,
+    regexFlags: value.flags.replace(/[^ims]/g, '') + 'u',
+  }
+}
+
 export const by = {
-  id(testID: string): Matcher {
-    return { type: 'id', value: testID }
+  id(testID: string | RegExp): Matcher {
+    return createMatcher('id', testID)
   },
 
-  text(text: string): Matcher {
-    return { type: 'text', value: text }
+  text(text: string | RegExp): Matcher {
+    return createMatcher('text', text)
   },
 
-  label(accessibilityLabel: string): Matcher {
-    return { type: 'label', value: accessibilityLabel }
+  label(accessibilityLabel: string | RegExp): Matcher {
+    return createMatcher('label', accessibilityLabel)
   },
 
   type(nativeType: string): Matcher {

package/dist-lib/agent-daemon-client.cjs

@@ -1,4 +1,4 @@
-/*! peach v0.1.1477 | (c) 2026 Tamagui LLC | Proprietary; see LICENSE */
+/*! peach v0.1.1481 | (c) 2026 Tamagui LLC | Proprietary; see LICENSE */
 let __sootsim_import_meta_url = '', __sootsim_import_meta_dirname = ''; try { __sootsim_import_meta_url = require('url').pathToFileURL(__filename).href; __sootsim_import_meta_dirname = __dirname; } catch {}
 "use strict";
 var __create = Object.create;