@tapflowio/ios-agent 0.27.0 → 0.28.0

package/LICENSE-APACHE-2.0

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,12 @@
+@tapflowio/ios-agent — Third-Party Notices
+
+This package is licensed under the MIT License (see LICENSE).
+
+It includes logic derived from baguette
+(https://github.com/tddworks/baguette),
+licensed under the Apache License, Version 2.0 (see LICENSE-APACHE-2.0).
+
+It includes a list of launchd labels selected from simslim
+(https://github.com/MobAI-App/simslim),
+licensed under the MIT License. Copyright (c) 2026 Interlap.
+The full notice is in dist/leanLabels.js.

package/dist/DeviceChromeLoader.d.ts

@@ -1,11 +1,39 @@
 import type { ChromeData, ChromeButton, ChromeRect } from '@tapflowio/protocol';
+/** Runs a tool and resolves its stdout. Killing on timeout ends the swift interpreter too: the `swift`
+ *  driver execs into `swift-frontend` under the same pid (measured). */
+export type ChromeRunner = (cmd: string, args: string[], timeoutMs: number, signal: AbortSignal) => Promise<Buffer>;
 type ScreenSize = {
     width: number;
     height: number;
 };
 export declare function screenSizeFromDeviceType(profile: unknown, capabilities: unknown): ScreenSize | null;
+export interface DeviceChromeLoaderOptions {
+    run?: ChromeRunner;
+    chromeMapPath?: string;
+    chromeDir?: string;
+    profilesDir?: string;
+    /** Where rendered PNGs are cached, and the render scripts written. */
+    cacheDir?: string;
+    loadBudgetMs?: number;
+}
 export declare class DeviceChromeLoader {
-    load(typeIdentifier: string): ChromeData | null;
+    private readonly run;
+    private readonly chromeMapPath;
+    private readonly chromeDir;
+    private readonly profilesDir;
+    private readonly cacheDir;
+    private readonly loadBudgetMs;
+    /** One load per device type at a time, and its result for the life of the process. A failure is not kept:
+     *  the dashboard mounts no viewer at all without chrome, so remembering a `null` from one slow first boot
+     *  would leave that model blank until the agent restarted. Xcode updated under a running agent keeps the old
+     *  chrome until restart — this bypasses the disk cache's mtime check. */
+    private readonly loads;
+    private deviceTypes;
+    constructor(options?: DeviceChromeLoaderOptions);
+    load(typeIdentifier: string): Promise<ChromeData | null>;
+    /** Once per process when it succeeds: it used to run twice on every boot. */
+    private listDeviceTypes;
+    private loadUncached;
 }
 export type { ChromeData, ChromeButton, ChromeRect };
 //# sourceMappingURL=DeviceChromeLoader.d.ts.map

package/dist/DeviceChromeLoader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"DeviceChromeLoader.d.ts","sourceRoot":"","sources":["../src/DeviceChromeLoader.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAA;AAiiB/E,KAAK,UAAU,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAA;AAmBnD,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,OAAO,GAAG,UAAU,GAAG,IAAI,CAiBnG;AAqFD,qBAAa,kBAAkB;IAC7B,IAAI,CAAC,cAAc,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI;CAqMhD;AAED,YAAY,EAAE,UAAU,EAAE,YAAY,EAAE,UAAU,EAAE,CAAA"}
+{"version":3,"file":"DeviceChromeLoader.d.ts","sourceRoot":"","sources":["../src/DeviceChromeLoader.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAA;AAgB/E;wEACwE;AACxE,MAAM,MAAM,YAAY,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,KAAK,OAAO,CAAC,MAAM,CAAC,CAAA;AAkjBnH,KAAK,UAAU,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAA;AAmBnD,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,OAAO,GAAG,UAAU,GAAG,IAAI,CAiBnG;AAgFD,MAAM,WAAW,yBAAyB;IACxC,GAAG,CAAC,EAAE,YAAY,CAAA;IAClB,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,sEAAsE;IACtE,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,YAAY,CAAC,EAAE,MAAM,CAAA;CACtB;AAED,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAc;IAClC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAQ;IACtC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAQ;IAClC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAQ;IACpC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAQ;IACjC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAQ;IACrC;;;6EAGyE;IACzE,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAgD;IACtE,OAAO,CAAC,WAAW,CAAgC;gBAEvC,OAAO,GAAE,yBAA8B;IASnD,IAAI,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IAgBxD,6EAA6E;YAC/D,eAAe;YAQf,YAAY;CAyM3B;AAED,YAAY,EAAE,UAAU,EAAE,YAAY,EAAE,UAAU,EAAE,CAAA"}

package/dist/DeviceChromeLoader.js

@@ -1,25 +1,53 @@
 // Button layout logic (computeButtonLayout) is derived from baguette (Apache-2.0):
 // https://github.com/tddworks/baguette
-import { execFileSync } from 'child_process';
-import { existsSync, readFileSync, writeFileSync, statSync } from 'fs';
+import { execFile } from 'child_process';
+import { existsSync, readFileSync, statSync } from 'fs';
+import { rename, rm, writeFile } from 'fs/promises';
 import { join } from 'path';
 import { tmpdir } from 'os';
 const CHROME_MAP_PATH = '/Library/Developer/DeviceKit/chrome_map.plist';
 const CHROME_DIR = '/Library/Developer/DeviceKit/Chrome';
 const PROFILES_DIR = '/Library/Developer/CoreSimulator/Profiles/DeviceTypes';
-// ---------------------------------------------------------------------------
-// Utilities
-// ---------------------------------------------------------------------------
-function readPlistAsJson(filePath) {
-    const json = execFileSync('plutil', ['-convert', 'json', '-o', '-', filePath]);
+const defaultRunner = (cmd, args, timeoutMs, signal) => new Promise((resolve, reject) => {
+    execFile(cmd, args, { timeout: timeoutMs, killSignal: 'SIGKILL', signal, encoding: 'buffer', maxBuffer: 16 * 1024 * 1024 }, (err, stdout) => (err ? reject(err) : resolve(stdout)));
+});
+/** Per call: plutil, sips and simctl answer in milliseconds; a swift render compiles first. */
+const TOOL_TIMEOUT_MS = 10_000;
+const SWIFT_TIMEOUT_MS = 45_000;
+/** For a whole load. A cold cache runs a frame render plus one per button state, so per-call bounds alone
+ *  could add up to minutes against a boot the relay clients give 180s in total. */
+const LOAD_BUDGET_MS = 60_000;
+let renderSeq = 0;
+async function readPlistAsJson(ctx, filePath) {
+    const json = await ctx.run('plutil', ['-convert', 'json', '-o', '-', filePath], TOOL_TIMEOUT_MS, ctx.signal);
     return JSON.parse(json.toString());
 }
-function getSipsSize(filePath) {
-    const out = execFileSync('sips', ['-g', 'pixelWidth', '-g', 'pixelHeight', filePath]).toString();
+async function getSipsSize(ctx, filePath) {
+    const out = (await ctx.run('sips', ['-g', 'pixelWidth', '-g', 'pixelHeight', filePath], TOOL_TIMEOUT_MS, ctx.signal)).toString();
     const w = out.match(/pixelWidth:\s*([\d.]+)/);
     const h = out.match(/pixelHeight:\s*([\d.]+)/);
     return { width: Math.round(parseFloat(w[1])), height: Math.round(parseFloat(h[1])) };
 }
+/**
+ * Runs a generated swift script that writes one PNG. Both the script and the image get a name of their own:
+ * the frame scripts carry per-device geometry in their text, so a shared script path let two concurrent
+ * loads render one device with the other's numbers and cache it; and the image is renamed into place, so a
+ * render killed half-way, or read by another load mid-write, never leaves a truncated PNG behind as cache.
+ */
+async function renderSwift(ctx, script, inputs, outPath) {
+    const tag = `${process.pid}-${++renderSeq}`;
+    const scriptPath = join(ctx.cacheDir, `tapflow-render-${tag}.swift`);
+    const tmpOut = `${outPath}.${tag}.tmp`;
+    try {
+        await writeFile(scriptPath, script);
+        await ctx.run('swift', [scriptPath, ...inputs, tmpOut], SWIFT_TIMEOUT_MS, ctx.signal);
+        await rename(tmpOut, outPath);
+    }
+    finally {
+        await rm(scriptPath, { force: true });
+        await rm(tmpOut, { force: true });
+    }
+}
 // Mirrors baguette's LiveChromes.computeMargins + buttonTopLeft.
 // compositeW/H = device body dimensions in 1× PDF pts (before button margin expansion).
 // For composite PDF: pdfSize.width / pdfSize.height.
@@ -27,7 +55,7 @@ function getSipsSize(filePath) {
 // leftWidth/rightWidth: bezel sizes; top/bottom-anchor x offsets are measured from
 //   the screen edge (after bezel), so we add leftWidth for leading and subtract
 //   rightWidth for trailing to convert to canvas coordinates.
-function computeButtonLayout(inputs, resourcesDir, compositeW, compositeH, scale = 2, leftWidth = 0, rightWidth = 0) {
+async function computeButtonLayout(ctx, inputs, resourcesDir, compositeW, compositeH, scale = 2, leftWidth = 0, rightWidth = 0) {
     const margins = { left: 0, top: 0, right: 0, bottom: 0 };
     const infos = [];
     for (const inp of inputs) {
@@ -37,11 +65,13 @@ function computeButtonLayout(inputs, resourcesDir, compositeW, compositeH, scale
         if (!existsSync(pdfPath))
             continue;
         try {
-            const size = getSipsSize(pdfPath);
+            const size = await getSipsSize(ctx, pdfPath);
             const roll = inp.offsets.rollover ?? inp.offsets.normal;
             infos.push({ input: inp, w: size.width, h: size.height, roll });
         }
-        catch { /* skip unmeasurable assets */ }
+        catch {
+            ctx.incomplete = true; /* skip unmeasurable assets */
+        }
     }
     // Pass 1 — margins (baguette's computeMargins, rollover offset)
     for (const { input: inp, w, h, roll } of infos) {
@@ -115,7 +145,7 @@ function computeButtonLayout(inputs, resourcesDir, compositeW, compositeH, scale
             const downPath = join(resourcesDir, `${inp.imageDown}.pdf`);
             if (existsSync(downPath)) {
                 try {
-                    const downSize = getSipsSize(downPath);
+                    const downSize = await getSipsSize(ctx, downPath);
                     pressed = {
                         pdfPath: downPath,
                         topLeftX: btnTopLeftX,
@@ -124,7 +154,9 @@ function computeButtonLayout(inputs, resourcesDir, compositeW, compositeH, scale
                         pdfH: downSize.height,
                     };
                 }
-                catch { /* skip unmeasurable pressed asset */ }
+                catch {
+                    ctx.incomplete = true; /* skip unmeasurable pressed asset */
+                }
             }
         }
         pressedData.push(pressed);
@@ -186,7 +218,7 @@ function computeButtonLayout(inputs, resourcesDir, compositeW, compositeH, scale
 // ---------------------------------------------------------------------------
 // Single PDF → PNG at 2× (used for pressed-state button images)
 // ---------------------------------------------------------------------------
-function renderPdfToPng(pdfPath, outPath) {
+function renderPdfToPng(ctx, pdfPath, outPath) {
     const SCRIPT = `
 import Foundation
 import CoreGraphics
@@ -217,15 +249,13 @@ let dest = CGImageDestinationCreateWithURL(URL(fileURLWithPath: dst) as CFURL, "
 CGImageDestinationAddImage(dest, img, nil)
 CGImageDestinationFinalize(dest)
 `;
-    const scriptPath = join(tmpdir(), 'tapflow-pdf-to-png.swift');
-    writeFileSync(scriptPath, SCRIPT);
-    execFileSync('swift', [scriptPath, pdfPath, outPath]);
+    return renderSwift(ctx, SCRIPT, [pdfPath], outPath);
 }
 // ---------------------------------------------------------------------------
 // Frame PNG rendering — composite PDF path
 // Renders composite PDF + physical button PDFs into one PNG at 2×.
 // ---------------------------------------------------------------------------
-function renderFramePng(compositePdf, outPath, margins, buttons) {
+function renderFramePng(ctx, compositePdf, outPath, margins, buttons) {
     const behind = buttons.filter(b => !b.onTop);
     const onTop = buttons.filter(b => b.onTop);
     function btnLiteral(b) {
@@ -297,16 +327,14 @@ let dest = CGImageDestinationCreateWithURL(URL(fileURLWithPath: dst) as CFURL, "
 CGImageDestinationAddImage(dest, img, nil)
 CGImageDestinationFinalize(dest)
 `;
-    const scriptPath = join(tmpdir(), 'tapflow-frame-png.swift');
-    writeFileSync(scriptPath, SCRIPT);
-    execFileSync('swift', [scriptPath, compositePdf, outPath]);
+    return renderSwift(ctx, SCRIPT, [compositePdf], outPath);
 }
 // ---------------------------------------------------------------------------
 // Frame PNG rendering — nine-slice path
 // Rasterizes 8 PDF slices to bitmaps, composes them around the screen hole,
 // then draws physical button PDFs. Matches baguette's compose9Slice approach.
 // ---------------------------------------------------------------------------
-function renderNineSlicePng(slicePaths, outPath, leftWidth, rightWidth, topHeight, bottomHeight, cornerW, cornerH, screenW, screenH, margins, buttons) {
+function renderNineSlicePng(ctx, slicePaths, outPath, leftWidth, rightWidth, topHeight, bottomHeight, cornerW, cornerH, screenW, screenH, margins, buttons) {
     const behind = buttons.filter(b => !b.onTop);
     const onTop = buttons.filter(b => b.onTop);
     function btnLiteral(b) {
@@ -437,22 +465,7 @@ let dest   = CGImageDestinationCreateWithURL(URL(fileURLWithPath: dst) as CFURL,
 CGImageDestinationAddImage(dest, outImg, nil)
 CGImageDestinationFinalize(dest)
 `;
-    const scriptPath = join(tmpdir(), 'tapflow-frame-nineslice.swift');
-    writeFileSync(scriptPath, SCRIPT);
-    execFileSync('swift', [scriptPath, outPath]);
-}
-// ---------------------------------------------------------------------------
-// Model identifier and profile lookups
-// ---------------------------------------------------------------------------
-function modelIdentifierForType(typeIdentifier) {
-    try {
-        const out = execFileSync('xcrun', ['simctl', 'list', 'devicetypes', '-j']);
-        const types = JSON.parse(out.toString())['devicetypes'];
-        return types.find(t => t.identifier === typeIdentifier)?.modelIdentifier ?? null;
-    }
-    catch {
-        return null;
-    }
+    return renderSwift(ctx, SCRIPT, [], outPath);
 }
 // Physical px ÷ scale → logical points. A missing or non-positive value is no answer rather than a
 // wrong one.
@@ -496,19 +509,16 @@ export function screenSizeFromDeviceType(profile, capabilities) {
     }
     return null;
 }
-function loadProfileScreenSize(typeIdentifier) {
+async function loadProfileScreenSize(ctx, profilesDir, name) {
     try {
-        const out = execFileSync('xcrun', ['simctl', 'list', 'devicetypes', '-j']);
-        const types = JSON.parse(out.toString())['devicetypes'];
-        const name = types.find(t => t.identifier === typeIdentifier)?.name;
         if (!name)
             return null;
-        const resourcesDir = join(PROFILES_DIR, `${name}.simdevicetype`, 'Contents', 'Resources');
+        const resourcesDir = join(profilesDir, `${name}.simdevicetype`, 'Contents', 'Resources');
         const plistPath = join(resourcesDir, 'profile.plist');
         if (!existsSync(plistPath))
             return null;
         const capabilitiesPath = join(resourcesDir, 'capabilities.plist');
-        return screenSizeFromDeviceType(readPlistAsJson(plistPath), existsSync(capabilitiesPath) ? readPlistAsJson(capabilitiesPath) : null);
+        return screenSizeFromDeviceType(await readPlistAsJson(ctx, plistPath), existsSync(capabilitiesPath) ? await readPlistAsJson(ctx, capabilitiesPath) : null);
     }
     catch {
         return null;
@@ -517,35 +527,37 @@ function loadProfileScreenSize(typeIdentifier) {
 // ---------------------------------------------------------------------------
 // Button PNG attachment — renders each button's normal PDF separately for CSS overlay
 // ---------------------------------------------------------------------------
-function attachButtonPngs(buttons, drawData, chromeName) {
+async function attachButtonPngs(ctx, buttons, drawData, chromeName) {
     for (let i = 0; i < buttons.length; i++) {
         if (i >= drawData.length)
             continue;
         const pdfPath = drawData[i].pdfPath;
         const cacheKey = `tapflow-btn-normal-${chromeName}-${i}.png`;
-        const outPath = join(tmpdir(), cacheKey);
+        const outPath = join(ctx.cacheDir, cacheKey);
         try {
             if (!existsSync(outPath) || statSync(pdfPath).mtimeMs > statSync(outPath).mtimeMs) {
-                renderPdfToPng(pdfPath, outPath);
+                await renderPdfToPng(ctx, pdfPath, outPath);
             }
             buttons[i].buttonPng = readFileSync(outPath).toString('base64');
         }
-        catch { /* skip if rendering fails */ }
+        catch {
+            ctx.incomplete = true; /* skip if rendering fails */
+        }
     }
 }
 // ---------------------------------------------------------------------------
 // Pressed PNG attachment — renders imageDown PDFs and attaches to buttons[]
 // ---------------------------------------------------------------------------
-function attachPressedPngs(buttons, pressedData, chromeName, scale) {
+async function attachPressedPngs(ctx, buttons, pressedData, chromeName, scale) {
     for (let i = 0; i < buttons.length; i++) {
         const pd = pressedData[i];
         if (!pd)
             continue;
         const cacheKey = `tapflow-btn-pressed-${chromeName}-${i}.png`;
-        const outPath = join(tmpdir(), cacheKey);
+        const outPath = join(ctx.cacheDir, cacheKey);
         try {
             if (!existsSync(outPath) || statSync(pd.pdfPath).mtimeMs > statSync(outPath).mtimeMs) {
-                renderPdfToPng(pd.pdfPath, outPath);
+                await renderPdfToPng(ctx, pd.pdfPath, outPath);
             }
             buttons[i].pressedPng = readFileSync(outPath).toString('base64');
             buttons[i].pressedRect = {
@@ -555,24 +567,71 @@ function attachPressedPngs(buttons, pressedData, chromeName, scale) {
                 height: Math.round(pd.pdfH * scale),
             };
         }
-        catch { /* skip if rendering fails */ }
+        catch {
+            ctx.incomplete = true; /* skip if rendering fails */
+        }
     }
 }
-// ---------------------------------------------------------------------------
-// DeviceChromeLoader
-// ---------------------------------------------------------------------------
 export class DeviceChromeLoader {
+    run;
+    chromeMapPath;
+    chromeDir;
+    profilesDir;
+    cacheDir;
+    loadBudgetMs;
+    /** One load per device type at a time, and its result for the life of the process. A failure is not kept:
+     *  the dashboard mounts no viewer at all without chrome, so remembering a `null` from one slow first boot
+     *  would leave that model blank until the agent restarted. Xcode updated under a running agent keeps the old
+     *  chrome until restart — this bypasses the disk cache's mtime check. */
+    loads = new Map();
+    deviceTypes = null;
+    constructor(options = {}) {
+        this.run = options.run ?? defaultRunner;
+        this.chromeMapPath = options.chromeMapPath ?? CHROME_MAP_PATH;
+        this.chromeDir = options.chromeDir ?? CHROME_DIR;
+        this.profilesDir = options.profilesDir ?? PROFILES_DIR;
+        this.cacheDir = options.cacheDir ?? tmpdir();
+        this.loadBudgetMs = options.loadBudgetMs ?? LOAD_BUDGET_MS;
+    }
     load(typeIdentifier) {
+        const pending = this.loads.get(typeIdentifier);
+        if (pending)
+            return pending;
+        const budget = new AbortController();
+        const timer = setTimeout(() => budget.abort(), this.loadBudgetMs);
+        timer.unref?.();
+        const ctx = { run: this.run, signal: budget.signal, cacheDir: this.cacheDir, incomplete: false };
+        const loading = this.loadUncached(typeIdentifier, ctx).catch(() => null).finally(() => clearTimeout(timer));
+        this.loads.set(typeIdentifier, loading);
+        // A load that skipped a button still gives this boot a device, but is not kept: the budget usually runs
+        // out in the button renders, and remembering that result would hide those buttons until a restart. What
+        // did render is on disk, so the next boot picks up where this one stopped.
+        void loading.then((chrome) => { if (!chrome || ctx.incomplete)
+            this.loads.delete(typeIdentifier); });
+        return loading;
+    }
+    /** Once per process when it succeeds: it used to run twice on every boot. */
+    async listDeviceTypes(ctx) {
+        if (this.deviceTypes)
+            return this.deviceTypes;
+        const out = await ctx.run('xcrun', ['simctl', 'list', 'devicetypes', '-j'], TOOL_TIMEOUT_MS, ctx.signal);
+        const types = JSON.parse(out.toString())['devicetypes'];
+        this.deviceTypes = types;
+        return types;
+    }
+    async loadUncached(typeIdentifier, ctx) {
         try {
-            const modelId = modelIdentifierForType(typeIdentifier);
+            const types = await this.listDeviceTypes(ctx);
+            const typeInfo = types.find(t => t.identifier === typeIdentifier);
+            const modelId = typeInfo?.modelIdentifier;
             if (!modelId)
                 return null;
-            const chromeMap = readPlistAsJson(CHROME_MAP_PATH);
+            const chromeMap = await readPlistAsJson(ctx, this.chromeMapPath);
             const entry = chromeMap[modelId];
             if (!entry)
                 return null;
             const chromeName = entry.ChromeIdentifier.split('.').pop();
-            const resourcesDir = join(CHROME_DIR, `${chromeName}.devicechrome`, 'Contents', 'Resources');
+            const resourcesDir = join(this.chromeDir, `${chromeName}.devicechrome`, 'Contents', 'Resources');
             const chromeJsonPath = join(resourcesDir, 'chrome.json');
             if (!existsSync(chromeJsonPath))
                 return null;
@@ -592,21 +651,23 @@ export class DeviceChromeLoader {
             // -----------------------------------------------------------------------
             const compositePdf = join(resourcesDir, 'PhoneComposite.pdf');
             if (existsSync(compositePdf)) {
-                const pdfSize = getSipsSize(compositePdf);
+                const pdfSize = await getSipsSize(ctx, compositePdf);
                 const screenW = pdfSize.width - leftWidth - rightWidth;
                 const screenH = pdfSize.height - topHeight - bottomHeight;
                 const bezelInset = Math.max(leftWidth, topHeight);
                 const screenCornerRadius1x = Math.max(0, outerRadius - bezelInset);
-                const { margins: btnM, drawData, buttons, pressedData } = computeButtonLayout(rawInputs, resourcesDir, pdfSize.width, pdfSize.height, scale, leftWidth, rightWidth);
+                const { margins: btnM, drawData, buttons, pressedData } = await computeButtonLayout(ctx, rawInputs, resourcesDir, pdfSize.width, pdfSize.height, scale, leftWidth, rightWidth);
                 const expandedW = pdfSize.width + btnM.left + btnM.right;
                 const expandedH = pdfSize.height + btnM.top + btnM.bottom;
-                // v3: buttons excluded from framePng — rendered separately as CSS-animated overlays
-                const framePath = join(tmpdir(), `tapflow-frame-v3-${chromeName}.png`);
+                // v3: buttons excluded from framePng — rendered separately as CSS-animated overlays.
+                // The canvas size is in the key, as for nine-slice: a button that could not be measured shrinks the
+                // margins, and a frame rendered that way must not be served to a later load that measured them all.
+                const framePath = join(this.cacheDir, `tapflow-frame-v3-${chromeName}-c${Math.round(expandedW)}x${Math.round(expandedH)}.png`);
                 if (!existsSync(framePath) || statSync(compositePdf).mtimeMs > statSync(framePath).mtimeMs) {
-                    renderFramePng(compositePdf, framePath, btnM, []);
+                    await renderFramePng(ctx, compositePdf, framePath, btnM, []);
                 }
-                attachButtonPngs(buttons, drawData, chromeName);
-                attachPressedPngs(buttons, pressedData, chromeName, scale);
+                await attachButtonPngs(ctx, buttons, drawData, chromeName);
+                await attachPressedPngs(ctx, buttons, pressedData, chromeName, scale);
                 const screenRect = {
                     x: Math.round((leftWidth + btnM.left) * scale),
                     y: Math.round((topHeight + btnM.top) * scale),
@@ -659,11 +720,11 @@ export class DeviceChromeLoader {
             // Corner PDF dimensions define the actual bezel insets used in composition.
             // The sizing.leftWidth/rightWidth in chrome.json is the VISIBLE bezel width
             // (interior of the corner), not the full corner PDF dimensions.
-            const cornerSize = getSipsSize(slicePaths.topLeft);
+            const cornerSize = await getSipsSize(ctx, slicePaths.topLeft);
             const cornerW = cornerSize.width;
             const cornerH = cornerSize.height; // should equal topHeight from sizing
             // Get logical screen dimensions from the device type's plists
-            const screenSize = loadProfileScreenSize(typeIdentifier);
+            const screenSize = await loadProfileScreenSize(ctx, this.profilesDir, typeInfo?.name);
             if (!screenSize)
                 return null;
             const screenW = screenSize.width;
@@ -673,18 +734,18 @@ export class DeviceChromeLoader {
             const compositeH = topHeight + screenH + bottomHeight;
             const bezelInset = Math.max(leftWidth, topHeight);
             const screenCornerRadius1x = Math.max(0, outerRadius - bezelInset);
-            const { margins: btnM, drawData, buttons, pressedData } = computeButtonLayout(rawInputs, resourcesDir, compositeW, compositeH, scale, leftWidth, rightWidth);
+            const { margins: btnM, drawData, buttons, pressedData } = await computeButtonLayout(ctx, rawInputs, resourcesDir, compositeW, compositeH, scale, leftWidth, rightWidth);
             const expandedW = compositeW + btnM.left + btnM.right;
             const expandedH = compositeH + btnM.top + btnM.bottom;
             // nb = no-buttons: buttons excluded from framePng, rendered separately as CSS-animated overlays
-            const framePath = join(tmpdir(), `tapflow-frame-nineslice-nb-${chromeName}-${screenW}x${screenH}-c${Math.round(expandedW)}x${Math.round(expandedH)}.png`);
+            const framePath = join(this.cacheDir, `tapflow-frame-nineslice-nb-${chromeName}-${screenW}x${screenH}-c${Math.round(expandedW)}x${Math.round(expandedH)}.png`);
             const needsRender = !existsSync(framePath)
                 || statSync(slicePaths.topLeft).mtimeMs > statSync(framePath).mtimeMs;
             if (needsRender) {
-                renderNineSlicePng(slicePaths, framePath, leftWidth, rightWidth, topHeight, bottomHeight, cornerW, cornerH, screenW, screenH, btnM, []);
+                await renderNineSlicePng(ctx, slicePaths, framePath, leftWidth, rightWidth, topHeight, bottomHeight, cornerW, cornerH, screenW, screenH, btnM, []);
             }
-            attachButtonPngs(buttons, drawData, chromeName);
-            attachPressedPngs(buttons, pressedData, chromeName, scale);
+            await attachButtonPngs(ctx, buttons, drawData, chromeName);
+            await attachPressedPngs(ctx, buttons, pressedData, chromeName, scale);
             // Screen hole: starts at sizing insets within the device body
             const screenRect = {
                 x: Math.round((btnM.left + leftWidth) * scale),