sootsim 0.1.83 → 0.1.85

package/src/metro-plugin.ts

@@ -0,0 +1,139 @@
+// sootsim metro plugin — serves the sootsim shell at /__soot/ on metro's server.
+// shell assets come from the active engine runtime under ~/.sootsim/runtimes/,
+// which is fetched by `sootsim runtime install` / `sootsim setup-repo`. resolved
+// per-request so swapping runtimes (`sootsim runtime use <v>`) takes effect
+// without restarting metro.
+//
+// usage in metro.config.js:
+//   const { withSootsim } = require('sootsim/metro')
+//   module.exports = withSootsim(getDefaultConfig(__dirname))
+
+import fs from 'fs'
+import path from 'path'
+import {
+  isRootRuntimeAssetPath,
+  resolveActiveRuntimeRoot,
+  resolveRuntimeFilePath,
+  serveRuntimeFile,
+  SOOTSIM_RUNTIME_MISSING_MESSAGE,
+} from './runtime-assets'
+
+const prefix = '/__soot'
+
+export interface SootsimMetroOptions {
+  bundleUrl?: string
+  enabled?: boolean
+}
+
+// the slice of metro's config we touch — keeps `T` open for whatever
+// shape consumers pass while letting us extend `server.enhanceMiddleware`.
+type MetroConfigWithServer = {
+  server?: {
+    enhanceMiddleware?: (middleware: unknown, server: unknown) => unknown
+    [key: string]: unknown
+  }
+}
+
+export function withSootsim<T extends Record<string, unknown>>(
+  config: T,
+  options: SootsimMetroOptions = {},
+): T {
+  if (options.enabled === false) return config
+
+  const bundleUrl =
+    options.bundleUrl || '/index.bundle?platform=ios&dev=true&hot=true&minify=false'
+
+  const cfgServer = (config as MetroConfigWithServer).server
+  const existingEnhance = cfgServer?.enhanceMiddleware
+
+  const serverConfig = {
+    ...cfgServer,
+    enhanceMiddleware: (metroMiddleware: any, metroServer: any) => {
+      let middleware = metroMiddleware
+      if (existingEnhance) {
+        middleware = existingEnhance(metroMiddleware, metroServer)
+      }
+
+      let connect: any
+      try {
+        connect = require('connect')
+      } catch {
+        console.warn('[sootsim] connect not available')
+        return middleware
+      }
+
+      const server = connect()
+
+      server.use((req: any, res: any, next: any) => {
+        const url = req.url || ''
+        const pathname = url.split('?')[0]
+        const runtimeRoot = resolveActiveRuntimeRoot()
+
+        if (!runtimeRoot) {
+          if (pathname === prefix || pathname === prefix + '/') {
+            res.statusCode = 500
+            res.end(SOOTSIM_RUNTIME_MISSING_MESSAGE)
+            return
+          }
+          next()
+          return
+        }
+
+        // root-relative runtime assets emitted by the shell and engine vite
+        // builds. if a user app has its own /assets/foo request, we only
+        // intercept when that exact file exists in the runtime; otherwise
+        // metro handles it normally.
+        if (isRootRuntimeAssetPath(pathname)) {
+          const fullPath = resolveRuntimeFilePath(runtimeRoot, pathname)
+          if (fullPath) {
+            serveRuntimeFile(res, fullPath)
+            return
+          }
+        }
+
+        // /__soot/* — serve runtime assets
+        if (pathname.startsWith(prefix + '/')) {
+          const fullPath = resolveRuntimeFilePath(
+            runtimeRoot,
+            pathname.slice(prefix.length),
+          )
+          if (fullPath) {
+            serveRuntimeFile(res, fullPath)
+            return
+          }
+        }
+
+        // serve HTML shell for /__soot and extensionless in-shell routes.
+        if (
+          pathname === prefix ||
+          pathname === prefix + '/' ||
+          pathname.startsWith(prefix + '/')
+        ) {
+          const ext = path.extname(pathname)
+          if (!ext) {
+            const htmlPath = path.join(runtimeRoot, 'index.html')
+            let html = fs.readFileSync(htmlPath, 'utf8')
+            html = html.replace(
+              '</head>',
+              `<script>history.replaceState(null,'','${prefix}/?bundle=${encodeURIComponent(bundleUrl)}')</script></head>`,
+            )
+            res.setHeader('content-type', 'text/html')
+            res.end(html)
+            return
+          }
+        }
+
+        next()
+      })
+
+      server.use(middleware)
+
+      console.log(`[sootsim] serving at ${prefix}/`)
+      return server
+    },
+  }
+
+  return { ...config, server: serverConfig } as T
+}
+
+export default withSootsim

package/src/native-dev-bundle-url.ts

@@ -0,0 +1,62 @@
+// canonical entry path for a plain Metro packager that serves no Expo
+// manifest. only used when `/status` confirms `packager-status:running` and
+// the server reports nothing else — never as a guess for a manifest-capable
+// dev server, whose `launchAsset.url` is always the source of truth.
+export const METRO_BUNDLE_PATH =
+  '/index.bundle?platform=ios&dev=true&hot=true&minify=false'
+
+function isAbsoluteHttpUrl(url: string): boolean {
+  return /^https?:\/\//i.test(url)
+}
+
+function isNativeDevBundlePath(pathname: string): boolean {
+  return pathname.endsWith('.bundle')
+}
+
+// opt-in (sootbot preview-recording context only): serve a production
+// minified bundle instead of the default dev=true unminified one. a
+// preview run just records the app — it never needs fast-refresh or dev
+// warnings — and the ~28MB unminified dev bundle cold-(re)boots
+// unreliably on small CI runners (tens of seconds when metro is warm,
+// minutes cold, sometimes past any wait-ready budget). a minified bundle
+// parses/executes far faster and reboots reliably. gated on
+// SOOTSIM_PREVIEW_PROD_BUNDLE so normal interactive `sootsim open` keeps
+// dev=true. app-agnostic: rewrites whatever metro/launchAsset advertised.
+function applyPreviewProdBundle(parsed: URL): void {
+  if (!process.env.SOOTSIM_PREVIEW_PROD_BUNDLE) return
+  parsed.searchParams.set('dev', 'false')
+  parsed.searchParams.set('minify', 'true')
+  // prod bundles have no HMR; keep metro's cache key consistent.
+  if (parsed.searchParams.has('hot')) parsed.searchParams.set('hot', 'false')
+}
+
+export function normalizeNativeDevBundleUrl(bundleUrl: string): string {
+  try {
+    const isAbsolute = isAbsoluteHttpUrl(bundleUrl)
+    const parsed = new URL(bundleUrl, 'http://soot.local')
+    parsed.pathname = parsed.pathname.replace(/\.\.bundle$/, '.bundle')
+    if (!isNativeDevBundlePath(parsed.pathname)) return bundleUrl
+    // do NOT force dev=true or minify=false — metro's dev server already
+    // defaults to dev mode + unminified, and iOS sim's launchAsset URL
+    // omits both params. forcing them gives metro a different cache key
+    // for the same bundle. only the prod-bundle override path
+    // (demo-upload-specs) sets dev=false&minify=true on purpose.
+    // do NOT touch `hot` either. real RN iOS clients load launchAsset.url
+    // verbatim — expo's createBundleUrlSearchParams hardcodes hot=false
+    // (with a `// TODO: Is this still needed?` comment) for every manifest
+    // it emits, and HMR still works on iOS because RN's HMRClient.js
+    // polyfill connects to /hot independently. sootsim's HmrClient is the
+    // same — connection happens via /hot regardless of this query param —
+    // so matching the iOS sim's URL exactly lets metro share its bundle
+    // cache between the two clients (otherwise the 28MB+ bundle rebuilds
+    // twice on first cold metro request).
+    // strip transform.bytecode — metro would return hermes bytecode and our
+    // bundle-loader can only execute plain JS.
+    parsed.searchParams.delete('transform.bytecode')
+    applyPreviewProdBundle(parsed)
+    if (isAbsolute) return parsed.toString()
+    return `${parsed.pathname}${parsed.search}${parsed.hash}`
+  } catch {
+    return bundleUrl
+  }
+}

package/src/native-seam-manifest.ts

@@ -0,0 +1,313 @@
+// native-seam manifest — the canonical registry of upstream packages whose
+// native-module spec files we override.
+//
+// the rule: when a guest bundle imports from one of these packages, vite lets
+// the package's JS resolve from node_modules normally. only the listed
+// `seamBasenames` are redirected to our stub. this keeps the upstream JS layer
+// (hooks, helpers, transforms, listeners) running unchanged.
+//
+// adding a new entry:
+//   1. identify upstream's native-module file (look for files calling
+//      `requireNativeModule`, `TurboModuleRegistry.getEnforced`,
+//      `requireNativeComponent`, or in `src/specs/Native*Module.ts`)
+//   2. write a thin stub at `packages/compat/src/stubs/native-seams/<pkg>.ts`
+//      that exports the same default + named exports upstream's seam file
+//      exports — except the implementation calls into sootsim's engine.
+//   3. append an entry below. the plugin handles the rest.
+//
+// canonical example: react-native-reanimated. see
+//   - `packages/compat/src/stubs/react-native-reanimated.ts` (the seam stub)
+//   - `reanimatedNativeSeamRedirect` in vite-plugin.ts (still hard-coded
+//     because it has package-specific edge cases — fabricUtils,
+//     validate-worklets-version. new entries should use this manifest path
+//     for the simple basename-match case.)
+
+export interface NativeSeamEntry {
+  /**
+   * upstream npm package name. all imports whose importer path includes
+   * `/<pkg>/` are candidates for redirect.
+   */
+  pkg: string
+  /**
+   * basenames of upstream files to redirect. each entry matches the file
+   * name (no extension, no platform suffix like `.ios` / `.android`) of any
+   * upstream module imported transitively from within `pkg`.
+   *
+   * example: if upstream has
+   * `node_modules/expo-notifications/src/NotificationsHandler.ts`, list
+   * `'NotificationsHandler'` here and we'll redirect any import resolving
+   * to that file to our seam stub.
+   */
+  seamBasenames: string[]
+  /**
+   * absolute path to the seam stub. typically
+   * `packages/compat/src/stubs/native-seams/<pkg>.ts` — but a single stub
+   * file may export every native module the package exposes, so the same
+   * `target` can appear in multiple entries if a package has multiple native
+   * modules that share an implementation file.
+   *
+   * authors set this via the `seamPath(<pkg>)` helper below.
+   */
+  target: string
+  /**
+   * notes — short reason this entry exists. shown by the debug logger when
+   * `SOOTSIM_NATIVE_SEAM_DEBUG=1` is set.
+   */
+  notes?: string
+}
+
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const HERE = path.dirname(fileURLToPath(import.meta.url))
+const NATIVE_SEAMS_DIR = path.resolve(HERE, '../../compat/src/stubs/native-seams')
+
+/** resolve a stub path under `packages/compat/src/stubs/native-seams/`. */
+export function seamPath(basename: string): string {
+  return path.resolve(NATIVE_SEAMS_DIR, `${basename}.ts`)
+}
+
+/**
+ * the manifest. agents append entries here during the native-seam migration
+ * (plans/compat-stubs-native-seam-audit.md). keep alphabetical by `pkg` to
+ * minimise merge conflicts.
+ */
+export const NATIVE_SEAM_MANIFEST: NativeSeamEntry[] = [
+  // entries land here during the Phase 1 migration. example shape:
+  //
+  // {
+  //   pkg: 'expo-notifications',
+  //   seamBasenames: [
+  //     'NotificationsHandler',
+  //     'NotificationsEmitter',
+  //     'NotificationScheduler',
+  //     'NotificationCategoriesService',
+  //     'ServerRegistrationModule',
+  //   ],
+  //   target: seamPath('expo-notifications'),
+  //   notes: 'route through engine NotificationBus',
+  // },
+  {
+    pkg: '@metamask/react-native-search-api',
+    // upstream is single-file `index.js`; no sub-imports inside the package
+    // to redirect at the basename layer. listed here for documentation parity
+    // — the bundle-loader's stub-registry routes the package-entry directly to
+    // `stubs/metamask-react-native-search-api.ts`, which pairs the upstream
+    // JS wrapper with the native seam below.
+    seamBasenames: ['index'],
+    target: seamPath('metamask-react-native-search-api'),
+    notes:
+      'iOS CoreSpotlight + NSUserActivity native seam; pure-JS wrapper class lives at stubs/metamask-react-native-search-api.ts',
+  },
+  {
+    pkg: '@ua/react-native-airship',
+    seamBasenames: [
+      // src/NativeRNAirship.ts — the RNAirship TurboModule
+      'NativeRNAirship',
+      // codegen host components (no native backing in sootsim)
+      'RNAirshipEmbeddedViewNativeComponent',
+      'RNAirshipMessageViewNativeComponent',
+    ],
+    target: seamPath('react-native-airship'),
+    notes:
+      'push-notification SAAS — noop the SAAS layer, route banners through NotificationBus',
+  },
+  {
+    pkg: 'react-native-background-fetch',
+    // src/NativeBackgroundFetch.ts — TurboModuleRegistry.getEnforcing('RNBackgroundFetch')
+    seamBasenames: ['NativeBackgroundFetch'],
+    target: seamPath('react-native-background-fetch'),
+    notes:
+      'iOS BGTaskScheduler / Android WorkManager TurboModule — no real scheduler in browser; acknowledge registrations, never fire periodic events',
+  },
+  {
+    pkg: 'expo-asset',
+    // src/ExpoAsset.ts — `requireNativeModule('ExpoAsset')`; only
+    // `downloadAsync` is on the native surface. all the rest (`Asset`,
+    // `AssetHooks`, `AssetSourceResolver`, ...) is pure JS that composes on
+    // top.
+    seamBasenames: ['ExpoAsset'],
+    target: seamPath('expo-asset'),
+    notes:
+      'expo-modules-core requireNativeModule(ExpoAsset) — only downloadAsync; mirror upstream web build (return remote URL)',
+  },
+  {
+    pkg: '@bam.tech/react-native-image-resizer',
+    // upstream is not shipped to most guest bundles via node_modules — it
+    // arrives through the bundle-loader stub-registry which routes the
+    // package entry to `stubs/bam-react-native-image-resizer.ts`. listed here
+    // for documentation parity; vite-path redirect would key on
+    // `NativeImageResizer`.
+    seamBasenames: ['NativeImageResizer'],
+    target: seamPath('bam-react-native-image-resizer'),
+    notes:
+      'ImageResizer TurboModule — browser-side canvas resize implementing the iOS contain/cover/stretch + onlyScaleDown semantics from ios/ImageResizer.mm',
+  },
+  {
+    pkg: 'react-native-adjust',
+    // upstream's `index.js` reads `NativeModules.Adjust` and
+    // `NativeModules.AdjustEventEmitter` directly — there is no NativeAdjust
+    // spec file. listed for documentation parity; the actual seam delivery is
+    // through the bundle-loader stub-registry routing the package entry to
+    // `stubs/react-native-adjust.ts`, which imports the native seam from this
+    // target.
+    seamBasenames: ['index'],
+    target: seamPath('react-native-adjust'),
+    notes:
+      'Adjust attribution SAAS — noop native side (Adjust + AdjustEventEmitter NativeModules), pure-JS classes (AdjustConfig/AdjustEvent/...) live in stubs/react-native-adjust.ts',
+  },
+  {
+    pkg: 'expo-clipboard',
+    // src/ExpoClipboard.ts — `requireNativeModule<ExpoClipboardModule>('ExpoClipboard')`.
+    // upstream also ships `ExpoClipboard.web.ts` (which we mirror); the
+    // redirect catches both `.ts` and `.web.ts` since basenames match.
+    seamBasenames: ['ExpoClipboard'],
+    target: seamPath('expo-clipboard'),
+    notes:
+      'expo-modules-core requireNativeModule(ExpoClipboard) — real navigator.clipboard text + ClipboardItem image; mirrors upstream ExpoClipboard.web.ts',
+  },
+  {
+    pkg: 'expo-font',
+    // src/ExpoFontLoader.ts — `requireNativeModule<ExpoFontLoaderModule>('ExpoFontLoader')`.
+    // we mirror upstream's web variant `ExpoFontLoader.web.ts` (FontFace API
+    // + managed <style id="expo-generated-fonts">).
+    seamBasenames: ['ExpoFontLoader'],
+    target: seamPath('expo-font'),
+    notes:
+      'expo-modules-core requireNativeModule(ExpoFontLoader) — FontFace API registration; mirrors upstream ExpoFontLoader.web.ts',
+  },
+  {
+    pkg: '@react-native-async-storage/async-storage',
+    // src/NativeAsyncStorageModule.ts — TurboModule spec for `RNCAsyncStorage`.
+    // src/RCTAsyncStorage.ts — legacy `NativeModules['RNCAsyncStorage']` resolver.
+    // both basenames redirect to the same seam; upstream's AsyncStorage.ts
+    // imports default from either depending on bridgeless vs paper.
+    seamBasenames: ['NativeAsyncStorageModule', 'RCTAsyncStorage'],
+    target: seamPath('async-storage'),
+    notes:
+      'RNCAsyncStorage TurboModule — localStorage-backed; preserves multiMerge JSON deep-merge semantics from upstream iOS module',
+  },
+  {
+    pkg: 'expo-contacts',
+    // src/ExpoContacts.ts — `requireNativeModule('ExpoContacts')`. seam
+    // exposes the native iOS module shape through sootsim's in-memory store.
+    seamBasenames: ['ExpoContacts'],
+    target: seamPath('expo-contacts'),
+    notes:
+      'expo-modules-core requireNativeModule(ExpoContacts) — granted native iOS-style contacts module backed by an in-memory store',
+  },
+  {
+    pkg: 'expo-calendar',
+    // src/ExpoCalendar.ts — `requireNativeModule('ExpoCalendar')`. seam
+    // exposes the native iOS module shape through sootsim's in-memory store.
+    seamBasenames: ['ExpoCalendar'],
+    target: seamPath('expo-calendar'),
+    notes:
+      'expo-modules-core requireNativeModule(ExpoCalendar) — granted native iOS-style calendar/reminders module backed by an in-memory store',
+  },
+  {
+    pkg: 'expo-media-library',
+    // src/ExpoMediaLibrary.ts — `requireNativeModule('ExpoMediaLibrary')`.
+    // seam mirrors upstream's `ExpoMediaLibrary.web.ts` (refuse permissions
+    // + expose MediaType/SortBy constants).
+    seamBasenames: ['ExpoMediaLibrary'],
+    target: seamPath('expo-media-library'),
+    notes:
+      'expo-modules-core requireNativeModule(ExpoMediaLibrary) — refuses permissions + exposes MediaType/SortBy enums per upstream ExpoMediaLibrary.web.ts',
+  },
+  {
+    pkg: 'expo-file-system',
+    // src/ExpoFileSystem.ts — `requireNativeModule('ExpoFileSystem')`. seam
+    // mirrors upstream's `ExpoFileSystem.web.ts` (warn-not-supported stubs).
+    seamBasenames: ['ExpoFileSystem'],
+    target: seamPath('expo-file-system'),
+    notes:
+      'expo-modules-core requireNativeModule(ExpoFileSystem) — warn-not-supported stubs per upstream ExpoFileSystem.web.ts; no general browser fs access',
+  },
+  {
+    pkg: 'expo-image-picker',
+    // src/ExponentImagePicker.ts — `requireNativeModule('ExponentImagePicker')`.
+    // seam routes selection requests through sootsim's engine-owned image
+    // picker (`SootSim.bridges.imagePicker.pickFromLibrary`) so the same
+    // canvas-rendered iOS picker handles every image-source library.
+    seamBasenames: ['ExponentImagePicker'],
+    target: seamPath('expo-image-picker'),
+    notes:
+      "expo-modules-core requireNativeModule(ExponentImagePicker) — routes through engine SootSim.bridges.imagePicker (shell-worker ImagePickerView) instead of upstream web build's DOM <input type=file>",
+  },
+  {
+    pkg: 'expo-camera',
+    // upstream splits the native surface across two files:
+    //   - src/ExpoCamera.ts        → requireNativeViewManager('ExpoCamera')
+    //   - src/ExpoCameraManager.ts → requireNativeModule('ExpoCamera')
+    // each basename redirects to a different seam — the view component vs.
+    // the imperative module. live preview + capture route through the same
+    // engine `camera-stream` module the built-in sootsim Camera app uses,
+    // so guest <CameraView> sees the same feed as the OS camera app.
+    seamBasenames: ['ExpoCamera'],
+    target: seamPath('expo-camera'),
+    notes:
+      'expo-camera native view manager — host component backed by engine camera-stream (same getUserMedia pipeline as the built-in CameraApp); exposes CameraViewRef methods (takePicture/...) via useImperativeHandle',
+  },
+  {
+    pkg: 'expo-camera',
+    seamBasenames: ['ExpoCameraManager'],
+    target: seamPath('expo-camera-manager'),
+    notes:
+      'expo-camera native module — permissions/feature-gates/codecs/Type/FlashMode constants; barcode scanner is noop (no engine scanner integration)',
+  },
+  {
+    pkg: 'expo-image',
+    // upstream splits the native surface across two files:
+    //   - src/ExpoImage.tsx → requireNativeViewManager('ExpoImage')
+    //   - src/ImageModule.ts → requireNativeModule('ExpoImage')
+    // the view-component seam translates expo-image's prop shape
+    // (contentFit, tintColor, source) onto sootsim's existing
+    // <sootsim-image> host. no new canvas component is needed — sootsim's
+    // image-loader + canvaskit-renderer already handle resizeMode,
+    // tintColor, and onLoad/onError lifecycle.
+    seamBasenames: ['ExpoImage'],
+    target: seamPath('expo-image'),
+    notes:
+      'expo-image native view — thin prop translator onto sootsim-image host (contentFit→resizeMode, tintColor passthrough); upstream Image.tsx + ImageBackground + useImage resolve from node_modules unchanged',
+  },
+  {
+    pkg: 'expo-image',
+    seamBasenames: ['ImageModule'],
+    target: seamPath('expo-image-module'),
+    notes:
+      'expo-image native module — prefetch/loadAsync route through sootsim image-loader; cache controls noop (browser owns HTTP cache); blurhash encode not yet implemented',
+  },
+  {
+    pkg: '@notifee/react-native',
+    // src/NotifeeNativeModule.ts — the base class NotifeeApiModule extends.
+    // upstream also ships .web.ts (returns `{}` from `native`); both
+    // basenames redirect to the same seam — a real implementation that
+    // routes `this.native.*` calls through the engine NotificationBus.
+    seamBasenames: ['NotifeeNativeModule'],
+    target: seamPath('notifee'),
+    notes:
+      'Notifee NotifeeApiModule base class — routes display/cancel/channel/badge calls through engine NotificationBus; tap events fan out via the shared NotifeeJSEventEmitter so onForegroundEvent listeners fire',
+  },
+  {
+    pkg: 'expo-notifications',
+    // five native module spec files, each `requireNativeModule(...)`-shaped.
+    // every one redirects to the same `expo-notifications` seam — see
+    // `stubs/native-seams/expo-notifications.ts` for the union surface.
+    seamBasenames: [
+      // src/NotificationsHandlerModule.ts — presentation policy
+      'NotificationsHandlerModule',
+      // src/NotificationsEmitterModule.ts — last-tap response + listener
+      'NotificationsEmitterModule',
+      // src/NotificationScheduler.ts — schedule / cancel
+      'NotificationScheduler',
+      // src/BadgeModule.ts — app badge count
+      'BadgeModule',
+      // src/ServerRegistrationModule.ts — expo push registration
+      'ServerRegistrationModule',
+    ],
+    target: seamPath('expo-notifications'),
+    notes:
+      'expo-notifications native modules — routes scheduling/badge/installation-id through engine NotificationBus; tap callbacks fan out via the bus event emitters',
+  },
+]