@stim-cli/server 1.12.0 → 1.13.0

package/README.md

@@ -165,23 +165,31 @@ Events are `{ "event", "subscription", ... }`.
   `$STIM_HOME/server/helpers/`, named by a hash of the sources and the
   compiler version. For a simulator it renders the display's framebuffer
   (CoreSimulator's IOSurface) when the display reports damage, turned
-  upright; for an emulator it keeps one gRPC `streamScreenshot` call open,
+  upright. An iPhone Duo lights one of its two panels, the cover while
+  folded and the inner panel while unfolded, and leaves the other black, so
+  the helper streams whichever panel is lit; its frames and video carry
+  `posture`, and the size changes with the panel. For an emulator it keeps one gRPC `streamScreenshot` call open,
   found through the discovery file and token the emulator writes when Stim
   boots it. It scales frames to fit the largest `maxEdge` and paces them to
   the highest `fps` its subscribers asked for. All subscribers of a device
-  share one helper, which sends a new subscriber the latest frame and exits
-  with the last subscriber or when the server's end of its stdin closes.
+  share one helper, which sends a new subscriber the latest frame. It keeps
+  running for 10 seconds after the last subscriber leaves, so a client that
+  subscribes for one frame at a time reuses it and gets the latest frame at
+  once, and exits after that or when the server's end of its stdin closes.
 
   A client that decodes H.264 adds `video: ["h264"]`. When the helper is
   built, the result carries `video: "h264"`, `fps` may go up to 60, and
   frames arrive as binary WebSocket messages instead of `frame` events: a
   big-endian header (u8 version 1, u8 flags with bit 0 set on a keyframe,
+  and on an iPhone Duo bit 1 while folded or bit 2 while unfolded,
   u16 header length, u32 sequence number of the messages sent on this
   subscription, f64 capture time in milliseconds since the epoch on the
   Mac's clock, u16 width, u16 height, u8 subscription id length and the
   ASCII id), then one Annex-B access unit. Every keyframe carries its SPS
   and PPS, and the stream has no B-frames, so each access unit is shown as
-  it arrives. The helper encodes with VideoToolbox in real time: Main
+  it arrives. A change of size, such as a rotation or a Duo fold, restarts
+  the encoder, and the next access unit is a keyframe with the new SPS and
+  PPS. The helper encodes with VideoToolbox in real time: Main
   profile, a keyframe at least every 2 seconds, straight from the
   simulator's IOSurface or from the emulator's RGBA frames, only when the
   screen changed. A subscriber starts at a keyframe, and `frames.keyframe`
@@ -195,13 +203,13 @@ Events are `{ "event", "subscription", ... }`.
   subscribers of the same device still get at most the `fps` they asked
   for. Watching video needs only `read`. Without the helper, the result has
   no `video`, `fps` above 30 is lowered to 30, and `frame` events arrive as
-  before; an iPhone Duo and a helper that fails before its first frame also
-  fall back to `frame` events within a video subscription.
+  before; a helper that fails before its first frame also falls back to
+  `frame` events within a video subscription.
 
   Without the helper (the compiler is missing or fails, which the server
-  retries every 5 minutes, or the helper fails before its first frame), for a
-  subscription made while it is still being built, and for an iPhone Duo,
-  frames come from screenshots, and `fps` and `maxEdge` only cap the rate. Simulators are
+  retries every 5 minutes, or the helper fails before its first frame), and
+  for a subscription made while it is still being built, frames come from
+  screenshots, and `fps` and `maxEdge` only cap the rate. Simulators are
   captured with `xcrun simctl io <udid> screenshot`, of the primary display,
   or of the default display when that `simctl` does not accept `primary`. An
   iPhone Duo lights one of two panels: the capture follows the lit one
@@ -365,7 +373,8 @@ streams its frames:
   through gRPC `setPhysicalModel` for rotation and `setPosture` for its hinge.
   An iPhone Duo folds with `sim-fold`, which the server builds from Stim
   Desktop's sources on the first fold and runs inside the simulator with
-  `xcrun simctl spawn`; it answers `{}` once the fold finished. `sim-fold`
+  `xcrun simctl spawn`; it answers `{}` once the fold finished, and fails
+  with `action-failed` when the fold does not finish within 40 seconds. `sim-fold`
   swaps the posture, so the server runs it only when the Duo's latest frame
   shows the other posture, and refuses the request until a frame showed one.
 

package/dist/{protocol-BElQc2vm.mjs → protocol-rC-5KT1O.mjs}

@@ -67,6 +67,12 @@ const LOG_LEVELS = [
 	"fatal"
 ];
 const MAX_LOG_TAIL = 5e3;
+/** `reload` also reaches the workspace's Stim-owned Chrome page. */
+const RELOAD_PLATFORMS = [
+	"ios",
+	"android",
+	"web"
+];
 const FRAME_FPS = {
 	default: 5,
 	max: 30,
@@ -81,6 +87,9 @@ const VIDEO_CODECS = ["h264"];
 const VIDEO_HEADER_VERSION = 1;
 /** The keyframe bit of a {@link VideoPacket}'s flags. */
 const VIDEO_KEYFRAME = 1;
+/** The flag bits of a {@link VideoPacket} that carry an iPhone Duo's posture, as `posture` on a `frame` event. */
+const VIDEO_FOLDED = 2;
+const VIDEO_UNFOLDED = 4;
 /** Each action runs one fixed `stim` command in the workspace. */
 const ACTIONS = ["reload", "stop"];
 const TOUCH_PHASES = [
@@ -263,7 +272,12 @@ function protocolJsonSchema() {
 					ts: { type: "number" },
 					src: { type: "string" },
 					level: { type: "string" },
-					msg: { type: "string" }
+					msg: { type: "string" },
+					context: {
+						type: "array",
+						items: { type: "string" },
+						description: "With `errors`: the code frame and stack lines Expo printed after this error."
+					}
 				}
 			},
 			LogFilter: {
@@ -343,7 +357,7 @@ function protocolJsonSchema() {
 						type: "string",
 						description: "An environment path from a status payload."
 					},
-					platform: { enum: ["ios", "android"] }
+					platform: { enum: [...RELOAD_PLATFORMS] }
 				}
 			}, {
 				type: "object",
@@ -805,4 +819,4 @@ function protocolJsonSchema() {
 	};
 }
 //#endregion
-export { TOUCH_PHASES as _, ERROR_CODES as a, VIDEO_KEYFRAME as b, INPUT_BUTTONS as c, MAX_INPUT_TEXT as d, MAX_LOG_TAIL as f, ROTATE_DIRECTIONS as g, PROTOCOL_VERSION as h, DEVICE_POSTURES as i, LOG_LEVELS as l, PROTOCOL_SCHEMA_FILE as m, CAPABILITIES as n, FRAME_EDGE as o, METHODS as p, CONTROL_END_REASONS as r, FRAME_FPS as s, ACTIONS as t, LOG_SOURCES as u, VIDEO_CODECS as v, protocolJsonSchema as x, VIDEO_HEADER_VERSION as y };
+export { VIDEO_UNFOLDED as C, VIDEO_KEYFRAME as S, ROTATE_DIRECTIONS as _, ERROR_CODES as a, VIDEO_FOLDED as b, INPUT_BUTTONS as c, MAX_INPUT_TEXT as d, MAX_LOG_TAIL as f, RELOAD_PLATFORMS as g, PROTOCOL_VERSION as h, DEVICE_POSTURES as i, LOG_LEVELS as l, PROTOCOL_SCHEMA_FILE as m, CAPABILITIES as n, FRAME_EDGE as o, METHODS as p, CONTROL_END_REASONS as r, FRAME_FPS as s, ACTIONS as t, LOG_SOURCES as u, TOUCH_PHASES as v, protocolJsonSchema as w, VIDEO_HEADER_VERSION as x, VIDEO_CODECS as y };

package/dist/protocol.d.mts

@@ -93,6 +93,9 @@ type StatsResult = Record<string, unknown>;
 /** `stim settings --json`; the CLI masks sensitive values. */
 type SettingsResult = Record<string, unknown>;
 type Platform = "ios" | "android";
+/** `reload` also reaches the workspace's Stim-owned Chrome page. */
+declare const RELOAD_PLATFORMS: readonly ["ios", "android", "web"];
+type ReloadPlatform = (typeof RELOAD_PLATFORMS)[number];
 declare const FRAME_FPS: {
   readonly default: 5;
   readonly max: 30;
@@ -122,7 +125,7 @@ declare const VIDEO_CODECS: readonly ["h264"];
 type VideoCodec = (typeof VIDEO_CODECS)[number];
 /**
  * With `video`, frames arrive as binary WebSocket messages, one H.264 access unit each; see {@link VideoPacket}.
- * A subscription whose device cannot be encoded, such as an iPhone Duo, still sends JSON `frame` events.
+ * A subscription whose device falls back to screenshots still sends JSON `frame` events.
  */
 interface FramesSubscribeResult extends SubscribeResult {
   video?: VideoCodec;
@@ -134,9 +137,12 @@ interface KeyframeParams {
 declare const VIDEO_HEADER_VERSION = 1;
 /** The keyframe bit of a {@link VideoPacket}'s flags. */
 declare const VIDEO_KEYFRAME = 1;
+/** The flag bits of a {@link VideoPacket} that carry an iPhone Duo's posture, as `posture` on a `frame` event. */
+declare const VIDEO_FOLDED = 2;
+declare const VIDEO_UNFOLDED = 4;
 /**
  * The layout of a binary video message, big-endian: u8 version ({@link VIDEO_HEADER_VERSION}), u8 flags
- * ({@link VIDEO_KEYFRAME}), u16 header length, u32 sequence number of the messages sent on this subscription, f64 capture time in milliseconds since the
+ * ({@link VIDEO_KEYFRAME}, and on an iPhone Duo {@link VIDEO_FOLDED} or {@link VIDEO_UNFOLDED}), u16 header length, u32 sequence number of the messages sent on this subscription, f64 capture time in milliseconds since the
  * epoch on the Mac's clock, u16 width, u16 height, u8 subscription id length N, N bytes of ASCII subscription
  * id. After the header comes one Annex-B H.264 access unit; a keyframe carries its SPS and PPS. The stream has
  * no B-frames, so each access unit is shown as it arrives.
@@ -148,19 +154,20 @@ interface VideoPacket {
   capturedAt: number;
   width: number;
   height: number;
+  posture?: "folded" | "unfolded";
   accessUnit: Uint8Array;
 }
 /** Each action runs one fixed `stim` command in the workspace. */
 declare const ACTIONS: readonly ["reload", "stop"];
 type ActionName = (typeof ACTIONS)[number];
 /**
- * `reload` runs `stim reload --json`, with `platform` when both platforms are live; `stop` runs
+ * `reload` runs `stim reload --json`, with `platform` when more than one platform is live; `stop` runs
  * `stim stop --json`. `workspace` is an environment `path` from a status payload. Needs `control`.
  */
 type ActionParams = {
   action: "reload";
   workspace: string;
-  platform?: Platform;
+  platform?: ReloadPlatform;
 } | {
   action: "stop";
   workspace: string;
@@ -468,4 +475,4 @@ type JsonSchema = Record<string, unknown>;
 /** The JSON Schema of every message on the wire, written to `dist/protocol.schema.json` at build time. */
 declare function protocolJsonSchema(): JsonSchema;
 //#endregion
-export { ACTIONS, ActionName, ActionParams, ActionResult, BuildPlanParams, BuildPlanResult, CAPABILITIES, CONTROL_END_REASONS, Capability, ClientRequest, ControlBeginParams, ControlBeginResult, ControlEndParams, ControlEndedEvent, DEVICE_POSTURES, DeviceAuth, DevicePosture, ERROR_CODES, ErrorCode, ErrorEvent, FRAME_EDGE, FRAME_FPS, FrameDelayedEvent, FrameEvent, FrameTarget, FramesSubscribeResult, HelloParams, HelloResult, INPUT_BUTTONS, InputButton, InputButtonParams, InputPostureParams, InputRotateParams, InputTextParams, InputTouchParams, KeyframeParams, LOG_LEVELS, LOG_SOURCES, LogFilter, LogLevel, LogRecord, LogSource, LogsEvent, LogsQueryResult, MAX_INPUT_TEXT, MAX_LOG_TAIL, METHODS, MachineHistory, MachineHistoryParams, MachineUsage, MachineVolume, MemoryPressure, Method, Methods, PROTOCOL_SCHEMA_FILE, PROTOCOL_VERSION, PairingAuth, Platform, ProtocolError, ROTATE_DIRECTIONS, RequestId, RotateDirection, ServerEvent, ServerMessage, ServerResponse, SettingsResult, StatsResult, StatusEvent, SubscribeResult, TOUCH_PHASES, TouchPhase, UnsubscribeParams, UsageSample, VIDEO_CODECS, VIDEO_HEADER_VERSION, VIDEO_KEYFRAME, VideoCodec, VideoPacket, WorkspaceParams, protocolJsonSchema };
+export { ACTIONS, ActionName, ActionParams, ActionResult, BuildPlanParams, BuildPlanResult, CAPABILITIES, CONTROL_END_REASONS, Capability, ClientRequest, ControlBeginParams, ControlBeginResult, ControlEndParams, ControlEndedEvent, DEVICE_POSTURES, DeviceAuth, DevicePosture, ERROR_CODES, ErrorCode, ErrorEvent, FRAME_EDGE, FRAME_FPS, FrameDelayedEvent, FrameEvent, FrameTarget, FramesSubscribeResult, HelloParams, HelloResult, INPUT_BUTTONS, InputButton, InputButtonParams, InputPostureParams, InputRotateParams, InputTextParams, InputTouchParams, KeyframeParams, LOG_LEVELS, LOG_SOURCES, LogFilter, LogLevel, LogRecord, LogSource, LogsEvent, LogsQueryResult, MAX_INPUT_TEXT, MAX_LOG_TAIL, METHODS, MachineHistory, MachineHistoryParams, MachineUsage, MachineVolume, MemoryPressure, Method, Methods, PROTOCOL_SCHEMA_FILE, PROTOCOL_VERSION, PairingAuth, Platform, ProtocolError, RELOAD_PLATFORMS, ROTATE_DIRECTIONS, ReloadPlatform, RequestId, RotateDirection, ServerEvent, ServerMessage, ServerResponse, SettingsResult, StatsResult, StatusEvent, SubscribeResult, TOUCH_PHASES, TouchPhase, UnsubscribeParams, UsageSample, VIDEO_CODECS, VIDEO_FOLDED, VIDEO_HEADER_VERSION, VIDEO_KEYFRAME, VIDEO_UNFOLDED, VideoCodec, VideoPacket, WorkspaceParams, protocolJsonSchema };

package/dist/protocol.mjs

@@ -1,2 +1,2 @@
-import { _ as TOUCH_PHASES, a as ERROR_CODES, b as VIDEO_KEYFRAME, c as INPUT_BUTTONS, d as MAX_INPUT_TEXT, f as MAX_LOG_TAIL, g as ROTATE_DIRECTIONS, h as PROTOCOL_VERSION, i as DEVICE_POSTURES, l as LOG_LEVELS, m as PROTOCOL_SCHEMA_FILE, n as CAPABILITIES, o as FRAME_EDGE, p as METHODS, r as CONTROL_END_REASONS, s as FRAME_FPS, t as ACTIONS, u as LOG_SOURCES, v as VIDEO_CODECS, x as protocolJsonSchema, y as VIDEO_HEADER_VERSION } from "./protocol-BElQc2vm.mjs";
-export { ACTIONS, CAPABILITIES, CONTROL_END_REASONS, DEVICE_POSTURES, ERROR_CODES, FRAME_EDGE, FRAME_FPS, INPUT_BUTTONS, LOG_LEVELS, LOG_SOURCES, MAX_INPUT_TEXT, MAX_LOG_TAIL, METHODS, PROTOCOL_SCHEMA_FILE, PROTOCOL_VERSION, ROTATE_DIRECTIONS, TOUCH_PHASES, VIDEO_CODECS, VIDEO_HEADER_VERSION, VIDEO_KEYFRAME, protocolJsonSchema };
+import { C as VIDEO_UNFOLDED, S as VIDEO_KEYFRAME, _ as ROTATE_DIRECTIONS, a as ERROR_CODES, b as VIDEO_FOLDED, c as INPUT_BUTTONS, d as MAX_INPUT_TEXT, f as MAX_LOG_TAIL, g as RELOAD_PLATFORMS, h as PROTOCOL_VERSION, i as DEVICE_POSTURES, l as LOG_LEVELS, m as PROTOCOL_SCHEMA_FILE, n as CAPABILITIES, o as FRAME_EDGE, p as METHODS, r as CONTROL_END_REASONS, s as FRAME_FPS, t as ACTIONS, u as LOG_SOURCES, v as TOUCH_PHASES, w as protocolJsonSchema, x as VIDEO_HEADER_VERSION, y as VIDEO_CODECS } from "./protocol-rC-5KT1O.mjs";
+export { ACTIONS, CAPABILITIES, CONTROL_END_REASONS, DEVICE_POSTURES, ERROR_CODES, FRAME_EDGE, FRAME_FPS, INPUT_BUTTONS, LOG_LEVELS, LOG_SOURCES, MAX_INPUT_TEXT, MAX_LOG_TAIL, METHODS, PROTOCOL_SCHEMA_FILE, PROTOCOL_VERSION, RELOAD_PLATFORMS, ROTATE_DIRECTIONS, TOUCH_PHASES, VIDEO_CODECS, VIDEO_FOLDED, VIDEO_HEADER_VERSION, VIDEO_KEYFRAME, VIDEO_UNFOLDED, protocolJsonSchema };

package/dist/protocol.schema.json

@@ -196,6 +196,13 @@
         },
         "msg": {
           "type": "string"
+        },
+        "context": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "With `errors`: the code frame and stack lines Expo printed after this error."
         }
       }
     },
@@ -318,7 +325,8 @@
             "platform": {
               "enum": [
                 "ios",
-                "android"
+                "android",
+                "web"
               ]
             }
           }

package/dist/stim-frames/main.swift

@@ -21,8 +21,9 @@ import IOSurface
 // keyboard.
 // stdout carries messages framed as a 4-byte big-endian length, then a kind byte:
 // 1 is a frame (2-byte width, 2-byte height, JPEG bytes), 2 is a JSON notice
-// ({"error": message} before a failed exit, {"inputError": message}, or on an emulator
-// {"keyboard": "yes|no"} once it reports its hardware), 3 is an H.264 access unit (1-byte
+// ({"error": message} before a failed exit, {"inputError": message}, on a simulator
+// with several displays {"display": n} when display n is the one lit and streamed, or
+// on an emulator {"keyboard": "yes|no"} once it reports its hardware), 3 is an H.264 access unit (1-byte
 // flags with bit 0 set on a keyframe, 8-byte big-endian float capture time in
 // milliseconds since the epoch, 2-byte width, 2-byte height, Annex-B bytes).
 // The helper exits when stdin closes.
@@ -88,7 +89,7 @@ enum Output {
     }
   }
 
-  static func notice(_ object: [String: String]) {
+  static func notice(_ object: [String: Any]) {
     guard let json = try? JSONSerialization.data(withJSONObject: object) else { return }
     writer.sync { write(Data([2]) + json) }
   }
@@ -191,7 +192,9 @@ final class SimulatorSource {
   let inputQueue = DispatchQueue(label: "stim.frames.input")
   var hid: SimulatorHID?
   private let pacer: Pacer
-  private var display: SimDisplay?
+  private var displays: [SimDisplay] = []
+  private var displayIndex = 0
+  private var reportedDisplay: Int?
   private let callbackID = NSUUID()
   private let video = videoEncoder()
   private let jpegGate = JpegGate()
@@ -206,37 +209,63 @@ final class SimulatorSource {
   var queue: DispatchQueue { pacer.queue }
 
   func start(deadline: Date = Date().addingTimeInterval(30)) {
-    guard let display = CoreSimulator.displays(udid: udid).first else {
+    let found = CoreSimulator.displays(udid: udid)
+    guard !found.isEmpty else {
       if Date() > deadline { fail("Simulator \(udid) has no display with a framebuffer. Is it booted?") }
       queue.asyncAfter(deadline: .now() + 1) { self.start(deadline: deadline) }
       return
     }
-    self.display = display
-    display.registerDamageCallback(callbackID) { [weak self] _ in self?.pacer.changed() }
-    display.registerSurfacesCallback(callbackID) { [weak self] _ in self?.pacer.changed() }
-    display.registerPropertiesCallback(callbackID) { [weak self] _ in self?.pacer.changed() }
+    displays = found
+    displayIndex = 0
+    for display in found {
+      display.registerDamageCallback(callbackID) { [weak self] _ in self?.pacer.changed() }
+      display.registerSurfacesCallback(callbackID) { [weak self] _ in self?.pacer.changed() }
+      display.registerPropertiesCallback(callbackID) { [weak self] _ in self?.pacer.changed() }
+    }
     pacer.changed()
-    watch(display)
+    watch()
   }
 
   // A simulator that shuts down and boots again gets new display objects, and
   // the old ones stop reporting damage; so does its HID client. CoreSimulator
   // returns a new proxy for the same display on every lookup, so the watch
   // follows the device state instead, where 3 is SimDeviceStateBooted.
-  private func watch(_ display: SimDisplay) {
+  private func watch() {
     queue.asyncAfter(deadline: .now() + 2) {
       guard CoreSimulator.device(udid: self.udid)?.value(forKey: "state") as? Int != 3 else {
-        return self.watch(display)
+        if self.displays.count > 1 { self.pacer.changed() }
+        return self.watch()
+      }
+      for display in self.displays {
+        display.unregisterDamageCallback(self.callbackID)
+        display.unregisterSurfacesCallback(self.callbackID)
+        display.unregisterPropertiesCallback(self.callbackID)
       }
-      display.unregisterDamageCallback(self.callbackID)
-      display.unregisterSurfacesCallback(self.callbackID)
-      display.unregisterPropertiesCallback(self.callbackID)
-      self.display = nil
+      self.displays = []
+      self.reportedDisplay = nil
       self.inputQueue.async { self.hid = nil }
       self.start()
     }
   }
 
+  // CoreSimulator keeps the built-in display an iPhone Duo's posture turned
+  // off, the cover or the inner one, all black, and sends no damage when it
+  // turns off, so watch() also re-renders a device with several displays.
+  private func litDisplay() -> SimDisplay? {
+    let panels = displays.indices.filter { displays[$0].screenProperties?.screenType == 0 }
+    guard panels.count > 1 else { return displays.first }
+    let lit = { (index: Int) in self.displays[index].framebufferSurface.map { !isBlack($0) } ?? false }
+    guard let index = lit(displayIndex) ? displayIndex : panels.first(where: lit) else {
+      return displays[displayIndex]
+    }
+    displayIndex = index
+    if reportedDisplay != index {
+      reportedDisplay = index
+      Output.notice(["display": index])
+    }
+    return displays[index]
+  }
+
   func configure(_ config: Config) {
     video.configure(enabled: config.video, maxEdge: config.maxEdge, fps: Int(config.fps), bitrate: config.bitrate)
     queue.async {
@@ -253,10 +282,10 @@ final class SimulatorSource {
   // uiOrientation is a UIInterfaceOrientation; the framebuffer stays in the
   // display's native portrait orientation, so the image is turned upright.
   private func render(_ config: Config) {
-    guard let surface = display?.framebufferSurface else { return }
+    guard let display = litDisplay(), let surface = display.framebufferSurface else { return }
     let orientation: CGImagePropertyOrientation
     let quarterTurns: Int
-    switch display?.screenProperties?.uiOrientation ?? 1 {
+    switch display.screenProperties?.uiOrientation ?? 1 {
     case 2: (orientation, quarterTurns) = (.down, 2)
     case 3: (orientation, quarterTurns) = (.right, 3)
     case 4: (orientation, quarterTurns) = (.left, 1)

package/dist/stim-server.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { _ as TOUCH_PHASES, c as INPUT_BUTTONS, f as MAX_LOG_TAIL, g as ROTATE_DIRECTIONS, l as LOG_LEVELS, n as CAPABILITIES, o as FRAME_EDGE, s as FRAME_FPS, t as ACTIONS, u as LOG_SOURCES } from "./protocol-BElQc2vm.mjs";
+import { _ as ROTATE_DIRECTIONS, c as INPUT_BUTTONS, f as MAX_LOG_TAIL, g as RELOAD_PLATFORMS, l as LOG_LEVELS, n as CAPABILITIES, o as FRAME_EDGE, s as FRAME_FPS, t as ACTIONS, u as LOG_SOURCES, v as TOUCH_PHASES } from "./protocol-rC-5KT1O.mjs";
 import { createRequire } from "node:module";
 import { accessSync, appendFileSync, constants, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, renameSync, rmSync, statSync, statfsSync, watch, writeFileSync } from "node:fs";
 import { availableParallelism, cpus, homedir, hostname, loadavg, tmpdir, totalmem } from "node:os";
@@ -284,9 +284,9 @@ function parseAction(params) {
 		action,
 		workspace
 	} };
-	if (platform !== void 0 && platform !== "ios" && platform !== "android") return {
+	if (platform !== void 0 && !RELOAD_PLATFORMS.includes(platform)) return {
 		code: "bad-request",
-		message: "platform must be ios or android."
+		message: `platform must be one of ${RELOAD_PLATFORMS.join(", ")}.`
 	};
 	return { action: {
 		action: "reload",
@@ -397,12 +397,20 @@ function runStim(stimCli, env, args, cwd, limits) {
 	const chunks = [];
 	let size = 0;
 	let stderr = "";
+	const release = () => {
+		child.stdout.destroy();
+		child.stderr.destroy();
+	};
 	const fail = (message) => {
 		if (failure) return;
 		failure = message;
+		release();
 		terminate(child);
 	};
-	const timer = setTimeout(() => fail(`${label} did not finish within ${limits.timeoutMs / 1e3} s.`), limits.timeoutMs);
+	const timer = setTimeout(() => {
+		if (child.exitCode !== null || child.signalCode !== null) return release();
+		fail(`${label} did not finish within ${limits.timeoutMs / 1e3} s.`);
+	}, limits.timeoutMs);
 	child.stdout.on("data", (chunk) => {
 		size += chunk.length;
 		if (size > limits.maxOutputBytes) return fail(`${label} printed more than ${limits.maxOutputBytes} bytes.`);
@@ -454,7 +462,8 @@ function videoPacket(subscription, sequence, unit) {
 	const id = Buffer.from(subscription, "ascii");
 	const header = Buffer.alloc(FIXED_HEADER_BYTES + id.length);
 	header.writeUInt8(1, 0);
-	header.writeUInt8(unit.keyframe ? 1 : 0, 1);
+	const posture = unit.posture === "folded" ? 2 : unit.posture === "unfolded" ? 4 : 0;
+	header.writeUInt8((unit.keyframe ? 1 : 0) | posture, 1);
 	header.writeUInt16BE(header.length, 2);
 	header.writeUInt32BE(sequence >>> 0, 4);
 	header.writeDoubleBE(unit.capturedAt, 8);
@@ -670,9 +679,11 @@ async function compiled(name, inputs, version, compile) {
 	return helper;
 }
 /**
-* One `stim-frames` process per device, shared by its subscribers and stopped with the last of them. It runs
+* One `stim-frames` process per device, shared by its subscribers and stopped `lingerMs` after the last of them
+* leaves, unchanged meanwhile, so a subscriber that comes back within that time gets the latest frame at once. It runs
 * at the highest fps and the largest edge any subscriber asked for; each subscriber paces its own frames. The
-* helper exits when its stdin closes, so it cannot outlive the server.
+* helper exits when its stdin closes, so it cannot outlive the server. `lit` turns the display the helper
+* reports it streams into a posture, which the frames and access units after it carry.
 */
 var HelperSource = class {
 	listeners = /* @__PURE__ */ new Map();
@@ -687,8 +698,14 @@ var HelperSource = class {
 	bitrate = new Bitrate(DEFAULT_VIDEO_LIMITS, Date.now());
 	keyframeAt = -Infinity;
 	keyframeTimer = null;
-	constructor(helper, device, env, ended) {
+	lit;
+	posture;
+	lingerMs;
+	lingerTimer = null;
+	constructor(helper, device, env, ended, lingerMs, lit) {
 		this.ended = ended;
+		this.lingerMs = lingerMs;
+		this.lit = lit;
 		const id = device.platform === "ios" ? device.udid : device.serial;
 		this.child = spawn(helper, [device.platform, id], {
 			env,
@@ -712,20 +729,23 @@ var HelperSource = class {
 	}
 	/** A null `hint` keeps the helper running for input without asking for frames. */
 	add(listener, hint) {
+		if (this.lingerTimer) clearTimeout(this.lingerTimer);
+		this.lingerTimer = null;
 		this.listeners.set(listener, hint);
 		this.configure();
 		if (listener.video) this.keyframe();
 		else if (this.last) listener.frame(this.last);
 		return () => {
 			if (!this.listeners.delete(listener)) return;
-			if (this.listeners.size === 0) this.stop();
-			else this.configure();
+			if (this.listeners.size > 0) this.configure();
+			else this.lingerTimer = setTimeout(() => void this.stop(), this.lingerMs);
 		};
 	}
 	stop() {
 		if (this.stopped) return Promise.resolve();
 		this.stopped = true;
 		if (this.keyframeTimer) clearTimeout(this.keyframeTimer);
+		if (this.lingerTimer) clearTimeout(this.lingerTimer);
 		this.listeners.clear();
 		this.ended();
 		this.child.stdin.end();
@@ -752,6 +772,7 @@ var HelperSource = class {
 		if (!this.stopped) this.child.stdin.write(`${JSON.stringify(command)}\n`);
 	}
 	configure() {
+		if (this.listeners.size === 0) return;
 		const watching = [...this.listeners].flatMap(([listener, hint]) => hint ? [{
 			listener,
 			hint
@@ -802,7 +823,8 @@ var HelperSource = class {
 			width: body.readUInt16BE(1),
 			height: body.readUInt16BE(3),
 			capturedAt: (/* @__PURE__ */ new Date()).toISOString(),
-			data: body.subarray(5).toString("base64")
+			data: body.subarray(5).toString("base64"),
+			...this.posture ? { posture: this.posture } : {}
 		};
 		for (const listener of this.listeners.keys()) if (!listener.video) listener.frame(this.last);
 	}
@@ -813,7 +835,8 @@ var HelperSource = class {
 			capturedAt: body.readDoubleBE(2),
 			width: body.readUInt16BE(10),
 			height: body.readUInt16BE(12),
-			data: body.subarray(VIDEO_HEADER_BYTES)
+			data: body.subarray(VIDEO_HEADER_BYTES),
+			...this.posture ? { posture: this.posture } : {}
 		};
 		if (this.bitrate.tick(Date.now()) !== null) this.configure();
 		for (const listener of this.listeners.keys()) listener.video?.(unit);
@@ -827,6 +850,8 @@ var HelperSource = class {
 			if (keyboard === "yes" || keyboard === "no") this.keyboard = keyboard === "yes";
 			const inputError = notice?.inputError;
 			if (typeof inputError === "string") console.error(`stim-server: stim-frames: ${inputError}`);
+			const display = notice?.display;
+			if (this.lit && typeof display === "number") this.posture = this.lit(display);
 		} catch {}
 	}
 };
@@ -836,7 +861,8 @@ const DEFAULT_FRAME_LIMITS = {
 	toolTimeoutMs: 3e4,
 	slowCaptureMs: 3e3,
 	failureBackoffMs: 3e3,
-	maxConsecutiveFailures: 3
+	maxConsecutiveFailures: 3,
+	lingerMs: 1e4
 };
 const MIN_INTERVAL_MS = 200;
 const MAX_INTERVAL_MS = 1e3;
@@ -1044,6 +1070,8 @@ function simulatorCapturer(device, env, limits, litPanels) {
 		}
 	};
 }
+/** The Duo's panels in the order the helper indexes CoreSimulator's displays, by screen ID. */
+const DUO_PANELS = ["primary", "primary-1"];
 const POSTURES = {
 	primary: "folded",
 	"primary-1": "unfolded"
@@ -1401,12 +1429,15 @@ var FrameSource = class {
 	}
 };
 /**
-* One capture per device, shared by its subscribers and stopped with the last of them. With the `stim-frames`
-* helper, a device streams frames as its screen changes, at the rate its subscribers ask for. Without it, for
-* an iPhone Duo, and while the helper is still being built, a screenshot loop sends a frame only when the
-* screen changed: up to 5 times a second while it changes, backing off to once a second while it does not,
-* spending at most half of its time capturing, with at most two captures at once across all devices. A helper
-* that fails before its first frame gives way to the screenshot loop.
+* One capture per device, shared by its subscribers. A `stim-frames` helper stops `lingerMs` after the last of
+* them leaves, so a client that takes one frame at a time reuses it; a screenshot loop stops with the last of
+* them. With the `stim-frames`
+* helper, a device streams frames as its screen changes, at the rate its subscribers ask for; an iPhone Duo
+* streams its lit panel, which is its posture. Without the helper, and while it is still being built, a
+* screenshot loop sends a frame only when the screen changed: up to 5 times a second while it changes, backing
+* off to once a second while it does not, spending at most half of its time capturing, with at most two
+* captures at once across all devices. A helper that fails before its first frame gives way to the screenshot
+* loop.
 */
 var FramePool = class {
 	sources = /* @__PURE__ */ new Map();
@@ -1422,7 +1453,7 @@ var FramePool = class {
 	}
 	subscribe(device, listener, hint = DEFAULT_FRAME_HINT) {
 		const helper = this.helper();
-		if (helper === null || device.platform === "ios" && device.foldable) return this.screenshots(device).add(listener);
+		if (helper === null) return this.screenshots(device).add(listener);
 		let streamed = false;
 		let cancelled = false;
 		const { video } = listener;
@@ -1490,9 +1521,15 @@ var FramePool = class {
 		const key = `helper:${deviceKey(device)}`;
 		const existing = this.sources.get(key);
 		if (existing instanceof HelperSource) return existing;
+		const lit = device.platform === "ios" && device.foldable ? (display) => {
+			const panel = DUO_PANELS[display];
+			if (!panel) return void 0;
+			this.litPanels.set(device.udid, panel);
+			return POSTURES[panel];
+		} : void 0;
 		const created = new HelperSource(helper, device, this.env, () => {
 			if (this.sources.get(key) === created) this.sources.delete(key);
-		});
+		}, this.limits.lingerMs, lit);
 		this.sources.set(key, created);
 		return created;
 	}
@@ -1696,8 +1733,6 @@ function adbPath(env) {
 	return "adb";
 }
 const ADB_TIMEOUT_MS = 1e4;
-/** `sim-fold` waits up to 20 seconds for SpringBoard to finish the fold; Stim Desktop stops it after 40. */
-const FOLD_TIMEOUT_MS = 4e4;
 const POSTURE_TIMEOUT_MS = 5e3;
 function runQuietly(env, file, args, label, timeoutMs) {
 	return new Promise((resolve, reject) => {
@@ -1710,18 +1745,24 @@ function runQuietly(env, file, args, label, timeoutMs) {
 			]
 		});
 		let stderr = "";
-		const timer = setTimeout(() => void terminate(child), timeoutMs);
+		const finish = (code) => {
+			clearTimeout(timer);
+			if (code === 0) resolve();
+			else reject(/* @__PURE__ */ new Error(`${label} failed (code ${code}): ${stderr.trim()}`));
+		};
+		const timer = setTimeout(() => {
+			child.stderr.destroy();
+			if (child.exitCode !== null || child.signalCode !== null) return finish(child.exitCode);
+			terminate(child);
+			reject(/* @__PURE__ */ new Error(`${label} did not finish within ${timeoutMs / 1e3} s.`));
+		}, timeoutMs);
 		child.stderr.setEncoding("utf8");
 		child.stderr.on("data", (chunk) => stderr = (stderr + chunk).slice(-500));
 		child.on("error", (error) => {
 			clearTimeout(timer);
 			reject(/* @__PURE__ */ new Error(`${label} could not start (${error.message}).`));
 		});
-		child.on("close", (code) => {
-			clearTimeout(timer);
-			if (code === 0) resolve();
-			else reject(/* @__PURE__ */ new Error(`${label} failed (code ${code}): ${stderr.trim()}`));
-		});
+		child.on("close", finish);
 	});
 }
 function runAdb(env, serial, args) {
@@ -1939,7 +1980,7 @@ var ControlHub = class {
 				"spawn",
 				udid,
 				helper
-			], "sim-fold", FOLD_TIMEOUT_MS);
+			], "sim-fold", this.options.foldTimeoutMs);
 			this.options.frames.folded(udid, posture === "folded" ? "folded" : "unfolded");
 			return null;
 		} catch (cause) {
@@ -2101,9 +2142,12 @@ var Feed = class {
 				return;
 			}
 			if (!isJsonObject(value)) return;
-			this.kept.push(value);
+			this.kept.push({
+				value,
+				text: line
+			});
 			if (this.kept.length > spec.keep) this.kept.shift();
-			for (const listener of this.listeners) listener.item(value);
+			for (const listener of this.listeners) listener.item(value, line);
 		});
 		const exited = (reason) => {
 			if (this.child !== child) return;
@@ -2119,7 +2163,7 @@ var Feed = class {
 	}
 	add(listener) {
 		this.listeners.add(listener);
-		for (const value of this.kept) listener.item(value);
+		for (const { value, text } of this.kept) listener.item(value, text);
 		return () => {
 			if (this.listeners.delete(listener) && this.listeners.size === 0) this.stop();
 		};
@@ -2673,7 +2717,8 @@ const CONTROL_LIMITS = {
 	leaseFor: "2m",
 	inputPerSecond: 120,
 	textCharsPerSecond: 40,
-	shapeChangesPerSecond: 2
+	shapeChangesPerSecond: 2,
+	foldTimeoutMs: 4e4
 };
 const LOCK_LIMITS = {
 	timeoutMs: 3e4,
@@ -2768,7 +2813,7 @@ function take(bucket, cost, perSecond, capacity) {
 	return true;
 }
 function send(socket, message) {
-	if (socket.readyState === socket.OPEN) socket.send(JSON.stringify(message));
+	if (socket.readyState === socket.OPEN) socket.send(typeof message === "string" ? message : JSON.stringify(message));
 }
 function requestId(value) {
 	return typeof value === "number" || typeof value === "string" ? value : null;
@@ -2871,7 +2916,8 @@ async function startServer(options) {
 		idleMs: controlLimits.idleMs,
 		renewMs: controlLimits.renewMs,
 		leaseFor: controlLimits.leaseFor,
-		foldHelper
+		foldHelper,
+		foldTimeoutMs: controlLimits.foldTimeoutMs
 	});
 	const wss = new WebSocketServer({
 		noServer: true,
@@ -3078,12 +3124,9 @@ async function startServer(options) {
 		function subscribeStatus(id) {
 			const subscription = openSubscription(id);
 			if (!subscription) return;
+			const envelope = `{"event":"status","subscription":${JSON.stringify(subscription)},"payload":`;
 			const unsubscribe = feeds.subscribe(STATUS_FEED, {
-				item: (payload) => send(socket, {
-					event: "status",
-					subscription,
-					payload
-				}),
+				item: (_payload, text) => send(socket, `${envelope}${text}}`),
 				failed: (message) => {
 					subscriptions.delete(subscription);
 					send(socket, {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stim-cli/server",
-  "version": "1.12.0",
+  "version": "1.13.0",
   "description": "Serves Stim status to paired clients over Tailscale, and runs reload and stop for clients granted control.",
   "license": "MIT",
   "repository": {
@@ -28,8 +28,8 @@
     "./protocol.schema.json": "./dist/protocol.schema.json"
   },
   "dependencies": {
-    "@stim-cli/core": "^1.12.0",
-    "stim": "1.12.0",
+    "@stim-cli/core": "^1.13.0",
+    "stim": "1.13.0",
     "ws": "^8.21.3"
   },
   "devDependencies": {