simframe 0.13.0 → 0.14.0

package/src/graph.js

@@ -396,7 +396,18 @@ export function describe(node) {
   if (tabs.length) return tabs.slice(0, 3).join(' / ');
   const anyChrome = labels(/:(nav-bar|tab-bar):/);
   if (anyChrome.length) return anyChrome.slice(0, 3).join(' ');
-  return node.hash.slice(0, 8);
+  // No name. Say so, rather than handing back a hash dressed as one.
+  //
+  // This fell back to `node.hash.slice(0, 8)`, and the map prints the name in
+  // quotes after the identity hash — so an unnamed screen read
+  // `screen 299dd147 "a9505378"`: two hashes, one of them looking like a title,
+  // beside the `screen 089bec77 "time sheets"` a named screen produces.
+  // Reported from the field, with the right fix attached: omit the quoted part
+  // rather than echo a second hash.
+  //
+  // Callers that need *something* to print in a list supply their own fallback,
+  // which is a decision about presentation and belongs at the point of display.
+  return null;
 }
 
 /** Find a known screen by what a human would call it. */
@@ -404,7 +415,9 @@ export function findScreen(udid, query) {
   const wanted = String(query ?? '').trim();
   if (!wanted) return null;
   const scored = allNodes(udid)
-    .map((node) => ({ node, name: describe(node) }))
+    // The short hash stays searchable: `goto 089bec77` worked before `describe`
+    // stopped inventing names and must keep working.
+    .map((node) => ({ node, name: describe(node) ?? node.hash.slice(0, 8) }))
     .map((c) => ({ ...c, score: matching.nameScore(c.name, wanted) }))
     .filter((c) => c.score > 0)
     .sort((a, b) => b.score - a.score);

package/src/matching.js

@@ -170,7 +170,23 @@ export function rank(targets, intent, { screen } = {}) {
     // An icon-only control has no readable name, so a synonym is the only way
     // to reach it — this is how "back" finds a bare chevron.
     if (group && base < 0.5 && !t.label && t.rawLabel) base = 0.55;
-    if (group && base < 0.5 && names.some((n) => group.words.includes(norm(n)))) base = 0.9;
+    // Genuine synonymy only: the name must be a *different* word in the group.
+    //
+    // This branch fires only when `base < 0.5`, which means its whole job is to
+    // overrule the coverage scaling the two branches in `nameScore` were taught
+    // — and when the query already contains the name literally, that scaling was
+    // the right answer and this flat 0.9 throws it away. Reported (138): a long
+    // descriptive phrase ending "…under Settings" scored a *heading* labelled
+    // "Settings" at 0.9 and the row the caller meant at 0.265, tapped the
+    // heading, and returned `ok [no visible change]` with an `or` list untried.
+    //
+    // A name the query spells out has already been scored on how much of the
+    // query it covers. What this branch is for is the case that scoring cannot
+    // see at all: "back" reaching a control labelled "Previous", "settings"
+    // reaching "Preferences". That is synonymy, and it is unaffected.
+    const spelledOut = (n) => bare.includes(norm(n)) || norm(intent).includes(norm(n));
+    if (group && base < 0.5
+      && names.some((n) => group.words.includes(norm(n)) && !spelledOut(n))) base = 0.9;
     if (base <= 0) continue;
 
     const reasons = [matched ? `label "${matched}"` : 'icon-only'];

package/src/mcp.js

@@ -15,7 +15,8 @@ import * as api from './index.js';
 import * as input from './input.js';
 import * as metrics from './metrics.js';
 import * as navigate from './navigate.js';
-import { bootedDevices, permissionServices } from './platform/index.js';
+import { bootedDevices, listDevices, permissionServices, resolveDevice } from './platform/index.js';
+import * as storage from './storage.js';
 import * as store from './store.js';
 import * as view from './view.js';
 
@@ -132,7 +133,7 @@ const TOOLS = [
         steps: {
           type: 'array',
           description:
-            'Ordered steps. Every selector below accepts "Save" | "#3" | "@120,400", in that order of preference. Act: {"tap":"Save"} (add "index" if a label is ambiguous), {"type":{"into":"Name","text":"Fryer 3"}}, {"paste":{"into":"Notes","text":"long text"}}, {"clear":"Notes"} to empty a field and "clear":true on a type/paste to replace rather than append (drop "into" to type into whatever already has focus, which is how you follow a browser next-field chevron — nothing can be read back then, and the step says so), {"scroll":"down"}, {"scrollTo":"Delete account"}, {"swipe":{"from":[x,y],"to":[x,y]}}, {"button":"HOME"}, {"key":"return"} (the keyboard return/enter key, which is how a mobile search field submits — also escape, tab, space, backspace, and the arrows), {"launch":{"value":"com.example.app","relaunch":true,"args":["-uiTest","1"]}}, {"openUrl":"myapp://x"}, {"permission":{"value":"photos","grant":"grant","bundleId":"com.example.app"}}. Check: {"assert":{"value":"Saved","is":"visible"}} (also gone | enabled | disabled | value with "equals"), {"waitFor":{"value":"Saved","timeoutMs":5000}}, {"settle":{"stableMs":600}}, {"pause":300}. Recover without a round trip: add "or" to any step for fallback selectors tried locally — {"tap":"Save","or":["Done","Confirm"]} — and {"seek":"change username","budget":6} explores for something not on this screen: it OPENS containers (a real action — state changes), checks, and returns to where it started, refusing to open anything that commits, abandons or answers. It does not tap the target; it leaves you on the screen where the target resolves so you tap it next. Do not point it into a flow whose progress you cannot afford to lose. A long screen is only knowable a viewport at a time, so {"sweep":"all","fill":{"Last Name":"Asadi","Email":"a@b.c"}} goes to the top, then reads and fills section by section to the bottom — filling each field while it is on screen, which beats finding one and scrolling back. Add "from":"here" to sweep down from where you are. It reports which section each element was in, what it filled, and what it never found at any scroll position. Prefer it to scrollTo on forms and long lists. Brief the supervisor from the plan: top-level "supervise" is standing guidance for the whole batch ("lists here render a count header before rows; REVIEW stays disabled until a provider is chosen") and per-step "expect" adds to it. When it stops a run the result names the steps it did not attempt — re-issue them with a corrected "supervise" note if the judgement was wrong.',
+            'Ordered steps. Every selector below accepts "Save" | "#3" | "@120,400", in that order of preference. Act: {"tap":"Save"} (add "index" if a label is ambiguous), {"type":{"into":"Name","text":"Fryer 3"}}, {"paste":{"into":"Notes","text":"long text"}}, {"clear":"Notes"} to empty a field and "clear":true on a type/paste to replace rather than append (drop "into" to type into whatever already has focus, which is how you follow a browser next-field chevron — nothing can be read back then, and the step says so), {"scroll":"down"}, {"scrollTo":"Delete account"}, {"swipe":{"from":[x,y],"to":[x,y]}}, {"button":"HOME"}, {"key":"return"} (the keyboard return/enter key, which is how a mobile search field submits — also escape, tab, space, backspace, and the arrows), {"launch":{"value":"com.example.app","relaunch":true,"args":["-uiTest","1"]}}, {"openUrl":"myapp://x"}, {"permission":{"value":"photos","grant":"grant","bundleId":"com.example.app"}}. Check: {"assert":{"value":"Saved","is":"visible"}} (also gone | enabled | disabled | value with "equals"), {"waitFor":{"value":"Saved","timeoutMs":5000}} (add "failIfStillFor":15000 to stop early once the screen has plainly stopped changing — a 180s wait once burned three minutes on an app that had logged itself out; without it a timeout still reports how long the screen had been still), {"settle":{"stableMs":600}}, {"pause":300}. Recover without a round trip: add "or" to any step for fallback selectors tried locally — {"tap":"Save","or":["Done","Confirm"]} — and {"seek":"change username","budget":6} explores for something not on this screen: it OPENS containers (a real action — state changes), checks, and returns to where it started, refusing to open anything that commits, abandons or answers. It does not tap the target; it leaves you on the screen where the target resolves so you tap it next. Do not point it into a flow whose progress you cannot afford to lose. A long screen is only knowable a viewport at a time, so {"sweep":"all","fill":{"Last Name":"Asadi","Email":"a@b.c"}} goes to the top, then reads and fills section by section to the bottom — filling each field while it is on screen, which beats finding one and scrolling back. Add "from":"here" to sweep down from where you are. It reports which section each element was in, what it filled, and what it never found at any scroll position. Prefer it to scrollTo on forms and long lists. Brief the supervisor from the plan: top-level "supervise" is standing guidance for the whole batch ("lists here render a count header before rows; REVIEW stays disabled until a provider is chosen") and per-step "expect" adds to it. When it stops a run the result names the steps it did not attempt — re-issue them with a corrected "supervise" note if the judgement was wrong.',
           items: { type: 'object' },
         },
         autoSettle: {
@@ -192,7 +193,19 @@ const TOOLS = [
     description: 'Block until something appears on screen, then return the screen map. Use this instead of pausing and re-reading.',
     inputSchema: {
       type: 'object',
-      properties: { ...deviceProp, ...modeProps, ...selectorProp('What to wait for'), timeoutMs: { type: 'number', description: 'Default 8000.' } },
+      properties: {
+        ...deviceProp,
+        ...modeProps,
+        ...selectorProp('What to wait for'),
+        timeoutMs: { type: 'number', description: 'Default 8000.' },
+        failIfStillFor: {
+          type: 'number',
+          description: 'Give up early once the screen has not moved for this long and the target is still absent.'
+            + ' Off by default, because a still screen is also what a pending network call looks like —'
+            + ' use it when the thing you await would arrive with a visible change or not at all.'
+            + ' A timeout reports the stillness either way.',
+        },
+      },
       required: ['sel'],
     },
   },
@@ -386,10 +399,42 @@ const TOOLS = [
       required: ['action'],
     },
   },
+  {
+    name: 'sim_storage',
+    description:
+      'What the app saved, as text: its UserDefaults and (for React Native) its AsyncStorage, read straight out of'
+      + ' the data container. sim_ui says what is drawn; sim_storage says what the app believes — use it when the'
+      + ' screen and the behaviour disagree, or to check a value without driving the UI to it.'
+      + ' Works on a device that is NOT running, so it can answer before anything is booted.'
+      + ' Call with no bundleId to list the apps that have a container (match filters that list).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        bundleId: { type: 'string', description: 'The app to read, e.g. com.example.myapp. Omit to list apps instead.' },
+        match: { type: 'string', description: 'When listing, show only bundle ids containing this string.' },
+        ...deviceProp,
+        ...modeProps,
+      },
+    },
+  },
   {
     name: 'sim_devices',
-    description: 'List the booted devices simframe can drive — iOS simulators and Android emulators.',
-    inputSchema: { type: 'object', properties: {} },
+    description: 'List the devices simframe can drive — iOS simulators and Android emulators.'
+      + ' Booted ones by default; pass all to see every device on the host and its state.'
+      + ' Also reports which simframe build is answering.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        all: {
+          type: 'boolean',
+          description: 'Also account for devices that are shut down, grouped by runtime.',
+        },
+        match: {
+          type: 'string',
+          description: 'With all, list shut-down devices whose name or runtime contains this, in full.',
+        },
+      },
+    },
   },
 ];
 
@@ -560,7 +605,7 @@ export async function serve({ device: defaultDevice, options: baseOptions = {} }
             options,
           );
         case 'sim_wait_for':
-          return await oneStep(target, { waitFor: args.sel, timeoutMs: args.timeoutMs }, args, options);
+          return await oneStep(target, { waitFor: args.sel, timeoutMs: args.timeoutMs, failIfStillFor: args.failIfStillFor }, args, options);
         case 'sim_assert':
           return await oneStep(target, { assert: args.sel, is: args.is, equals: args.equals }, args, options);
         case 'sim_launch':
@@ -585,8 +630,10 @@ export async function serve({ device: defaultDevice, options: baseOptions = {} }
           return await flowRun(target, args, options);
         case 'sim_capture':
           return await capture(target, args, options);
+        case 'sim_storage':
+          return await appStorage(args);
         case 'sim_devices':
-          return await devices();
+          return await devices(args);
         default:
           throw new Error(`unknown tool ${req.params.name}`);
       }
@@ -935,7 +982,7 @@ function verdictLineFor(results) {
 
 function stepLines(res) {
   const lines = [
-    `${res.ok ? 'flow completed' : 'FLOW FAILED'} — ${res.ranSteps}/${res.totalSteps} steps in ${res.totalMs}ms`,
+    actions.flowSummary(res),
   ];
   for (const r of res.results) {
     const settle = r.settled
@@ -1142,12 +1189,94 @@ function listStateDirs() {
   }
 }
 
-async function devices() {
+/**
+ * What an app has persisted.
+ *
+ * Deliberately not a daemon call and deliberately not a `simctl` call. Measured
+ * on this Xcode, `simctl get_app_container` and `simctl listapps` both refuse on
+ * a device that is not running — so the one property that made the field
+ * reporter rate this the highest-leverage thing in their session, answering
+ * *before the device is booted*, is only reachable by reading the container off
+ * the host filesystem. That is what the backend does.
+ */
+async function appStorage({ bundleId, match: query, device } = {}) {
+  const resolved = await resolveDevice(device);
+  if (!bundleId) {
+    const list = await storage.apps(resolved.udid);
+    const needle = query ? String(query).toLowerCase() : null;
+    const shown = needle ? list.filter((a) => a.bundleId.toLowerCase().includes(needle)) : list;
+    return { content: [text(storage.formatApps(shown))] };
+  }
+  const result = await storage.read(resolved.udid, bundleId);
+  return { content: [text(storage.format(result))] };
+}
+
+async function devices({ all = false, match: query } = {}) {
   const booted = await bootedDevices();
-  if (!booted.length) return { content: [text('no booted devices')] };
   // Noticing a name collision here is what lets every later header disambiguate
   // itself, and it costs nothing: this listing is already being made.
   const clash = noteBooted(booted);
-  const list = booted.map((d) => `${d.name} · ${d.runtime} · ${d.udid}`).join('\n');
-  return { content: [text(clash ? `${clash}\n\n${list}` : list)] };
+  // The build that is answering, on the one call every session starts with.
+  //
+  // Reported from the field: a session told to test 0.13.0 could not find out
+  // what it was running. The globally installed CLI said 0.12.2 while the MCP
+  // server ran from a checkout, and answering "am I on the build under test?"
+  // took three shell calls and a read of `~/.claude.json`. A tool being field
+  // tested should be able to state its own build, and this is the cheapest
+  // place to put it.
+  const head = `simframe ${packageVersion()}`;
+  if (!all) {
+    if (!booted.length) {
+      // Never a bare "no devices". The host almost always has some, they are
+      // just off, and the reporter who hit this fell out of the tool entirely
+      // and went to `xcrun simctl` — for a tool whose whole job is driving
+      // simulators, that is the conspicuous hole.
+      const every = await listDevices().catch(() => []);
+      return { content: [text(`${head}\n\nno booted devices`
+        + (every.length ? ` — the host has ${every.length}, all shut down. Pass all:true to see them.` : ''))] };
+    }
+    const list = booted.map((d) => `● ${d.name} · ${d.runtime} · ${d.udid}`).join('\n');
+    return { content: [text([head, clash, list].filter(Boolean).join('\n\n'))] };
+  }
+  const every = await listDevices();
+  if (!every.length) return { content: [text(`${head}\n\nno devices on this host`)] };
+
+  // Summarised, not dumped.
+  //
+  // The first version of this listed every device in full and produced **126
+  // rows** on this host — two thousand tokens to answer "what else is here",
+  // from a tool whose entire argument is that text beats a screenshot because
+  // it is cheaper. A listing that costs more than the screenshot it replaces has
+  // lost the plot.
+  //
+  // So: booted devices in full, because those are the ones a caller can act on,
+  // and the rest grouped by runtime with counts. `match` lists in full, because
+  // a caller who names what they are looking for has already narrowed it.
+  const wanted = String(query ?? '').trim().toLowerCase();
+  const off = every.filter((d) => d.state !== 'Booted');
+  const lines = [head, clash].filter(Boolean);
+  lines.push(booted.length
+    ? booted.map((d) => `● ${d.name} · ${d.runtime} · ${d.udid}`).join('\n')
+    : 'no booted devices');
+
+  const hits = wanted
+    ? off.filter((d) => `${d.name} ${d.runtime}`.toLowerCase().includes(wanted))
+    : [];
+  if (wanted) {
+    lines.push(hits.length
+      ? `shut down, matching "${query}":\n`
+        + hits.map((d) => `○ ${d.name} · ${d.runtime} · ${d.udid}`).join('\n')
+      : `no shut-down device matches "${query}" (${off.length} are shut down)`);
+  } else if (off.length) {
+    const byRuntime = new Map();
+    for (const d of off) byRuntime.set(d.runtime, (byRuntime.get(d.runtime) ?? 0) + 1);
+    const summary = [...byRuntime.entries()]
+      .sort((a, b) => b[1] - a[1])
+      .map(([runtime, n]) => `  ${runtime} — ${n}`)
+      .join('\n');
+    lines.push(`${off.length} device(s) shut down, by runtime:\n${summary}\n`
+      + 'pass match to list the ones you mean, e.g. match:"iPhone 17 Pro".');
+  }
+  lines.push('simframe cannot drive a device until it is booted.');
+  return { content: [text(lines.join('\n\n'))] };
 }

package/src/navigate.js

@@ -133,7 +133,10 @@ export async function goto(deviceQuery, target, { options, ...runOptions } = {})
 }
 
 export function knownScreens(udid) {
-  return graph.allNodes(udid).map((n) => ({ name: graph.describe(n), hash: n.hash.slice(0, 8), edges: n.edges.length }));
+  // A listing needs a handle for every row, so an unnamed screen falls back to
+  // its own short hash here — where it is plainly the hash column's value and
+  // not a title in quotes.
+  return graph.allNodes(udid).map((n) => ({ name: graph.describe(n) ?? n.hash.slice(0, 8), hash: n.hash.slice(0, 8), edges: n.edges.length }));
 }
 
 /**

package/src/platform/android.js

@@ -1018,6 +1018,37 @@ async function restartDevice(serial) {
   );
 }
 
+/**
+ * Reading an app's own storage is not implemented for Android, and says so.
+ *
+ * Not a stub and not a borrowed answer. The iOS version reads a CoreSimulator
+ * data container straight off the host filesystem, which an emulator has no
+ * equivalent of: an app's files live inside the emulator's own userdata image,
+ * and the way in is `adb shell run-as <package>` — which works only for a
+ * debuggable build, needs the emulator running, and would be a different
+ * feature with different guarantees rather than the same one.
+ *
+ * The standing rule is that a layer a platform does not have is declined with a
+ * reason, never described in the other platform's vocabulary. Claiming a data
+ * container here is how `doctor` once told an emulator its input driver was
+ * idb.
+ */
+const noStorage = (serial, what) => {
+  throw new Error(
+    `simframe cannot read ${what} on an emulator (${serial}) yet. The iOS version reads a`
+    + ' simulator data container off the host filesystem and an emulator has no such thing —'
+    + ' its app data lives inside the userdata image, reachable only through'
+    + ' `adb shell run-as <package>` on a debuggable build, with the emulator running.'
+    + ' That is a different feature and it has not been built.',
+  );
+};
+
+async function listApps(serial) { return noStorage(serial, 'the list of installed apps'); }
+async function appContainer(serial) { return noStorage(serial, "an app's data container"); }
+async function readPropertyList() {
+  throw new Error('property lists are an iOS format; Android has no equivalent to read');
+}
+
 /** @type {import('./index.js').Platform} */
 export const platform = {
   id: 'android',
@@ -1034,6 +1065,9 @@ export const platform = {
   terminateApp,
   openUrl,
   restartDevice,
+  listApps,
+  appContainer,
+  readPropertyList,
   setPermission,
   setPasteboard,
   getPasteboard,

package/src/platform/index.js

@@ -63,6 +63,7 @@ export const PLATFORM_SURFACE = Object.freeze([
   'geometry', 'inputDriver',
   'screenshot', 'launchApp', 'terminateApp', 'openUrl', 'restartDevice',
   'setPermission', 'setPasteboard', 'permissionServices', 'capabilities', 'toolchain',
+  'listApps', 'appContainer', 'readPropertyList',
   'bootedAt',
 ]);
 
@@ -209,6 +210,12 @@ export const openUrl = (udid, ...args) => platformFor(udid).openUrl(udid, ...arg
 export const setPermission = (udid, ...args) => platformFor(udid).setPermission(udid, ...args);
 export const setPasteboard = (udid, ...args) => platformFor(udid).setPasteboard(udid, ...args);
 
+// Reading what an app persisted. Routed like everything else, and declined by a
+// backend that has no equivalent rather than answered in the other's terms.
+export const listApps = (udid, ...args) => platformFor(udid).listApps(udid, ...args);
+export const appContainer = (udid, ...args) => platformFor(udid).appContainer(udid, ...args);
+export const readPropertyList = (udid, file) => platformFor(udid).readPropertyList(file);
+
 /**
  * The permission services a device understands, or every service any backend
  * understands when no device is named.

package/src/platform/ios.js

@@ -9,6 +9,7 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { promisify } from 'node:util';
+import * as plist from './plist.js';
 
 const run = promisify(execFile);
 
@@ -334,6 +335,100 @@ function ownsUdid(udid) {
   return /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(String(udid ?? ''));
 }
 
+/**
+ * Where CoreSimulator keeps a device's data.
+ *
+ * Read straight off disk, and that is the whole point of this family rather
+ * than an optimisation. Measured on this Xcode: `simctl get_app_container` and
+ * `simctl listapps` **both** fail on a device that is not running —
+ * `Unable to lookup in current state: Shutdown`. The field report that asked
+ * for this feature rated it highest-leverage precisely because it answered
+ * "what did the app save?" *before the device was booted*, and simctl cannot do
+ * that. The filesystem can, so this reads the filesystem.
+ */
+const deviceRoot = (udid) =>
+  path.join(os.homedir(), 'Library/Developer/CoreSimulator/Devices', String(udid));
+
+const containerRoot = (udid) => path.join(deviceRoot(udid), 'data/Containers/Data/Application');
+
+/** The per-container metadata file that says which app owns it. */
+const METADATA = '.com.apple.mobile_container_manager.metadata.plist';
+
+/**
+ * Every app with a data container on this device, booted or not.
+ *
+ * The bundle id lives in `MCMMetadataIdentifier` in each container's metadata
+ * plist. It is *not* recoverable by grepping the file — the binary plist
+ * encodes strings in a way that does not leave the id as a plain substring, and
+ * an early version of this that tried to pre-filter that way matched nothing.
+ * So each metadata file is asked properly. Measured at **0.52s for 150
+ * containers**, which is a listing cost rather than a per-read one.
+ */
+async function listApps(udid) {
+  const root = containerRoot(udid);
+  let entries;
+  try {
+    entries = await fs.promises.readdir(root, { withFileTypes: true });
+  } catch (err) {
+    if (err.code === 'ENOENT') {
+      const exists = fs.existsSync(deviceRoot(udid));
+      throw new Error(exists
+        ? `device ${udid} has no app data containers yet — nothing has been installed on it`
+        : `no simulator data directory for ${udid} (looked in ${root})`);
+    }
+    throw err;
+  }
+  const apps = [];
+  await Promise.all(entries.filter((e) => e.isDirectory()).map(async (e) => {
+    const dir = path.join(root, e.name);
+    try {
+      const { stdout } = await run('plutil',
+        ['-extract', 'MCMMetadataIdentifier', 'raw', '-o', '-', path.join(dir, METADATA)],
+        { timeout: 10_000 });
+      const bundleId = stdout.trim();
+      if (bundleId) apps.push({ bundleId, container: dir });
+    } catch {
+      // A container without readable metadata is not an app we can name, and
+      // naming it by its UUID would be offering an id nobody can use.
+    }
+  }));
+  return apps.sort((a, b) => a.bundleId.localeCompare(b.bundleId));
+}
+
+/** The data container for one app, or a listing of what is there instead. */
+async function appContainer(udid, bundleId) {
+  const apps = await listApps(udid);
+  const hit = apps.find((a) => a.bundleId === bundleId);
+  if (hit) return hit.container;
+  // Near misses first: the id is the thing people get wrong, and a bare "not
+  // installed" on a device with the app under a slightly different id is the
+  // least useful true sentence available.
+  const needle = String(bundleId).toLowerCase();
+  const near = apps.filter((a) => a.bundleId.toLowerCase().includes(needle)
+    || needle.includes(a.bundleId.toLowerCase())).slice(0, 5);
+  throw new Error(
+    `"${bundleId}" has no data container on ${udid}`
+    + (near.length ? ` — did you mean ${near.map((a) => a.bundleId).join(', ')}?` : '')
+    + ` (${apps.length} app(s) have one)`,
+  );
+}
+
+/**
+ * Read a property list, whatever it contains.
+ *
+ * `-convert xml1` and not `json`: six of the twenty real preference plists on
+ * the bench device cannot be represented as JSON at all, because `<data>` and
+ * `<date>` have no JSON form and plutil refuses rather than inventing one. See
+ * the note at the top of plist.js.
+ */
+async function readPropertyList(file) {
+  const { stdout } = await run('plutil', ['-convert', 'xml1', '-o', '-', file], {
+    timeout: 20_000,
+    maxBuffer: 64 * 1024 * 1024,
+  });
+  return plist.parse(stdout);
+}
+
 /**
  * The prerequisites `simframe doctor` reports for this backend. Returned rather
  * than printed so doctor stays one renderer: a backend says what it needs, and
@@ -440,6 +535,9 @@ export const platform = {
   terminateApp,
   openUrl,
   restartDevice,
+  listApps,
+  appContainer,
+  readPropertyList,
   setPermission,
   setPasteboard,
   permissionServices: () => PERMISSION_SERVICES,

package/src/platform/plist.js

@@ -0,0 +1,156 @@
+// Property lists, parsed without a dependency.
+//
+// Below the platform boundary on purpose. A plist is not a neutral file format
+// this project happens to read — it is how one platform stores what an app
+// believes, and `plutil` is that platform's tool. Android's answer to the same
+// question is a different file in a different shape, which is why the parsing
+// lives beside the backend that needs it rather than above the seam.
+//
+// **Why XML and not JSON.** `plutil -convert json` is the obvious route and it
+// does not work: measured across the twenty real `Library/Preferences` plists
+// on the bench device, **six of them failed to convert** — 30%, because JSON
+// has no representation for `<data>` or `<date>` and plutil refuses rather than
+// inventing one. `-convert xml1` succeeded on all twenty. A format that drops
+// three in ten real files is not a parser, it is a sampler.
+//
+// The XML here is machine-written by plutil, so this is a reader for that
+// output and not a general XML parser: no namespaces, no processing
+// instructions beyond the declaration, no mixed content. It is strict about
+// what it does not understand — an unknown tag throws rather than being skipped,
+// because a silently dropped key in a store read is a wrong answer about what
+// an app believes, and this whole feature exists to be trusted on that point.
+
+const ENTITIES = { lt: '<', gt: '>', amp: '&', quot: '"', apos: "'" };
+
+/** Decode the five XML entities plutil emits, plus numeric escapes. */
+export function decodeEntities(s) {
+  return String(s).replace(/&(#x?[0-9a-fA-F]+|[a-z]+);/g, (whole, body) => {
+    if (body[0] === '#') {
+      const code = body[1] === 'x' || body[1] === 'X'
+        ? parseInt(body.slice(2), 16)
+        : parseInt(body.slice(1), 10);
+      return Number.isFinite(code) ? String.fromCodePoint(code) : whole;
+    }
+    return ENTITIES[body] ?? whole;
+  });
+}
+
+/**
+ * A `<data>` value.
+ *
+ * Kept as a tagged object rather than decoded to a Buffer or dropped. The
+ * caller is usually a human asking what an app persisted, and "a 4 KB blob"
+ * is a real and often sufficient answer — while silently omitting the key
+ * would misreport the store as not having it.
+ */
+const dataValue = (base64) => {
+  const clean = base64.replace(/\s+/g, '');
+  return {
+    __type: 'data',
+    bytes: Math.floor((clean.length * 3) / 4) - (clean.endsWith('==') ? 2 : clean.endsWith('=') ? 1 : 0),
+    base64: clean,
+  };
+};
+
+/**
+ * Parse the XML property list plutil writes.
+ *
+ * @param {string} xml output of `plutil -convert xml1 -o -`
+ * @returns {*} the plist's root value — normally an object
+ */
+export function parse(xml) {
+  const src = String(xml);
+  // Everything before <plist> is the declaration and the DOCTYPE, neither of
+  // which carries data.
+  const start = src.indexOf('<plist');
+  if (start < 0) throw new Error('not an XML property list (no <plist> element)');
+  let i = src.indexOf('>', start);
+  if (i < 0) throw new Error('not an XML property list (unterminated <plist>)');
+  i += 1;
+
+  /** The next tag at or after `i`, skipping text that is only whitespace. */
+  const nextTag = () => {
+    const open = src.indexOf('<', i);
+    if (open < 0) return null;
+    const close = src.indexOf('>', open);
+    if (close < 0) throw new Error('unterminated tag in property list');
+    const raw = src.slice(open + 1, close);
+    i = close + 1;
+    const selfClosing = raw.endsWith('/');
+    const name = raw.replace(/\/$/, '').trim().split(/\s/)[0];
+    return { name: name.replace(/^\//, ''), closing: raw.startsWith('/'), selfClosing };
+  };
+
+  /** Text up to the matching close tag, which plutil never nests inside a leaf. */
+  const textUntilClose = (tag) => {
+    const close = src.indexOf(`</${tag}>`, i);
+    if (close < 0) throw new Error(`unterminated <${tag}> in property list`);
+    const text = src.slice(i, close);
+    i = close + tag.length + 3;
+    return text;
+  };
+
+  const readValue = (tag) => {
+    switch (tag.name) {
+      case 'true': return true;
+      case 'false': return false;
+      case 'string': return tag.selfClosing ? '' : decodeEntities(textUntilClose('string'));
+      case 'integer': {
+        const text = textUntilClose('integer').trim();
+        const n = Number(text);
+        // A plist integer is 64-bit and JavaScript's is not. Returning a
+        // silently-rounded number would be a wrong answer about a stored value,
+        // so the exact digits survive as a string and the shape says why.
+        if (!Number.isSafeInteger(n)) return { __type: 'integer', exact: text };
+        return n;
+      }
+      case 'real': return Number(textUntilClose('real').trim());
+      case 'date': return { __type: 'date', iso: textUntilClose('date').trim() };
+      case 'data': return dataValue(textUntilClose('data'));
+      case 'dict': {
+        if (tag.selfClosing) return {};
+        const out = {};
+        for (;;) {
+          const t = nextTag();
+          if (!t) throw new Error('unterminated <dict> in property list');
+          if (t.closing && t.name === 'dict') return out;
+          if (t.name !== 'key') throw new Error(`expected <key> in <dict>, found <${t.name}>`);
+          const key = t.selfClosing ? '' : decodeEntities(textUntilClose('key'));
+          const vt = nextTag();
+          if (!vt) throw new Error(`<key>${key}</key> has no value`);
+          out[key] = readValue(vt);
+        }
+      }
+      case 'array': {
+        if (tag.selfClosing) return [];
+        const out = [];
+        for (;;) {
+          const t = nextTag();
+          if (!t) throw new Error('unterminated <array> in property list');
+          if (t.closing && t.name === 'array') return out;
+          out.push(readValue(t));
+        }
+      }
+      default:
+        // Deliberately not a skip. See the note at the top of this file.
+        throw new Error(`unsupported property-list element <${tag.name}>`);
+    }
+  };
+
+  const root = nextTag();
+  if (!root || root.closing) return null;
+  return readValue(root);
+}
+
+/**
+ * What kind of thing a parsed value is, in one word, for a listing.
+ *
+ * `typeof` is not enough: the tagged shapes above are objects, and calling a
+ * date "object" in a store listing tells the reader nothing they wanted.
+ */
+export function typeOf(value) {
+  if (value === null) return 'null';
+  if (Array.isArray(value)) return 'array';
+  if (typeof value === 'object') return value.__type ?? 'dict';
+  return typeof value;
+}