peachsim 0.1.527

package/src/native-seam-manifest.ts

@@ -0,0 +1,341 @@
+// 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 fs from 'node:fs'
+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/`.
+ * resolves to `.tsx` when only that exists (JSX-bearing seams like
+ * expo-image, react-native-webview). preferred order: `.ts`, `.tsx`. */
+export function seamPath(basename: string): string {
+  const ts = path.resolve(NATIVE_SEAMS_DIR, `${basename}.ts`)
+  if (fs.existsSync(ts)) return ts
+  const tsx = path.resolve(NATIVE_SEAMS_DIR, `${basename}.tsx`)
+  if (fs.existsSync(tsx)) return tsx
+  // fall through to .ts so vite's "Could not load" error names the .ts
+  // path the author probably intended to create, instead of silently
+  // pointing at something that doesn't exist with no extension.
+  return ts
+}
+
+/**
+ * the manifest. agents append entries here during the native-seam migration
+ * (plans/sootsim/compat/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-apple-authentication',
+    // src/ExpoAppleAuthenticationButton.ts is the package's native-view
+    // boundary. direct-compiled apps do not run the fetched-bundle lazy seam
+    // loader, so route that boundary to the same view manager implementation.
+    seamBasenames: ['ExpoAppleAuthenticationButton'],
+    target: seamPath('expo-apple-authentication-view'),
+    notes:
+      'ASAuthorizationAppleIDButton native view — render the system button surface while upstream AppleAuthenticationButton.tsx remains unchanged',
+  },
+  {
+    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',
+  },
+  // expo-calendar and expo-contacts deliberately have NO entry here. expo
+  // renamed their native module ids across majors (`ExpoCalendar` →
+  // `CalendarNext`, `ExpoContacts` → `ExpoContactsNext`) and kept the old
+  // ids serving the `/legacy` subpath, so one package now asks for two
+  // different native modules depending on which entry point you import.
+  // basename matching cannot tell `src/ExpoCalendar.ts` from
+  // `src/legacy/ExpoCalendar.ts`, so a redirect here forces the legacy API
+  // onto the class-based seam, whose methods throw.
+  //
+  // registering by module NAME instead is what keeps old and new package
+  // versions both working: ../../compat/src/stubs/expo-{calendar,contacts}-register.ts
+  // installs every id either version asks for, and upstream's own
+  // `requireNativeModule` picks the right one per entry point. a file
+  // redirect can only match one layout, so it breaks the versions it was
+  // not written for.
+  {
+    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',
+  },
+  {
+    pkg: 'react-native-enriched-markdown',
+    seamBasenames: [
+      'EnrichedMarkdownTextNativeComponent',
+      'EnrichedMarkdownNativeComponent',
+      'EnrichedMarkdownTextInputNativeComponent',
+    ],
+    target: seamPath('react-native-enriched-markdown'),
+    notes:
+      'generated Fabric markdown host components; upstream Streamdown/enriched-markdown JS runs unchanged',
+  },
+]

package/src/playwright-host-log.ts

@@ -0,0 +1,16 @@
+// the playwright driver writes its browser-host stderr to a tmpdir log, and
+// that log carries the only hardware-WebGL proof the hosted recorder accepts.
+// the driver names the file and the recorder scans for it, so the prefix lives
+// here rather than as a literal in both. it was already renamed once
+// (sootsim- -> rnx-) without the recorder following, which silently failed
+// every hosted job with "run completed without hardware WebGL proof" even when
+// the preview itself uploaded fine.
+export const PLAYWRIGHT_HOST_LOG_PREFIX = 'rnx-playwright-host-'
+
+export function playwrightHostLogName(nowMs: number, pid: number): string {
+  return `${PLAYWRIGHT_HOST_LOG_PREFIX}${nowMs.toString(36)}-${pid}.log`
+}
+
+export function isPlaywrightHostLog(name: string): boolean {
+  return name.startsWith(PLAYWRIGHT_HOST_LOG_PREFIX) && name.endsWith('.log')
+}

package/src/plist.ts

@@ -0,0 +1,27 @@
+import plistModule from '@expo/plist'
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+function resolvePlistParser(value: unknown): ((source: string) => unknown) | null {
+  if (!isRecord(value)) return null
+  const direct = value.parse
+  if (typeof direct === 'function') {
+    return (source) => Reflect.apply(direct, value, [source])
+  }
+  const nested = value.default
+  if (!isRecord(nested)) return null
+  const nestedParse = nested.parse
+  return typeof nestedParse === 'function'
+    ? (source) => Reflect.apply(nestedParse, nested, [source])
+    : null
+}
+
+// bun consumes @expo/plist's default export directly, while the compiled commonjs
+// scanner receives the package namespace with that export nested under default.
+const parsePlist = resolvePlistParser(plistModule)
+
+export function parsePlistSource(source: string): unknown {
+  return parsePlist?.(source) ?? null
+}

package/src/poll-until.ts

@@ -0,0 +1,123 @@
+export interface PollUntilOptions {
+  timeoutMs: number
+  intervalMs?: number
+  label: string
+  signal?: AbortSignal
+}
+
+type PollReadOutcome<T> = { kind: 'value'; value: T } | { kind: 'error'; error: unknown }
+
+export async function pollUntil<T>(
+  read: () => Promise<T>,
+  ready: (value: T) => boolean,
+  options: PollUntilOptions,
+): Promise<T> {
+  if (!Number.isFinite(options.timeoutMs) || options.timeoutMs <= 0) {
+    throw new Error('poll timeout must be a positive finite number')
+  }
+  const intervalMs = options.intervalMs ?? 100
+  if (!Number.isFinite(intervalMs) || intervalMs < 0) {
+    throw new Error('poll interval must be a non-negative finite number')
+  }
+
+  const deadline = Date.now() + options.timeoutMs
+  let lastError: unknown
+  let lastRead: { value: T } | null = null
+  // a poll that expires because its predicate kept returning false is the
+  // ordinary case, and the error used to name nothing but the label: every one
+  // of those sent the reader back to re-run the whole flow just to learn what
+  // the state had been. reporting the last value the read produced makes the
+  // failure say it. bounded, because a polled value is often a whole evidence
+  // snapshot and a failure report is not a data dump.
+  const describeLastRead = (): string => {
+    if (lastRead === null) {
+      if (lastError === undefined) return 'no read settled'
+      const message = lastError instanceof Error ? lastError.message : String(lastError)
+      return `last read failed: ${message}`
+    }
+    let serialized: string
+    try {
+      const seen = new WeakSet()
+      serialized =
+        JSON.stringify(lastRead.value, (_key, entry: unknown) => {
+          if (typeof entry !== 'object' || entry === null) return entry
+          if (seen.has(entry)) return '[circular]'
+          seen.add(entry)
+          return entry
+        }) ?? String(lastRead.value)
+    } catch {
+      return 'last value (unserializable)'
+    }
+    if (serialized.length <= 300) return `last value ${serialized}`
+    return `last value ${serialized.slice(0, 300)}... (${serialized.length} chars)`
+  }
+  const timeoutError = () =>
+    new Error(
+      `${options.label} timed out after ${options.timeoutMs}ms; ${describeLastRead()}`,
+      { cause: lastError },
+    )
+
+  options.signal?.throwIfAborted()
+  let rejectBoundary: (reason: unknown) => void = () => {}
+  const boundary = new Promise<never>((_, reject) => {
+    rejectBoundary = reject
+  })
+  const onAbort = () =>
+    rejectBoundary(
+      options.signal?.reason ??
+        new DOMException('The operation was aborted', 'AbortError'),
+    )
+  options.signal?.addEventListener('abort', onAbort, { once: true })
+  const deadlineTimer = setTimeout(
+    () => rejectBoundary(timeoutError()),
+    options.timeoutMs,
+  )
+
+  try {
+    while (true) {
+      if (Date.now() >= deadline) throw timeoutError()
+
+      const outcome = await Promise.race([
+        Promise.resolve()
+          .then(read)
+          .then(
+            (value): PollReadOutcome<T> => ({ kind: 'value', value }),
+            (error: unknown): PollReadOutcome<T> => ({ kind: 'error', error }),
+          ),
+        boundary,
+      ])
+
+      options.signal?.throwIfAborted()
+      if (outcome.kind === 'error') {
+        lastError = outcome.error
+      } else {
+        lastRead = { value: outcome.value }
+        if (Date.now() >= deadline) throw timeoutError()
+        try {
+          if (ready(outcome.value)) return outcome.value
+        } catch (error) {
+          lastError = error
+        }
+      }
+
+      const remaining = deadline - Date.now()
+      if (remaining <= 0) throw timeoutError()
+      if (intervalMs > 0) {
+        let intervalTimer: ReturnType<typeof setTimeout> | undefined
+        try {
+          await Promise.race([
+            new Promise<void>((resolve) => {
+              intervalTimer = setTimeout(resolve, Math.min(intervalMs, remaining))
+            }),
+            boundary,
+          ])
+        } finally {
+          clearTimeout(intervalTimer)
+        }
+      }
+    }
+  } finally {
+    clearTimeout(deadlineTimer)
+    options.signal?.removeEventListener('abort', onAbort)
+  }
+}

package/src/profiles.ts

@@ -0,0 +1,179 @@
+import fs from 'fs'
+import path from 'path'
+import { electronUserDataDir, ensureRnxHome, profilesDir } from './home-paths'
+
+export const DEFAULT_PROFILE_ID = 'default'
+const PROFILE_INDEX_FILE = 'profiles.json'
+const PROFILE_INDEX_VERSION = 1 as const
+
+export interface StorageProfile {
+  id: string
+  createdAt: string
+  updatedAt: string
+}
+
+interface ProfileIndex {
+  version: 1
+  profiles: StorageProfile[]
+}
+
+export function normalizeProfileId(input: string): string {
+  const id = input.trim()
+  if (!id) throw new Error('profile id is required')
+  if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(id)) {
+    throw new Error(
+      'profile ids must start with a letter or number and contain only letters, numbers, dot, dash, or underscore',
+    )
+  }
+  if (id === '.' || id === '..') throw new Error(`invalid profile id: ${id}`)
+  return id
+}
+
+export function profileIndexPath(): string {
+  return path.join(profilesDir(), PROFILE_INDEX_FILE)
+}
+
+export function electronProfilePartitionName(profileId: string): string {
+  return `sootsim-profile-${normalizeProfileId(profileId)}`
+}
+
+export function electronProfilePartition(profileId: string): string {
+  return `persist:${electronProfilePartitionName(profileId)}`
+}
+
+export function electronProfilePartitionDir(profileId: string): string {
+  return path.join(
+    electronUserDataDir(),
+    'Partitions',
+    electronProfilePartitionName(profileId),
+  )
+}
+
+export function playwrightProfileUserDataDir(profileId: string): string {
+  return path.join(profilesDir(), 'playwright', normalizeProfileId(profileId))
+}
+
+function readIndexRaw(): ProfileIndex {
+  try {
+    const parsed = JSON.parse(
+      fs.readFileSync(profileIndexPath(), 'utf8'),
+    ) as Partial<ProfileIndex> | null
+    if (!parsed || parsed.version !== PROFILE_INDEX_VERSION) {
+      return { version: PROFILE_INDEX_VERSION, profiles: [] }
+    }
+    const profiles = Array.isArray(parsed.profiles)
+      ? parsed.profiles
+          .filter(
+            (profile): profile is StorageProfile =>
+              !!profile &&
+              typeof profile.id === 'string' &&
+              typeof profile.createdAt === 'string' &&
+              typeof profile.updatedAt === 'string',
+          )
+          .map((profile) => ({
+            id: normalizeProfileId(profile.id),
+            createdAt: profile.createdAt,
+            updatedAt: profile.updatedAt,
+          }))
+      : []
+    return { version: PROFILE_INDEX_VERSION, profiles }
+  } catch {
+    return { version: PROFILE_INDEX_VERSION, profiles: [] }
+  }
+}
+
+function sortProfiles(profiles: StorageProfile[]): StorageProfile[] {
+  return [...profiles].sort((a, b) => {
+    if (a.id === DEFAULT_PROFILE_ID) return -1
+    if (b.id === DEFAULT_PROFILE_ID) return 1
+    return a.id.localeCompare(b.id)
+  })
+}
+
+function withDefault(index: ProfileIndex): ProfileIndex {
+  if (index.profiles.some((profile) => profile.id === DEFAULT_PROFILE_ID)) {
+    return { ...index, profiles: sortProfiles(index.profiles) }
+  }
+  const now = new Date().toISOString()
+  return {
+    version: PROFILE_INDEX_VERSION,
+    profiles: sortProfiles([
+      { id: DEFAULT_PROFILE_ID, createdAt: now, updatedAt: now },
+      ...index.profiles,
+    ]),
+  }
+}
+
+function writeIndex(index: ProfileIndex): ProfileIndex {
+  ensureRnxHome()
+  const next = withDefault(index)
+  const tmp = `${profileIndexPath()}.tmp`
+  fs.writeFileSync(tmp, `${JSON.stringify(next, null, 2)}\n`, 'utf8')
+  fs.renameSync(tmp, profileIndexPath())
+  return next
+}
+
+export function listProfiles(): StorageProfile[] {
+  return writeIndex(readIndexRaw()).profiles
+}
+
+export function getProfile(id: string): StorageProfile | null {
+  const normalized = normalizeProfileId(id)
+  return listProfiles().find((profile) => profile.id === normalized) ?? null
+}
+
+export function ensureProfile(id = DEFAULT_PROFILE_ID): StorageProfile {
+  const normalized = normalizeProfileId(id)
+  const existing = getProfile(normalized)
+  if (existing) return existing
+  return createProfile(normalized)
+}
+
+export function createProfile(id: string): StorageProfile {
+  const normalized = normalizeProfileId(id)
+  const index = withDefault(readIndexRaw())
+  if (index.profiles.some((profile) => profile.id === normalized)) {
+    throw new Error(`profile already exists: ${normalized}`)
+  }
+  const now = new Date().toISOString()
+  const profile = { id: normalized, createdAt: now, updatedAt: now }
+  writeIndex({ version: PROFILE_INDEX_VERSION, profiles: [...index.profiles, profile] })
+  return profile
+}
+
+export function nextGeneratedProfileId(): string {
+  const existing = new Set(listProfiles().map((profile) => profile.id))
+  for (let i = 1; i < 10_000; i++) {
+    const id = `profile-${i}`
+    if (!existing.has(id)) return id
+  }
+  throw new Error('could not allocate a new profile id')
+}
+
+export function deleteProfile(id: string): StorageProfile {
+  const normalized = normalizeProfileId(id)
+  if (normalized === DEFAULT_PROFILE_ID) {
+    throw new Error('the default profile cannot be deleted; clear it instead')
+  }
+  const index = withDefault(readIndexRaw())
+  const profile = index.profiles.find((entry) => entry.id === normalized)
+  if (!profile) throw new Error(`profile not found: ${normalized}`)
+  writeIndex({
+    version: PROFILE_INDEX_VERSION,
+    profiles: index.profiles.filter((entry) => entry.id !== normalized),
+  })
+  clearProfileStorage(normalized)
+  return profile
+}
+
+export function clearProfileStorage(id: string): void {
+  const normalized = normalizeProfileId(id)
+  for (const dir of [
+    electronProfilePartitionDir(normalized),
+    playwrightProfileUserDataDir(normalized),
+  ]) {
+    try {
+      fs.rmSync(dir, { recursive: true, force: true })
+    } catch {}
+  }
+}