peachsim 0.1.657 → 0.1.658

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "peachsim",
-  "version": "0.1.657",
+  "version": "0.1.658",
   "description": "Vite and Metro plugins, testing drivers, and SDK exports for peach.",
   "author": "Tamagui LLC",
   "license": "SEE LICENSE IN LICENSE",
@@ -84,6 +84,13 @@
       "import": "./dist-lib/metro-production-bundle.mjs",
       "default": "./dist-lib/metro-production-bundle.cjs"
     },
+    "./plist": {
+      "types": "./src/plist.ts",
+      "source": "./src/plist.ts",
+      "bun": "./src/plist.ts",
+      "import": "./dist-lib/plist.mjs",
+      "default": "./dist-lib/plist.cjs"
+    },
     "./native-app-identity": {
       "types": "./src/native-app-identity.ts",
       "source": "./src/native-app-identity.ts",

package/skills/peach-setup/SKILL.md

@@ -113,6 +113,33 @@ peach open https://my-app.local  # load a hosted bundle
 - the compatibility scan's partial, unsupported, unknown, and version-mismatched
   packages have been summarized without treating its aggregate score as a pass/fail gate
 
+## the app's own native code
+
+an app's own native modules and views (a local Expo module, a
+`requireNativeComponent` view written in Swift or Kotlin) have no Peach
+implementation until the app supplies one. when the scan or the running app
+shows one missing (an empty view where content belongs, a "native module not
+found" error), add it to `peach.config.ts` at the app root:
+
+```ts
+import { defineConfig } from 'peachsim/config'
+
+export default defineConfig({
+  nativeModules: { MyAppModule: { file: './peach/my-app-module.ts' } },
+  nativeViews: {
+    RNBalanceLabel: { file: './peach/BalanceLabel.tsx' }, // requireNativeComponent name
+    MyModule_StatusView: { file: './peach/StatusView.tsx' }, // requireNativeView('MyModule', 'StatusView')
+  },
+})
+```
+
+a `nativeViews` file default-exports a component that receives the native
+view's props and renders what it shows on device, using `react-native` and
+`contrast-kit` primitives. a `nativeModules` file exports the module's
+methods, served to `NativeModules` and to Expo's `requireNativeModule`. a
+file may import other project files by relative path, so a large view splits
+into components and helpers. reopen the app to load the change.
+
 ## compatibility feedback requires approval
 
 run `peach compat --json` from the app project root during setup. if the scan

package/src/android-theme.ts

@@ -0,0 +1,167 @@
+// android theme resolution for a pure Kotlin app's window: app styles from the
+// module's res/values over the device's framework styles, resolved the way
+// Resources.Theme does (explicit or dotted parents, `?attr` references,
+// `@color` references). the framework half is generated from the platform's
+// own res/values (scripts/generate/android-framework-themes.ts).
+
+import { parseXml } from './android-xml'
+
+export interface StyleValues {
+  parent: string | null
+  items: Record<string, string>
+}
+
+// a values namespace: the framework's (`android:`) or the app's
+export interface ResourceValues {
+  styles: Record<string, StyleValues>
+  colors: Record<string, string>
+}
+
+export function readResourceValues(
+  files: Array<{ file: string; text: string }>,
+): ResourceValues {
+  const values: ResourceValues = { styles: {}, colors: {} }
+  for (const { file, text } of files) {
+    for (const resources of parseXml(text, file).children) {
+      if (resources.name !== 'resources') continue
+      for (const entry of resources.children) {
+        const name = entry.attributes.name
+        if (!name) continue
+        if (entry.name === 'color') values.colors[name] = entry.text.trim()
+        if (entry.name !== 'style') continue
+        const items: Record<string, string> = {}
+        for (const item of entry.children)
+          if (item.name === 'item' && item.attributes.name)
+            items[item.attributes.name] = item.text.trim()
+        values.styles[name] = { parent: entry.attributes.parent ?? null, items }
+      }
+    }
+  }
+  return values
+}
+
+type Namespace = 'android' | 'app'
+interface StyleRef {
+  namespace: Namespace
+  name: string
+}
+
+export interface ThemeSources {
+  android: ResourceValues
+  app: ResourceValues
+}
+
+// a reference written in `namespace`'s files: `@style/X`, `@android:style/X`
+// or a bare `android:X` parent
+function styleRef(value: string, namespace: Namespace): StyleRef {
+  const match = /^@?(?:(android):)?(?:style\/)?(.+)$/.exec(value)
+  if (!match?.[2]) throw new Error(`unreadable style reference ${value}`)
+  return { namespace: match[1] ? 'android' : namespace, name: match[2] }
+}
+
+// a theme's styles from itself to its root, as Resources.Theme applies them
+function styleChain(
+  theme: StyleRef,
+  sources: ThemeSources,
+): Array<StyleRef & StyleValues> {
+  const chain: Array<StyleRef & StyleValues> = []
+  let current: StyleRef | null = theme
+  while (current) {
+    const style: StyleValues | undefined = sources[current.namespace].styles[current.name]
+    if (!style)
+      throw new Error(
+        `${current.namespace === 'android' ? 'android:' : ''}style/${current.name} is not defined`,
+      )
+    chain.push({ ...current, ...style })
+    if (style.parent !== null)
+      current = style.parent ? styleRef(style.parent, current.namespace) : null
+    else {
+      // a dotted name inherits its prefix in the same namespace
+      const dot = current.name.lastIndexOf('.')
+      current =
+        dot > 0
+          ? { namespace: current.namespace, name: current.name.slice(0, dot) }
+          : null
+    }
+  }
+  return chain
+}
+
+// an attribute as items name it in `namespace`'s files: framework files write
+// bare names, app files write `android:` for framework attributes
+function attributeKey(attribute: string, namespace: Namespace): string {
+  if (namespace === 'android')
+    return attribute.startsWith('android:') ? attribute.slice(8) : attribute
+  return attribute
+}
+
+function lookup(
+  chain: Array<StyleRef & StyleValues>,
+  attribute: { namespace: Namespace; name: string },
+): { value: string; namespace: Namespace } | null {
+  for (const style of chain) {
+    for (const [key, value] of Object.entries(style.items)) {
+      const keyNamespace: Namespace =
+        style.namespace === 'android' || key.startsWith('android:') ? 'android' : 'app'
+      if (
+        keyNamespace === attribute.namespace &&
+        attributeKey(key, keyNamespace) === attribute.name
+      )
+        return { value, namespace: style.namespace }
+    }
+  }
+  return null
+}
+
+function color(value: string): number {
+  const hex = /^#([0-9a-fA-F]{3,8})$/.exec(value)?.[1]
+  if (!hex || ![3, 4, 6, 8].includes(hex.length))
+    throw new Error(`unreadable color ${value}`)
+  const full = hex.length <= 4 ? hex.replace(/./g, '$&$&') : hex
+  const argb = full.length === 6 ? `ff${full}` : full
+  return Number.parseInt(argb, 16) >>> 0
+}
+
+// resolves a framework attribute (`statusBarColor`) of a theme to a value:
+// an ARGB color, a boolean, null for `@null`, or undefined when no style in the
+// chain sets it
+export function resolveThemeAttribute(
+  theme: string,
+  attribute: string,
+  sources: ThemeSources,
+): number | boolean | null | undefined {
+  const chain = styleChain(styleRef(theme, 'app'), sources)
+  const seen = new Set<string>()
+  let found = lookup(chain, { namespace: 'android', name: attribute })
+  while (found) {
+    const { value, namespace } = found
+    if (seen.has(`${namespace}:${value}`))
+      throw new Error(`${theme}: ${attribute} refers to itself`)
+    seen.add(`${namespace}:${value}`)
+    if (value === 'true' || value === 'false') return value === 'true'
+    if (value === '@null') return null
+    if (value.startsWith('#')) return color(value)
+    const attr = /^\?(?:(android):)?(?:attr\/)?(.+)$/.exec(value)
+    if (attr?.[2]) {
+      found = lookup(chain, { namespace: attr[1] ? 'android' : namespace, name: attr[2] })
+      if (!found) throw new Error(`${theme}: ${value} is not set`)
+      continue
+    }
+    const ref = /^@(?:(android):)?color\/(.+)$/.exec(value)
+    if (ref?.[2]) {
+      const colorNamespace: Namespace = ref[1] ? 'android' : namespace
+      // system_ colors are the device's dynamic palette, set at runtime
+      if (colorNamespace === 'android' && ref[2].startsWith('system_'))
+        throw new Error(
+          `${theme}: ${attribute} uses the dynamic color ${ref[2]}, which peach kotlin does not model`,
+        )
+      const next = sources[colorNamespace].colors[ref[2]]
+      if (next === undefined) throw new Error(`${theme}: ${value} is not defined`)
+      found = { value: next, namespace: colorNamespace }
+      continue
+    }
+    throw new Error(`${theme}: ${attribute} has the unsupported value ${value}`)
+  }
+  // unset: the reader's own default applies, as PhoneWindow's getBoolean/getColor do
+  return undefined
+}

package/src/android-xml.ts

@@ -0,0 +1,70 @@
+// the XML an Android module and the platform's resources are written in:
+// elements, single- or double-quoted attributes and text, with comments and
+// declarations skipped. markup outside that (CDATA, a doctype, a malformed
+// tag or an unknown entity) is rejected with its file, never skipped.
+
+export interface XmlElement {
+  name: string
+  attributes: Record<string, string>
+  children: XmlElement[]
+  text: string
+}
+
+const ENTITIES: Record<string, string> = {
+  quot: '"',
+  apos: "'",
+  amp: '&',
+  lt: '<',
+  gt: '>',
+}
+
+const TAG = /<(\/?)([\w:.-]+)((?:\s+[\w:.-]+\s*=\s*(?:"[^"]*"|'[^']*'))*)\s*(\/?)>/y
+const ATTRIBUTE = /([\w:.-]+)\s*=\s*(?:"([^"]*)"|'([^']*)')/g
+
+function decode(value: string, file: string): string {
+  return value.replace(/&(#x[0-9a-fA-F]+|#\d+|\w+);/g, (_match, entity: string) => {
+    if (entity.startsWith('#x'))
+      return String.fromCodePoint(Number.parseInt(entity.slice(2), 16))
+    if (entity.startsWith('#'))
+      return String.fromCodePoint(Number.parseInt(entity.slice(1), 10))
+    const character = ENTITIES[entity]
+    if (character === undefined) throw new Error(`${file}: unknown entity &${entity};`)
+    return character
+  })
+}
+
+export function parseXml(text: string, file: string): XmlElement {
+  const root: XmlElement = { name: '#document', attributes: {}, children: [], text: '' }
+  const stack = [root]
+  const body = text.replace(/<!--[\s\S]*?-->/g, '').replace(/<\?[\s\S]*?\?>/g, '')
+  let index = 0
+  while (index < body.length) {
+    const open = body.indexOf('<', index)
+    const content = body.slice(index, open === -1 ? body.length : open)
+    const parent = stack.at(-1)
+    if (parent && content.trim()) parent.text += decode(content, file)
+    if (open === -1) break
+    TAG.lastIndex = open
+    const match = TAG.exec(body)
+    if (!match)
+      throw new Error(`${file}: unreadable markup at ${body.slice(open, open + 40)}`)
+    index = TAG.lastIndex
+    const [, closing, name, rawAttributes, selfClosing] = match
+    if (!name) continue
+    if (closing) {
+      const element = stack.pop()
+      if (element?.name !== name)
+        throw new Error(`${file}: </${name}> closes <${element?.name}>`)
+      continue
+    }
+    const attributes: Record<string, string> = {}
+    for (const [, key, double, single] of (rawAttributes ?? '').matchAll(ATTRIBUTE))
+      if (key) attributes[key] = decode(double ?? single ?? '', file)
+    const element: XmlElement = { name, attributes, children: [], text: '' }
+    stack.at(-1)?.children.push(element)
+    if (!selfClosing) stack.push(element)
+  }
+  if (stack.length !== 1)
+    throw new Error(`${file}: <${stack.at(-1)?.name}> is never closed`)
+  return root
+}

package/src/bridge-contract-input.ts

@@ -9,6 +9,7 @@ import type {
   SemanticWaitOptions,
   SimSemanticQuery,
   SimSemanticResolveSelector,
+  SimSemanticTargetSelector,
   SimSemanticSelector,
   SimStateOptions,
 } from './bridge-contract'
@@ -396,7 +397,15 @@ function semanticResolveSelector(
   return validationFailure(path, 'must select testID or text')
 }
 
-export function parseSemanticResolveSelector(value: unknown): SimSemanticResolveSelector {
+export function parseSemanticResolveSelector(value: unknown): SimSemanticTargetSelector {
+  const selector = recordValue(value, 'selector')
+  if (selector.nodeId !== undefined) {
+    const nodeId = numberValue(selector.nodeId, 'selector.nodeId')
+    if (!Number.isSafeInteger(nodeId)) {
+      return validationFailure('selector.nodeId', 'must be an integer')
+    }
+    return { nodeId }
+  }
   return semanticResolveSelector(value, 'selector')
 }
 

package/src/bridge-contract.ts

@@ -104,7 +104,7 @@ export interface WsCommand {
   stateOptions?: SimStateOptions
   // query / resolve — structured visible-tree reads and selector geometry
   query?: SimSemanticQuery
-  selector?: SimSemanticResolveSelector
+  selector?: SimSemanticTargetSelector
   // reset — two-tier app state wipe
   resetOptions?: ResetOptions
   // camera — fixture injection into the host camera pipeline
@@ -505,10 +505,16 @@ export interface SimSemanticQueryResult {
 
 export type SimSemanticResolveSelector = { testID: string } | { text: string }
 
+// what `resolve` may name: a selector, or a node a tree read already returned,
+// so a caller that picked one node taps that node and never re-searches.
+export type SimSemanticTargetSelector = SimSemanticResolveSelector | { nodeId: number }
+
 export interface SimSemanticResolveResult {
   match: SimSemanticNode
   target: SimSemanticNode
   point: { x: number; y: number }
+  // the screen a finger can reach, for refusing an offscreen point.
+  viewport: { width: number; height: number }
 }
 
 // ---------------------------------------------------------------------------

package/src/config.ts

@@ -17,12 +17,18 @@ export type ModuleResolution =
 
 export type NativeModuleResolution = ModuleResolution | Record<string, any> // direct native module object for non-url configs
 
+// an app's own native view, keyed by its `requireNativeComponent` name or, for
+// an expo module view, `Module_View` (`Module` for a module's only view). the
+// file default-exports the component that renders in its place with its props.
+export type NativeViewResolution = { file: string }
+
 export interface PeachConfig<Settings extends Record<string, any> = Record<string, any>> {
   // host-only engine selection. omitted means the current stable runtime.
   runtimeVersion?: string
   modules?: Record<string, ModuleResolution>
   turboModules?: Record<string, NativeModuleResolution>
   nativeModules?: Record<string, NativeModuleResolution>
+  nativeViews?: Record<string, NativeViewResolution>
   env?: Record<string, string>
   // generic per-sim network rewrites for the guest app's runtime fetches.
   // `remap` keys/values are `host:port` (or bare `host`) — a tenant fetch whose
@@ -67,6 +73,7 @@ export function hasPeachConfig<
     hasOwnKeys(config.modules as Record<string, unknown> | undefined) ||
     hasOwnKeys(config.turboModules as Record<string, unknown> | undefined) ||
     hasOwnKeys(config.nativeModules as Record<string, unknown> | undefined) ||
+    hasOwnKeys(config.nativeViews) ||
     hasOwnKeys(config.env as Record<string, unknown> | undefined) ||
     hasOwnKeys(config.network?.remap as Record<string, unknown> | undefined) ||
     hasOwnKeys(config.settings as Record<string, unknown> | undefined) ||
@@ -92,6 +99,7 @@ export function mergePeachConfig<
       ...(base.nativeModules || {}),
       ...(override.nativeModules || {}),
     },
+    nativeViews: { ...(base.nativeViews || {}), ...(override.nativeViews || {}) },
     env: { ...(base.env || {}), ...(override.env || {}) },
     network: {
       remap: { ...(base.network?.remap || {}), ...(override.network?.remap || {}) },