dsh-mobilecode 0.11.8 → 0.12.0

package/lib/reference-workspace.js

@@ -0,0 +1,283 @@
+/**
+ * dsh-mobilecode — reference-comparison workspace (Feature A vertical slice).
+ *
+ * A project-scoped store of imported design references and device captures,
+ * persisted under ~/.dsh/mobilecode/reference/ (Setup.HOME), surviving GUI
+ * reloads. The store never trusts caller-supplied paths: images are written
+ * under generated ids, records carry metadata only, and association happens
+ * through the project/screen/stateId keys.
+ *
+ * Originals are preserved verbatim; alignment/crop transforms are recorded as
+ * metadata on the record (applied at compare time), never baked into the image.
+ *
+ * Image imports are guarded before any decode: header-only dimension parsing
+ * (PNG IHDR, JPEG SOF, WebP chunks) enforces a decompression limit — no pixel
+ * buffer is ever materialized by this module.
+ *
+ * Compare rendering (side-by-side / opacity overlay / swipe slider) is a
+ * client concern; this module serves the pair + metadata.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync, copyFileSync, rmSync, renameSync } from "node:fs"
+import path from "node:path"
+import crypto from "node:crypto"
+
+export const MAX_IMPORT_BYTES = 25 * 1024 * 1024 // 25 MB raw body cap (base64 inside JSON)
+export const MAX_IMAGE_DIMENSION = 8192 // header-only decompression fence
+const ALLOWED_EXT = new Set([".png", ".jpg", ".jpeg", ".webp"])
+const META = "meta.json"
+const IMAGES = "images"
+
+/** Header-only dimension read. Returns {width,height} or null when undetectable. */
+export function imageDimensions(buf) {
+  if (!Buffer.isBuffer(buf) || buf.length < 12) return null
+  // PNG: 8-byte signature, IHDR length+type, then width/height big-endian.
+  if (buf[0] === 0x89 && buf[1] === 0x50 && buf[2] === 0x4e && buf[3] === 0x47) {
+    if (buf.length < 24 || buf.toString("latin1", 12, 16) !== "IHDR") return null
+    return { width: buf.readUInt32BE(16), height: buf.readUInt32BE(20) }
+  }
+  // JPEG: scan markers for SOF0..SOF15 (skip SOF1-style 0xC0..0xCF except DHT C4).
+  if (buf[0] === 0xff && buf[1] === 0xd8) {
+    for (let i = 2; i + 9 < buf.length;) {
+      if (buf[i] !== 0xff) { i += 1; continue }
+      const marker = buf[i + 1]
+      if (marker === 0xd8 || marker === 0xd9 || (marker >= 0xd0 && marker <= 0xd7)) { i += 2; continue }
+      const len = buf.readUInt16BE(i + 2)
+      if (len < 2 || i + 2 + len > buf.length) break
+      if (marker >= 0xc0 && marker <= 0xcf && marker !== 0xc4 && marker !== 0xc8 && marker !== 0xcc) {
+        return { height: buf.readUInt16BE(i + 5), width: buf.readUInt16BE(i + 7) }
+      }
+      i += 2 + len
+    }
+    return null
+  }
+  // WebP: RIFF....WEBP + chunk header.
+  if (buf.toString("latin1", 0, 4) === "RIFF" && buf.toString("latin1", 8, 12) === "WEBP") {
+    const four = buf.toString("latin1", 12, 16)
+    if (four === "VP8X" && buf.length >= 30) {
+      const w = 1 + buf.readUIntLE(24, 3)
+      const h = 1 + buf.readUIntLE(27, 3)
+      return { width: w, height: h }
+    }
+    if (four === "VP8L" && buf.length >= 25) {
+      const bits = buf.readUInt32LE(21)
+      return { width: (bits & 0x3fff) + 1, height: ((bits >> 14) & 0x3fff) + 1 }
+    }
+    if (four === "VP8 " && buf.length >= 30) {
+      return { width: buf.readUInt16LE(26) & 0x3fff, height: buf.readUInt16LE(28) & 0x3fff }
+    }
+  }
+  return null
+}
+
+function nowIso() { return new Date().toISOString() }
+
+/** Validate + normalize the caller-declared import metadata. Throws on bad shape. */
+export function validateImportMeta({ project, screen, stateId, filename, provenance, intendedUse } = {}) {
+  const clean = (value, label, max) => {
+    if (typeof value !== "string" || value.trim() === "" || value.length > max) {
+      throw new Error(`${label} is required and must be a non-empty string <= ${max} chars`)
+    }
+    return value.trim()
+  }
+  const opt = (value, max) => (typeof value === "string" && value.trim() !== "" ? value.trim().slice(0, max) : undefined)
+  return {
+    project: clean(project, "project", 120),
+    screen: clean(screen, "screen", 120),
+    stateId: clean(stateId, "stateId", 120),
+    filename: opt(filename, 200),
+    provenance: opt(provenance, 1000),
+    intendedUse: opt(intendedUse, 500),
+  }
+}
+
+export class ReferenceWorkspace {
+  constructor(home) {
+    this.root = path.join(home, "reference")
+    this.imagesDir = path.join(this.root, IMAGES)
+    this.metaFile = path.join(this.root, META)
+  }
+
+  ensure() {
+    if (!existsSync(this.imagesDir)) mkdirSync(this.imagesDir, { recursive: true })
+  }
+
+  /** Tolerant read: malformed meta is quarantined (original preserved), never crashes the store. */
+  readMeta() {
+    this.ensure()
+    if (!existsSync(this.metaFile)) return []
+    let raw
+    try { raw = readFileSync(this.metaFile, "utf8") } catch { return [] }
+    let parsed
+    try { parsed = JSON.parse(raw) } catch {
+      const corrupt = `${this.metaFile}.corrupt-${Date.now()}`
+      try { copyFileSync(this.metaFile, corrupt); rmSync(this.metaFile) } catch { /* keep serving empty */ }
+      return []
+    }
+    if (!Array.isArray(parsed)) return []
+    // Drop records that no longer satisfy the shape (tolerate unknowns, keep knowns).
+    return parsed.filter((r) => r && typeof r === "object" && typeof r.id === "string" && typeof r.project === "string")
+  }
+
+  writeMeta(records) {
+    this.ensure()
+    // atomic (audit F2): a torn meta.json would quarantine the whole store
+    const tmp = this.metaFile + ".tmp"
+    writeFileSync(tmp, JSON.stringify(records, null, 2) + "\n", "utf8")
+    renameSync(tmp, this.metaFile)
+  }
+
+  #nextId(records) {
+    let id
+    do { id = crypto.randomBytes(8).toString("hex") } while (records.some((r) => r.id === id))
+    return id
+  }
+
+  #resolveFile(record) {
+    // Never accept caller input as a path: id + stored extension only.
+    const ext = typeof record.ext === "string" && ALLOWED_EXT.has(record.ext.toLowerCase()) ? record.ext.toLowerCase() : ".png"
+    return path.join(this.imagesDir, `${record.id}${ext}`)
+  }
+
+  list({ project } = {}) {
+    const records = this.readMeta()
+    const scoped = project === undefined ? records : records.filter((r) => r.project === project)
+    return scoped.map((r) => ({ ...r, file: this.#resolveFile(r) }))
+  }
+
+  get(id) {
+    const record = this.readMeta().find((r) => r.id === id)
+    return record === undefined ? undefined : { ...record, file: this.#resolveFile(record) }
+  }
+
+  latest(project, screen, stateId, kind) {
+    const records = this.readMeta()
+    const matches = records.filter((r) =>
+      r.project === project && r.screen === screen && r.stateId === stateId && r.kind === kind)
+    if (matches.length === 0) return undefined
+    matches.sort((a, b) => String(b.importedAt ?? "").localeCompare(String(a.importedAt ?? "")))
+    const record = matches[0]
+    return { ...record, file: this.#resolveFile(record) }
+  }
+
+  active(project) {
+    const record = this.readMeta().find((r) => r.project === project && r.active === true)
+    return record === undefined ? undefined : { ...record, file: this.#resolveFile(record) }
+  }
+
+  setActive(id) {
+    const records = this.readMeta()
+    const target = records.find((r) => r.id === id)
+    if (target === undefined) throw new Error(`unknown reference id: ${id}`)
+    for (const record of records) record.active = record.id === id
+    this.writeMeta(records)
+    return { ...target, active: true, file: this.#resolveFile(target) }
+  }
+
+  /** Baseline approval — bound to the stored BYTES and recorded capture config at
+   *  approval time. A later byte change or config change silently invalidates it
+   *  (the diff route re-verifies the binding); candidates never need approval. */
+  setApproved(id, approved = true) {
+    const records = this.readMeta()
+    const target = records.find((r) => r.id === id)
+    if (target === undefined) throw new Error(`unknown reference id: ${id}`)
+    if (approved) {
+      target.approved = true
+      target.approval = {
+        sha256: crypto.createHash("sha256").update(this.readImage(target)).digest("hex"),
+        config: target.device ?? null,
+        approvedAt: nowIso(),
+      }
+    } else {
+      target.approved = false
+      delete target.approval
+    }
+    this.writeMeta(records)
+    return { ...target, file: this.#resolveFile(target) }
+  }
+
+  /**
+   * Import a design reference from a base64 data URL (data:image/png;base64,..)
+   * or a raw base64 string. Decode-free validation: extension whitelist, byte
+   * cap, header-only dimension fence. Original bytes are stored verbatim.
+   */
+  import(meta, data) {
+    const validated = validateImportMeta(meta)
+    const match = /^data:image\/(png|jpeg|jpg|webp);base64,([A-Za-z0-9+/=]+)$/.exec(String(data ?? ""))
+    const b64 = match ? match[2] : (() => {
+      const cleaned = String(data ?? "").replace(/^data:image\/[a-z]+;base64,/, "")
+      return /^[A-Za-z0-9+/=]+$/.test(cleaned) ? cleaned : ""
+    })()
+    if (b64 === "") throw new Error("image data must be a base64 data URL (data:image/png;base64,...)")
+    const buf = Buffer.from(b64, "base64")
+    if (buf.length === 0) throw new Error("image data is empty")
+    if (buf.length > MAX_IMPORT_BYTES) throw new Error(`image exceeds ${MAX_IMPORT_BYTES} bytes`)
+    const ext = match ? `.${match[1]}` : path.extname(validated.filename ?? "ref.png").toLowerCase()
+    // Note: path.extname(".png") returns "" (dotfile semantics), so the matched
+    // data-URL extension bypasses extname entirely.
+    if (!ALLOWED_EXT.has(ext)) throw new Error(`unsupported image type "${ext}" (png/jpg/webp only)`)
+    const dims = imageDimensions(buf)
+    if (dims === null) throw new Error("unable to read image dimensions from header")
+    if (dims.width > MAX_IMAGE_DIMENSION || dims.height > MAX_IMAGE_DIMENSION) {
+      throw new Error(`image is ${dims.width}x${dims.height} — exceeds ${MAX_IMAGE_DIMENSION}px fence`)
+    }
+    const records = this.readMeta()
+    const id = this.#nextId(records)
+    const record = {
+      id, kind: "reference", project: validated.project, screen: validated.screen, stateId: validated.stateId,
+      ext, width: dims.width, height: dims.height,
+      source: validated.filename, provenance: validated.provenance, intendedUse: validated.intendedUse,
+      importedAt: nowIso(), approved: false, active: false, transform: null,
+    }
+    this.writeFile(id, ext, buf)
+    records.push(record)
+    this.writeMeta(records)
+    return { ...record, file: this.#resolveFile(record) }
+  }
+
+  /**
+   * Associate an existing device capture (PNG path from DeviceBuild.screenCapture)
+   * with a project/screen/state. The original capture file is copied into the
+   * store verbatim; device configuration is recorded as metadata, never edited.
+   */
+  capture({ project, screen, stateId, pngPath, device }) {
+    const validated = validateImportMeta({ project, screen, stateId })
+    if (typeof pngPath !== "string" || !existsSync(pngPath)) throw new Error(`capture file not found: ${pngPath}`)
+    const buf = readFileSync(pngPath)
+    if (buf.length === 0) throw new Error("capture file is empty")
+    const dims = imageDimensions(buf)
+    if (dims === null) throw new Error("capture is not a readable PNG/JPEG/WebP")
+    const records = this.readMeta()
+    const id = this.#nextId(records)
+    const record = {
+      id, kind: "capture", project: validated.project, screen: validated.screen, stateId: validated.stateId,
+      ext: ".png", width: dims.width, height: dims.height,
+      source: path.basename(pngPath), provenance: "device-capture", intendedUse: "baseline-evidence",
+      importedAt: nowIso(), approved: false, active: false, transform: null,
+      device: device ?? {},
+    }
+    copyFileSync(pngPath, this.#resolveFile(record))
+    records.push(record)
+    this.writeMeta(records)
+    return { ...record, file: this.#resolveFile(record) }
+  }
+
+  writeFile(id, ext, buf) {
+    this.ensure()
+    writeFileSync(path.join(this.imagesDir, `${id}${ext}`), buf)
+  }
+
+  readImage(record) {
+    return readFileSync(this.#resolveFile(record))
+  }
+
+  remove(id) {
+    const records = this.readMeta()
+    const target = records.find((r) => r.id === id)
+    if (target === undefined) return false
+    const file = this.#resolveFile(target)
+    try { rmSync(file, { force: true }) } catch { /* best-effort file removal */ }
+    this.writeMeta(records.filter((r) => r.id !== id))
+    return true
+  }
+}

package/lib/skill.js

@@ -47,7 +47,7 @@ The loop is **observe once → act with an assertion → observe again only if t
 - Prefer \`device_tap_element\` (resource-id / text / content-desc). Raw pixel coordinates through \`device_input action=tap\` are the last resort — they break on the next layout change.
 - When you must tap pixels, take the center of a box from \`device_ui_tree\`/\`device_screen\`: x=(x1+x2)/2, y=(y1+y2)/2. Coordinates are ABSOLUTE pixels of the current display.
 - \`device_input action=swipe\` scrolls; \`action=key\` with "back" is a first-class verb on Android — use it instead of hunting for an on-screen back arrow.
-- Typing: ASCII goes through `input text` directly. Non-ASCII (Chinese, emoji) needs the ADBKeyboard IME — `device_input` uses it automatically when installed, and refuses with the install hint otherwise (github.com/senzhk/ADBKeyBoard); do not retry a refused non-ASCII type.
+- Typing: ASCII goes through \`input text\` directly. Non-ASCII (Chinese, emoji) needs the ADBKeyboard IME — \`device_input\` uses it automatically when installed, and refuses with the install hint otherwise (github.com/senzhk/ADBKeyBoard); do not retry a refused non-ASCII type.
 
 ## Never guess a package name or a control
 

package/lib/visual-compare.js

@@ -0,0 +1,196 @@
+/**
+ * dsh-mobilecode — visual comparison core (pure, dependency-free).
+ *
+ * Operates on decoded RGBA frames ({width, height, rgba:Uint8ClampedArray|Buffer}).
+ * Decoding is the CALLER's boundary: the browser canvas for the GUI, test
+ * fixtures for headless checks. The plugin server never pixel-decodes, so no
+ * image library is added to the base plugin.
+ *
+ * Two modes, kept SEPARATE by design (they answer different questions and
+ * must never share a single pass/fail threshold):
+ *  - regression:        same environment, approved native baseline vs current.
+ *                       Absolute pixel diff is meaningful here.
+ *  - design-reference:  implementation vs design target image. Pixel equality
+ *                       is NOT expected (different renderer, font stack,
+ *                       typography metrics) — this reports structure and
+ *                       regions, it does not grade a score.
+ *
+ * Findings are concrete (regions that changed, where, by how much); no
+ * "UI quality 98/100" anywhere. OCR corroboration is passed IN as boxes by
+ * the caller — disagreement between observers is reported, never averaged.
+ */
+
+/** RGBA L1 distance > per-channel threshold counts as a changed pixel. */
+export function diffFrames(a, b, { threshold = 24, masks = [], skip = [] } = {}) {
+  if (a.width !== b.width || a.height !== b.height) {
+    // Frames of different sizes cannot be diffed as-is: the caller must align
+    // (record explicit transform) or this is honestly blocked, not approximated.
+    return { status: "blocked", reason: `frame size mismatch ${a.width}x${a.height} vs ${b.width}x${b.height} — align first`, changedPixels: 0, totalPixels: 0 }
+  }
+  const w = a.width, h = a.height
+  const skipAll = [...masks, ...skip]
+  let changed = 0
+  const marks = new Uint8Array(w * h)
+  for (let i = 0; i < w * h; i++) {
+    const x = i % w, y = (i / w) | 0
+    if (skipAll.some((r) => x >= r.x && x < r.x + r.width && y >= r.y && y < r.y + r.height)) continue
+    const p = i * 4
+    const d = Math.abs(a.rgba[p] - b.rgba[p]) + Math.abs(a.rgba[p + 1] - b.rgba[p + 1]) + Math.abs(a.rgba[p + 2] - b.rgba[p + 2]) + Math.abs(a.rgba[p + 3] - b.rgba[p + 3])
+    if (d > threshold) { changed += 1; marks[i] = 1 }
+  }
+  const total = w * h - skipAll.reduce((acc, r) => acc + r.width * r.height, 0)
+  const filterStats = { droppedClusters: 0, droppedPixels: 0 }
+  const clusters = clusterMarks(marks, w, h, 40, filterStats)
+  return {
+    status: "ok",
+    changedPixels: changed,
+    totalPixels: Math.max(total, 1),
+    changePct: Number(((changed / Math.max(total, 1)) * 100).toFixed(3)),
+    threshold,
+    clusters, // [{x,y,width,height,pixels}] — VISUALIZATION only
+    // The verdict (changedPixels) is INDEPENDENT of cluster filtering: small
+    // clusters dropped below minPixels never hide a change from regression.
+    clusterFilter: { minPixels: 40, ...filterStats },
+  }
+}
+
+/** Connected components (4-neighbour flood fill) over changed-pixel marks. */
+export function clusterMarks(marks, w, h, minPixels = 40, stats = null) {
+  const seen = new Uint8Array(w * h)
+  const clusters = []
+  const stack = new Int32Array(w * h)
+  for (let start = 0; start < w * h; start++) {
+    if (!marks[start] || seen[start]) continue
+    let top = 0
+    stack[top++] = start
+    seen[start] = 1
+    let minX = w, minY = h, maxX = 0, maxY = 0, pixels = 0
+    while (top > 0) {
+      const i = stack[--top]
+      const x = i % w, y = (i / w) | 0
+      pixels += 1
+      if (x < minX) minX = x; if (x > maxX) maxX = x
+      if (y < minY) minY = y; if (y > maxY) maxY = y
+      if (x > 0 && marks[i - 1] && !seen[i - 1]) { seen[i - 1] = 1; stack[top++] = i - 1 }
+      if (x < w - 1 && marks[i + 1] && !seen[i + 1]) { seen[i + 1] = 1; stack[top++] = i + 1 }
+      if (y > 0 && marks[i - w] && !seen[i - w]) { seen[i - w] = 1; stack[top++] = i - w }
+      if (y < h - 1 && marks[i + w] && !seen[i + w]) { seen[i + w] = 1; stack[top++] = i + w }
+    }
+    if (pixels >= minPixels) clusters.push({ x: minX, y: minY, width: maxX - minX + 1, height: maxY - minY + 1, pixels })
+    else if (stats) { stats.droppedClusters += 1; stats.droppedPixels += pixels }
+  }
+  clusters.sort((p, q) => q.pixels - p.pixels)
+  return clusters.slice(0, 50)
+}
+
+/**
+ * Explicit alignment transform (recorded, never baked into stored images).
+ * Output-space contract: out(x,y) samples in((x-dx)/scaleX,(y-dy)/scaleY).
+ * dx/dy are output-space offsets — THE SAME transform the panel must render
+ * (audit §3: displayed overlay and computed diff share one contract).
+ */
+export function applyAlign(frame, { scaleX = 1, scaleY = 1, dx = 0, dy = 0 } = {}) {
+  if (scaleX === 1 && scaleY === 1 && dx === 0 && dy === 0) return frame
+  const w = Math.max(1, Math.round(frame.width * scaleX) + Math.abs(dx))
+  const h = Math.max(1, Math.round(frame.height * scaleY) + Math.abs(dy))
+  const out = new Uint8ClampedArray(w * h * 4)
+  for (let y = 0; y < h; y++) {
+    const sy = Math.floor((y - dy) / scaleY)
+    if (sy < 0 || sy >= frame.height) continue
+    for (let x = 0; x < w; x++) {
+      const sx = Math.floor((x - dx) / scaleX)
+      if (sx < 0 || sx >= frame.width) continue
+      const t = (y * w + x) * 4
+      const s = (sy * frame.width + sx) * 4
+      out[t] = frame.rgba[s]; out[t + 1] = frame.rgba[s + 1]; out[t + 2] = frame.rgba[s + 2]; out[t + 3] = frame.rgba[s + 3]
+    }
+  }
+  return { width: w, height: h, rgba: out, align: { scaleX, scaleY, dx, dy } }
+}
+
+/**
+ * Map a region from ALIGNED comparison space back to the ORIGINAL frame's
+ * pixel space, so reported findings are reviewable on stored originals.
+ */
+export function mapRegionToFrame(region, { scaleX = 1, scaleY = 1, dx = 0, dy = 0 } = {}) {
+  const r = (v) => Math.max(0, Math.round(v))
+  return {
+    x: r((region.x - dx) / scaleX), y: r((region.y - dy) / scaleY),
+    width: Math.max(1, r(region.width / scaleX)), height: Math.max(1, r(region.height / scaleY)),
+  }
+}
+
+/** Integer box-average downsample — simulates a canvas reduction; used by tests to PROVE reduced-resolution diffs can lose real changes. */
+export function boxAverage(frame, factor) {
+  const f = Math.max(1, Math.round(factor))
+  const w = Math.max(1, Math.floor(frame.width / f))
+  const h = Math.max(1, Math.floor(frame.height / f))
+  const out = new Uint8ClampedArray(w * h * 4)
+  for (let y = 0; y < h; y++) for (let x = 0; x < w; x++) {
+    let r = 0, g = 0, b = 0, a = 0, n = 0
+    for (let yy = y * f; yy < Math.min((y + 1) * f, frame.height); yy++) for (let xx = x * f; xx < Math.min((x + 1) * f, frame.width); xx++, n++) {
+      const p = (yy * frame.width + xx) * 4
+      r += frame.rgba[p]; g += frame.rgba[p + 1]; b += frame.rgba[p + 2]; a += frame.rgba[p + 3]
+    }
+    const t = (y * w + x) * 4
+    out[t] = r / n; out[t + 1] = g / n; out[t + 2] = b / n; out[t + 3] = a / n
+  }
+  return { width: w, height: h, rgba: out }
+}
+
+/** Masks are opt-in exclusions with a REQUIRED documented reason — no silent masking (audit §2). */
+export function validateMasks(masks) {
+  return (masks ?? []).map((m, i) => {
+    if (!m || typeof m !== "object") throw new Error(`mask ${i}: must be an object`)
+    if (typeof m.reason !== "string" || m.reason.trim() === "") throw new Error(`mask ${i}: a documented reason is required (masks hide defects — never adjust them to make a comparison pass)`)
+    for (const k of ["x", "y", "width", "height"]) if (typeof m[k] !== "number" || !Number.isFinite(m[k]) || m[k] < 0) throw new Error(`mask ${i}: ${k} must be a non-negative number`)
+    return { x: m.x | 0, y: m.y | 0, width: m.width | 0, height: m.height | 0, reason: m.reason.trim().slice(0, 500) }
+  })
+}
+
+/**
+ * Corroborate clusters against OCR text boxes passed in by the caller.
+ * Reports DISAGREEMENT explicitly: changed pixels with no text, text with no
+ * change — evidence to look at, not averaged truth.
+ */
+export function ocrCorroboration(clusters, ocrBoxes = []) {
+  const inCluster = (box) => clusters.some((c) =>
+    box.x < c.x + c.width && box.x + box.width > c.x && box.y < c.y + c.height && box.y + box.height > c.y)
+  return {
+    textInChangedRegions: ocrBoxes.filter(inCluster).map((b) => b.text ?? "(unlabeled)"),
+    changedRegionsWithoutText: clusters.filter((c) => !ocrBoxes.some((b) => inCluster([{ ...b }]) &&
+      b.x < c.x + c.width && b.x + b.width > c.x && b.y < c.y + c.height && b.y + b.height > c.y)).length,
+    note: "disagreements listed; never averaged into a single score",
+  }
+}
+
+/** Unified result envelope — status is about the OPERATION, never a verdict on UI quality. */
+export function compareEnvelope({ runId, project, screen, stateId, mode, diff, observations = [], evidenceRefs = [], env = {}, comparisonSpace = "native", transforms = null, limitations = [] }) {
+  if (mode !== "regression" && mode !== "design-reference") throw new Error('mode must be "regression" | "design-reference"')
+  if (comparisonSpace !== "native" && comparisonSpace !== "downsampled") throw new Error('comparisonSpace must be "native" | "downsampled"')
+  let checkStatus
+  if (diff.status === "blocked") checkStatus = "blocked"
+  else if (mode === "regression") {
+    // A REDUCED-resolution comparison can never prove native pixel equality
+    // (downsampling can erase small changes) — it is triage, needs_review at best.
+    if (diff.changedPixels > 0) checkStatus = "failed"
+    else checkStatus = comparisonSpace === "native" ? "passed" : "needs_review"
+  } else checkStatus = "needs_review"
+  return {
+    runId, project, screen, stateId, mode,
+    operation: diff.status === "blocked" ? "blocked" : "completed",
+    checkStatus,
+    comparisonSpace,
+    transforms: transforms ?? undefined,
+    diff,
+    observations, // [{source, finding}] — concrete observations only
+    evidenceRefs,
+    env,
+    limitations: [
+      ...(mode === "design-reference" ? ["design-reference mode compares structure, not pixels; renderer and typography differ by nature"] : []),
+      ...(comparisonSpace === "downsampled" ? ["reduced-resolution comparison is triage only — it CANNOT establish native pixel equality (small changes may be erased); run full-resolution regression for a passed verdict"] : []),
+      ...limitations,
+    ],
+    note: "tool ran; this is NOT a visual pass. regression (native): any changed pixel fails; masks require documented reasons and are shown in review, never adjusted to hide defects. design-reference: human/critic review required.",
+  }
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-mobilecode",
   "description": "MobileCode for the dsh web GUI: detect iOS/Android projects, run preview servers, and drive the simulator/emulator from the session — 37 agent tools (device_run, device_screen, device_ui_tree, device_ui_rows, device_tap_row, device_tap_element, device_wait_for, device_scroll_to, device_input, device_batch, device_intent, device_connect, device_pair_qr, device_perf, device_meminfo, device_backtrace, device_display, device_avd_create, device_pair_capture, device_app_info, device_install, device_uninstall, device_reboot, device_log, live screen stream, multimodal screenshots) plus a host-mediated co-op mesh hub (random callsigns, JSON pub/sub, tunable latency/jitter/drop/dup/throttle) so two virtual devices — and the AI watching them — can talk in real time. One classified adb boundary and a Wi-Fi connect/pair QR flow in the Connection settings tab. Hot-pluggable — mounted via the profile bundle list + cordis.patch.yml, no dsh source changes.",
-  "version": "0.11.8",
+  "version": "0.12.0",
   "type": "module",
   "packageManager": "pnpm@11.22.0",
   "engines": {