peachsim 0.1.1640 → 0.1.1641

package/dist-lib/vite.cjs

@@ -1,4 +1,4 @@
-/*! peach v0.1.1640 | (c) 2026 Tamagui LLC | Proprietary; see LICENSE */
+/*! peach v0.1.1641 | (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;

package/dist-lib/worklet-executable.cjs

@@ -1,4 +1,4 @@
-/*! peach v0.1.1640 | (c) 2026 Tamagui LLC | Proprietary; see LICENSE */
+/*! peach v0.1.1641 | (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 __defProp = Object.defineProperty;

package/dist-lib/worklet-executable.mjs

@@ -1,4 +1,4 @@
-/*! peach v0.1.1640 | (c) 2026 Tamagui LLC | Proprietary; see LICENSE */
+/*! peach v0.1.1641 | (c) 2026 Tamagui LLC | Proprietary; see LICENSE */
 
 // src/worklet-executable.ts
 import { parse } from "acorn";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "peachsim",
-  "version": "0.1.1640",
+  "version": "0.1.1641",
   "description": "Vite and Metro plugins, testing drivers, and SDK exports for peach.",
   "author": "Tamagui LLC",
   "license": "SEE LICENSE IN LICENSE",

package/src/backend-origin.ts

@@ -29,6 +29,14 @@ export function isLoopbackHost(hostname: string): boolean {
   )
 }
 
+export function isLoopbackOrigin(origin: string): boolean {
+  try {
+    return isLoopbackHost(new URL(origin).hostname)
+  } catch {
+    return false
+  }
+}
+
 // a browser page may use a local peach bridge (its proxies, websocket,
 // settings and account routes) only when this machine served the page: a
 // loopback origin, or the bridge's own host when a tunnel or reverse proxy

package/src/react-native-bridge-modules.ts

@@ -6,7 +6,11 @@
 import fs from 'node:fs'
 import path from 'node:path'
 import { swiftCodeMask, swiftSourceClosure } from './swift-compile'
-import { listXcodeAppTargets, readXcodeAppTarget } from './xcode-project'
+import {
+  findXcodeProject,
+  listXcodeAppTargets,
+  readXcodeAppTarget,
+} from './xcode-project'
 import type { ExpoSwiftSourceUnit } from './expoSwiftContract'
 
 interface MethodInfo {
@@ -312,9 +316,9 @@ function swiftClassFor(objcName: string, files: Record<string, string>): string
 export const BRIDGE_MODULE_FILE_PREFIX = '__peach_react_module_'
 
 /**
- * the app target's legacy bridge modules, one compile unit each, or null
- * when the app has no iOS project or registers none. a module the host
- * cannot provide is a unit with a diagnostic instead of files.
+ * the app and its framework targets' legacy bridge modules, one compile unit
+ * each, or null when the app has no iOS project or registers none. a module
+ * the host cannot provide is a unit with a diagnostic instead of files.
  */
 export function collectBridgeModuleSources(
   appRoot: string,
@@ -327,20 +331,13 @@ export function collectBridgeModuleSources(
   const iosRoot = path.join(appRoot, 'ios')
   if (!fs.existsSync(iosRoot)) return null
   const projectRoot = fs.realpathSync(appRoot)
-  const projects = fs
-    .readdirSync(iosRoot, { withFileTypes: true })
-    .filter((entry) => entry.isDirectory() && entry.name.endsWith('.xcodeproj'))
-    .map((entry) => path.join(iosRoot, entry.name))
-  const targets = projects.flatMap((project) =>
-    listXcodeAppTargets(project, { requireSources: false }).map((name) => ({
-      project,
-      name,
-    })),
-  )
+  const project = findXcodeProject(iosRoot)
+  if (!project) return null
+  const targets = listXcodeAppTargets(project, { requireSources: false })
   // RCTRegisterModule runs in the one app binary; several targets are
   // several apps, and nothing here says which one this bundle runs in
   if (targets.length !== 1) return null
-  const app = readXcodeAppTarget(targets[0]!.project, targets[0]!.name, 'Release', {
+  const app = readXcodeAppTarget(project, targets[0]!, 'Release', {
     requireSources: false,
   })
   const own = (file: string) => {
@@ -360,72 +357,88 @@ export function collectBridgeModuleSources(
       throw new Error(`${file}: app native source outside ${projectRoot}`)
     return true
   }
-  const objc = app.allSources.filter((file) => /\.mm?$/.test(file) && own(file))
-  if (objc.length === 0) return null
-  // headers declare the superclasses; they sit beside the sources that import them
-  const headers = [...new Set(objc.map((file) => path.dirname(file)))].flatMap((dir) =>
-    fs
-      .readdirSync(dir)
-      .filter((name) => name.endsWith('.h'))
-      .sort()
-      .map((name) => path.join(dir, name))
-      .filter(own),
-  )
-  const declarations = parseObjectiveCModules(
-    [...objc, ...headers].map((file) => ({ file, text: fs.readFileSync(file, 'utf8') })),
-  )
-  if (declarations.modules.length === 0) return null
-  const namespace = app.moduleName.replace(/[^A-Za-z0-9_]/g, '_')
-  const swiftFiles: Record<string, string> = {}
-  for (const file of app.sources.filter(own)) {
-    const relative = path.relative(projectRoot, fs.realpathSync(file))
-    swiftFiles[`Sources/${namespace}/${relative.split(path.sep).join('/')}`] =
-      `#sourceLocation(file: ${JSON.stringify(file)}, line: 1)\n${fs.readFileSync(file, 'utf8')}`
-  }
   const units: ExpoSwiftSourceUnit[] = []
   const failures: { namespace: string; diagnostic: string }[] = []
-  const seen = new Set<string>()
-  for (const module of declarations.modules) {
+  // the reader owns dependency order and visits a shared framework only once.
+  // each target keeps its own Swift module identity and compilation settings.
+  for (const target of [...app.frameworks, app]) {
     signal?.throwIfAborted()
-    if (seen.has(module.className)) continue
-    seen.add(module.className)
-    const moduleId = `${namespace}.${module.className}`
-    const methods = declarations.methods.get(module.className) ?? []
-    const swiftClass = module.extern ? swiftClassFor(module.className, swiftFiles) : null
-    const unit: ExpoSwiftSourceUnit = {
-      namespace,
-      moduleId,
-      classes: [],
-      bridgeModules: [],
-      files: {},
-      frameworks: [],
-      swiftLanguageMode: app.languageMode,
+    const objc = [
+      ...new Set(
+        target.allSources
+          .filter((file) => /\.mm?$/.test(file) && own(file))
+          .map((file) => fs.realpathSync(file)),
+      ),
+    ]
+    if (objc.length === 0) continue
+    // headers declare the superclasses; they sit beside the sources that import them
+    const headers = [...new Set(objc.map((file) => path.dirname(file)))].flatMap((dir) =>
+      fs
+        .readdirSync(dir)
+        .filter((name) => name.endsWith('.h'))
+        .sort()
+        .map((name) => path.join(dir, name))
+        .filter(own),
+    )
+    const declarations = parseObjectiveCModules(
+      [...objc, ...headers].map((file) => ({
+        file,
+        text: fs.readFileSync(file, 'utf8'),
+      })),
+    )
+    if (declarations.modules.length === 0) continue
+    const namespace = target.moduleName.replace(/[^A-Za-z0-9_]/g, '_')
+    const swiftFiles: Record<string, string> = {}
+    for (const file of target.sources.filter(own)) {
+      const relative = path.relative(projectRoot, fs.realpathSync(file))
+      swiftFiles[`Sources/${namespace}/${relative.split(path.sep).join('/')}`] =
+        `#sourceLocation(file: ${JSON.stringify(file)}, line: 1)\n${fs.readFileSync(file, 'utf8')}`
     }
-    if (swiftClass) {
-      const register = `__peachReactModule_${module.className}`
-      unit.files = swiftSourceClosure(swiftFiles, [swiftClass])
-      unit.files[
-        `Sources/${namespace}/${BRIDGE_MODULE_FILE_PREFIX}${module.className}.swift`
-      ] =
-        `import React\n\n// ${module.file}: RCT_EXTERN_MODULE(${module.className})\npublic func ${register}() -> RCTModuleHost.Registration {\n  RCTModuleHost.Registration(className: ${swiftString(module.className)}, moduleName: ${swiftString(module.jsName)}, methods: ${methodsLiteral(methods)}, make: { ${swiftClass}() })\n}\n`
-      unit.bridgeModules = [`${namespace}.${register}()`]
-    } else {
-      const superclass = compiledSuperclass(module.className, declarations.superclasses)
-      const selectors = declarations.implementations.get(module.className)
-      if (!selectors || !superclass) {
-        failures.push({
-          namespace: moduleId,
-          diagnostic: !selectors
-            ? `${module.file}: no Swift class or Objective-C @implementation provides ${module.className}`
-            : `${module.file}: ${module.className}'s superclass ${declarations.superclasses.get(module.className) ?? '(none)'} is Objective-C, which Peach does not compile`,
-        })
-        continue
+    const seen = new Set<string>()
+    for (const module of declarations.modules) {
+      signal?.throwIfAborted()
+      if (seen.has(module.className)) continue
+      seen.add(module.className)
+      const moduleId = `${namespace}.${module.className}`
+      const methods = declarations.methods.get(module.className) ?? []
+      const swiftClass = module.extern
+        ? swiftClassFor(module.className, swiftFiles)
+        : null
+      const unit: ExpoSwiftSourceUnit = {
+        namespace,
+        moduleId,
+        classes: [],
+        bridgeModules: [],
+        files: {},
+        frameworks: [],
+        swiftLanguageMode: target.languageMode,
+      }
+      if (swiftClass) {
+        const register = `__peachReactModule_${module.className}`
+        unit.files = swiftSourceClosure(swiftFiles, [swiftClass])
+        unit.files[
+          `Sources/${namespace}/${BRIDGE_MODULE_FILE_PREFIX}${module.className}.swift`
+        ] =
+          `import React\n\n// ${module.file}: RCT_EXTERN_MODULE(${module.className})\npublic func ${register}() -> RCTModuleHost.Registration {\n  RCTModuleHost.Registration(className: ${swiftString(module.className)}, moduleName: ${swiftString(module.jsName)}, methods: ${methodsLiteral(methods)}, make: { ${swiftClass}() })\n}\n`
+        unit.bridgeModules = [`${namespace}.${register}()`]
+      } else {
+        const superclass = compiledSuperclass(module.className, declarations.superclasses)
+        const selectors = declarations.implementations.get(module.className)
+        if (!selectors || !superclass) {
+          failures.push({
+            namespace: moduleId,
+            diagnostic: !selectors
+              ? `${module.file}: no Swift class or Objective-C @implementation provides ${module.className}`
+              : `${module.file}: ${module.className}'s superclass ${declarations.superclasses.get(module.className) ?? '(none)'} is Objective-C, which Peach does not compile`,
+          })
+          continue
+        }
+        unit.bridgeModules = [
+          `RCTModuleHost.Registration(className: ${swiftString(module.className)}, moduleName: ${swiftString(module.jsName)}, methods: ${methodsLiteral(methods)}, objectiveCSelectors: ${JSON.stringify([...selectors].sort())}, superclass: { ${superclass}() })`,
+        ]
       }
-      unit.bridgeModules = [
-        `RCTModuleHost.Registration(className: ${swiftString(module.className)}, moduleName: ${swiftString(module.jsName)}, methods: ${methodsLiteral(methods)}, objectiveCSelectors: ${JSON.stringify([...selectors].sort())}, superclass: { ${superclass}() })`,
-      ]
+      units.push(unit)
     }
-    units.push(unit)
   }
-  return { units, failures }
+  return units.length === 0 && failures.length === 0 ? null : { units, failures }
 }

package/src/swift-compile.ts

@@ -33,6 +33,7 @@ import {
   swiftTargetModuleName,
   type SwiftPackageTarget,
 } from './swift-package'
+import { withSwiftRootLock } from './swift-root-lock'
 import { swiftEnvironment, swiftSdkOptions, type SwiftWasmSdk } from './swift-toolchain'
 import { isSwiftResourceBundles } from './swiftContract'
 import type { SwiftImageUpload } from './swift-submit'
@@ -178,6 +179,8 @@ export interface SwiftCompileOptions {
   toolchainBin: string
   timeoutMs?: number
   signal?: AbortSignal
+  /** called as the compile reaches each stage, in addition to the stderr line. */
+  onStage?: (stage: string) => void
 }
 
 export interface SwiftCompileArtifact {
@@ -948,9 +951,10 @@ export function emitSwiftPackageManifest(args: {
     // compiled: whole, and ahead of the sdk libraries, so PeachICU's
     // reservation keeps icu's data member out. merged into one relocatable
     // object (wasm-ld -r) or linked from an archive, a protocol conformance
-    // goes unfound at runtime or icu links twice (RAN, the Expo fixture). the
-    // libraries the objects autolink follow, since the driver reads autolink
-    // entries only from objects it compiled.
+    // goes unfound at runtime or icu links twice (RAN, the Expo fixture).
+    // clang loads configuration inputs before command-line libraries. forward
+    // the file opaquely so swift neither expands it nor scans every framework
+    // object for autolinks; distribution.link supplies those libraries.
     const imports = distribution
       ? `, "-I", ${JSON.stringify(path.join(moduleRoot, 'modules'))}`
       : ''
@@ -994,7 +998,7 @@ export function emitSwiftPackageManifest(args: {
     ].join(', ')
     const library =
       distribution && distributionLink
-        ? ['-Xlinker', `@${distributionLink.path}`, ...distribution.link]
+        ? ['-Xclang-linker', `--config=${distributionLink.path}`, ...distribution.link]
             .map((flag) => `, ${JSON.stringify(flag)}`)
             .join('')
         : ''
@@ -6149,8 +6153,10 @@ export function compileSwiftProjectUnit(
   }
   const hash = swiftArtifactHash(input, options.release, moduleRoot)
   const sharedRoot = path.join(rnxHomeDir(), 'cache', 'swift-projects', hash)
-  const report = (message: string) =>
+  const report = (message: string) => {
     console.error(`[swift-project ${hash.slice(0, 16)}] ${message}`)
+    options.onStage?.(message)
+  }
   report('checking verified artifacts')
   return serialize(
     root,
@@ -6232,88 +6238,84 @@ export function compileSwiftProjectUnit(
           rmSync(requestRoot, { recursive: true, force: true })
         }
       }
-      writeSwiftProject(layout, input, moduleRoot)
-      const swift = path.join(options.toolchainBin, 'swift')
-      if (!existsSync(swift)) {
-        throw new Error(
-          `swift-compile: no swift.org toolchain at ${options.toolchainBin}; install ${options.release} and its matching wasm sdk`,
-        )
-      }
-      report('preparing compiler plugins')
-      const macroPlugins = await ensureMacroPlugins(
-        moduleRoot,
-        options.toolchainBin,
-        options.release,
-        options.signal,
-      )
-      // memoized per toolchain, so only a process's first build waits on it,
-      // and that one reads and gzips it while swift builds
-      const sdk = swiftModuleSdk(moduleRoot).wasmSdkId
-      const icu = swiftIcuAsset(options.toolchainBin, sdk)
-      const buildArgs = [
-        'build',
-        ...swiftPackageCacheOptions(),
-        '--build-system',
-        'native',
-        '-j',
-        BUILD_JOBS,
-        '--package-path',
+      // the root's sources, manifest and executable are shared by every process
+      // using it, so one process writes, builds and reads them at a time.
+      return withSwiftRootLock(
         root,
-        ...swiftSdkOptions(),
-        '--swift-sdk',
-        sdk,
-        '-c',
-        'release',
-        '-Xswiftc',
-        '-Osize',
-        '-Xswiftc',
-        '-num-threads',
-        '-Xswiftc',
-        BUILD_JOBS,
-        ...macroPlugins.flatMap((plugin) => [
-          '-Xswiftc',
-          '-load-plugin-library',
-          '-Xswiftc',
-          plugin,
-        ]),
-      ]
-      const buildOptions = {
-        env: {
-          ...process.env,
-          // shipped host plugins resolve against the selected compiler's runtime.
-          ...(process.platform === 'linux'
-            ? {
-                LD_LIBRARY_PATH: [
-                  path.resolve(options.toolchainBin, '../lib/swift/linux'),
-                  path.resolve(options.toolchainBin, '../lib/swift/host'),
-                  process.env.LD_LIBRARY_PATH,
-                ]
-                  .filter(Boolean)
-                  .join(':'),
-              }
-            : {}),
-        },
-        maxBuffer: 64 * 1024 * 1024,
-        timeout: options.timeoutMs,
-        signal: options.signal,
-      }
-      report('compiling and linking Swift modules')
-      try {
-        await runCompiler(swift, buildArgs, buildOptions, SWIFTPM_PROGRESS, SWIFTPM_NOISE)
-      } catch (error) {
-        const output = outputOf(error)
-        const moduleCache = path.join(
-          root,
-          '.build',
-          WASM_TRIPLE,
-          'release',
-          'ModuleCache',
-        )
-        if (
-          output.includes('was compiled with module cache path') &&
-          existsSync(moduleCache)
-        ) {
-          rmSync(moduleCache, { recursive: true, force: true })
+        async () => {
+          // a process that held the root while this one waited may have built
+          // this exact address.
+          const built = readCompiledArtifact(path.join(sharedRoot, 'artifact'), hash)
+          if (built) {
+            report('reusing verified disk artifact')
+            return retain(root, built)
+          }
+          writeSwiftProject(layout, input, moduleRoot)
+          const swift = path.join(options.toolchainBin, 'swift')
+          if (!existsSync(swift)) {
+            throw new Error(
+              `swift-compile: no swift.org toolchain at ${options.toolchainBin}; install ${options.release} and its matching wasm sdk`,
+            )
+          }
+          report('preparing compiler plugins')
+          const macroPlugins = await ensureMacroPlugins(
+            moduleRoot,
+            options.toolchainBin,
+            options.release,
+            options.signal,
+          )
+          // memoized per toolchain, so only a process's first build waits on it,
+          // and that one reads and gzips it while swift builds
+          const sdk = swiftModuleSdk(moduleRoot).wasmSdkId
+          const icu = swiftIcuAsset(options.toolchainBin, sdk)
+          const buildArgs = [
+            'build',
+            ...swiftPackageCacheOptions(),
+            '--build-system',
+            'native',
+            '-j',
+            BUILD_JOBS,
+            '--package-path',
+            root,
+            ...swiftSdkOptions(),
+            '--swift-sdk',
+            sdk,
+            '-c',
+            'release',
+            '-Xswiftc',
+            '-Osize',
+            '-Xswiftc',
+            '-num-threads',
+            '-Xswiftc',
+            BUILD_JOBS,
+            ...macroPlugins.flatMap((plugin) => [
+              '-Xswiftc',
+              '-load-plugin-library',
+              '-Xswiftc',
+              plugin,
+            ]),
+          ]
+          const buildOptions = {
+            env: {
+              ...process.env,
+              // shipped host plugins resolve against the selected compiler's runtime.
+              ...(process.platform === 'linux'
+                ? {
+                    LD_LIBRARY_PATH: [
+                      path.resolve(options.toolchainBin, '../lib/swift/linux'),
+                      path.resolve(options.toolchainBin, '../lib/swift/host'),
+                      process.env.LD_LIBRARY_PATH,
+                    ]
+                      .filter(Boolean)
+                      .join(':'),
+                  }
+                : {}),
+            },
+            maxBuffer: 64 * 1024 * 1024,
+            timeout: options.timeoutMs,
+            signal: options.signal,
+          }
+          report('compiling and linking Swift modules')
           try {
             await runCompiler(
               swift,
@@ -6322,29 +6324,54 @@ export function compileSwiftProjectUnit(
               SWIFTPM_PROGRESS,
               SWIFTPM_NOISE,
             )
-          } catch (retryError) {
-            throw new Error(
-              projectDiagnostic(outputOf(retryError), layout, input.files),
-              {
-                cause: retryError,
-              },
+          } catch (error) {
+            const output = outputOf(error)
+            const moduleCache = path.join(
+              root,
+              '.build',
+              WASM_TRIPLE,
+              'release',
+              'ModuleCache',
             )
+            if (
+              output.includes('was compiled with module cache path') &&
+              existsSync(moduleCache)
+            ) {
+              rmSync(moduleCache, { recursive: true, force: true })
+              try {
+                await runCompiler(
+                  swift,
+                  buildArgs,
+                  buildOptions,
+                  SWIFTPM_PROGRESS,
+                  SWIFTPM_NOISE,
+                )
+              } catch (retryError) {
+                throw new Error(
+                  projectDiagnostic(outputOf(retryError), layout, input.files),
+                  {
+                    cause: retryError,
+                  },
+                )
+              }
+            } else {
+              throw new Error(projectDiagnostic(output, layout, input.files), {
+                cause: error,
+              })
+            }
           }
-        } else {
-          throw new Error(projectDiagnostic(output, layout, input.files), {
-            cause: error,
-          })
-        }
-      }
-      const artifact = {
-        hash,
-        bytes: readFileSync(builtArtifact(layout)),
-        icu: await icu,
-      }
-      saveCompiledArtifact(root, artifact)
-      saveCompiledArtifact(sharedRoot, artifact)
-      report('compiled artifact verified')
-      return retain(root, artifact)
+          const artifact = {
+            hash,
+            bytes: readFileSync(builtArtifact(layout)),
+            icu: await icu,
+          }
+          saveCompiledArtifact(root, artifact)
+          saveCompiledArtifact(sharedRoot, artifact)
+          report('compiled artifact verified')
+          return retain(root, artifact)
+        },
+        options.signal,
+      )
     },
     options.signal,
   )

package/src/swift-distribution.lock.json

@@ -1,10 +1,10 @@
 {
-  "id": "77123740e6b79652",
+  "id": "e8dd3a9ff9c4dc74",
   "release": "swift-6.4.0-RELEASE-custom-0d775d32d7c74eae",
   "wasmSdkId": "swift-6.4.0-RELEASE_wasm-peach-21f60db0",
   "wasmSdkUrl": "https://r2.sootsim.com/swift-wasm-sdk/swift-6.4.0-RELEASE_wasm-peach-21f60db0.artifactbundle.tar.gz",
   "wasmSdkChecksum": "7b7573fd23120549fc928581a42968676f5f00f9ef63e5618032a6928a724e16",
-  "source": "7625fb75d15f047f1e8c0b14b73407c50263f0c4",
+  "source": "693296741f3865605388c21ee7e220cb0b6ccaa3",
   "targets": [
     "ImagePlayground",
     "QuickLookThumbnailing",
@@ -46,6 +46,7 @@
     "Darwin",
     "MachO",
     "ObjectiveC",
+    "PeachObjCRuntime",
     "PeachObjC",
     "UIUtilities",
     "UIKitCore",
@@ -191,16 +192,16 @@
   },
   "hosts": {
     "darwin-arm64": {
-      "sha256": "cc4a8f39ea9e3f12864196793a248bea28c05917ef4e7220ad516447da88d582",
-      "size": 71374056
+      "sha256": "0e06928cd63077f30226a27b2a3e92e89bdcaaf2fcd57fcac6a38a8465ee6865",
+      "size": 71438614
     },
     "linux-x64": {
-      "sha256": "c3938547ce5a453c63dc261e98753be6420ee8f2501b64d3622ef16f63d8bd1f",
-      "size": 71380196
+      "sha256": "baae9a89308dfde3cc47366ab4163369ac8537274361d10381004f006a965afa",
+      "size": 71444190
     },
     "linux-arm64": {
-      "sha256": "0b32aaf29f8ad7a1ca021a42f889bc4da28d239680c4cff82ca96a803c3d31e1",
-      "size": 71378226
+      "sha256": "422e2fbd6f65a8aebe0456e9becc2a6a28505825457c9758e8275f35e2fe63f1",
+      "size": 71442522
     }
   }
 }

package/src/swift-host.ts

@@ -1401,10 +1401,11 @@ async function compile(
     throw new SwiftMissingModulesError(await missingModulesMessage(packagePath, missing))
   const artifact = await compileSwiftProjectUnit(input, {
     // the compile rewrites Sources/App in its root before swiftpm builds, and
-    // its lock orders one process only: two vites on one root (a lane's dev
-    // server and a capture, or two checkouts) build each other's sources. so
-    // each app and module checkout gets its own root, which keeps the same
-    // app's incremental build across restarts.
+    // a root lock orders every process using it, so two vites on one root
+    // (a lane's dev server and a capture, or two checkouts) queue instead of
+    // building each other's sources. each app and module checkout still gets
+    // its own root, so they do not queue and the same app keeps its
+    // incremental build across restarts.
     buildRoot: (() => {
       if (process.env.CONTRAST_SWIFT_BUILD_ROOT)
         return process.env.CONTRAST_SWIFT_BUILD_ROOT
@@ -1656,6 +1657,7 @@ async function compileRemote(
     },
     origin,
     signal,
+    (stage) => console.error(`Peach: compiling ${path.basename(packagePath)}: ${stage}`),
   )
   // the app's JS calls with the hash its own `one typegen` wrote; glue the
   // service rendered from another One would reject every call as stale.