@palgroup/simstream 0.7.0 → 0.9.0

package/README.md

@@ -39,6 +39,20 @@ await sim.pushBuild('https://your-bucket/App.zip');
 
 It goes only to hosts holding *your* sessions.
 
+## Keeping builds
+
+The registry keeps every build a project uploads, so nobody has to keep a list of URLs on their side:
+
+```ts
+const build = await sim.uploadBuild(zippedApp, { description: 'main · 26 Sep 18:40' }); // a zipped simulator .app
+const { builds } = await sim.listBuilds();                                              // newest first
+const session = await sim.runBuild({ build: build.id }, { device: 'iPhone 17', wait: true });
+```
+
+Completing an upload publishes the build and moves its app's `latest` channel to it, so
+`runBuild({ channel: 'com.example.app:latest' })` always opens the newest one. `setChannel(id, 'beta')`
+names others.
+
 ## When there is nothing free
 
 `startSession()` throws a `SimStreamError`. The `code` says what to do about it:

package/dist/index.d.ts

@@ -10,6 +10,7 @@
  * customer and the tenth, and the day one of them needs a method the others cannot have, the
  * separation has stopped being real.
  */
+import type { SourceAnswer } from './source';
 export interface SimStreamOptions {
     /** Coordinator base URL, e.g. https://simstream.example */
     baseUrl: string;
@@ -41,10 +42,24 @@ export interface DeviceKind {
     count: number;
     free: number;
 }
+/**
+ * Which of a simulator's two apps something is.
+ *
+ * ‼️ A PREVIEW HOST IS NOT THE APP. `preview` is a build whose @main is generated: it carries every
+ * screen the project was written with and swaps between them live, which is what to look at while a
+ * screen is being built. `app` is the person's own binary, launched from their own @main — the only
+ * one that runs their launch sequence, their delegate, their deep links and their navigation, and so
+ * the only one that is the app rather than a picture of it.
+ *
+ * Nothing in a .app says which it is, so whoever built it says so when they push it.
+ */
+export type SimMode = 'app' | 'preview';
 export interface AppStatus {
     /** Empty when nothing has been pushed to this simulator yet. */
     phase?: 'downloading' | 'installing' | 'launching' | 'ready' | 'failed';
     bundle?: string;
+    /** Which of the two this install is, when the push said so. */
+    mode?: SimMode;
     /** Present only with phase 'failed', and it says what went wrong rather than that it did. */
     error?: string;
     elapsed?: string;
@@ -52,6 +67,13 @@ export interface AppStatus {
 export interface StartOptions {
     /** A .app directory, or a .zip/.tar.gz containing one. Simulator builds, not .ipa. */
     app?: string;
+    /**
+     * A build in this project's registry, by its opaque id. Use this rather than `app` for anything
+     * that was uploaded: a registry record has no URL a caller could pass, on purpose.
+     */
+    build?: string;
+    /** …or a channel pointer, which moves to whatever was uploaded last. */
+    channel?: string;
     /**
      * The kind of device to open — "iPad", "iphone-17", or an exact udid.
      *
@@ -61,6 +83,11 @@ export interface StartOptions {
     device?: string;
     /** Launch it once installed. Default true. */
     launch?: boolean;
+    /**
+     * Which of the simulator's two apps `app` is. Say so whenever you intend to push the other one
+     * too: an unlabelled build runs perfectly well and simply cannot be switched away from.
+     */
+    mode?: SimMode;
     /**
      * Wait for a device when the fleet is full or this customer is at its limit, instead of
      * failing. The wait is usually seconds — a session ends every time somebody closes a tab.
@@ -93,7 +120,171 @@ export interface CustomerUsage {
     live: number;
     cost: number;
 }
-export type SimStreamErrorCode = 'unauthorized' | 'quota' | 'capacity' | 'timeout' | 'gone' | 'http';
+/** What a simulator says about its own two apps. */
+export interface SessionMode {
+    /** What is on screen. Absent on a simulator holding one unlabelled build. */
+    running?: SimMode;
+    /** What it can be switched to, right now. */
+    holds: SimMode[];
+    /** The bundle id on screen, so two launches of the same mode are tellable apart. */
+    bundle?: string;
+    /**
+     * Whether what is on screen takes live screen selection. False in `app` mode, and that is not a
+     * fault: the person's own binary carries no listener of ours.
+     */
+    live: boolean;
+}
+/** A rectangle in device points, in the window's own space. */
+export interface Rect {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+/**
+ * One thing on the screen.
+ *
+ * ‼️ `witness` IS NOT DECORATION, IT IS HOW MUCH THE ROW KNOWS ABOUT ITSELF. `ax` and `view` rows
+ * came from something the app can name — they carry a label, a role, a value. A `layer` row is a
+ * rectangle the app draws and cannot name: on a SwiftUI screen that is most of the card backgrounds
+ * and images, and it is selectable precisely because it would otherwise be invisible to this. Code
+ * that treats the two alike will one day report a shadow as a button.
+ */
+export interface UiNode {
+    id: number;
+    class: string;
+    label?: string;
+    /**
+     * The `accessibilityIdentifier` the app's author wrote, when there is one.
+     *
+     * ‼️ PREFER THIS OVER `label` FOR ANYTHING THAT HAS TO BE RIGHT TWICE. A label is what the screen
+     * says today: it gets translated, reworded, or drawn as an icon, and two different controls happily
+     * share one — the testbed has two buttons both reading "Continue", on purpose. An identifier is
+     * written in code and stays. Absent when the app never set one; present on almost everything in an
+     * app PalCore generated, because its template requires one on every control.
+     */
+    identifier?: string;
+    value?: string;
+    frame: Rect;
+    pressable?: boolean;
+    selected?: boolean;
+    enabled?: boolean;
+    /** `ax`, `view` or `layer`. */
+    w?: 'ax' | 'view' | 'layer';
+}
+export interface UiTree {
+    /** The device's own size in points — turn a frame into a position with frame/device. */
+    device: Rect;
+    nodes: UiNode[];
+    /**
+     * What this reading could not do, said out loud.
+     *
+     * ‼️ AN EMPTY LIST IS A CLAIM AND A FULL ONE IS AN EXPLANATION. A witness that did not run leaves
+     * a sentence here rather than a shorter list with no reason, so "clean screen" and "could not
+     * look" are never the same answer.
+     */
+    notes?: string[];
+}
+/** Which of the app's own `#Preview`s was on screen when an element was marked. */
+export interface ShownScreen {
+    previewId: string;
+    group: string;
+    state: string;
+    /** Swift's fileID — MODULE/FILE, not a path on disk. */
+    file: string;
+    line: number;
+}
+/** A marked element, with everything the service knows about it. */
+export interface SelectedElement {
+    /** Minted by the viewer, so a chip in your UI and this record are the same thing. */
+    pickId: string;
+    node: number;
+    frame: Rect;
+    label?: string;
+    /** The id the app's author wrote on the element — see {@link UiNode.identifier}. */
+    identifier?: string;
+    screen?: ShownScreen;
+    source: SourceAnswer;
+}
+/**
+ * One build in this project's registry.
+ *
+ * ‼️ THESE FIELD NAMES ARE THE COORDINATOR'S, AND THAT DIRECTION IS THE POINT. The one definition
+ * of the wire is `buildView`'s JSON tags in `coordinator/builds.go`; `cli/client.go` and the Swift
+ * SDK read from there too. This interface once spoke camelCase and agreed only with the Swift SDK
+ * — the two clients matched each other and neither matched the server. Measured 2026-08-27 against
+ * the coordinator's real answer: `page.builds[0].bundleId` came back `undefined`, silently, because
+ * the body is an `as` cast and TypeScript has nothing to check it against.
+ *
+ * There is no bucket, no key and no presigned URL here, and there will not be: an API answer is a
+ * place things get logged, and a presigned URL is a bearer token with a clock on it.
+ */
+export interface Build {
+    /** Opaque. The only identifier that appears in a link or on the wire. */
+    id: string;
+    /**
+     * `sha256:…` over the .app TREE, not over the archive it arrived in — a zip is not canonical and
+     * carries mtimes, so the same directory compressed twice is two byte strings and would be two
+     * builds.
+     */
+    digest: string;
+    /** `uploading`, `published`, `rejected`. Always on the wire. */
+    status: string;
+    /**
+     * ‼️ ALL OPTIONAL, BECAUSE THE COORDINATOR WRITES THEM `omitempty`. A build has a record before
+     * it has been extracted, and at that point it has no Info.plist field at all.
+     */
+    bundle_id?: string;
+    version_name?: string;
+    version_code?: string;
+    min_os?: string;
+    /** `UIDeviceFamily`: 1 iPhone, 2 iPad. */
+    device_family?: number[];
+    /** Whatever the uploader wrote about this build; the coordinator calls it `description`. */
+    description?: string;
+    bytes: number;
+    /** RFC 3339, UTC. */
+    created_at: string;
+}
+export interface BuildPage {
+    builds: Build[];
+    /**
+     * Pass back as `cursor` for the next page. Absent on the last one.
+     *
+     * ‼️ IT IS CALLED `next` BECAUSE THAT IS WHAT THE WIRE CALLS IT. There was never a `nextCursor`
+     * field in the coordinator's answer, so this read `undefined` on every page and pagination
+     * stopped silently after the first one — no error, just a short list.
+     */
+    next?: string;
+}
+/** Which build to run: the record's own immutable id, or a channel that moves as uploads land. */
+export type BuildRef = {
+    build: string;
+} | {
+    channel: string;
+};
+/**
+ * A project the caller can reach: what a build is uploaded to and what a session is billed to.
+ *
+ * ‼️ THE FIELD NAMES ARE THE COORDINATOR'S, AND THIS DIRECTION IS DELIBERATE. The one definition
+ * of this wire shape is `projectView`'s JSON tags in `coordinator/store.go`; the Swift SDK reads
+ * the same words. `Build` above learnt this the expensive way — it once spoke camelCase, matched
+ * only itself, and every non-empty registry crashed the Swift client with
+ * `keyNotFound("bundleId")`. Renaming a field here is now visible work in three clients at once.
+ */
+export interface Project {
+    /** Opaque. This is what `--project` names and what a key is issued against. */
+    id: string;
+    /** Unique inside the organization, which is why it is usable as a human's choice. */
+    name: string;
+    /** How many sessions this project has run. A measurement, not an invoice. */
+    sessions?: number;
+    seconds?: number;
+    cost?: number;
+}
+export type SimStreamErrorCode = 'unauthorized' | 'quota' | 'capacity' | 'timeout' | 'gone'
+/** The Mac holding this session runs an agent older than the method you called. */
+ | 'stale-fleet' | 'http';
 export declare class SimStreamError extends Error {
     readonly code: SimStreamErrorCode;
     readonly status?: number | undefined;
@@ -128,10 +319,59 @@ export declare class SimStream {
     pushBuild(app: string, opts?: {
         version?: string;
         launch?: boolean;
+        mode?: SimMode;
     }): Promise<{
         hosts: number;
         version?: string;
     }>;
+    /**
+     * What this project has uploaded, newest first.
+     *
+     * ‼️ THE LIST IS THE POINT. Without it a customer keeps its own catalogue of URLs and versions —
+     * which is to say the version list lives on their side and this service holds bytes it cannot
+     * name. Paged by cursor: send back the `next` you were given, and its absence is the last
+     * page. Only this project's records are ever returned.
+     */
+    listBuilds(opts?: {
+        cursor?: string;
+        limit?: number;
+    }): Promise<BuildPage>;
+    /**
+     * Put a build in this project's registry: the .app zipped, as the CLI's `simstream upload` sends it.
+     *
+     * Three requests, the ones the coordinator reads (`coordinator/builds.go`): start an upload with the archive's size
+     * and a description, PUT the bytes to the presigned address that answers, and complete it — which is when the
+     * coordinator reads the archive back, refuses a device build or anything that is not a simulator .app, publishes it
+     * and moves the app's `latest` channel to it.
+     *
+     * ‼️ THE PUT CARRIES NO KEY. It goes to the object store, not the coordinator; the address is the capability, and the
+     * customer's key has no business at a storage host.
+     *
+     * ‼️ THE ARCHIVE IS SIZED. A presigned PUT needs its length up front and the coordinator checks the object against the
+     * size it was told, so the bytes are a Uint8Array or a Blob rather than a stream of unknown length.
+     */
+    uploadBuild(archive: Uint8Array | Blob, opts?: {
+        description?: string;
+        signal?: AbortSignal;
+    }): Promise<Build>;
+    /**
+     * Point one of a build's app channels at it — `beta`, `demo`, anything of a-z, 0-9, - and _ up to 32 characters.
+     * Completing an upload already moves `latest`; this is for the channels a team names itself.
+     */
+    setChannel(build: string, channel: string): Promise<{
+        channel: string;
+        app: string;
+        build: string;
+    }>;
+    /**
+     * Open a session with a registry build already on it.
+     *
+     * This is `startSession` with the bytes named by record rather than by address — same queueing,
+     * same errors, same session. Name a build by id to pin a version for good, or a channel to get
+     * whatever was uploaded last: `{ channel: 'com.example.app:latest' }` is the same target a share
+     * link follows, so a demo and a tester see the same build without anybody reissuing anything.
+     */
+    runBuild(ref: BuildRef, opts?: StartOptions): Promise<Session>;
     /**
      * A fresh link to a session that is already running.
      *
@@ -183,6 +423,27 @@ export declare class SimStream {
         screen?: string;
         variant?: string;
     }): Promise<void>;
+    /**
+     * Which of the simulator's two apps is on screen, and what it can be switched to.
+     *
+     * ‼️ THIS IS A LAUNCH, AND showPreview IS A MESSAGE. Picking a screen lands inside the process
+     * that is already running and arrives in a frame. Switching mode is a different bundle with a
+     * different bundle id, so it costs a terminate and a start — a second or two, because both builds
+     * are already on the device, rather than the build it would otherwise mean.
+     *
+     * `setMode` is rejected when that simulator was never given the build being asked for, and the
+     * message says which of the two it IS holding — "no app build" and "no build at all" send you to
+     * different places. Push both, labelled, and the switch is always available.
+     */
+    mode(session: string): Promise<SessionMode>;
+    /**
+     * Run the person's own app, or go back to the preview host.
+     *
+     * See `mode()` for reading where a session stands without moving it — which is what a panel
+     * drawing the toggle needs on load, because POSTing the mode it GUESSES is current is a relaunch
+     * every time the guess is wrong.
+     */
+    setMode(session: string, mode: SimMode): Promise<SessionMode>;
     /**
      * Press one of the simulator's hardware buttons.
      *
@@ -216,6 +477,42 @@ export declare class SimStream {
      * of the switch — and on a fleet with one device free, refused the very thing they asked for.
      */
     switchDevice(session: string, device: string, opts?: StartOptions): Promise<Session>;
+    /**
+     * Everything on the screen: what the app can name, and what it can only draw.
+     *
+     * ‼️ IT ANSWERS IN BOTH OF A DEVICE'S MODES. `setMode('app')` reports `live: false`, and that means
+     * one thing — the person's own binary carries no listener for a CHOICE OF SCREEN. Reading what is
+     * drawn is a different question, and it works while somebody is using their own app.
+     */
+    inspect(session: string): Promise<UiTree>;
+    /**
+     * What is drawn at a point — for a caller with no person clicking.
+     *
+     * Send both numbers as ratios of the picture (0..1) or both as device points. One of each is
+     * refused rather than guessed: a click a hair outside the picture arrives as 1.02, and read as
+     * points that is the top-left corner and a completely different element.
+     */
+    elementAt(session: string, at: {
+        x: number;
+        y: number;
+    }): Promise<{
+        node?: UiNode;
+        nothing?: boolean;
+        device: Rect;
+    }>;
+    /** One element's full properties, as the app reports them: colour, font, padding, ancestors. */
+    inspectNode(session: string, node: number): Promise<Record<string, unknown>>;
+    /**
+     * Everything a person has marked on this session's screen.
+     *
+     * The viewer posts only an identity to your page; this is where the record lives. That is the
+     * separation on purpose: the data path is this SDK, and the browser is where the gesture happens.
+     */
+    picks(session: string): Promise<SelectedElement[]>;
+    /** One of them, by the id the viewer gave your page. */
+    pick(session: string, pickId: string): Promise<SelectedElement | undefined>;
+    /** Drop one mark, or every mark on this session, and the viewer's highlight goes with it. */
+    clearPicks(session: string, pickId?: string): Promise<void>;
     /** What this customer has used, in total. A measurement, not an invoice. */
     usage(): Promise<CustomerUsage[]>;
     /**
@@ -224,10 +521,25 @@ export declare class SimStream {
      * rewrite what somebody already used.
      */
     sessions(): Promise<UsageRecord[]>;
+    /**
+     * The projects this credential can reach.
+     *
+     * Without it a caller holding one credential and several projects has to be told out of band
+     * which id to name — and an id somebody pasted from a chat is how a build lands in the wrong
+     * project.
+     *
+     * ‼️ A BARE ARRAY AND A `{"projects":…}` ENVELOPE READ THE SAME, ON PURPOSE. The coordinator
+     * writes both shapes today — `/api/usage` answers a bare array, `/api/me` puts projects under a
+     * key — and which one this route picks is not this SDK's decision to make. Tolerating both here
+     * costs one line; getting it wrong costs an empty list with nothing reporting an error.
+     */
+    listProjects(): Promise<Project[]>;
     private sessionUrl;
     private collect;
     private request;
     private errorFor;
 }
+export { resolveSource, isCertain } from './source';
+export type { SourceAnswer, SourceConfidence } from './source';
 export { SimStreamAdmin } from './admin';
 export type { AdminOptions, Customer } from './admin';

package/dist/index.js

@@ -12,7 +12,7 @@
  * separation has stopped being real.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SimStreamAdmin = exports.SimStream = exports.SimStreamError = void 0;
+exports.SimStreamAdmin = exports.isCertain = exports.resolveSource = exports.SimStream = exports.SimStreamError = void 0;
 class SimStreamError extends Error {
     code;
     status;
@@ -55,7 +55,10 @@ class SimStream {
     async startSession(opts = {}) {
         const body = {
             app: opts.app,
+            build: opts.build,
+            channel: opts.channel,
             launch: opts.launch,
+            mode: opts.mode,
             queue: opts.wait === true,
             device: opts.device,
         };
@@ -95,11 +98,101 @@ class SimStream {
             app,
             version: opts.version,
             launch: opts.launch,
+            mode: opts.mode,
         });
         if (res.status !== 200)
             throw await this.errorFor(res);
         return (await res.json());
     }
+    /**
+     * What this project has uploaded, newest first.
+     *
+     * ‼️ THE LIST IS THE POINT. Without it a customer keeps its own catalogue of URLs and versions —
+     * which is to say the version list lives on their side and this service holds bytes it cannot
+     * name. Paged by cursor: send back the `next` you were given, and its absence is the last
+     * page. Only this project's records are ever returned.
+     */
+    async listBuilds(opts = {}) {
+        const q = new URLSearchParams();
+        if (opts.cursor)
+            q.set('cursor', opts.cursor);
+        if (opts.limit)
+            q.set('limit', String(opts.limit));
+        const query = q.toString();
+        const res = await this.request('GET', `/api/builds${query ? `?${query}` : ''}`);
+        if (res.status !== 200)
+            throw await this.errorFor(res);
+        // The cast says `builds?` although the wire type does not: TypeScript 5.6+ makes `x ?? y`
+        // an error when the left side can never be nullish, and an empty registry answers `{}`.
+        const page = (await res.json());
+        // ‼️ AN EMPTY STRING IS NOT A CURSOR. `next` has no `omitempty` on the coordinator's side, so
+        // the last page arrives as exactly `{"builds":[],"next":""}` — dumped from the handler, not
+        // guessed. A loop that treats "" as a cursor asks for `cursor=` forever.
+        return { builds: page.builds ?? [], next: page.next || undefined };
+    }
+    /**
+     * Put a build in this project's registry: the .app zipped, as the CLI's `simstream upload` sends it.
+     *
+     * Three requests, the ones the coordinator reads (`coordinator/builds.go`): start an upload with the archive's size
+     * and a description, PUT the bytes to the presigned address that answers, and complete it — which is when the
+     * coordinator reads the archive back, refuses a device build or anything that is not a simulator .app, publishes it
+     * and moves the app's `latest` channel to it.
+     *
+     * ‼️ THE PUT CARRIES NO KEY. It goes to the object store, not the coordinator; the address is the capability, and the
+     * customer's key has no business at a storage host.
+     *
+     * ‼️ THE ARCHIVE IS SIZED. A presigned PUT needs its length up front and the coordinator checks the object against the
+     * size it was told, so the bytes are a Uint8Array or a Blob rather than a stream of unknown length.
+     */
+    async uploadBuild(archive, opts = {}) {
+        const bytes = archive instanceof Uint8Array ? archive.byteLength : archive.size;
+        const started = await this.request('POST', '/api/builds/upload', {
+            bytes,
+            ...(opts.description ? { description: opts.description } : {}),
+        });
+        if (started.status !== 200)
+            throw await this.errorFor(started);
+        const upload = (await started.json());
+        if (!upload.upload_id || !upload.url)
+            throw new SimStreamError('the coordinator started an upload with no destination', 'http');
+        // Checked here as well as on the server, so an archive past the ceiling fails before it is sent rather than after.
+        if (upload.max_bytes && bytes > upload.max_bytes) {
+            throw new SimStreamError(`the archive is ${bytes} bytes and this coordinator accepts ${upload.max_bytes} bytes`, 'http', 413);
+        }
+        const put = await this.fetchImpl(upload.url, {
+            method: 'PUT',
+            headers: { 'content-type': 'application/zip' },
+            body: archive,
+            ...(opts.signal ? { signal: opts.signal } : {}),
+        });
+        if (!put.ok)
+            throw new SimStreamError(`the archive could not be stored (${put.status})`, 'http', put.status);
+        const completed = await this.request('POST', `/api/builds/upload/${encodeURIComponent(upload.upload_id)}/complete`);
+        if (completed.status !== 200)
+            throw await this.errorFor(completed);
+        return (await completed.json());
+    }
+    /**
+     * Point one of a build's app channels at it — `beta`, `demo`, anything of a-z, 0-9, - and _ up to 32 characters.
+     * Completing an upload already moves `latest`; this is for the channels a team names itself.
+     */
+    async setChannel(build, channel) {
+        const res = await this.request('POST', `/api/builds/${encodeURIComponent(build)}/channel`, { channel });
+        if (res.status !== 200)
+            throw await this.errorFor(res);
+        return (await res.json());
+    }
+    /**
+     * Open a session with a registry build already on it.
+     *
+     * This is `startSession` with the bytes named by record rather than by address — same queueing,
+     * same errors, same session. Name a build by id to pin a version for good, or a channel to get
+     * whatever was uploaded last: `{ channel: 'com.example.app:latest' }` is the same target a share
+     * link follows, so a demo and a tester see the same build without anybody reissuing anything.
+     */
+    async runBuild(ref, opts = {}) {
+        return this.startSession({ ...opts, ...ref });
+    }
     /**
      * A fresh link to a session that is already running.
      *
@@ -163,6 +256,37 @@ class SimStream {
         if (res.status !== 200)
             throw await this.errorFor(res);
     }
+    /**
+     * Which of the simulator's two apps is on screen, and what it can be switched to.
+     *
+     * ‼️ THIS IS A LAUNCH, AND showPreview IS A MESSAGE. Picking a screen lands inside the process
+     * that is already running and arrives in a frame. Switching mode is a different bundle with a
+     * different bundle id, so it costs a terminate and a start — a second or two, because both builds
+     * are already on the device, rather than the build it would otherwise mean.
+     *
+     * `setMode` is rejected when that simulator was never given the build being asked for, and the
+     * message says which of the two it IS holding — "no app build" and "no build at all" send you to
+     * different places. Push both, labelled, and the switch is always available.
+     */
+    async mode(session) {
+        const res = await this.request('GET', `/api/session/mode?session=${encodeURIComponent(session)}`);
+        if (res.status !== 200)
+            throw await this.errorFor(res);
+        return (await res.json());
+    }
+    /**
+     * Run the person's own app, or go back to the preview host.
+     *
+     * See `mode()` for reading where a session stands without moving it — which is what a panel
+     * drawing the toggle needs on load, because POSTing the mode it GUESSES is current is a relaunch
+     * every time the guess is wrong.
+     */
+    async setMode(session, mode) {
+        const res = await this.request('POST', '/api/session/mode', { session, mode });
+        if (res.status !== 200)
+            throw await this.errorFor(res);
+        return (await res.json());
+    }
     /**
      * Press one of the simulator's hardware buttons.
      *
@@ -206,6 +330,62 @@ class SimStream {
         await this.endSession(session);
         return this.startSession({ ...opts, device });
     }
+    /**
+     * Everything on the screen: what the app can name, and what it can only draw.
+     *
+     * ‼️ IT ANSWERS IN BOTH OF A DEVICE'S MODES. `setMode('app')` reports `live: false`, and that means
+     * one thing — the person's own binary carries no listener for a CHOICE OF SCREEN. Reading what is
+     * drawn is a different question, and it works while somebody is using their own app.
+     */
+    async inspect(session) {
+        const res = await this.request('GET', `/api/session/inspect?session=${encodeURIComponent(session)}`);
+        if (res.status !== 200)
+            throw await this.errorFor(res);
+        return (await res.json());
+    }
+    /**
+     * What is drawn at a point — for a caller with no person clicking.
+     *
+     * Send both numbers as ratios of the picture (0..1) or both as device points. One of each is
+     * refused rather than guessed: a click a hair outside the picture arrives as 1.02, and read as
+     * points that is the top-left corner and a completely different element.
+     */
+    async elementAt(session, at) {
+        const res = await this.request('POST', '/api/session/inspect/at', { session, ...at });
+        if (res.status !== 200)
+            throw await this.errorFor(res);
+        return (await res.json());
+    }
+    /** One element's full properties, as the app reports them: colour, font, padding, ancestors. */
+    async inspectNode(session, node) {
+        const res = await this.request('GET', `/api/session/inspect/node?session=${encodeURIComponent(session)}&n=${node}`);
+        if (res.status !== 200)
+            throw await this.errorFor(res);
+        return (await res.json());
+    }
+    /**
+     * Everything a person has marked on this session's screen.
+     *
+     * The viewer posts only an identity to your page; this is where the record lives. That is the
+     * separation on purpose: the data path is this SDK, and the browser is where the gesture happens.
+     */
+    async picks(session) {
+        const res = await this.request('GET', `/api/session/inspect/picks?session=${encodeURIComponent(session)}`);
+        if (res.status !== 200)
+            throw await this.errorFor(res);
+        return (await res.json()).picks ?? [];
+    }
+    /** One of them, by the id the viewer gave your page. */
+    async pick(session, pickId) {
+        return (await this.picks(session)).find((p) => p.pickId === pickId);
+    }
+    /** Drop one mark, or every mark on this session, and the viewer's highlight goes with it. */
+    async clearPicks(session, pickId) {
+        const q = pickId ? `&pick=${encodeURIComponent(pickId)}` : '';
+        const res = await this.request('DELETE', `/api/session/inspect/picks?session=${encodeURIComponent(session)}${q}`);
+        if (res.status !== 200)
+            throw await this.errorFor(res);
+    }
     /** What this customer has used, in total. A measurement, not an invoice. */
     async usage() {
         const res = await this.request('GET', '/api/usage');
@@ -224,6 +404,27 @@ class SimStream {
             throw await this.errorFor(res);
         return (await res.json());
     }
+    /**
+     * The projects this credential can reach.
+     *
+     * Without it a caller holding one credential and several projects has to be told out of band
+     * which id to name — and an id somebody pasted from a chat is how a build lands in the wrong
+     * project.
+     *
+     * ‼️ A BARE ARRAY AND A `{"projects":…}` ENVELOPE READ THE SAME, ON PURPOSE. The coordinator
+     * writes both shapes today — `/api/usage` answers a bare array, `/api/me` puts projects under a
+     * key — and which one this route picks is not this SDK's decision to make. Tolerating both here
+     * costs one line; getting it wrong costs an empty list with nothing reporting an error.
+     */
+    async listProjects() {
+        const res = await this.request('GET', '/api/projects');
+        if (res.status !== 200)
+            throw await this.errorFor(res);
+        const body = (await res.json());
+        if (Array.isArray(body))
+            return body;
+        return body?.projects ?? [];
+    }
     sessionUrl(ttl) {
         return ttl ? `/api/session?ttl=${encodeURIComponent(ttl)}` : '/api/session';
     }
@@ -265,10 +466,18 @@ class SimStream {
             : res.status === 429 ? 'quota'
                 : res.status === 503 ? 'capacity'
                     : res.status === 410 ? 'gone'
-                        : 'http';
+                        // ‼️ 501 IS THE FLEET BEING BEHIND, WHICH IS NOT A FAULT OF THE CALL. The coordinator and the
+                        // Macs ship separately, so a method added here can reach a Mac that has never heard of it. The
+                        // message names the Mac and what to do; the code exists so a caller can retry after an update
+                        // instead of treating it like a bad request.
+                        : res.status === 501 ? 'stale-fleet'
+                            : 'http';
         return new SimStreamError(text || `HTTP ${res.status}`, code, res.status);
     }
 }
 exports.SimStream = SimStream;
+var source_1 = require("./source");
+Object.defineProperty(exports, "resolveSource", { enumerable: true, get: function () { return source_1.resolveSource; } });
+Object.defineProperty(exports, "isCertain", { enumerable: true, get: function () { return source_1.isCertain; } });
 var admin_1 = require("./admin");
 Object.defineProperty(exports, "SimStreamAdmin", { enumerable: true, get: function () { return admin_1.SimStreamAdmin; } });

package/dist/source.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Where a selected element was written, and how sure the answer is.
+ *
+ * ‼️ THIS IS ITS OWN FILE BECAUSE THE ANSWER IS GOING TO GET BETTER AND THE SHAPE MUST NOT.
+ * Today one mechanism fills it: the build's dSYM, which knows the line a view type's `body` is
+ * written on. Two more are designed and not built — a compile-time map of every expression, and a
+ * search of the caller's own checkout — and both answer the same question. Callers that read
+ * `file`, `startLine` and `confidence` keep working when they land.
+ */
+/** How much to trust the location. */
+export type SourceConfidence = 
+/** One view type on this element's chain was written in the project, and it resolved. */
+'high'
+/** Several fit, and none of them is the answer — read `candidates`. */
+ | 'low'
+/** No location: `note` says why, and it is a reason rather than a failure. */
+ | 'none';
+export interface SourceAnswer {
+    /** Relative to the source root, with the build machine's own path removed. */
+    file?: string;
+    /** The line the view's `body` is written on. */
+    startLine?: number;
+    /** The last line of the deepest thing written inside that body. */
+    endLine?: number;
+    /** Which mechanism answered: `dsym` today, `none` when nothing could. */
+    via: string;
+    confidence: SourceConfidence;
+    /**
+     * Every location that fits, when more than one does.
+     *
+     * ‼️ READ THIS BEFORE ACTING ON A `low` ANSWER. A wrong line is worse than no line: an agent
+     * believes it and edits there. The service refuses to pick for you on purpose — the last system
+     * that picked recoloured the wrong element in front of somebody.
+     */
+    candidates?: SourceAnswer[];
+    /** Why the answer is the size it is. Present exactly when it needs to be. */
+    note?: string;
+}
+/**
+ * The source location for a selected element.
+ *
+ * The record the SDK already handed you carries this; the function exists so that the day a
+ * caller's own checkout can narrow it further, the call site does not change — only what it can
+ * reach does.
+ */
+export declare function resolveSource(record: {
+    source?: SourceAnswer;
+}): SourceAnswer;
+/** True when this answer names one place and means it. */
+export declare function isCertain(answer: SourceAnswer): boolean;

package/dist/source.js

@@ -0,0 +1,32 @@
+"use strict";
+/**
+ * Where a selected element was written, and how sure the answer is.
+ *
+ * ‼️ THIS IS ITS OWN FILE BECAUSE THE ANSWER IS GOING TO GET BETTER AND THE SHAPE MUST NOT.
+ * Today one mechanism fills it: the build's dSYM, which knows the line a view type's `body` is
+ * written on. Two more are designed and not built — a compile-time map of every expression, and a
+ * search of the caller's own checkout — and both answer the same question. Callers that read
+ * `file`, `startLine` and `confidence` keep working when they land.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveSource = resolveSource;
+exports.isCertain = isCertain;
+/**
+ * The source location for a selected element.
+ *
+ * The record the SDK already handed you carries this; the function exists so that the day a
+ * caller's own checkout can narrow it further, the call site does not change — only what it can
+ * reach does.
+ */
+function resolveSource(record) {
+    return (record.source ?? {
+        via: 'none',
+        confidence: 'none',
+        note: 'this record carries no source answer at all, which means it was made by a version of ' +
+            'the service that predates them',
+    });
+}
+/** True when this answer names one place and means it. */
+function isCertain(answer) {
+    return answer.confidence === 'high' && !!answer.file && !!answer.startLine;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@palgroup/simstream",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "Start and drive remote iOS simulator sessions.",
   "license": "Apache-2.0",
   "main": "dist/index.js",