rnxsim 0.1.402 → 0.1.404

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rnxsim",
-  "version": "0.1.402",
+  "version": "0.1.404",
   "description": "Vite and Metro plugins, testing drivers, and SDK exports for rnx.",
   "author": "Tamagui LLC",
   "license": "SEE LICENSE IN LICENSE",
@@ -45,6 +45,13 @@
       "import": "./dist-lib/metro-production-bundle.mjs",
       "default": "./dist-lib/metro-production-bundle.cjs"
     },
+    "./metro-fingerprint-registry": {
+      "types": "./src/metro-fingerprint-registry.ts",
+      "source": "./src/metro-fingerprint-registry.ts",
+      "bun": "./src/metro-fingerprint-registry.ts",
+      "import": "./dist-lib/metro-fingerprint-registry.mjs",
+      "default": "./dist-lib/metro-fingerprint-registry.cjs"
+    },
     "./react-native-host-modules": {
       "types": "./src/react-native-host-modules.ts",
       "source": "./src/react-native-host-modules.ts",

package/src/bridge-contract.ts

@@ -37,6 +37,7 @@ export type BridgeCommandType =
   | 'resolve'
   | 'reset'
   | 'camera'
+  | 'diagnostics'
 
 export interface WsCommand {
   id: string | number
@@ -86,6 +87,9 @@ export interface WsCommand {
   resetOptions?: ResetOptions
   // camera — fixture injection into the host camera pipeline
   camera?: CameraCommand
+  // diagnostics — read-only engine debug state: channel recording, the sheet /
+  // portal / boundary finders, and the recent event ring.
+  diagnostics?: DiagnosticsOptions
 }
 
 // ---------------------------------------------------------------------------
@@ -258,6 +262,22 @@ export interface SemanticWaitResult {
 // state — one round-trip situational awareness
 // ---------------------------------------------------------------------------
 
+export interface DiagnosticsOptions {
+  // debug channels to record from this point on. omitted leaves recording as
+  // it is; an empty list stops recording.
+  channels?: readonly string[]
+  find?: 'sheets' | 'portals' | 'boundaries'
+  recentChannel?: string
+  recentLimit?: number
+}
+
+export interface DiagnosticsResult {
+  channels: string[]
+  runtime: unknown
+  found: unknown[] | null
+  events: unknown[]
+}
+
 export interface SimStateOptions {
   // omit a section an agent does not need this turn
   screenshot?: boolean

package/src/capture-contract.ts

@@ -162,6 +162,7 @@ export interface RnxRasterRegionTree {
     nodeId: number
     parentNodeId: number | null
     type: string
+    text?: string | null
     style: Record<string, unknown>
     layout: RnxCaptureRect
     frame: RnxCaptureRect | null
@@ -178,6 +179,12 @@ export function selectRnxRasterNodeIds(tree: RnxRasterRegionTree): Set<number> {
     if (!visibleFrame || visibleFrame.width <= 0 || visibleFrame.height <= 0) continue
     if (
       node.type === 'masked-view' ||
+      (node.type === 'text' &&
+        typeof node.text === 'string' &&
+        (/\p{Emoji_Presentation}/u.test(node.text) ||
+          /\uFE0F|\u200D|\u20E3|\p{Emoji_Modifier}|\p{Regional_Indicator}/u.test(
+            node.text,
+          ))) ||
       node.style._liquidGlass !== undefined ||
       node.style._liquidGlassEdge !== undefined
     ) {
@@ -293,6 +300,7 @@ export function rnxCaptureRasterRegions(
       nodeId: node.nodeId,
       parentNodeId: node.parentNodeId,
       type: node.type,
+      text: node.text,
       style: node.style.resolved,
       layout: node.layout.local,
       frame: node.layout.frame,

package/src/cloud-contract.ts

@@ -22,6 +22,7 @@ export const RNX_CLOUD_COMMAND_TYPES = Object.freeze([
   'tap',
   'longPress',
   'memory',
+  'diagnostics',
 ]) satisfies readonly BridgeCommandType[]
 
 const RNX_CLOUD_COMMAND_TYPE_SET = new Set<string>(RNX_CLOUD_COMMAND_TYPES)

package/src/metro-fingerprint-registry.ts

@@ -0,0 +1,302 @@
+export const RNX_METRO_FINGERPRINT_SCHEMA_VERSION = 2
+export const RNX_METRO_FINGERPRINT_POINTER_PATH = '/compile/metro-fingerprints.json'
+export const RNX_METRO_FINGERPRINT_MAX_POINTER_BYTES = 16 * 1024
+export const RNX_METRO_FINGERPRINT_MAX_PAYLOAD_BYTES = 8 * 1024 * 1024
+
+export type RNXMetroFingerprintPlatform = 'ios' | 'android'
+
+export interface RNXMetroFingerprintAtom {
+  key: string
+  exports: string[]
+  literals: string[]
+  dependencyArity: number
+  factoryDigest: string
+}
+
+export interface RNXMetroFingerprintNode {
+  atom: number
+  internalDependencies: Array<{ position: number; node: number }>
+  landmarkPath?: string
+}
+
+export interface RNXMetroFingerprintRoot {
+  node: number
+}
+
+export interface RNXMetroFingerprintTemplate {
+  packageName: string
+  packageVersion: string
+  sourceIntegrity: string
+  profile: string
+  platform: RNXMetroFingerprintPlatform
+  nodes: RNXMetroFingerprintNode[]
+  roots: RNXMetroFingerprintRoot[]
+}
+
+export interface RNXMetroFingerprintCandidate {
+  template: number
+  root: number
+}
+
+export interface RNXMetroFingerprintRegistry {
+  schemaVersion: typeof RNX_METRO_FINGERPRINT_SCHEMA_VERSION
+  revision: string
+  atoms: RNXMetroFingerprintAtom[]
+  templates: RNXMetroFingerprintTemplate[]
+  candidatesByFactoryDigest: Record<string, RNXMetroFingerprintCandidate[]>
+  candidatesByDiscriminator: Record<string, RNXMetroFingerprintCandidate[]>
+}
+
+export interface RNXMetroFingerprintPointer {
+  schemaVersion: typeof RNX_METRO_FINGERPRINT_SCHEMA_VERSION
+  revision: string
+  integrity: string
+  bytes: number
+  payloadUrl: string
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+function isSha256(value: unknown): value is string {
+  return typeof value === 'string' && /^[a-f0-9]{64}$/.test(value)
+}
+
+function readStringArray(value: unknown): string[] | null {
+  if (!Array.isArray(value) || !value.every((entry) => typeof entry === 'string')) {
+    return null
+  }
+  const entries = [...value]
+  if (
+    new Set(entries).size !== entries.length ||
+    entries.some((entry, index) => index > 0 && entries[index - 1] >= entry)
+  ) {
+    return null
+  }
+  return entries
+}
+
+export function parseRNXMetroFingerprintPointer(
+  value: unknown,
+): RNXMetroFingerprintPointer | null {
+  if (!isRecord(value)) return null
+  const { schemaVersion, revision, integrity, bytes, payloadUrl } = value
+  if (
+    schemaVersion !== RNX_METRO_FINGERPRINT_SCHEMA_VERSION ||
+    !isSha256(revision) ||
+    !isSha256(integrity) ||
+    typeof bytes !== 'number' ||
+    !Number.isSafeInteger(bytes) ||
+    bytes < 1 ||
+    typeof payloadUrl !== 'string' ||
+    payloadUrl.length === 0
+  ) {
+    return null
+  }
+  return { schemaVersion, revision, integrity, bytes, payloadUrl }
+}
+
+export function parseRNXMetroFingerprintRegistry(
+  value: unknown,
+): RNXMetroFingerprintRegistry | null {
+  if (!isRecord(value)) return null
+  const { schemaVersion, revision } = value
+  if (
+    schemaVersion !== RNX_METRO_FINGERPRINT_SCHEMA_VERSION ||
+    !isSha256(revision) ||
+    !Array.isArray(value.atoms) ||
+    !Array.isArray(value.templates) ||
+    !isRecord(value.candidatesByFactoryDigest) ||
+    !isRecord(value.candidatesByDiscriminator)
+  ) {
+    return null
+  }
+
+  const atoms: RNXMetroFingerprintAtom[] = []
+  for (const atomValue of value.atoms) {
+    if (!isRecord(atomValue)) return null
+    const exports = readStringArray(atomValue.exports)
+    const literals = readStringArray(atomValue.literals)
+    if (
+      typeof atomValue.key !== 'string' ||
+      atomValue.key.length === 0 ||
+      !exports ||
+      !literals ||
+      typeof atomValue.dependencyArity !== 'number' ||
+      !Number.isSafeInteger(atomValue.dependencyArity) ||
+      atomValue.dependencyArity < 0 ||
+      !isSha256(atomValue.factoryDigest)
+    ) {
+      return null
+    }
+    atoms.push({
+      key: atomValue.key,
+      exports,
+      literals,
+      dependencyArity: atomValue.dependencyArity,
+      factoryDigest: atomValue.factoryDigest,
+    })
+  }
+
+  const templates: RNXMetroFingerprintTemplate[] = []
+  for (const templateValue of value.templates) {
+    if (
+      !isRecord(templateValue) ||
+      typeof templateValue.packageName !== 'string' ||
+      templateValue.packageName.length === 0 ||
+      typeof templateValue.packageVersion !== 'string' ||
+      templateValue.packageVersion.length === 0 ||
+      !isSha256(templateValue.sourceIntegrity) ||
+      typeof templateValue.profile !== 'string' ||
+      templateValue.profile.length === 0 ||
+      (templateValue.platform !== 'ios' && templateValue.platform !== 'android') ||
+      !Array.isArray(templateValue.nodes) ||
+      templateValue.nodes.length === 0 ||
+      !Array.isArray(templateValue.roots) ||
+      templateValue.roots.length === 0
+    ) {
+      return null
+    }
+    const nodes: RNXMetroFingerprintNode[] = []
+    for (const nodeValue of templateValue.nodes) {
+      if (
+        !isRecord(nodeValue) ||
+        typeof nodeValue.atom !== 'number' ||
+        !Number.isSafeInteger(nodeValue.atom) ||
+        nodeValue.atom < 0 ||
+        nodeValue.atom >= atoms.length ||
+        !Array.isArray(nodeValue.internalDependencies) ||
+        (nodeValue.landmarkPath !== undefined &&
+          (typeof nodeValue.landmarkPath !== 'string' ||
+            nodeValue.landmarkPath.length === 0))
+      ) {
+        return null
+      }
+      const internalDependencies: Array<{ position: number; node: number }> = []
+      const positions = new Set<number>()
+      for (const edgeValue of nodeValue.internalDependencies) {
+        if (
+          !isRecord(edgeValue) ||
+          typeof edgeValue.position !== 'number' ||
+          !Number.isSafeInteger(edgeValue.position) ||
+          edgeValue.position < 0 ||
+          positions.has(edgeValue.position) ||
+          typeof edgeValue.node !== 'number' ||
+          !Number.isSafeInteger(edgeValue.node) ||
+          edgeValue.node < 0 ||
+          edgeValue.node >= templateValue.nodes.length
+        ) {
+          return null
+        }
+        positions.add(edgeValue.position)
+        internalDependencies.push({
+          position: edgeValue.position,
+          node: edgeValue.node,
+        })
+      }
+      internalDependencies.sort((left, right) => left.position - right.position)
+      nodes.push({
+        atom: nodeValue.atom,
+        internalDependencies,
+        ...(typeof nodeValue.landmarkPath === 'string'
+          ? { landmarkPath: nodeValue.landmarkPath }
+          : {}),
+      })
+    }
+    const roots: RNXMetroFingerprintRoot[] = []
+    for (const rootValue of templateValue.roots) {
+      if (
+        !isRecord(rootValue) ||
+        typeof rootValue.node !== 'number' ||
+        !Number.isSafeInteger(rootValue.node) ||
+        rootValue.node < 0 ||
+        rootValue.node >= nodes.length ||
+        !nodes[rootValue.node].landmarkPath
+      ) {
+        return null
+      }
+      roots.push({ node: rootValue.node })
+    }
+    templates.push({
+      packageName: templateValue.packageName,
+      packageVersion: templateValue.packageVersion,
+      sourceIntegrity: templateValue.sourceIntegrity,
+      profile: templateValue.profile,
+      platform: templateValue.platform,
+      nodes,
+      roots,
+    })
+  }
+
+  const candidatesByFactoryDigest: Record<string, RNXMetroFingerprintCandidate[]> = {}
+  for (const [factoryDigest, candidateValues] of Object.entries(
+    value.candidatesByFactoryDigest,
+  )) {
+    if (!isSha256(factoryDigest) || !Array.isArray(candidateValues)) return null
+    const candidates: RNXMetroFingerprintCandidate[] = []
+    for (const candidateValue of candidateValues) {
+      if (
+        !isRecord(candidateValue) ||
+        typeof candidateValue.template !== 'number' ||
+        !Number.isSafeInteger(candidateValue.template) ||
+        candidateValue.template < 0 ||
+        candidateValue.template >= templates.length ||
+        typeof candidateValue.root !== 'number' ||
+        !Number.isSafeInteger(candidateValue.root) ||
+        candidateValue.root < 0 ||
+        candidateValue.root >= templates[candidateValue.template].roots.length
+      ) {
+        return null
+      }
+      const template = templates[candidateValue.template]
+      const root = template.roots[candidateValue.root]
+      if (atoms[template.nodes[root.node].atom].factoryDigest !== factoryDigest) {
+        return null
+      }
+      candidates.push({
+        template: candidateValue.template,
+        root: candidateValue.root,
+      })
+    }
+    candidatesByFactoryDigest[factoryDigest] = candidates
+  }
+
+  const candidatesByDiscriminator: Record<string, RNXMetroFingerprintCandidate[]> = {}
+  for (const [discriminator, candidateValues] of Object.entries(
+    value.candidatesByDiscriminator,
+  )) {
+    if (!/^(?:e|l|ea|la|el|ela):[a-f0-9]{16}$/.test(discriminator)) return null
+    if (!Array.isArray(candidateValues) || candidateValues.length === 0) return null
+    const candidates: RNXMetroFingerprintCandidate[] = []
+    for (const candidateValue of candidateValues) {
+      if (
+        !isRecord(candidateValue) ||
+        typeof candidateValue.template !== 'number' ||
+        !Number.isSafeInteger(candidateValue.template) ||
+        candidateValue.template < 0 ||
+        candidateValue.template >= templates.length ||
+        typeof candidateValue.root !== 'number' ||
+        !Number.isSafeInteger(candidateValue.root) ||
+        candidateValue.root < 0 ||
+        candidateValue.root >= templates[candidateValue.template].roots.length
+      ) {
+        return null
+      }
+      candidates.push({
+        template: candidateValue.template,
+        root: candidateValue.root,
+      })
+    }
+    candidatesByDiscriminator[discriminator] = candidates
+  }
+
+  return {
+    schemaVersion,
+    revision,
+    atoms,
+    templates,
+    candidatesByFactoryDigest,
+    candidatesByDiscriminator,
+  }
+}

package/src/metro-plugin.ts

@@ -24,8 +24,11 @@ import {
   isReplacementModuleRequestUrl,
 } from './host/replacement-module-handler'
 import {
-  createRNXMetroModulePathsFooter,
+  appendRNXMetroModuleIdentityFooter,
+  RNX_METRO_MODULE_IDENTITY_VERSION,
+  toRNXDevelopmentBundleUrl,
   toRNXProductionBundleUrl,
+  type RNXMetroModuleIdentityMetadata,
 } from './metro-production-bundle'
 import {
   isRootRuntimeAssetPath,
@@ -36,13 +39,21 @@ import {
 } from './runtime-assets'
 
 const prefix = '/__soot'
-export { toRNXProductionBundleUrl }
+export { toRNXDevelopmentBundleUrl, toRNXProductionBundleUrl }
+
+type MetroSerializerModule = {
+  path: string
+  dependencies?: ReadonlyMap<
+    string,
+    {
+      absolutePath?: string
+      data?: { name?: string }
+    }
+  >
+}
 
 type MetroSerializerGraph = {
-  dependencies?: ReadonlyMap<unknown, { path: string }>
-  transformOptions?: {
-    dev?: boolean
-  }
+  dependencies?: ReadonlyMap<unknown, MetroSerializerModule>
 }
 
 type MetroSerializerOptions = {
@@ -70,6 +81,12 @@ export interface RNXMetroOptions {
    * bundle the app ships and rnx can load it directly.
    */
   productionBundles?: boolean
+  /**
+   * append the `moduleId -> sourcePath` identity footer to every development
+   * bundle. resolution and transforms stay ordinary, while Metro keeps verbose
+   * module names and its source map.
+   */
+  developmentBundles?: boolean
 }
 
 // the slice of metro's config we touch — keeps `T` open for whatever
@@ -130,11 +147,10 @@ function createMetroDefaultSerializer(projectRoot: string): MetroSerializer {
   }
 }
 
-// the only thing rnx adds to a production bundle. Metro drops the fourth `__d`
-// argument when `dev` is false, so nothing in the artifact names its modules;
-// the engine's `__d` trap needs those names to swap react, react-native, and
-// the native-seam packages for its own. the footer restores exactly that, and
-// is inert everywhere else — on a device it assigns one unused global.
+// the only thing rnx adds to an ordinary Metro bundle. production needs the
+// footer because Metro drops the fourth `__d` argument when `dev` is false;
+// development keeps that verbose name and receives the same identity without
+// changing resolution, transforms, or the trailing source map.
 function appendRNXModulePaths(
   result: MetroSerializerResult,
   graph: MetroSerializerGraph,
@@ -144,9 +160,7 @@ function appendRNXModulePaths(
   const dependencies = graph.dependencies
   const createModuleId = options.createModuleId
   if (!dependencies || !createModuleId) {
-    throw new Error(
-      'rnxsim: Metro did not provide the production module graph and createModuleId',
-    )
+    throw new Error('rnxsim: Metro did not provide the module graph and createModuleId')
   }
 
   const modulePaths: Record<string, string> = {}
@@ -156,20 +170,56 @@ function appendRNXModulePaths(
       .replaceAll(path.sep, '/')
   }
   if (Object.keys(modulePaths).length !== dependencies.size) {
-    throw new Error('rnxsim: production module IDs were not unique')
+    throw new Error('rnxsim: bundle module IDs were not unique')
   }
 
-  const footer = createRNXMetroModulePathsFooter(modulePaths)
+  const specifiersByModuleId = new Map<string, Set<string>>()
+  for (const module of dependencies.values()) {
+    for (const [dependencyKey, dependency] of module.dependencies ?? []) {
+      const specifier = dependency.data?.name ?? dependencyKey
+      if (
+        specifier.length === 0 ||
+        specifier.startsWith('.') ||
+        specifier.startsWith('/') ||
+        typeof dependency.absolutePath !== 'string'
+      ) {
+        continue
+      }
+      const moduleId = String(createModuleId(dependency.absolutePath))
+      if (!Object.prototype.hasOwnProperty.call(modulePaths, moduleId)) continue
+      const found = specifiersByModuleId.get(moduleId)
+      if (found) found.add(specifier)
+      else specifiersByModuleId.set(moduleId, new Set([specifier]))
+    }
+  }
+  const logicalSpecifiers = Object.fromEntries(
+    [...specifiersByModuleId]
+      .sort(([left], [right]) => Number(left) - Number(right))
+      .map(([moduleId, specifiers]) => [moduleId, [...specifiers].sort()]),
+  )
+  const identity: RNXMetroModuleIdentityMetadata = {
+    version: RNX_METRO_MODULE_IDENTITY_VERSION,
+    identitySource: 'rnx-plugin',
+    modulePaths,
+    logicalSpecifiers,
+  }
   return typeof result === 'string'
-    ? result + footer
-    : { ...result, code: result.code + footer }
+    ? appendRNXMetroModuleIdentityFooter(result, identity)
+    : { ...result, code: appendRNXMetroModuleIdentityFooter(result.code, identity) }
 }
 
 export function withRNX<T extends Record<string, unknown>>(
   config: T,
   options: RNXMetroOptions = {},
 ): T {
-  if (!options.devServer && !options.open && !options.productionBundles) return config
+  if (
+    !options.devServer &&
+    !options.open &&
+    !options.productionBundles &&
+    !options.developmentBundles
+  ) {
+    return config
+  }
 
   const cfgProjectRoot = (config as MetroConfigWithServer).projectRoot || process.cwd()
   const appName = resolveRnxDesktopAppName(options.open, cfgProjectRoot)
@@ -191,7 +241,7 @@ export function withRNX<T extends Record<string, unknown>>(
   const existingSerializer = cfgSerializer?.customSerializer
   let productionConfig: Partial<MetroConfigWithServer> = {}
 
-  if (options.productionBundles) {
+  if (options.productionBundles || options.developmentBundles) {
     let defaultSerializer: MetroSerializer | undefined
 
     productionConfig = {
@@ -212,10 +262,9 @@ export function withRNX<T extends Record<string, unknown>>(
             graph,
             serializerOptions,
           )
-          // every production build gets the footer, so the artifact the app
-          // already ships is the one rnx loads. a development build keeps
-          // Metro's fourth `__d` argument and needs nothing.
-          return graph.transformOptions?.dev === false
+          const dev = serializerOptions.dev
+          return (dev === false && options.productionBundles === true) ||
+            (dev === true && options.developmentBundles === true)
             ? appendRNXModulePaths(result, graph, serializerOptions, cfgProjectRoot)
             : result
         },