simframe 0.4.2 → 0.6.0-rc.1

package/native/simframed/Tests/SimframeCoreTests/HashingTests.swift

@@ -0,0 +1,270 @@
+import XCTest
+import PrivateAPI
+@testable import SimframeCore
+
+/// These run without a simulator, against StubPlatform, so the pure logic is
+/// testable on any machine — including CI, which has no booted device.
+final class HashingTests: XCTestCase {
+
+    private func solid(_ w: Int, _ h: Int, _ v: UInt8) -> Bitmap {
+        var data = [UInt8](repeating: 0, count: w * h * 4)
+        for i in stride(from: 0, to: data.count, by: 4) {
+            data[i] = v; data[i + 1] = v; data[i + 2] = v; data[i + 3] = 255
+        }
+        return Bitmap(width: w, height: h, data: data)
+    }
+
+    private func split(_ w: Int, _ h: Int, left: UInt8, right: UInt8) -> Bitmap {
+        var data = [UInt8](repeating: 0, count: w * h * 4)
+        for y in 0..<h {
+            for x in 0..<w {
+                let v = x < w / 2 ? left : right
+                let i = (y * w + x) * 4
+                data[i] = v; data[i + 1] = v; data[i + 2] = v; data[i + 3] = 255
+            }
+        }
+        return Bitmap(width: w, height: h, data: data)
+    }
+
+    func testFitMatchesSipsLongEdgeBehaviour() {
+        // The real device shapes this has to reproduce.
+        XCTAssertEqual(Bitmap.fit(width: 1206, height: 2622, longEdge: 700).0, 322)
+        XCTAssertEqual(Bitmap.fit(width: 1206, height: 2622, longEdge: 700).1, 700)
+        XCTAssertEqual(Bitmap.fit(width: 2064, height: 2752, longEdge: 700).0, 525)
+        XCTAssertEqual(Bitmap.fit(width: 2064, height: 2752, longEdge: 700).1, 700)
+        // Smaller than the target is left alone rather than upscaled.
+        XCTAssertEqual(Bitmap.fit(width: 100, height: 200, longEdge: 700).1, 200)
+    }
+
+    func testGrayGridAveragesToLuminance() {
+        XCTAssertEqual(Hashing.grayGrid(solid(20, 20, 255), cols: 2, rows: 2), [255, 255, 255, 255])
+        XCTAssertEqual(Hashing.grayGrid(solid(20, 20, 0), cols: 2, rows: 2), [0, 0, 0, 0])
+    }
+
+    func testIdenticalScreensHashIdentically() {
+        let a = split(64, 128, left: 20, right: 220)
+        let b = split(64, 128, left: 20, right: 220)
+        XCTAssertEqual(Hashing.frameHash(a), Hashing.frameHash(b))
+        XCTAssertEqual(Hashing.layoutHash(a), Hashing.layoutHash(b))
+        XCTAssertEqual(Hashing.signatureDiff(Hashing.regionSignature(a), Hashing.regionSignature(b)), 0)
+    }
+
+    func testMirroredLayoutIsFarAway() {
+        let a = split(64, 128, left: 20, right: 220)
+        let b = split(64, 128, left: 220, right: 20)
+        // Well beyond the tolerance of 12 the screen memory uses.
+        XCTAssertGreaterThan(Hashing.hashDistance(Hashing.layoutHash(a), Hashing.layoutHash(b)), 20)
+    }
+
+    func testHashesAreTheExpectedWidth() {
+        let bmp = split(64, 128, left: 20, right: 220)
+        XCTAssertEqual(Hashing.frameHash(bmp).count, 32, "128 bits as 32 hex characters")
+        XCTAssertEqual(Hashing.layoutHash(bmp).count, 72, "288 bits as 72 hex characters")
+        XCTAssertEqual(Hashing.signatureToHex(Hashing.regionSignature(bmp)).count, 64)
+    }
+
+    func testSignatureDiffTreatsMissingBaselineAsFullChange() {
+        XCTAssertEqual(Hashing.signatureDiff(Hashing.regionSignature(solid(8, 8, 100)), nil), 1)
+    }
+
+    func testHashDistanceCountsBits() {
+        XCTAssertEqual(Hashing.hashDistance("abcd", "abcd"), 0)
+        XCTAssertEqual(Hashing.hashDistance("0", "f"), 4)
+        XCTAssertEqual(Hashing.hashDistance("abc", "abcd"), Int.max, "different widths are incomparable")
+    }
+
+    func testStubPlatformProducesReadablePaddedFrames() throws {
+        let stub = StubPlatform(width: 120, height: 260)
+        _ = try stub.attach(udid: nil)
+        let bmp = try stub.withFrame { frame -> Bitmap in
+            // The stub pads its rows on purpose: honouring bytesPerRow is the
+            // single easiest thing to get wrong against a real surface.
+            XCTAssertEqual(frame.bytesPerRow, frame.width * 4 + 40)
+            return Bitmap.from(frame, targetLongEdge: 130)
+        }
+        XCTAssertEqual(bmp.height, 130)
+        XCTAssertEqual(bmp.width, 60)
+        // Left half dark, right half light — a shear from bad padding would blur this.
+        let leftPixel = Int(bmp.data[(65 * bmp.width + 5) * 4])
+        let rightPixel = Int(bmp.data[(65 * bmp.width + bmp.width - 5) * 4])
+        XCTAssertLessThan(leftPixel, 100)
+        XCTAssertGreaterThan(rightPixel, 150)
+    }
+
+    func testChangeIsDetectedAcrossStubFrames() throws {
+        let stub = StubPlatform(width: 80, height: 160)
+        _ = try stub.attach(udid: nil)
+        let before = try stub.withFrame { Hashing.regionSignature(Bitmap.from($0, targetLongEdge: 80)) }
+        stub.simulateChange()
+        let after = try stub.withFrame { Hashing.regionSignature(Bitmap.from($0, targetLongEdge: 80)) }
+        XCTAssertGreaterThan(Hashing.signatureDiff(after, before), 0.004)
+    }
+}
+
+/// The Platform surface, exercised through StubPlatform so gestures and app
+/// lifecycle can be tested with no simulator and no private frameworks.
+final class PlatformSurfaceTests: XCTestCase {
+    private func stub() throws -> StubPlatform {
+        let s = StubPlatform(width: 120, height: 260)
+        _ = try s.attach(udid: nil)
+        return s
+    }
+
+    func testGesturesReachThePlatform() throws {
+        let s = try stub()
+        try s.tap(at: CGPoint(x: 10, y: 20), durationMs: 70)
+        try s.longPress(at: CGPoint(x: 30, y: 40), durationMs: 600)
+        try s.drag(from: CGPoint(x: 1, y: 2), to: CGPoint(x: 3, y: 4), holdMs: 500, durationMs: 400)
+        try s.swipe(from: CGPoint(x: 5, y: 6), to: CGPoint(x: 7, y: 8), durationMs: 300)
+        XCTAssertEqual(s.recorded, [
+            "tap(10,20)",
+            "longPress(30,40,600)",
+            "drag(1,2->3,4,hold=500)",
+            "swipe(5,6->7,8)",
+        ])
+    }
+
+    func testAppLifecycleReachesThePlatform() throws {
+        let s = try stub()
+        _ = try s.launch(bundleId: "com.example.app", arguments: ["-a"], environment: ["K": "V"])
+        try s.terminate(bundleId: "com.example.app")
+        try s.openURL("myapp://x")
+        try s.permission(action: "grant", service: "photos", bundleId: "com.example.app")
+        XCTAssertEqual(s.recorded, [
+            "launch(com.example.app)",
+            "terminate(com.example.app)",
+            "openURL(myapp://x)",
+            "permission(grant,photos,com.example.app)",
+        ])
+    }
+
+    func testTextRoutesAreDistinct() throws {
+        let s = try stub()
+        try s.type("abc")
+        try s.paste("abc")
+        // Two different mechanisms: key events are layout-dependent, paste is not.
+        XCTAssertEqual(s.recorded, ["type(abc)", "paste(abc)"])
+    }
+
+    func testAsciiIsTypeableAndEmojiIsNot() {
+        XCTAssertTrue(HIDKeyboard.canType("Fryer 3!"))
+        XCTAssertFalse(HIDKeyboard.canType("Fryer 🍟"), "emoji has no usage code and must go via paste")
+    }
+
+    func testOnlyVerifiedButtonsHaveCodes() {
+        XCTAssertEqual(HIDKeyboard.buttonCode(.home), 2)
+        // Unverified codes must refuse rather than guess: a wrong Indigo button
+        // can crash backboardd or lock the device.
+        for button in [HardwareButton.lock, .siri, .volumeUp, .volumeDown] {
+            XCTAssertNil(HIDKeyboard.buttonCode(button), "\(button.rawValue) is not verified")
+        }
+    }
+}
+
+/// Motion analysis, on synthetic frames so the expected answer is known.
+final class MotionTests: XCTestCase {
+    private func grid(_ fill: (Int, Int) -> UInt8) -> [UInt8] {
+        var g = [UInt8](repeating: 0, count: Motion.cols * Motion.rows)
+        for r in 0..<Motion.rows { for c in 0..<Motion.cols { g[r * Motion.cols + c] = fill(c, r) } }
+        return g
+    }
+
+    /// Content that varies in both directions, so a shift has a unique best
+    /// match. Horizontally uniform content makes every horizontal offset score
+    /// identically, and the search then reports an arbitrary one.
+    private func striped(offsetRows: Int = 0) -> [UInt8] {
+        grid { c, r in UInt8((((r + offsetRows) * 13) + c * 7) % 256) }
+    }
+
+    func testIdenticalFramesAreStill() {
+        XCTAssertEqual(Motion.difference(striped(), striped()), 0)
+    }
+
+    func testSettleNeedsConsecutiveStillFrames() {
+        let still = striped()
+        var history: [Motion.Frame] = []
+        for i in 0..<5 { history.append(Motion.Frame(at: Double(i) * 100, gray: still)) }
+        let state = Motion.state(history: history, now: 500)
+        XCTAssertTrue(state.settled)
+        XCTAssertGreaterThanOrEqual(state.stillFrames, Motion.stillFramesRequired)
+    }
+
+    func testAChangingScreenIsNotSettled() {
+        var history: [Motion.Frame] = []
+        for i in 0..<5 { history.append(Motion.Frame(at: Double(i) * 100, gray: striped(offsetRows: i * 6))) }
+        XCTAssertFalse(Motion.state(history: history, now: 500).settled)
+    }
+
+    func testSpinnerIsNeitherStillNorASceneChange() {
+        // Everything holds still except a small patch that keeps changing.
+        var history: [Motion.Frame] = []
+        for i in 0..<5 {
+            var g = striped()
+            for r in 40..<45 { for c in 20..<25 { g[r * Motion.cols + c] = UInt8((i * 90) % 256) } }
+            history.append(Motion.Frame(at: Double(i) * 100, gray: g))
+        }
+        let state = Motion.state(history: history, now: 500)
+        XCTAssertFalse(state.settled, "a spinner must not read as settled")
+        XCTAssertNotNil(state.animatingRegion, "the moving patch should be localised")
+    }
+
+    func testVerticalShiftIsMeasured() {
+        let (dx, dy, score) = Motion.shift(striped(), striped(offsetRows: 8))
+        XCTAssertEqual(dy, -8, "content moved up by eight rows")
+        XCTAssertEqual(dx, 0)
+        XCTAssertLessThan(score, 0.02)
+    }
+
+    func testScrollIsClassifiedWithAnOffset() throws {
+        let t = Motion.classify(before: striped(), after: striped(offsetRows: 8),
+                                pointHeight: 874, pointWidth: 402)
+        XCTAssertEqual(t.kind, .scroll)
+        // XCTUnwrap rather than `!`: a force unwrap here kills the whole test
+        // process with signal 5 and hides every other result.
+        let offset = try XCTUnwrap(t.offset)
+        // Eight of ninety-six rows of an 874pt screen.
+        XCTAssertEqual(offset.y, -874 * 8 / 96, accuracy: 1)
+    }
+
+    func testIdenticalScreensClassifyAsNoChange() {
+        let t = Motion.classify(before: striped(), after: striped(), pointHeight: 874, pointWidth: 402)
+        XCTAssertEqual(t.kind, .none)
+    }
+
+    func testDimmingTheWholeScreenReadsAsSomethingPresenting() {
+        let base = striped()
+        let dimmed = base.map { UInt8(max(0, Int($0) - 60)) }
+        let t = Motion.classify(before: base, after: dimmed, pointHeight: 874, pointWidth: 402)
+        XCTAssertTrue([.sheetPresent, .alertPresent].contains(t.kind), "got \(t.kind)")
+    }
+}
+
+/// An accessibility node becoming an element. The subrole matters: a search
+/// field is a TextField to the tree and a SearchField to anyone reading the
+/// map, and losing that costs the reader the only word that identifies it.
+final class AccessibilityElementTests: XCTestCase {
+    func testSubroleWinsWhenThereIsOne() {
+        let node = AXNode(role: "TextField", subrole: "SearchField", label: nil, value: "Search",
+                          identifier: "search", enabled: true, selected: false, focused: nil,
+                          frame: CGRect(x: 32, y: 803, width: 336, height: 38), depth: 2)
+        let element = Element(id: 0, node: node)
+        XCTAssertEqual(element.role, "SearchField")
+        XCTAssertEqual(element.value, "Search")
+        XCTAssertEqual(element.identifier, "search")
+        XCTAssertEqual(element.state.enabled, true)
+        XCTAssertEqual(element.state.selected, false)
+        XCTAssertNil(element.state.focused, "unknown stays unknown rather than becoming false")
+        XCTAssertEqual(element.source.names, ["ax"])
+        XCTAssertEqual(element.center, CGPoint(x: 200, y: 822))
+    }
+
+    func testPlainRoleSurvivesWithNoSubrole() {
+        let node = AXNode(role: "Button", label: "Continue",
+                          frame: CGRect(x: 38, y: 784, width: 326, height: 52), depth: 1)
+        let element = Element(id: 3, node: node)
+        XCTAssertEqual(element.role, "Button")
+        XCTAssertEqual(element.label, "Continue")
+        XCTAssertNil(element.identifier)
+        XCTAssertNil(element.json["identifier"], "an absent identifier is absent, not null")
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "simframe",
-  "version": "0.4.2",
+  "version": "0.6.0-rc.1",
   "mcpName": "io.github.lvlrSajjad/simframe",
   "description": "Always-warm iOS Simulator frames: agents read the screen in ~20ms instead of waiting on screenshots. MCP server + CLI.",
   "keywords": [
@@ -40,14 +40,22 @@
   },
   "files": [
     "src",
-    "native",
+    "native/ocr.swift",
+    "native/simframed/Package.swift",
+    "native/simframed/Sources",
+    "native/simframed/Tests",
+    "skills",
+    "scripts",
     "README.md",
     "LICENSE"
   ],
   "scripts": {
-    "test": "node --test test/unit.test.mjs",
+    "test": "SIMFRAME_HOME=\"$(mktemp -d)\" node --test test/unit.test.mjs",
     "mcp": "node src/cli.js mcp",
-    "smoke": "node scripts/smoke.mjs"
+    "smoke": "node scripts/smoke.mjs",
+    "bench": "./scripts/bench.sh",
+    "check:package": "node scripts/check-package.mjs",
+    "version": "node scripts/sync-server-version.mjs"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0"

package/scripts/bench-flow.mjs

@@ -0,0 +1,54 @@
+// Times a realistic navigation flow end to end, and reports where the time went.
+// Used to check that the input driver works at all, and to measure sim_do.
+import { runScript } from '../src/actions.js';
+import * as input from '../src/input.js';
+import * as api from '../src/index.js';
+import { launchApp, terminateApp } from '../src/simctl.js';
+
+const BUNDLE = process.argv[2];
+const device = process.argv[3];
+
+if (!BUNDLE) {
+  console.error('usage: node scripts/bench-flow.mjs <bundle-id> [device]');
+  process.exit(2);
+}
+
+const driver = await input.detectDriver();
+console.log(`driver: ${driver.available ? driver.version : driver.reason}`);
+if (!driver.available) process.exit(1);
+
+const { device: dev } = await api.ensureDaemon(device);
+console.log(`device: ${dev.name} (${dev.runtime})`);
+const geo = await input.screenInfo(dev.udid);
+console.log(`screen: ${geo.pixelWidth}x${geo.pixelHeight}px @${geo.density}x = ${geo.pointWidth}x${geo.pointHeight}pt\n`);
+
+const t0 = Date.now();
+try { await terminateApp(dev.udid, BUNDLE); } catch { /* not running */ }
+await launchApp(dev.udid, BUNDLE);
+const launched = await api.waitFor(device, { mode: 'settle', stableMs: 800, timeoutMs: 20_000 });
+console.log(`cold launch + settle: ${Date.now() - t0}ms (satisfied=${launched.satisfied})`);
+
+const nodes = await input.describeAll(dev.udid);
+console.log(`accessibility tree: ${nodes.length} elements`);
+const labelled = nodes.filter((n) => n.label && n.frame.width > 8 && n.frame.height > 8);
+console.log('\nlabelled elements (type, tap point, label):');
+for (const n of labelled.slice(0, 40)) {
+  const c = input.centerOf(n);
+  console.log(`  ${(n.type || '?').padEnd(14)} ${String(`${c.x},${c.y}`).padEnd(10)} ${n.label}`);
+}
+
+// Anything sitting in the bottom eighth of the screen is probably a tab bar.
+const tabs = labelled.filter((n) => n.frame.y > geo.pointHeight * 0.86);
+console.log(`\nlikely tab bar: ${tabs.map((t) => t.label).join(', ') || '(none found)'}`);
+
+if (tabs.length >= 2) {
+  const steps = tabs.slice(0, 4).map((t) => ({ tap: t.label }));
+  console.log(`\nrunning ${steps.length} tab switches as ONE sim_do call...`);
+  const t1 = Date.now();
+  const res = await runScript(device, { steps, stableMs: 500, timeoutMs: 10_000 });
+  for (const r of res.results) {
+    console.log(`  ${r.ok ? 'ok  ' : 'FAIL'} ${r.action}: ${r.ok ? r.detail : r.error}` +
+      (r.settled ? ` (settled ${r.settled.waitedMs}ms, changed=${r.settled.sawChange})` : ''));
+  }
+  console.log(`\n${res.ok ? 'flow completed' : 'FLOW FAILED'} — ${res.ranSteps}/${res.totalSteps} steps in ${Date.now() - t1}ms`);
+}

package/scripts/bench.sh

@@ -0,0 +1,98 @@
+#!/usr/bin/env bash
+# Reproduces every number in docs/BENCHMARKS.md.
+#
+# Needs a booted simulator. Numbers are medians; the first sample of anything
+# involving Vision is discarded, because its warm-up dwarfs the measurement.
+set -uo pipefail
+cd "$(dirname "$0")/.."
+
+DEVICE="${1:-}"
+BIN=native/simframed/.build/release/simframed
+
+say() { printf '\n\033[1m%s\033[0m\n' "$*"; }
+have() { command -v "$1" >/dev/null 2>&1; }
+
+say "environment"
+printf '  chip    %s\n' "$(sysctl -n machdep.cpu.brand_string 2>/dev/null)"
+printf '  macOS   %s\n' "$(sw_vers -productVersion)"
+printf '  Xcode   %s\n' "$(xcodebuild -version 2>/dev/null | head -1)"
+
+say "building simframed (release)"
+swift build -c release --package-path native/simframed 2>&1 | tail -1
+
+UDID="$DEVICE"
+if [ -z "$UDID" ]; then
+  UDID=$($BIN devices | head -1 | awk '{print $1}')
+fi
+if [ -z "$UDID" ]; then
+  echo "  no booted simulator; boot one and re-run" >&2
+  exit 1
+fi
+printf '  device  %s\n' "$($BIN devices | grep "$UDID" | cut -c40-)"
+
+say "capture pipeline (Phase 0)"
+$BIN bench --udid="$UDID" --n=300 | sed 's/^/  /'
+$BIN bench --udid="$UDID" --n=300 --max-dim=420 | sed 's/^/  /'
+
+say "simctl + sips, the path it replaces"
+for _ in 1 2 3 4 5; do
+  /usr/bin/time -p sh -c "xcrun simctl io $UDID screenshot --type=png --mask=ignored /tmp/bench.png >/dev/null 2>&1 && sips -Z 700 /tmp/bench.png --out /tmp/bench-s.png >/dev/null 2>&1" 2>&1 | grep real
+done | awk '{s+=$2; n++} END {printf "  mean %.0f ms over %d runs\n", s/n*1000, n}'
+
+say "hash compatibility (Swift vs JavaScript, needs a still screen)"
+node -e '
+const { execSync } = require("child_process");
+(async () => {
+  const api = await import("./src/index.js");
+  const { hashDistance } = await import("./src/analyze.js");
+  let a, b;
+  for (let i = 0; i < 25; i++) {
+    a = (await api.getState(undefined, {})).state;
+    await new Promise(r => setTimeout(r, 1000));
+    b = (await api.getState(undefined, {})).state;
+    if (a.hash === b.hash && a.layoutHash === b.layoutHash) break;
+  }
+  if (a.hash !== b.hash) { console.log("  screen never settled; skipped"); return; }
+  const sw = JSON.parse(execSync("native/simframed/.build/release/simframed hash").toString());
+  console.log(`  frameHash  delta ${hashDistance(b.hash, sw.hash)}/128`);
+  console.log(`  layoutHash delta ${hashDistance(b.layoutHash, sw.layoutHash)}/288`);
+})()' 2>/dev/null
+
+say "control socket round trips (Phase 1)"
+node -e '
+import("./src/control.js").then(async (c) => {
+  const UD = process.argv[1];
+  const med = a => { const s=[...a].sort((x,y)=>x-y); return s[s.length>>1]; };
+  const bench = async (label, fn, n) => {
+    const t = []; for (let i=0;i<n;i++){ const t0=Date.now(); await fn(i); t.push(Date.now()-t0); }
+    console.log(`  ${label.padEnd(22)} n=${String(n).padStart(3)}  median ${med(t)}ms`);
+  };
+  await bench("ping", () => c.request(UD,{action:"ping"}), 100);
+  await bench("status", () => c.status(UD), 50);
+  await bench("tap (70ms hold)", i => c.tap(UD, 200+(i%3), 300), 100);
+  await bench("tap (10ms hold)", i => c.tap(UD, 200+(i%3), 300, {durationMs:10}), 100);
+})' "$UDID" 2>/dev/null
+
+say "text recognition (Phase 2)"
+node -e '
+import("./src/control.js").then(async (c) => {
+  const UD = process.argv[1];
+  const med = a => { const s=[...a].sort((x,y)=>x-y); return s[s.length>>1]; };
+  const t=[]; for (let i=0;i<12;i++){ const t0=Date.now(); await c.request(UD,{action:"ui"}); t.push(Date.now()-t0); }
+  // Drop the first: Vision warm-up dwarfs it.
+  console.log(`  in-process   first ${t[0]}ms  median ${med(t.slice(1))}ms`);
+})' "$UDID" 2>/dev/null
+
+say "screen map build (Phase 2)"
+node -e '
+import("./src/index.js").then(async (api) => {
+  const UD = process.argv[1];
+  for (const pass of [1,2,3]) {
+    api.screenmap.forget(UD);
+    const t0 = Date.now();
+    try { await api.locate(undefined, "a", {}); } catch { /* the label need not exist */ }
+    console.log(`  build ${pass}: ${Date.now()-t0}ms`);
+  }
+})' "$UDID" 2>/dev/null
+
+say "done — compare against docs/BENCHMARKS.md"

package/scripts/check-package.mjs

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+// Does the tarball contain everything the installed tool needs?
+//
+// This is the cheapest catch for the two worst regressions this project has
+// shipped, both of which passed every test and printed nothing:
+//
+//   - `Tests/` was absent, so Package.swift declared a test target with no
+//     directory, SwiftPM reported overlapping sources, and every install
+//     silently fell back to the simctl engine.
+//   - `native/ocr.swift` was absent, so OCR was silently off for all users.
+//
+// The required list is DERIVED from what the build actually reads, never
+// hand-maintained. A hand-written list is how `files` rotted in the first
+// place: it was correct when written and wrong three commits later. Add a new
+// Swift source or a new module here and it becomes required automatically.
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const rel = (p) => path.relative(ROOT, p).split(path.sep).join('/');
+
+function walk(dir, filter, out = []) {
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return out;
+  }
+  for (const e of entries) {
+    const full = path.join(dir, e.name);
+    // .build holds compiled output, not inputs, and is never published.
+    if (e.isDirectory()) {
+      if (e.name === '.build' || e.name === 'node_modules') continue;
+      walk(full, filter, out);
+    } else if (filter(full)) {
+      out.push(full);
+    }
+  }
+  return out;
+}
+
+/** Everything the SwiftPM build and the Node runtime read at install or run time. */
+function requiredFiles() {
+  const swiftPackage = path.join(ROOT, 'native', 'simframed');
+  const required = new Set();
+
+  // The SwiftPM manifest, and every source under the targets it declares.
+  required.add(rel(path.join(swiftPackage, 'Package.swift')));
+  for (const dir of ['Sources', 'Tests']) {
+    for (const f of walk(path.join(swiftPackage, dir), (p) => p.endsWith('.swift'))) {
+      required.add(rel(f));
+    }
+  }
+  // Test targets are build inputs whether or not anyone runs them: a declared
+  // target with a missing directory fails the whole build.
+  if (!walk(path.join(swiftPackage, 'Tests'), (p) => p.endsWith('.swift')).length) {
+    throw new Error('no Swift test sources found — has the layout moved? This check would silently pass.');
+  }
+
+  // The standalone OCR helper, compiled on demand by src/ocr.js.
+  required.add(rel(path.join(ROOT, 'native', 'ocr.swift')));
+
+  // Every runtime module. `files` ships "src" wholesale today; asserting each
+  // one catches anybody narrowing that later.
+  for (const f of walk(path.join(ROOT, 'src'), (p) => p.endsWith('.js'))) required.add(rel(f));
+
+  // The Claude Code skill. It is the low-token path this tool is designed
+  // around, and an installed copy without it is an installation of half the
+  // idea — silently, which is the failure mode this whole check exists for.
+  for (const f of walk(path.join(ROOT, 'skills'), (p) => p.endsWith('.md'))) required.add(rel(f));
+  if (!walk(path.join(ROOT, 'skills'), (p) => p.endsWith('.md')).length) {
+    throw new Error('no skill found under skills/ — has the layout moved? This check would silently pass.');
+  }
+
+  // Anything package.json points at to run.
+  const pkg = JSON.parse(fs.readFileSync(path.join(ROOT, 'package.json'), 'utf8'));
+  for (const target of Object.values(pkg.bin ?? {})) required.add(target.replace(/^\.\//, ''));
+  if (pkg.main) required.add(pkg.main.replace(/^\.\//, ''));
+
+  return [...required].sort();
+}
+
+const required = requiredFiles();
+const packed = JSON.parse(execFileSync('npm', ['pack', '--dry-run', '--json'], { cwd: ROOT, encoding: 'utf8' }));
+const shipped = new Set(packed[0].files.map((f) => f.path));
+const missing = required.filter((f) => !shipped.has(f));
+
+console.log(`${required.length} build inputs required, ${shipped.size} files in the tarball`);
+for (const f of missing) console.log(`MISSING ${f}`);
+if (missing.length) {
+  console.error(
+    `\n${missing.length} file(s) the build needs are absent from the published package.` +
+      `\nThis does not fail a build or a test — it fails silently for whoever installs it.`,
+  );
+  process.exit(1);
+}
+console.log('ok — every build input ships');