lecodes-cli 0.20.2 → 2.0.0

package/src/compile/shaders.ts

@@ -8,9 +8,9 @@ import {
   matcArgs, MATC_PLATFORMS, TARGET_MATRIX_GENERATION,
   type AnyMatcPlatform, type AnyShaderPlatform,
 } from "lecodes-sdk/compile"
-import { resolveMatcExe, resolveMatcExeCached } from "../matcTool"
-import { LECODES_DIR } from "../manifest"
-import { CliError } from "../util"
+import { resolveMatcExe, resolveMatcExeCached } from "../hosts/matcTool"
+import { LECODES_DIR } from "../project/manifest"
+import { CliError } from "../cli"
 import type { CompileEntry } from "./projectCompile"
 
 /*

package/src/{lecodes-3d-editor.d.ts → declarations/lecodes-3d-editor.d.ts}

@@ -24,6 +24,10 @@ declare module "lecodes-3d-editor/server" {
 
   export function startSceneServer(options: SceneServerOptions): Promise<SceneServer>
 
+  /** The editor's harness — its half that runs in the scene's world — as module name → source:
+   *  what the compile closure hands to the SDK's `sceneEditorEntries`. */
+  export function sceneHarness(): Record<string, string>
+
   /* The asset-preview cache (server/previewCache.ts) — `lecodes thumbs` writes into the same
    * `.lecodes/preview/<asset>.<hash>.png` layout the editor reads. */
 

package/src/{lecodes-assets.d.ts → declarations/lecodes-assets.d.ts}

@@ -1,6 +1,6 @@
 // Types for the optional `lecodes-assets` package's CLI entry (lazy-loaded by the `assets` command).
 // The real package is installed separately; this lets the dynamic import typecheck without it
-// present. Keep in sync with packages/lecodes-assets/src/cli.ts.
+// present. Keep in sync with tools/assets/src/cli.ts.
 declare module "lecodes-assets/cli" {
   /** Runs `convert | probe | doctor` with the given argv (sub-command first). Resolves to the exit code. */
   export function runAssetsCli(argv: string[]): Promise<number>

package/src/{lecodes-renderer.d.ts → declarations/lecodes-headless.d.ts}

@@ -1,7 +1,7 @@
-// Types for the optional `lecodes-renderer` package's node headless entry (lazy-loaded by the
+// Types for the optional `lecodes-headless` package's node headless entry (lazy-loaded by the
 // `render` command). The real package is installed separately; this lets the dynamic import
 // typecheck without it present.
-declare module "lecodes-renderer/headless" {
+declare module "lecodes-headless/headless" {
   export type RenderOptions = {
     width?: number
     height?: number
@@ -21,7 +21,7 @@ declare module "lecodes-renderer/headless" {
     safeArea?: [number, number, number, number]
     /** Receive the project's console.* output (unset → swallowed). */
     onConsole?: (level: string, text: string) => void
-    /** Canned `_creatorUtils.fetch` responses (URL pattern → { status?, json?, text? }); they beat
+    /** Canned `_creatorFetch.fetch` responses (URL pattern → { status?, json?, text? }); they beat
      *  every other fetch path, including waitNetwork. */
     fixtures?: Fixtures
   }

package/src/dev/androidDev.ts

@@ -1,7 +1,7 @@
 import { existsSync, writeFileSync } from "node:fs"
 import { join } from "node:path"
 import { spawnSync } from "node:child_process"
-import { CliError, note, warnErr } from "../util"
+import { CliError, note, warnErr } from "../cli"
 
 /*
  * `lecodes dev --android` — open the dev URL in the LeCodes app on the connected phone, through adb.

package/src/dev/clientTemplates.ts

@@ -7,9 +7,9 @@
  *   header says `// gl: disable`, so the app launcher creates no engine for it.
  *
  * - DEV_PRELUDE_JS — plain JS appended VERBATIM to every bundle the dev server serves (dev.js and
- *   bundle.js alike). It only touches the raw `_creatorUtils` / `_creator` bridge — no SDK — so it
- *   can ride along any compiled project without duplicating the injected runtime. Each
- *   `_creatorUtils.run()` world therefore carries its own copy: the running world holds the live
+ *   bundle.js alike). It only touches the raw `_creatorFetch` / `_creatorSocket` / `_creatorApp` /
+ *   `_creator` bridge — no SDK — so it can ride along any compiled project without duplicating the
+ *   injected runtime. Each `_creatorApp.run()` world therefore carries its own copy: the running world holds the live
  *   connection; when it loads the next bundle, the NEW world's copy connects and the native
  *   per-world socket teardown closes the old one. On eval error, run()'s rollback keeps the
  *   current world (and its connection) alive, so the reject callback here reports + keeps serving.
@@ -33,6 +33,11 @@ UIScreen([
 
 export const DEV_PRELUDE_JS = `
 ;(function () {
+  // The raw bridges (sdk/src/bridges): fetch's onComplete hands an OWNED handle ({ id }) whose
+  // body is freed when the handle is collected — the readers / run take the NUMBER (handle.id).
+  var F = _creatorFetch
+  var S = _creatorSocket
+  var A = _creatorApp
   var ORIGIN = "__DEV_ORIGIN__"
   var BASE = "__DEV_BASE__"
   var TRANSPORT = "__DEV_TRANSPORT__"
@@ -44,12 +49,12 @@ export const DEV_PRELUDE_JS = `
   function post(obj) {
     var text = JSON.stringify(obj)
     if (TRANSPORT === "ws") {
-      if (wsId !== null) { try { _creatorUtils.websocketSend(wsId, text) } catch (e) {} }
+      if (wsId !== null) { try { S.send(wsId, text) } catch (e) {} }
       return
     }
     try {
-      _creatorUtils.fetch(ORIGIN + BASE + "/log", { method: "POST", body: text, headers: { "content-type": "application/json" } },
-        function (id) { try { _creatorUtils.disposeFetch(id) } catch (e) {} }, function () {})
+      F.fetch(ORIGIN + BASE + "/log", { method: "POST", body: text, headers: { "content-type": "application/json" } },
+        function () {}, function () {})
     } catch (e) {}
   }
 
@@ -80,16 +85,16 @@ export const DEV_PRELUDE_JS = `
   function load(v) {
     if (busy) { queued = v; return }
     busy = true
-    _creatorUtils.fetch(ORIGIN + BASE + "/bundle.js?v=" + v + "&t=" + TRANSPORT, {}, function (id, status) {
+    F.fetch(ORIGIN + BASE + "/bundle.js?v=" + v + "&t=" + TRANSPORT, {}, function (body, status) {
       if (status >= 400) { busy = false; report("bundle fetch: HTTP " + status); return }
       // Same engine bringup the app launcher does for a fresh launch (see desktop initial.ts).
       var head = ""
-      try { head = _creatorUtils.fetchSlice(id, 0, 300) } catch (e) {}
+      try { head = F.slice(body.id, 0, 300) } catch (e) {}
       var preloads = head.match(/\\/\\/ preload: (.+)/)
       if (head.indexOf("// gl:") < 0) {
         try { _creator.createEngine(preloads ? preloads[1].split(";") : []) } catch (e) { report("createEngine: " + String(e)) }
       }
-      _creatorUtils.run(id, function (err) {
+      A.run(body.id, function (err) {
         // Eval failed → native rollback kept THIS world (and its connection) alive. Keep serving.
         busy = false
         report(err)
@@ -109,9 +114,9 @@ export const DEV_PRELUDE_JS = `
     var url = ORIGIN.replace("http", "ws") + BASE + "/ws"
     var open = function () {
       try {
-        wsId = _creatorUtils.websocketOpen(url, function (channel, data) {
+        wsId = S.open(url, function (channel, data) {
           if (channel === "open") {
-            try { _creatorUtils.websocketSend(wsId, JSON.stringify({ type: "hello", v: V })) } catch (e) {}
+            try { S.send(wsId, JSON.stringify({ type: "hello", v: V })) } catch (e) {}
           } else if (channel === "message") {
             onServer(data)
           } else if (channel === "close" || channel === "error") {
@@ -124,10 +129,9 @@ export const DEV_PRELUDE_JS = `
     open()
   } else {
     var poll = function () {
-      _creatorUtils.fetch(ORIGIN + BASE + "/version", {}, function (id, status) {
+      F.fetch(ORIGIN + BASE + "/version", {}, function (body, status) {
         var v = null
-        try { v = _creatorUtils.fetchToJson(id).v } catch (e) {}
-        try { _creatorUtils.disposeFetch(id) } catch (e) {}
+        try { v = F.toJson(body.id).v } catch (e) {}
         setTimeout(poll, 700)
         if (status < 400 && typeof v === "number" && v !== V && !busy) load(v)
       }, function () { setTimeout(poll, 1500) })

package/src/dev/devServer.ts

@@ -1,8 +1,8 @@
 import { createServer, type IncomingMessage, type Server, type ServerResponse } from "node:http"
 import { createReadStream, statSync } from "node:fs"
 import { join } from "node:path"
-import type { Manifest } from "../manifest"
-import { resolveLocalPath } from "../localFiles"
+import type { Manifest } from "../project/manifest"
+import { resolveLocalPath } from "../project/localFiles"
 import { collectLocalEntries } from "../compile/collectLocal"
 import { applyLocalShaders, isShaderArtifactName, shadersCacheDir } from "../compile/shaders"
 import { ambiguousEntryWarning, compileProject } from "../compile/projectCompile"
@@ -10,8 +10,9 @@ import { applyProjectFonts } from "../compile/fonts"
 import { applyAppAssetIcons } from "../compile/assetIcons"
 import { renderDevScreen, renderPrelude } from "./clientTemplates"
 import { upgradeWebSocket, type WsConnection } from "./wsServer"
-import { toKey } from "../util"
+import { toKey } from "../project/paths"
 import { makeStackDemangler } from "../compile/nativeStack"
+import type { WebRunner } from "./webRunner"
 
 /*
  * The `lecodes dev` LAN server: serves the project to devices and hot-reloads it on change.
@@ -24,9 +25,12 @@ import { makeStackDemangler } from "../compile/nativeStack"
  *   GET /t/<tok>/version         {"v":N} — polling fallback
  *   POST /t/<tok>/log            log/error backchannel for polling clients
  *   WS  /t/<tok>/ws              reload push + log/error backchannel
- *   GET /t/<tok>/web/[file]      the Web Lite browser runner (viewer-lite dist-embed, `dev --web`):
- *                                it loads bundle.js?t=web — the bundle WITHOUT the native prelude;
- *                                the page owns reload (ws / version polling) and the log backchannel
+ *   GET /t/<tok>/web/[file]      the page of `dev --web` (lecodes-web-frame's dist-page): the app
+ *                                in a device, the buttons, the console — around an <iframe> of…
+ *   GET /t/<tok>/web/player/[file]  …the web player (lecodes-web-player's dist), opened as
+ *                                player/?dev=../.. — it loads bundle.js?t=web, the bundle WITHOUT
+ *                                the native prelude; the player owns reload (ws / version
+ *                                polling) and the log backchannel. A phone is sent here at once
  *
  * Compile is eager: the command calls recompile() on every file change; a successful compile bumps
  * `v` and broadcasts {type:"reload", v} to connected sockets (polling clients see /version move).
@@ -44,8 +48,9 @@ export type DevServerOptions = {
   port: number
   token: string
   entryOverride?: string
-  /** The Web Lite runner folder to serve under /web/ (src/dev/webRunner.ts); absent = no browser route. */
-  webDir?: string | null
+  /** What is served under /web/ (src/dev/webRunner.ts): the player, and the page around it; absent =
+   *  no browser route. */
+  web?: WebRunner | null
   /** Diagnostics (compile errors, device logs); defaults to stderr-style silence-safe noop. */
   log?: (msg: string) => void
 }
@@ -89,6 +94,32 @@ const sendText = (res: ServerResponse, status: number, type: string, body: strin
   res.end(body)
 }
 
+/** A working-tree file with byte-range support. AVPlayer (the iOS host's video / audio players)
+ *  opens an HTTP source with `Range: bytes=0-1` and fails the item with -11850 "The server is not
+ *  correctly configured" when the answer is a plain 200, so an asset route must answer ranges. */
+const sendFile = (req: IncomingMessage, res: ServerResponse, abs: string, type: string) => {
+  const size = statSync(abs).size
+  const headers = { "content-type": type, "cache-control": "no-store", "accept-ranges": "bytes" }
+  const m = /^bytes=(\d*)-(\d*)$/.exec(req.headers.range ?? "")
+  if (m && (m[1] || m[2])) {
+    // bytes=a-b, bytes=a- (to the end), bytes=-n (the last n bytes)
+    const start = m[1] ? Number(m[1]) : Math.max(0, size - Number(m[2]))
+    const end = m[1] && m[2] ? Math.min(Number(m[2]), size - 1) : size - 1
+    if (start >= size || start > end) {
+      res.writeHead(416, { ...headers, "content-range": `bytes */${size}` })
+      res.end()
+      return
+    }
+    res.writeHead(206, { ...headers, "content-range": `bytes ${start}-${end}/${size}`, "content-length": end - start + 1 })
+    if (req.method === "HEAD") return void res.end()
+    createReadStream(abs, { start, end }).pipe(res)
+    return
+  }
+  res.writeHead(200, { ...headers, "content-length": size })
+  if (req.method === "HEAD") return void res.end()
+  createReadStream(abs).pipe(res)
+}
+
 const sendJson = (res: ServerResponse, status: number, body: unknown) =>
   sendText(res, status, "application/json", JSON.stringify(body))
 
@@ -138,7 +169,7 @@ export const startDevServer = async (options: DevServerOptions): Promise<DevServ
         const ambiguous = ambiguousEntryWarning(entries)
         if (ambiguous) warnings.push(ambiguous)
       }
-      const js = await compileProject({ entries, name, publicUrl: origin, entryOverride, header: true, fontsHeader, iconsHeader })
+      const js = await compileProject({ entries, name, publicUrl: origin, entryOverride, header: true, fontsHeader, iconsHeader, onWarning: (w) => warnings.push(w) })
       const changed = bundleJs === null || stripVolatile(js) !== stripVolatile(bundleJs)
       if (changed) {
         bundleJs = js
@@ -195,14 +226,30 @@ export const startDevServer = async (options: DevServerOptions): Promise<DevServ
     const t = url.searchParams.get("t")
     return t === "poll" ? "poll" : t === "web" ? "web" : "ws"
   }
-  const withPrelude = (js: string, url: URL, v: number, forced?: "poll") => {
+  // The prelude talks back to the origin THIS request came through (the Host header): a phone on
+  // `adb reverse` reached us as 127.0.0.1:<port> and can't see the LAN address the QR carries.
+  const withPrelude = (js: string, url: URL, v: number, reqOrigin: string, forced?: "poll") => {
     const transport = forced ?? transportOf(url)
-    return transport === "web" ? js : js + "\n" + renderPrelude({ origin, base, transport, v })
+    return transport === "web" ? js : js + "\n" + renderPrelude({ origin: reqOrigin, base, transport, v })
+  }
+  const web = options.web ?? null
+  /** A file of a built folder; the entry files revalidate — a CLI update swaps them under the same
+   *  url — while what is under assets/ carries its hash in its name. */
+  const sendBuilt = (res: ServerResponse, dir: string, rel: string) => {
+    if (rel.split("/").some((seg) => seg === ".." || seg === "" || seg === ".")) return sendText(res, 400, "text/plain", "Bad path")
+    const abs = join(dir, ...rel.split("/"))
+    try {
+      if (!statSync(abs).isFile()) throw new Error("not a file")
+    } catch {
+      return sendText(res, 404, "text/plain", "Not found")
+    }
+    res.writeHead(200, { "content-type": contentType(rel), "cache-control": rel.startsWith("assets/") ? "max-age=31536000, immutable" : "no-store" })
+    createReadStream(abs).pipe(res)
   }
-  const webDir = options.webDir ?? null
 
   const handle = async (req: IncomingMessage, res: ServerResponse) => {
-    const url = new URL(req.url ?? "/", origin)
+    const reqOrigin = req.headers.host ? `http://${req.headers.host}` : origin
+    const url = new URL(req.url ?? "/", reqOrigin)
     const path = url.pathname
     // Browsers ask for it on every page load (the /web/ runner) — keep the console clean.
     if (path === "/favicon.ico") { res.writeHead(204); res.end(); return }
@@ -210,40 +257,32 @@ export const startDevServer = async (options: DevServerOptions): Promise<DevServ
     const route = path.slice(base.length)
 
     if (route === "/dev.js") {
-      return sendText(res, 200, "text/javascript", withPrelude(devJs, url, -1))
+      return sendText(res, 200, "text/javascript", withPrelude(devJs, url, -1, reqOrigin))
     }
     // The poll transport as a PATH: the Android app's initial.js only fetches a launch url that ends
     // in ".js" (anything else goes to le.codes/api/code), so `?t=poll` can't reach it. Same bundle,
     // prelude polls instead of the websocket — what `dev --android` opens under Bun (no ws there).
     if (route === "/dev-poll.js") {
-      return sendText(res, 200, "text/javascript", withPrelude(devJs, url, -1, "poll"))
+      return sendText(res, 200, "text/javascript", withPrelude(devJs, url, -1, reqOrigin, "poll"))
     }
     if (route === "/bundle.js") {
       if (bundleJs === null) return sendText(res, 503, "text/plain", "No successful compile yet — check the terminal.")
       res.setHeader("x-lecodes-v", String(v))   // the browser runner learns the version it runs
-      return sendText(res, 200, "text/javascript", withPrelude(bundleJs, url, v))
-    }
-    // The browser runner: a static folder with relative asset paths, so it needs the trailing slash.
-    if (route === "/web") {
-      res.writeHead(302, { location: `${base}/web/${url.search}` })
-      res.end()
-      return
+      return sendText(res, 200, "text/javascript", withPrelude(bundleJs, url, v, reqOrigin))
     }
-    if (route.startsWith("/web/")) {
-      if (!webDir) return sendText(res, 404, "text/plain", "No Web Lite runner vendored with this CLI (lecodes-viewer-lite dist-embed).")
-      const rel = route === "/web/" ? "embed.html" : route.slice("/web/".length)
-      if (rel.split("/").some((seg) => seg === ".." || seg === "" || seg === ".")) return sendText(res, 400, "text/plain", "Bad path")
-      const abs = join(webDir, ...rel.split("/"))
-      try {
-        if (!statSync(abs).isFile()) throw new Error("not a file")
-      } catch {
-        return sendText(res, 404, "text/plain", "Not found")
-      }
-      // The entry files (html, embed.js) must revalidate — a CLI update swaps them under the same URL.
-      const hashed = rel.startsWith("assets/")
-      res.writeHead(200, { "content-type": contentType(rel), "cache-control": hashed ? "max-age=31536000, immutable" : "no-store" })
-      createReadStream(abs).pipe(res)
-      return
+    // The browser: built folders with relative asset paths, so each needs its trailing slash. The
+    // player is told the server it runs the project of (`dev`: this one, two folders up).
+    if (route === "/web" || route.startsWith("/web/")) {
+      if (!web) return sendText(res, 404, "text/plain", "No web player vendored with this CLI (lecodes-web-player's dist).")
+      const redirect = (to: string) => { res.writeHead(302, { location: to }); res.end() }
+      const query = (extra?: [string, string]) => { if (extra) url.searchParams.set(...extra); const q = url.searchParams.toString(); return q ? `?${q}` : "" }
+      const rel = route.slice("/web".length)
+      if (rel === "/player" || (rel === "/player/" && !url.searchParams.has("dev"))) return redirect(`${base}/web/player/${query(["dev", "../.."])}`)
+      if (rel.startsWith("/player/")) return sendBuilt(res, web.player, rel === "/player/" ? "index.html" : rel.slice("/player/".length))
+      // no page around the player in this CLI: the player alone
+      if (!web.page) return redirect(`${base}/web/player/${query(["dev", "../.."])}`)
+      if (rel === "") return redirect(`${base}/web/${query()}`)
+      return sendBuilt(res, web.page, rel === "/" ? "index.html" : rel.slice(1))
     }
     if (route === "/version") {
       return sendJson(res, 200, { v })
@@ -274,9 +313,7 @@ export const startDevServer = async (options: DevServerOptions): Promise<DevServ
       }
       const abs = resolveLocalPath(root, key)
       if (!abs || !statSync(abs).isFile()) return sendText(res, 404, "text/plain", "Not found")
-      res.writeHead(200, { "content-type": contentType(key), "cache-control": "no-store" })
-      createReadStream(abs).pipe(res)
-      return
+      return sendFile(req, res, abs, contentType(key))
     }
     return sendText(res, 404, "text/plain", "Not found")
   }
@@ -325,7 +362,7 @@ export const startDevServer = async (options: DevServerOptions): Promise<DevServ
 
   return {
     url: `${origin}${base}/dev.js`,
-    webUrl: webDir ? `${origin}${base}/web/` : null,
+    webUrl: web ? `${origin}${base}/web/` : null,
     base,
     port: boundPort,
     v: () => v,

package/src/dev/iosDev.ts

@@ -0,0 +1,180 @@
+import { existsSync, readdirSync, readFileSync, statSync, unlinkSync } from "node:fs"
+import { homedir } from "node:os"
+import { join } from "node:path"
+import { spawnSync } from "node:child_process"
+import { CliError, note, warnErr } from "../cli"
+
+/*
+ * `lecodes dev --ios` — open the dev URL in the LeCodes app on a simulator or a plugged-in iPhone,
+ * through Xcode's tools (`xcrun simctl` for a simulator, `xcrun devicectl` for a device). The twin of
+ * dev/androidDev.ts, on a Mac only.
+ *
+ * The url reaches the app as a LAUNCH ARGUMENT (`--lecodes-url <url>`, read by LeCodesViewController
+ * and seeded as the launch URL before the launcher boots — hosts/apple/lecodes): a simulator has no
+ * universal links (no AASA), and `simctl openurl` on an http url opens Safari. A simulator shares the
+ * Mac's network, so it gets the 127.0.0.1 url (no Wi-Fi involved, like adb reverse); a device gets the
+ * LAN url the QR shows — there is no reverse tunnel over USB for iPhones.
+ *
+ * Like Android, every exit path terminates the app: a device run has no frame cap, and a 3D scene
+ * left rendering is a sustained GPU load on a charging phone.
+ */
+
+export const DEFAULT_IOS_BUNDLE = "com.letary.lecodes"
+
+export type IosDevOptions = {
+  /** The url for a simulator (127.0.0.1) and the one for a device (the LAN address). */
+  simulatorUrl: string
+  deviceUrl: string
+  /** A simulator's or a device's udid (or a simulator's name); omitted = the booted simulator, else the paired device. */
+  udid?: string
+  /** A built LeCodesApp.app to install first. */
+  app?: string
+  bundleId?: string
+}
+
+export type IosDevSession = {
+  kind: "simulator" | "device"
+  udid: string
+  name: string
+  bundleId: string
+  /** `simctl io screenshot` → the file; false on a device (no screenshot channel). */
+  screenshot: (file: string) => boolean
+  /** Terminate the app. Idempotent. */
+  stop: () => void
+  /** Crash reports of the app written since the launch (the simulator's, on this Mac). */
+  crashLines: () => string[]
+}
+
+const run = (args: string[]): { ok: boolean, out: string } => {
+  const r = spawnSync("xcrun", args, { encoding: "utf8", maxBuffer: 64 * 1024 * 1024 })
+  const out = `${r.stdout ?? ""}${r.stderr ?? ""}`.trim()
+  return { ok: r.status === 0, out }
+}
+
+type Simulator = { udid: string, name: string, state: string, runtime: string }
+type Device = { udid: string, name: string, model: string, state: string }
+
+/** The simulators (`simctl list devices`), every runtime. */
+export const listSimulators = (): Simulator[] => {
+  const { ok, out } = run(["simctl", "list", "devices", "--json"])
+  if (!ok) return []
+  try {
+    const json = JSON.parse(out) as { devices: Record<string, { udid: string, name: string, state: string, isAvailable?: boolean }[]> }
+    const all: Simulator[] = []
+    for (const [runtime, list] of Object.entries(json.devices)) {
+      for (const d of list) if (d.isAvailable !== false) all.push({ udid: d.udid, name: d.name, state: d.state, runtime: runtime.split(".").pop() ?? runtime })
+    }
+    return all
+  } catch { return [] }
+}
+
+/** The paired physical devices (`devicectl list devices`). */
+export const listDevices = (): Device[] => {
+  const tmp = join(process.env.TMPDIR ?? "/tmp", `lecodes-devicectl-${process.pid}.json`)
+  const { ok } = run(["devicectl", "list", "devices", "--json-output", tmp])
+  if (!ok || !existsSync(tmp)) return []
+  try {
+    const json = JSON.parse(readFileSync(tmp, "utf8")) as { result?: { devices?: { identifier: string, deviceProperties?: { name?: string }, hardwareProperties?: { marketingName?: string }, connectionProperties?: { pairingState?: string, tunnelState?: string } }[] } }
+    return (json.result?.devices ?? []).map((d) => ({
+      udid: d.identifier,
+      name: d.deviceProperties?.name ?? d.identifier,
+      model: d.hardwareProperties?.marketingName ?? "",
+      state: d.connectionProperties?.tunnelState ?? d.connectionProperties?.pairingState ?? "unknown",
+    }))
+  } catch { return [] } finally { try { unlinkSync(tmp) } catch { /* gone */ } }
+}
+
+const pickTarget = (udid: string | undefined): { kind: "simulator" | "device", udid: string, name: string } => {
+  if (process.platform !== "darwin") throw new CliError("--ios needs a Mac with Xcode (xcrun simctl / devicectl).")
+  const sims = listSimulators()
+  if (udid) {
+    const sim = sims.find((s) => s.udid === udid || s.name === udid)
+    if (sim) return { kind: "simulator", udid: sim.udid, name: `${sim.name} (${sim.runtime})` }
+    const dev = listDevices().find((d) => d.udid === udid || d.name === udid)
+    if (dev) return { kind: "device", udid: dev.udid, name: `${dev.name}${dev.model ? ` (${dev.model})` : ""}` }
+    throw new CliError(`No simulator or device "${udid}" — simulators: ${sims.map((s) => `${s.name} [${s.udid}]`).join(", ") || "none"}.`)
+  }
+  const booted = sims.filter((s) => s.state === "Booted")
+  if (booted.length === 1) return { kind: "simulator", udid: booted[0].udid, name: `${booted[0].name} (${booted[0].runtime})` }
+  if (booted.length > 1) throw new CliError(`Several booted simulators: ${booted.map((s) => `${s.name} [${s.udid}]`).join(", ")} — pick one with --udid <id|name>.`)
+  const devices = listDevices()
+  if (devices.length === 1) return { kind: "device", udid: devices[0].udid, name: `${devices[0].name}${devices[0].model ? ` (${devices[0].model})` : ""}` }
+  if (devices.length > 1) throw new CliError(`Several devices: ${devices.map((d) => `${d.name} [${d.udid}]`).join(", ")} — pick one with --udid <id|name>.`)
+  throw new CliError("No booted simulator and no paired iPhone: boot one in Simulator.app (or `xcrun simctl boot \"iPhone 17\"`), or plug a phone in and trust this Mac.")
+}
+
+const simulatorHasApp = (udid: string, bundleId: string): boolean => run(["simctl", "get_app_container", udid, bundleId]).ok
+
+const deviceHasApp = (udid: string, bundleId: string): boolean => {
+  const tmp = join(process.env.TMPDIR ?? "/tmp", `lecodes-devicectl-apps-${process.pid}.json`)
+  const { ok } = run(["devicectl", "device", "info", "apps", "--device", udid, "--json-output", tmp])
+  if (!ok || !existsSync(tmp)) return false
+  try {
+    const json = JSON.parse(readFileSync(tmp, "utf8")) as { result?: { apps?: { bundleIdentifier?: string }[] } }
+    return (json.result?.apps ?? []).some((a) => a.bundleIdentifier === bundleId)
+  } catch { return false } finally { try { unlinkSync(tmp) } catch { /* gone */ } }
+}
+
+/** Install (optional), launch the app on the dev url. Returns the session handle. */
+export const launchOnIos = (opts: IosDevOptions): IosDevSession => {
+  const target = pickTarget(opts.udid)
+  const bundleId = opts.bundleId ?? process.env.LECODES_IOS_BUNDLE ?? DEFAULT_IOS_BUNDLE
+  const launchedAt = Date.now()
+
+  if (opts.app) {
+    if (!existsSync(opts.app)) throw new CliError(`--app: ${opts.app} does not exist.`)
+    note(`Installing ${opts.app} on ${target.name}…`)
+    const r = target.kind === "simulator"
+      ? run(["simctl", "install", target.udid, opts.app])
+      : run(["devicectl", "device", "install", "app", "--device", target.udid, opts.app])
+    if (!r.ok) throw new CliError(`install failed: ${r.out}`)
+  }
+  const installed = target.kind === "simulator" ? simulatorHasApp(target.udid, bundleId) : deviceHasApp(target.udid, bundleId)
+  if (!installed) {
+    throw new CliError(`${bundleId} is not installed on ${target.name} — pass --app <LeCodesApp.app> (hosts/apple/app: xcodebuild -scheme LeCodesApp -destination 'generic/platform=iOS Simulator' build → DerivedData/…/LeCodesApp.app).`)
+  }
+
+  const url = target.kind === "simulator" ? opts.simulatorUrl : opts.deviceUrl
+  let pid: string | null = null
+  if (target.kind === "simulator") {
+    run(["simctl", "terminate", target.udid, bundleId])
+    const start = run(["simctl", "launch", target.udid, bundleId, "--lecodes-url", url])
+    if (!start.ok) throw new CliError(`Could not launch ${bundleId} on ${target.name}: ${start.out}`)
+    pid = /:\s*(\d+)\s*$/.exec(start.out)?.[1] ?? null
+  } else {
+    const tmp = join(process.env.TMPDIR ?? "/tmp", `lecodes-devicectl-launch-${process.pid}.json`)
+    const start = run(["devicectl", "device", "process", "launch", "--device", target.udid, "--terminate-existing", "--json-output", tmp, bundleId, "--lecodes-url", url])
+    if (!start.ok) throw new CliError(`Could not launch ${bundleId} on ${target.name}: ${start.out}`)
+    try {
+      const json = JSON.parse(readFileSync(tmp, "utf8")) as { result?: { process?: { processIdentifier?: number } } }
+      pid = json.result?.process?.processIdentifier?.toString() ?? null
+    } catch { pid = null } finally { try { unlinkSync(tmp) } catch { /* gone */ } }
+    if (!pid) warnErr("devicectl reported no pid — Ctrl+C will not terminate the app on the phone.")
+  }
+
+  let stopped = false
+  return {
+    kind: target.kind, udid: target.udid, name: target.name, bundleId,
+    screenshot: (file: string) => {
+      if (target.kind !== "simulator") return false
+      return run(["simctl", "io", target.udid, "screenshot", file]).ok
+    },
+    stop: () => {
+      if (stopped) return
+      stopped = true
+      if (target.kind === "simulator") run(["simctl", "terminate", target.udid, bundleId])
+      else if (pid) run(["devicectl", "device", "process", "terminate", "--device", target.udid, "--pid", pid])
+    },
+    crashLines: () => {
+      // A simulator app's crash lands in this Mac's DiagnosticReports as <AppName>-<date>.ips.
+      if (target.kind !== "simulator") return []
+      const dir = join(homedir(), "Library", "Logs", "DiagnosticReports")
+      if (!existsSync(dir)) return []
+      const appName = bundleId.split(".").pop() ?? ""
+      return readdirSync(dir)
+        .filter((f) => f.endsWith(".ips") && (f.startsWith("LeCodes") || (appName && f.toLowerCase().startsWith(appName.toLowerCase()))))
+        .filter((f) => statSync(join(dir, f)).mtimeMs >= launchedAt)
+        .map((f) => join(dir, f))
+    },
+  }
+}