peachsim 0.1.1594 → 0.1.1619

package/kotlin/JniSources/dev/peach/jni/IncomingBindings.kt

@@ -0,0 +1,157 @@
+package dev.peach.jni
+
+private data class IncomingKey(val owner: String, val name: String, val descriptor: String, val isStatic: Boolean)
+private data class IncomingClass(val parents: Array<String>, val accepts: (Any?) -> Boolean)
+private data class IncomingMethod(
+    val key: IncomingKey,
+    val arguments: Int,
+    val virtual: (Any?, Array<Any?>) -> Any?,
+    val nonvirtual: ((Any?, Array<Any?>) -> Any?)?,
+)
+private data class IncomingField(val key: IncomingKey, val read: (Any?) -> Any?, val write: ((Any?, Any?) -> Unit)?)
+private val incomingClasses = mutableMapOf<String, IncomingClass>()
+private val incomingMethods = mutableListOf<IncomingMethod>()
+private val incomingMethodIds = mutableMapOf<IncomingKey, Int>()
+private val incomingFields = mutableListOf<IncomingField>()
+private val incomingFieldIds = mutableMapOf<IncomingKey, Int>()
+private var incomingInitialized = false
+private var incomingRetired = false
+
+// the compiler replaces this body with registrations of original declarations.
+internal fun initializeIncomingBindings() {
+    error("JNI incoming bindings require the compiler plugin")
+}
+
+private fun requireIncomingBindings() {
+    check(!incomingRetired) { "native binding runtime retired" }
+    if (!incomingInitialized) {
+        initializeIncomingBindings()
+        incomingInitialized = true
+    }
+}
+
+internal fun registerIncomingClass(owner: String, parents: Array<String>, accepts: (Any?) -> Boolean) {
+    check(incomingClasses.put(owner, IncomingClass(parents, accepts)) == null) { "duplicate incoming class: $owner" }
+}
+
+internal fun registerIncomingMethod(
+    owner: String, name: String, descriptor: String, isStatic: Boolean, arguments: Int,
+    virtual: (Any?, Array<Any?>) -> Any?, nonvirtual: ((Any?, Array<Any?>) -> Any?)?,
+) {
+    val key = IncomingKey(owner, name, descriptor, isStatic)
+    check(key !in incomingMethodIds) { "duplicate incoming method: $owner.$name$descriptor" }
+    incomingMethods += IncomingMethod(key, arguments, virtual, nonvirtual)
+    incomingMethodIds[key] = incomingMethods.size
+}
+
+internal fun registerIncomingField(owner: String, name: String, descriptor: String, isStatic: Boolean, read: (Any?) -> Any?, write: ((Any?, Any?) -> Unit)?) {
+    val key = IncomingKey(owner, name, descriptor, isStatic)
+    check(key !in incomingFieldIds) { "duplicate incoming field: $owner.$name:$descriptor" }
+    incomingFields += IncomingField(key, read, write)
+    incomingFieldIds[key] = incomingFields.size
+}
+
+fun requireIncomingClass(owner: String) {
+    requireIncomingBindings()
+    if (owner !in incomingClasses) throw ClassNotFoundException(owner)
+}
+
+fun isIncomingInstance(owner: String, receiver: Any?): Boolean {
+    requireIncomingClass(owner)
+    return incomingClasses.getValue(owner).accepts(receiver)
+}
+
+fun isIncomingAssignableFrom(target: String, source: String): Boolean {
+    requireIncomingClass(target)
+    requireIncomingClass(source)
+    fun inherits(type: String): Boolean = type == target || incomingClasses[type]?.parents.orEmpty().any(::inherits)
+    return inherits(source)
+}
+
+fun incomingClassOf(receiver: Any): String {
+    requireIncomingBindings()
+    val matches = incomingClasses.filterValues { it.accepts(receiver) }.keys
+    return matches.firstOrNull { candidate -> matches.none { it != candidate && isIncomingAssignableFrom(candidate, it) } }
+        ?: throw ClassNotFoundException("receiver has no registered class")
+}
+
+private fun lookupIncoming(owner: String, name: String, descriptor: String, isStatic: Boolean, ids: Map<IncomingKey, Int>): Int? {
+    val key = IncomingKey(owner, name, descriptor, isStatic)
+    ids[key]?.let { return it }
+    if (name == "<init>") return null
+    for (parent in incomingClasses[owner]?.parents.orEmpty()) {
+        lookupIncoming(parent, name, descriptor, isStatic, ids)?.let { return it }
+    }
+    return null
+}
+
+// ids describe declarations; a cached base id remains valid on derived instances.
+fun lookupIncomingMethod(owner: String, name: String, descriptor: String, isStatic: Boolean = false): Int {
+    requireIncomingClass(owner)
+    return lookupIncoming(owner, name, descriptor, isStatic, incomingMethodIds)
+        ?: throw NoSuchMethodError("$owner.$name$descriptor")
+}
+
+fun lookupIncomingField(owner: String, name: String, descriptor: String, isStatic: Boolean = false): Int {
+    requireIncomingClass(owner)
+    return lookupIncoming(owner, name, descriptor, isStatic, incomingFieldIds)
+        ?: throw NoSuchFieldError("$owner.$name:$descriptor")
+}
+
+private fun requireIncomingReceiver(key: IncomingKey, receiver: Any?) {
+    if (!key.isStatic && key.name != "<init>") {
+        if (receiver == null) throw NullPointerException("null receiver for ${key.owner}.${key.name}")
+        if (!incomingClasses.getValue(key.owner).accepts(receiver))
+            throw IllegalArgumentException("receiver is not an instance of ${key.owner}")
+    }
+}
+
+fun invokeIncoming(id: Int, receiver: Any?, arguments: Array<Any?>, nonvirtual: Boolean = false): Any? {
+    requireIncomingBindings()
+    val method = incomingMethods.getOrNull(id - 1) ?: throw NoSuchMethodError("invalid incoming method id: $id")
+    require(method.key.name != "<init>") { "constructors require constructIncoming" }
+    requireIncomingReceiver(method.key, receiver)
+    require(arguments.size == method.arguments) { "wrong argument count for ${method.key.owner}.${method.key.name}${method.key.descriptor}" }
+    val body = if (nonvirtual) method.nonvirtual
+        ?: throw AbstractMethodError("${method.key.owner}.${method.key.name}${method.key.descriptor}")
+        else method.virtual
+    return body(receiver, arguments)
+}
+
+fun constructIncoming(id: Int, arguments: Array<Any?>): Any {
+    requireIncomingBindings()
+    val method = incomingMethods.getOrNull(id - 1) ?: throw NoSuchMethodError("invalid incoming constructor id: $id")
+    require(method.key.name == "<init>" && !method.key.isStatic) { "method is not a constructor" }
+    require(arguments.size == method.arguments) { "wrong constructor argument count for ${method.key.owner}${method.key.descriptor}" }
+    return checkNotNull(method.virtual(null, arguments))
+}
+
+fun readIncomingField(id: Int, receiver: Any?): Any? {
+    requireIncomingBindings()
+    val field = incomingFields.getOrNull(id - 1) ?: throw NoSuchFieldError("invalid incoming field id: $id")
+    requireIncomingReceiver(field.key, receiver)
+    return field.read(receiver)
+}
+
+fun writeIncomingField(id: Int, receiver: Any?, value: Any?) {
+    requireIncomingBindings()
+    val field = incomingFields.getOrNull(id - 1) ?: throw NoSuchFieldError("invalid incoming field id: $id")
+    requireIncomingReceiver(field.key, receiver)
+    val write = field.write ?: throw IllegalAccessError("final field: ${field.key.owner}.${field.key.name}")
+    write(receiver, value)
+}
+
+internal fun retireIncomingBindings() {
+    incomingRetired = true
+    incomingClasses.clear()
+    incomingMethods.clear()
+    incomingMethodIds.clear()
+    incomingFields.clear()
+    incomingFieldIds.clear()
+}
+
+class ClassNotFoundException(message: String) : Exception(message)
+class NoSuchMethodError(message: String) : Error(message)
+class NoSuchFieldError(message: String) : Error(message)
+class AbstractMethodError(message: String) : Error(message)
+class IllegalAccessError(message: String) : Error(message)

package/kotlin/JniSources/dev/peach/jni/NativeBindings.kt

@@ -0,0 +1,79 @@
+@file:OptIn(kotlin.js.ExperimentalWasmJsInterop::class)
+
+package dev.peach.jni
+
+import kotlin.js.*
+
+private data class Method(val owner: String, val name: String, val descriptor: String)
+private val methods = mutableMapOf<Method, (Any?, Array<Any?>) -> Any?>()
+private var nativeRuntime: NativeRuntime? = null
+private var retired = false
+private var retiring = false
+private val retirementActions = mutableListOf<() -> Unit>()
+private fun assertActive() = check(!retired) { "native binding runtime retired" }
+
+fun isNativeRuntimeActive(): Boolean = !retired && !retiring
+
+fun registerNativeRetirement(action: () -> Unit) {
+    check(isNativeRuntimeActive()) { "native binding runtime retired" }
+    retirementActions += action
+}
+
+// registration glue supplies native entrypoints; package method bodies stay unchanged.
+fun registerNative(owner: String, method: String, descriptor: String, body: (Any?, Array<Any?>) -> Any?) {
+    check(isNativeRuntimeActive()) { "native binding runtime retired" }
+    val key = Method(owner, method, descriptor)
+    check(key !in methods) { "native method already bound: $owner.$method$descriptor" }
+    methods[key] = body
+}
+
+fun invoke(receiver: Any?, owner: String, method: String, descriptor: String, arguments: Array<Any?>): Any? {
+    assertActive()
+    val body = methods[Method(owner, method, descriptor)]
+        ?: throw UnsatisfiedLinkError("unbound native method: $owner.$method$descriptor")
+    return body(receiver, arguments)
+}
+
+class UnsatisfiedLinkError(message: String) : Error(message)
+
+external interface NativePeer : JsAny {
+    fun reset()
+    fun isValid(): Boolean
+}
+
+external interface NativeCallback : JsAny {
+    fun invoke(arguments: JsReference<Array<Any?>>): JsReference<Any>?
+    fun release()
+}
+
+external interface NativeRuntime : JsAny {
+    fun create(owner: String, receiver: JsReference<Any>): NativePeer
+    fun attach(peer: NativePeer, owner: JsReference<Any>)
+    fun capture(peer: NativePeer, receiver: JsReference<Any>, dispatch: (JsReference<Any>, JsReference<Array<Any?>>) -> JsReference<Any>?): NativeCallback
+    fun retire()
+}
+
+fun installNativeRuntime(runtime: NativeRuntime) {
+    check(isNativeRuntimeActive()) { "native binding runtime retired" }
+    check(nativeRuntime == null) { "native binding runtime is already installed" }
+    nativeRuntime = runtime
+}
+
+fun retireNativeRuntime() {
+    if (retired || retiring) return
+    retiring = true
+    var failure: Throwable? = null
+    try {
+        for (action in retirementActions) {
+            try { action() } catch (error: Throwable) { if (failure == null) failure = error }
+        }
+    } finally {
+        retirementActions.clear()
+        retired = true
+        retireIncomingBindings()
+        nativeRuntime?.retire()
+        methods.clear()
+    }
+    failure?.let { throw it }
+    // retirement is terminal for this Kotlin process.
+}

package/kotlin/JniTransportSources/dev/peach/jni/integration/JniTransport.kt

@@ -0,0 +1,91 @@
+@file:OptIn(kotlin.js.ExperimentalWasmJsInterop::class)
+
+package dev.peach.jni.integration
+
+import dev.peach.jni.*
+import kotlin.js.*
+
+external interface JniTransportReply : JsAny {
+    val value: JsReference<Any>?
+    val error: JsReference<Throwable>?
+}
+
+private fun transportReply(value: JsReference<Any>?, error: JsReference<Throwable>?): JniTransportReply =
+    js("({ value, error })")
+
+private inline fun transport(body: () -> Any?): JniTransportReply = try {
+    transportReply(body()?.toJsReference(), null)
+} catch (error: Throwable) {
+    transportReply(null, error.toJsReference())
+}
+
+@JsExport fun jniMethod(owner: String, name: String, descriptor: String, isStatic: Boolean): JniTransportReply =
+    transport { lookupIncomingMethod(owner, name, descriptor, isStatic) }
+
+@JsExport fun jniField(owner: String, name: String, descriptor: String, isStatic: Boolean): JniTransportReply =
+    transport { lookupIncomingField(owner, name, descriptor, isStatic) }
+
+@JsExport fun jniInvoke(id: Int, receiver: JsReference<Any>?, arguments: JsReference<Array<Any?>>, nonvirtual: Boolean): JniTransportReply =
+    transport { invokeIncoming(id, receiver?.get(), arguments.get(), nonvirtual) }
+
+@JsExport fun jniConstruct(id: Int, arguments: JsReference<Array<Any?>>): JniTransportReply =
+    transport { constructIncoming(id, arguments.get()) }
+
+@JsExport fun jniRead(id: Int, receiver: JsReference<Any>?): JniTransportReply =
+    transport { readIncomingField(id, receiver?.get()) }
+
+@JsExport fun jniWrite(id: Int, receiver: JsReference<Any>?, value: JsReference<Any>?): JniTransportReply =
+    transport { writeIncomingField(id, receiver?.get(), value?.get()); null }
+
+@JsExport fun jniRequireClass(owner: String): JniTransportReply = transport { requireIncomingClass(owner); null }
+@JsExport fun jniClassOf(receiver: JsReference<Any>): JniTransportReply = transport { incomingClassOf(receiver.get()) }
+@JsExport fun jniInstanceOf(owner: String, receiver: JsReference<Any>?): JniTransportReply = transport { isIncomingInstance(owner, receiver?.get()) }
+@JsExport fun jniAssignable(target: String, source: String): JniTransportReply = transport { isIncomingAssignableFrom(target, source) }
+@JsExport fun jniSame(a: JsReference<Any>?, b: JsReference<Any>?): Boolean = a?.get() === b?.get()
+
+@JsExport fun jniArguments(count: Int): JsReference<Array<Any?>> = arrayOfNulls<Any>(count).toJsReference()
+@JsExport fun jniArgument(arguments: JsReference<Array<Any?>>, index: Int, value: JsReference<Any>?) { arguments.get()[index] = value?.get() }
+@JsExport fun jniArgumentAt(arguments: JsReference<Array<Any?>>, index: Int): JsReference<Any>? = arguments.get()[index]?.toJsReference()
+@JsExport fun jniArgumentCount(arguments: JsReference<Array<Any?>>): Int = arguments.get().size
+@JsExport fun jniInt(value: JsReference<Any>): Int = when (val scalar = value.get()) {
+    is Int -> scalar
+    is Byte -> scalar.toInt()
+    is Short -> scalar.toInt()
+    is Char -> scalar.code
+    else -> error("JNI value is not an integer scalar")
+}
+@JsExport fun jniLong(value: JsReference<Any>): String = (value.get() as Long).toString()
+@JsExport fun jniString(value: JsReference<Any>): String = value.get() as String
+@JsExport fun jniBoolean(value: JsReference<Any>): Boolean = value.get() as Boolean
+@JsExport fun jniNumber(value: JsReference<Any>): Double = when (val scalar = value.get()) {
+    is Float -> scalar.toDouble()
+    is Double -> scalar
+    else -> error("JNI value is not a floating-point scalar")
+}
+@JsExport fun jniPrimitive(descriptor: String, integer: String, number: Double, text: String): JniTransportReply = transport {
+    when (descriptor) {
+        "Z" -> when (integer) { "0" -> false; "1" -> true; else -> error("invalid JNI boolean") }
+        "B" -> integer.toByte()
+        "C" -> integer.toInt().also { require(it in 0..65535) }.toChar()
+        "S" -> integer.toShort()
+        "I" -> integer.toInt()
+        "J" -> integer.toLong()
+        "F" -> number.toFloat()
+        "D" -> number
+        "Ljava/lang/String;" -> text
+        else -> error("unsupported JNI scalar descriptor: $descriptor")
+    }
+}
+@JsExport fun jniErrorClass(error: JsReference<Throwable>): String? = error.get()::class.simpleName
+@JsExport fun jniErrorMessage(error: JsReference<Throwable>): String? = error.get().message
+
+@JsExport fun jniBind(owner: String, name: String, descriptor: String,
+    callback: (JsReference<Any>?, JsReference<Array<Any?>>) -> JniTransportReply): JniTransportReply = transport {
+    registerNative(owner, name, descriptor) { receiver, arguments ->
+        val result = callback(receiver?.toJsReference(), arguments.toJsReference())
+        result.error?.let { throw it.get() }
+        result.value?.get()
+    }
+    null
+}
+@JsExport fun jniRetire(): JniTransportReply = transport { retireNativeRuntime(); null }

package/kotlin/README.md

@@ -31,6 +31,24 @@ traffic in `scripts/debug/peach-swift-lazy-network.sh`.
 - `ExpoSources/`: the expo-modules-core Kotlin DSL port and `PeachExpoRuntime`
   that local Expo Android modules compile against. Owner spec:
   [`specs/peach-kotlin-expo-modules.md`](../../../specs/peach-kotlin-expo-modules.md).
+- `CompilerSources/`: the native member compiler plugin and its JVM service
+  registration. The shared host compiles it into a classes directory cached by
+  the pinned compiler and every plugin source byte. Completed directories publish
+  atomically under `~/.peach/kotlin/compiler-plugins/`; all Kotlin entry paths
+  load that plugin. `JniPlatformSources/` and `JniSources/` supply the shared
+  platform declarations and native invocation runtime for imported modules,
+  pure Kotlin apps and Expo modules.
+  Incoming JNI lookup has stable method and field IDs, declaration-backed private
+  and virtual calls, actual constructors and backing-field access. Native static
+  companion calls preserve the enclosing JVM owner and null receiver. The
+  [binding contract](../../../docs/research/peach/kotlin-native-bindings.md)
+  owns the APIs, holder lifetime and unsupported forms.
+
+App artifact hashes include compiler and library pins, plugin sources, platform
+and runtime sources, app sources and generated glue. The host compiles byte
+snapshots of the hashed app, platform and plugin inputs, preserving their
+original paths in compiler diagnostics. A cached artifact needs no compiler
+process; another app reuses the compiled plugin without rebuilding it.
 
 The dev server compiles every `.kt` source of the app, One's glue for each and
 a generated entry into one Kotlin/Wasm module, held to the Kotlin language

package/package.json

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

package/scripts/dev-server-scanner.ts

@@ -44,8 +44,9 @@ import {
   parseSwiftHostDiscovery,
 } from '../src/swiftDiscoveryContract'
 import { loadOptionalDemoApps, optionalDemoAppsSync } from './optional-demo-registry.ts'
-import type { ConfiguredOneWidget } from '../src/oneWidgetContract'
-import type { AppSettingsSpecifier } from '@peach/globals'
+import type { DiscoveredServer } from '../src/serverDiscoveryContract'
+
+export type { DiscoveredServer } from '../src/serverDiscoveryContract'
 
 // one machine-wide lock. lsof walks every open fd, so overlapping scans from
 // every peach process are what drives the load average through the roof.
@@ -297,37 +298,6 @@ function spawnReaped(
   )
 }
 
-export interface DiscoveredServer {
-  port: number
-  framework: 'metro' | 'expo' | 'vxrn' | 'one' | 'swift' | 'kotlin' | 'unknown'
-  status?: 'compiling' | 'ready' | 'error'
-  projectName?: string
-  bundleUrl: string
-  hmrUrl?: string
-  lastSeen: number
-  iconUrl?: string
-  iconPath?: string
-  /** the app's own brand colour from its manifest, used as the home tile's
-   *  background so the tile reads as that app before its icon decodes and
-   *  when the icon is missing entirely. */
-  primaryColor?: string
-  bundleId?: string
-  widget?: ConfiguredOneWidget | null
-  settingsBundle?: readonly AppSettingsSpecifier[]
-  settingsStorageScopeUrl?: string
-  patched?: boolean
-  /** true when `bundleUrl` was NOT derived from the server's own manifest —
-   *  the manifest probe got no answer, so this is the generic `/index.bundle`
-   *  guess. good enough to LIST the server; never good enough to open it. see
-   *  `manifestState` below for why the two are different answers. */
-  bundleUrlProvisional?: boolean
-  /** absolute cwd of the owning node/bun process — resolved from `lsof -d cwd`
-   *  when the scanner can see the pid. used to auto-attach the project for
-   *  agent sessions without requiring a manual `sootsim agent attach`. */
-  cwd?: string
-  pid?: number
-}
-
 /** how the manifest probe (`GET /` with expo-platform) actually went. the same
  *  three answers `dev-bundle-resolution.ts` uses, deliberately spelled the same
  *  way: a second vocabulary for one question is how the two resolvers drift.
@@ -876,14 +846,18 @@ function makeResult(
 }
 
 function withRuntimeConfig(port: number, bundleUrl: string, projectCwd?: string): string {
+  // bun's realpathSync opens the directory, and another process's cwd can sit on a volume
+  // whose privacy grant blocks that open behind a pending prompt, so only resolve it when
+  // the internal registry has an app to match. a published install has none.
+  const demoApps = optionalDemoAppsSync()
   let physicalProjectCwd: string | undefined
-  if (projectCwd) {
+  if (projectCwd && demoApps.length > 0) {
     try {
       physicalProjectCwd = realpathSync(resolve(projectCwd))
     } catch {}
   }
   const knownApps = physicalProjectCwd
-    ? optionalDemoAppsSync().filter((app) => {
+    ? demoApps.filter((app) => {
         try {
           return realpathSync(resolve(app.dir)) === physicalProjectCwd
         } catch {
@@ -982,13 +956,28 @@ function applyManifest(
             rawLaunchUrl,
             buildLoopbackProbeBaseUrl('http:', manifestRes.hostname, result.port),
           )
-        : rawLaunchUrl
+        : undefined
     if (launchUrl && !result.patched && !isDirectOneBundleUrl(result.bundleUrl)) {
       result.bundleUrl = withRuntimeConfig(result.port, launchUrl, result.cwd)
     }
-    const localIcon = client.icon || client.ios?.icon
-    const remoteIcon = client.iconUrl || client.ios?.iconUrl
-    const rawIcon = localIcon || remoteIcon
+    // expo's withIosIcons.ts selects its base icon as light || dark || tinted.
+    // normalize before publishing iconPath, which local asset probes consume.
+    const iosIcon: unknown = client.ios?.icon
+    const defaultIosIcon =
+      iosIcon && typeof iosIcon === 'object'
+        ? ('light' in iosIcon && iosIcon.light) ||
+          ('dark' in iosIcon && iosIcon.dark) ||
+          ('tinted' in iosIcon && iosIcon.tinted)
+        : iosIcon
+    const icons: unknown[] = [
+      defaultIosIcon,
+      client.icon,
+      client.ios?.iconUrl,
+      client.iconUrl,
+    ]
+    const rawIcon = icons.find(
+      (icon): icon is string => typeof icon === 'string' && icon.trim().length > 0,
+    )
     if (rawIcon) {
       result.iconPath = rawIcon
       let resolvedIconUrl: string | undefined
@@ -1483,7 +1472,8 @@ export async function probePort(
     oneRes &&
     oneRes.statusCode > 0 &&
     oneRes.statusCode < 400 &&
-    /application\/javascript/i.test(oneRes.contentType || '')
+    // one's native dev engine serves text/javascript; metro uses application/javascript.
+    /^(?:application|text)\/javascript(?:\s*;|$)/i.test(oneRes.contentType?.trim() || '')
   ) {
     knownNonPatched.add(port)
     knownOne.add(port)

package/skills/contrast/SKILL.md

@@ -39,7 +39,7 @@ automation, inspecting the render tree, and managing sims.
 | `peach do` | drive the app (tap, type, scroll, swipe, key, reload, …) |
 | `peach wait` | block until the runtime reaches a known state |
 | `peach shell` | drive shell state and simulator chrome |
-| `peach mode` | toggle screenshot, touch indicators, and 3D display modes |
+| `peach mode` | toggle screenshot, touch indicators, the agent indicator, and 3D display modes |
 | `peach device` | inspect or change the live device preset for a sim |
 | `peach network` | inspect live network traffic from the running peach worker |
 | `peach logs` | inspect live console output from the running peach worker |

package/skills/peach-perf/SKILL.md

@@ -62,6 +62,31 @@ indict, remeasure — and every wasted week came from skipping a step.
 
 ## measuring
 
+### record a Performance timeline
+
+`peach perf record` and the devtools Performance tab share one recording.
+Start from either, interact with the app, then Stop from either. The saved
+category choice is used unless the command supplies a preset or category list:
+
+```sh
+peach perf record start --preset default
+peach perf record status --json
+peach perf record stop -o /tmp/app.profile.jsonl.gz
+```
+
+Default records compositor frames, Animated and Reanimated animation runs,
+interactions, network and logs. `--categories frames,animations,react` selects
+specific categories. React attribution and memory cost more than Default;
+Paint Detail changes the renderer's path, so do not compare those frame
+times with a Default run. A recording retains its last five minutes and
+reports gaps when frame coverage is lost. Stop releases its profiling resources.
+Save writes the preview timeline’s gzip JSONL format. Open reads it, plain
+JSONL, or a CLI JSON profile; a `.json` CLI output keeps the JSON form. Both
+forms include frame columns, animation spans, discrete events, missed display
+ticks and optional value samples. Upload shares the profile alongside the
+currently loaded app through the preview uploader. This is a diagnostic capture; use the independent
+presentation evidence below to make smoothness claims.
+
 ### presentation proof must stay outside the simulator
 
 Performance acceptance must not use `peach record`, `liveComposite`,

package/skills/peach-setup/SKILL.md

@@ -74,6 +74,28 @@ debugging or `/peach-test` for writing tests.
   saved sim to reuse. verify the development server and Peach runtime, then
   retry once after fixing the cause.
 
+## choose the runtime
+
+on Apple silicon macOS and Linux x64, recommend trying the optional native
+runtime for faster simulation. it is beta, so the user may run into more issues
+than in the browser. keep the current default unless the user chooses native:
+
+```sh
+peach desktop install
+peach open 8081 --driver desktop
+```
+
+use the app's actual development server port. the Linux desktop app needs a
+desktop session; its `.deb` installer uses `sudo apt-get install`.
+`peach desktop install --native` on Linux installs the standalone headless host
+instead of the desktop app. Intel Mac and Linux arm64 use the browser.
+`peach open 8081 --driver playwright --headed` explicitly opens a browser window.
+pass the selected driver when opening the app in the steps below; installing
+the desktop app alone does not change the saved window preference.
+
+the native runtime renders the simulator. the background service below keeps
+the bridge ready for either runtime and is a separate optional choice.
+
 ## first move
 
 ```sh
@@ -97,11 +119,13 @@ scripts should use `peach open <port-or-url>` so the target is explicit.
 
 if you do not know the port, run `peach open` with no target and pick from
 the detected dev servers. for hosted or unusual targets, pass the URL
-explicitly:
+explicitly. a built bundle file needs no dev server; `peach help open` shows
+the build command for One, Expo and React Native:
 
 ```sh
 peach open 8081                  # load a metro dev server
 peach open https://my-app.local  # load a hosted bundle
+peach open ./dist/ios.js         # load a built production bundle, no dev server
 ```
 
 ## you're done when

package/src/assetCatalogContract.ts

@@ -54,18 +54,46 @@ export interface SfSymbolShaderImage {
   readonly pixels: Uint8Array
 }
 
-// UIImage's ordered monochrome layers and unrounded content bearings.
+// UIImage's ordered monochrome layers and unrounded content bearings. a layer
+// with a variable threshold turns off below it; one without never does.
 export interface SfSymbolImageDrawing {
   referencePointSize: number
   basePointSize: number
   baselineOffsetUnrounded: number
   referenceCanvasSize: readonly [number, number]
   insets: readonly [number, number, number, number]
-  layers: readonly { d: string; opacity: number; eraser: boolean }[]
+  layers: readonly { d: string; opacity: number; eraser: boolean; threshold?: number }[]
+  // an image view reflects a flippable drawing under right to left
+  flippable?: boolean
+  // automatic variable mode draws the value along the paths rather than
+  // turning layers off by threshold
+  variableDraw?: boolean
+  // coreui's own right to left rendition, which replaces the drawing there
+  rightToLeft?: SfSymbolImageDrawing
 }
 
-export interface SfSymbolImageMetadata extends Omit<SfSymbolImageDrawing, 'layers'> {
+// a symbol's palette layers, bottom first, in its monochrome outline's space.
+// level is the palette slot a layer paints in (0 primary, 1 secondary, 2
+// tertiary); a layer with a variable threshold turns off below it, as its
+// image layer does.
+export interface SfSymbolPalette {
+  layers: readonly { d: string; level: number; threshold?: number }[]
+}
+
+export interface SfSymbolImageMetadata extends Omit<
+  SfSymbolImageDrawing,
+  'layers' | 'rightToLeft'
+> {
   layers: readonly { opacity: number; eraser: boolean }[]
+  rightToLeft?: SfSymbolImageMetadata
+}
+
+// the drawing a symbol image view shows in its laid out direction
+export function sfSymbolImageForDirection(
+  drawing: SfSymbolImageMetadata,
+  rightToLeft: boolean,
+): SfSymbolImageMetadata {
+  return rightToLeft && drawing.rightToLeft ? drawing.rightToLeft : drawing
 }
 
 export function sfSymbolImageDimensions(

package/src/auth/shared-session.ts

@@ -11,6 +11,7 @@ import {
 } from 'node:fs'
 import { basename, dirname, join, resolve } from 'node:path'
 import { electronUserDataDir } from '../home-paths.ts'
+import { peachPublicBrand } from '../public-brand.ts'
 
 export type SharedDesktopAuthTeamSummary = {
   id: string
@@ -61,7 +62,7 @@ export function sharedDesktopAuthAccounts(
 
 const SESSION_VERSION = 1 as const
 const SESSION_FILE_ENV = 'SOOTSIM_SHARED_AUTH_FILE'
-const DEFAULT_ORIGIN = 'https://contrast.dev'
+const DEFAULT_ORIGIN = peachPublicBrand.origin
 
 function getBaseDir() {
   const explicit = process.env[SESSION_FILE_ENV]
@@ -186,7 +187,7 @@ export function writeSharedDesktopAuthSession(
     version: SESSION_VERSION,
     token,
     user: session.user ? normalizeUser(session.user) : null,
-    origin: session.origin?.trim() || DEFAULT_ORIGIN,
+    origin: session.origin?.trim() || same?.origin || DEFAULT_ORIGIN,
     source: same?.source ?? session.source,
     updatedAt: session.updatedAt || new Date().toISOString(),
     validatedAt: session.validatedAt ?? same?.validatedAt,

package/src/bridge-contract.ts

@@ -14,6 +14,7 @@ import type {
   SootSimCaptureFilter,
   SootSimExternalAppLifecycleOptions,
   SootSimStorageResetStrategy,
+  TextInputEditCommand,
 } from '@peach/globals'
 
 export type BridgeCommandType =
@@ -67,6 +68,9 @@ export interface WsCommand {
   acquireLock?: boolean
   // bridge:claim — take the lease even when another cli holds it.
   force?: boolean
+  // bridge:list-sims — also report the retained disconnected sims (readyState
+  // closed with disconnectCause) after the live ones. read in bridge-host.
+  includeRetained?: boolean
   // flowStatus — live flow-runner progress payload (see flow-run-store)
   status?: Record<string, unknown>
   code?: string
@@ -79,6 +83,7 @@ export interface WsCommand {
   target?: SootSimAgentActionDetail['target']
   action?: string
   text?: string
+  edit?: TextInputEditCommand
   appearance?: 'light' | 'dark'
   url?: string
   includeVisual?: boolean