dsh-mobilecode 0.11.9 → 0.12.1

package/lib/openpencil.js

@@ -0,0 +1,139 @@
+/**
+ * dsh-mobilecode — OpenPencil narrow adapter (T7/Feature D).
+ *
+ * OpenPencil is a design EDITOR whose CLI exports PNG/JPG/WEBP/SVG/JSX/HTML
+ * (verified against openpencil.dev/reference/cli, 2026-09-14). Its exports are
+ * web-oriented — this adapter NEVER claims native Compose export. Value here:
+ * frame → PNG reference into the comparison workspace + design-token
+ * inspection (`variables --json`).
+ *
+ * Safety:
+ *  - optional: nothing in this module runs at plugin load; absence of the
+ *    binary degrades to a status report (base plugin unaffected);
+ *  - every path is confined to an explicitly allowed project root
+ *    (realpath-based: no traversal through .. or symlinks);
+ *  - CLI called with argument arrays only; no shell; no network calls;
+ *  - output goes to a caller-invisible temp location inside the store, never
+ *    next to the user's design file.
+ */
+
+import { existsSync, lstatSync, realpathSync, mkdirSync } from "node:fs"
+import path from "node:path"
+import * as DeviceBuild from "./device-build.js"
+
+const CLI = "openpencil"
+const DOC_TIMEOUT_MS = 60_000
+
+export function probe() {
+  const resolved = DeviceBuild.resolveExecutable(CLI)
+  return { installed: resolved !== undefined && resolved !== null && resolved !== "", resolved: resolved ?? undefined }
+}
+
+/** Run the CLI with an argument array; bounded output + timeout.
+ * Uses DeviceBuild.launch (audit P4-2): npm installs resolve to openpencil.cmd,
+ * which bare spawn() refuses with EINVAL on Windows. */
+function runCli(args, { timeoutMs = DOC_TIMEOUT_MS } = {}) {
+  return new Promise((resolve) => {
+    const child = DeviceBuild.launch(DeviceBuild.resolveExecutable(CLI) ?? CLI, args, { windowsHide: true, stdio: ["ignore", "pipe", "pipe"] })
+    let out = ""
+    let err = ""
+    let truncated = false
+    const grab = (chunk, which) => {
+      if (out.length + err.length > 2_000_000) { truncated = true; return }
+      if (which === "out") out += chunk; else err += chunk
+    }
+    child.stdout.on("data", (c) => grab(c, "out"))
+    child.stderr.on("data", (c) => grab(c, "err"))
+    const timer = setTimeout(() => { try { child.kill() } catch { /* gone */ } }, timeoutMs)
+    child.on("error", (e) => { clearTimeout(timer); resolve({ code: -1, out, err: String(e), truncated }) })
+    child.on("close", (code) => { clearTimeout(timer); resolve({ code, out, err, truncated }) })
+  })
+}
+
+/**
+ * Confine a caller-supplied file path inside `root` (realpath-based).
+ * Returns the resolved absolute path or throws with an actionable reason.
+ */
+export function confinePath(root, target, { mustExist = true } = {}) {
+  if (typeof target !== "string" || target.trim() === "") throw new Error("path is required")
+  const abs = path.resolve(root, target)
+  let realRoot
+  let realTarget
+  try { realRoot = realpathSync(root) } catch { throw new Error(`allowed root not found: ${root}`) }
+  if (mustExist) {
+    try { realTarget = realpathSync(abs) } catch { throw new Error(`file not found: ${target}`) }
+  } else {
+    // for outputs the file may not exist yet: realpath the nearest existing ancestor.
+    // audit P4-3: existsSync follows reparse points — a BROKEN junction returns false
+    // and its name would be re-joined unresolved, escaping root. Resolve any
+    // symlink/junction component through realpath instead of keeping its name.
+    let cursor = abs
+    const missing = []
+    for (;;) {
+      let st
+      try { st = lstatSync(cursor) } catch { st = undefined }
+      if (st !== undefined && st.isSymbolicLink()) {
+        // a symlink/junction (incl. broken ones) must resolve inside root or be refused
+        try { cursor = realpathSync(cursor); break } catch { throw new Error(`path escapes the allowed project root (broken link): ${target}`) }
+      }
+      if (st !== undefined) break // real existing entry
+      missing.unshift(path.basename(cursor))
+      const parent = path.dirname(cursor)
+      if (parent === cursor) break
+      cursor = parent
+    }
+    let base
+    try { base = realpathSync(cursor) } catch { base = cursor }
+    realTarget = path.join(base, ...missing)
+  }
+  const rel = path.relative(realRoot, realTarget)
+  if (rel === "" || rel.startsWith("..") || path.isAbsolute(rel)) {
+    throw new Error(`path escapes the allowed project root: ${target}`)
+  }
+  return realTarget
+}
+
+/** Inspect a .fig document (pages + node tree, depth-bounded). */
+export async function inspect(file, root) {
+  const confined = confinePath(root, file)
+  if (!/\.(fig)$/i.test(confined)) throw new Error("only .fig documents are inspected")
+  const info = await runCli(["info", confined, "--json"])
+  const pages = await runCli(["pages", confined, "--json"])
+  return {
+    status: info.code === 0 ? "passed" : "failed",
+    info: safeJson(info.out),
+    pages: safeJson(pages.out),
+    exit: info.code,
+    limitations: ["read-only inspection; the editor owns the document", "no remote/RPC mode used (file mode only)"],
+  }
+}
+
+/** Export one frame/page of a .fig to PNG inside the store and return provenance. */
+export async function exportFrame({ file, root, node, page, scale = 2, workspace }) {
+  const confined = confinePath(root, file)
+  if (!/\.(fig)$/i.test(confined)) throw new Error("only .fig documents are exported")
+  if (node !== undefined && !/^[A-Za-z0-9:._-]{1,64}$/.test(String(node))) throw new Error("node id has an unexpected shape")
+  const outDir = path.join(workspace.root, "openpencil")
+  mkdirSync(outDir, { recursive: true })
+  const outName = `${Date.now()}-${String(node ?? "page").replaceAll(/[^\w.-]/g, "_")}.png`
+  const outPath = confinePath(workspace.root, path.join("openpencil", outName), { mustExist: false })
+  const args = ["export", confined, "-f", "png", "-s", String(Math.min(Math.max(Number(scale) || 2, 1), 4)), "-o", outPath]
+  if (node) args.push("--node", String(node))
+  if (page) args.push("--page", String(page))
+  const result = await runCli(args)
+  if (result.code !== 0 || !existsSync(outPath)) {
+    return { status: "failed", exit: result.code, stderrTail: String(result.err ?? "").split(/\r?\n/).slice(-6).join("\n") }
+  }
+  return { status: "passed", pngPath: outPath }
+}
+
+/** Design variables (tokens) from the document — returns them raw; mapping is a human step. */
+export async function variables(file, root) {
+  const confined = confinePath(root, file)
+  const r = await runCli(["variables", confined, "--json"])
+  return { status: r.code === 0 ? "passed" : "failed", variables: safeJson(r.out), exit: r.code }
+}
+
+function safeJson(text) {
+  try { return JSON.parse(String(text ?? "").trim()) } catch { return undefined }
+}

package/lib/png-decode.js

@@ -0,0 +1,86 @@
+/**
+ * dsh-mobilecode — bounded PNG decoder for native-space regression.
+ *
+ * Runs ONLY on bytes already inside the store — but store ownership is NOT
+ * trust: those bytes originated as user imports. So every input is treated as
+ * hostile: per-chunk CRC verification, dimension fences re-enforced at decode
+ * time (files can be swapped after import), a decompressed-size budget plus
+ * zlib maxOutputLength (deflate bombs die), exact scanline-length validation
+ * (truncated IDAT refused), unknown filter bytes refused, and every unsupported
+ * format (palette, 16-bit, interlaced, non-PNG) rejected with an explicit
+ * reason — NEVER silently approximated, and never falling back to caller
+ * pixels while keeping a verified-native label.
+ * Scope stays the smallest sufficient subset: 8-bit non-interlaced
+ * gray/RGB/RGBA, five scanline filters, stdlib zlib only.
+ * ponytail: ceiling = what device screencap + editor exports produce;
+ * upgrade path = a real codec dependency IF a workflow needs palette/16-bit.
+ */
+import zlib from "node:zlib"
+
+const SIG = Buffer.from([137, 80, 78, 71, 13, 10, 26, 10])
+const MAX_DIM = 8192 // re-enforced at DECODE time: stored bytes can be swapped
+const MAX_RAW = 64_000_000 // decompressed scanline budget — bombs die here
+
+export function decodePngToRgba(buf, { maxPixels = 24_000_000 } = {}) {
+  if (buf.length < 33 || !buf.subarray(0, 8).equals(SIG)) throw new Error("not a PNG")
+  let p = 8, width = 0, height = 0, bitDepth = 0, colorType = 0, interlace = 0, iend = false
+  const idat = []
+  while (p + 8 <= buf.length) {
+    const len = buf.readUInt32BE(p)
+    if (len > buf.length) throw new Error(`truncated chunk (declared ${len} > file ${buf.length})`)
+    const type = buf.toString("latin1", p + 4, p + 8)
+    const data = buf.subarray(p + 8, p + 8 + len)
+    if (p + 12 + len > buf.length) throw new Error(`truncated ${type} chunk body`)
+    if ((zlib.crc32(buf.subarray(p + 4, p + 8 + len)) >>> 0) !== (buf.readUInt32BE(p + 8 + len) >>> 0)) throw new Error(`corrupt ${type} chunk (CRC mismatch)`)
+    if (type === "IHDR") {
+      if (len !== 13) throw new Error(`short/oversized IHDR (${len} bytes, spec says 13)`)
+      width = data.readUInt32BE(0); height = data.readUInt32BE(4)
+      bitDepth = data[8]; colorType = data[9]; interlace = data[12]
+      if (width < 1 || height < 1 || width > MAX_DIM || height > MAX_DIM) throw new Error(`dimension fence violated: ${width}x${height}`)
+      if (width * height > maxPixels) throw new Error(`decode guard: ${width}x${height} exceeds ${maxPixels}px`)
+    } else if (type === "IDAT") idat.push(Buffer.from(data))
+    else if (type === "IEND") { iend = true; break }
+    p += 12 + len
+  }
+  if (!iend) throw new Error("missing IEND — truncated stream")
+  if (!width || !height) throw new Error("no IHDR")
+  if (interlace !== 0) throw new Error("interlaced PNG not supported (no native claim — refuse, do not approximate)")
+  if (bitDepth !== 8) throw new Error(`bit depth ${bitDepth} not supported (8-bit only)`)
+  const channels = colorType === 6 ? 4 : colorType === 2 ? 3 : colorType === 0 ? 1 : 0
+  if (!channels) throw new Error(`color type ${colorType} not supported (grayscale/RGB/RGBA only — palette refused)`)
+  const stride = width * channels
+  const rawSize = (stride + 1) * height
+  if (rawSize > MAX_RAW) throw new Error(`decompression budget: ${rawSize} raw bytes > ${MAX_RAW}`)
+  const raw = zlib.inflateSync(Buffer.concat(idat), { maxOutputLength: MAX_RAW })
+  if (raw.length !== rawSize) throw new Error(`truncated IDAT: ${raw.length} decompressed bytes, scanlines need ${rawSize}`)
+  const out = Buffer.alloc(width * height * 4)
+  const prev = Buffer.alloc(stride)
+  let off = 0
+  for (let y = 0; y < height; y++) {
+    const filter = raw[off++]
+    const line = raw.subarray(off, off + stride); off += stride
+    const cur = Buffer.alloc(stride)
+    for (let x = 0; x < stride; x++) {
+      const a = x >= channels ? cur[x - channels] : 0
+      const b = prev[x]
+      const c = x >= channels ? prev[x - channels] : 0
+      let v = line[x]
+      if (filter === 1) v += a
+      else if (filter === 2) v += b
+      else if (filter === 3) v += (a + b) >> 1
+      else if (filter === 4) {
+        const pa = Math.abs(b - c), pb = Math.abs(a - c), pc = Math.abs(a + b - 2 * c)
+        v += (pa <= pb && pa <= pc) ? a : (pb <= pc ? b : c)
+      } else if (filter !== 0) throw new Error(`unknown filter ${filter}`)
+      cur[x] = v & 0xff
+    }
+    cur.copy(prev)
+    for (let x = 0; x < width; x++) {
+      const s = x * channels, d = (y * width + x) * 4
+      if (channels === 4) { out[d] = cur[s]; out[d + 1] = cur[s + 1]; out[d + 2] = cur[s + 2]; out[d + 3] = cur[s + 3] }
+      else if (channels === 3) { out[d] = cur[s]; out[d + 1] = cur[s + 1]; out[d + 2] = cur[s + 2]; out[d + 3] = 255 }
+      else { out[d] = out[d + 1] = out[d + 2] = cur[s]; out[d + 3] = 255 }
+    }
+  }
+  return { width, height, rgba: out }
+}

package/lib/preview-gallery.js

@@ -0,0 +1,309 @@
+/**
+ * dsh-mobilecode — Compose preview gallery (Feature B/T5, primary path per
+ * docs/design/render-adapter-decision.md: official com.android.compose.screenshot
+ * 0.0.1-alpha16, host-rendered via layoutlib).
+ *
+ * Discovery reads the app's screenshotTest source; rendering runs the Gradle
+ * task with ARGUMENT ARRAYS through the existing safe launcher; every result
+ * carries provenance (renderer, command, exit, timestamps, source-vs-output
+ * mtimes). A stale/failed render is never labeled current.
+ *
+ * Host-rendered previews do NOT prove real-device behavior.
+ */
+
+import { existsSync, readdirSync, readFileSync, statSync, writeFileSync, mkdirSync } from "node:fs"
+import { spawn } from "node:child_process"
+import crypto from "node:crypto"
+import os from "node:os"
+import path from "node:path"
+import * as DeviceBuild from "./device-build.js"
+
+/**
+ * Kill the whole process tree (audit phase-3 low (b)): child.kill() on the
+ * cmd.exe shim would orphan the Gradle JVM; taskkill /T takes the tree.
+ */
+function killTree(child) {
+  if (child?.pid === undefined) return
+  if (process.platform === "win32") {
+    try { spawn("taskkill", ["/pid", String(child.pid), "/T", "/F"], { windowsHide: true, stdio: "ignore" }) } catch { /* already gone */ }
+  } else {
+    try { child.kill("SIGKILL") } catch { /* already gone */ }
+  }
+}
+
+export const RENDER_TIMEOUT_MS = 10 * 60_000
+export const MAX_RENDER_TIMEOUT_MS = 30 * 60_000
+const MAX_TAIL_LINES = 200
+
+/** Adapter availability for a project (drives the capability report). */
+export function previewSupportStatus(appDir) {
+  const wrapper = !!DeviceBuild.gradleWrapper(appDir)
+  const screenshotTest = wrapper && moduleNames(appDir).some((m) => existsSync(path.join(appDir, m, "src", "screenshotTest")))
+  return { wrapper, screenshotTest }
+}
+
+/** Recursively list .kt files under dir. */
+function ktFiles(dir) {
+  if (!existsSync(dir)) return []
+  const out = []
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const p = path.join(dir, entry.name)
+    if (entry.isDirectory()) out.push(...ktFiles(p))
+    else if (entry.isFile() && entry.name.endsWith(".kt")) out.push(p)
+  }
+  return out
+}
+
+/**
+ * Discover @PreviewTest entries in one app dir. Returns [] when the module has
+ * no screenshotTest source (adapter not set up — caller reports that honestly).
+ * Entry: {module, package, className, fqClass, method, previewName, widthDp, sourceFile, sourceMtime}
+ *
+ * `warnings` (optional array): parse limitations are SURFACED, not hidden —
+ * line-based parsing covers the common one-line-annotation form; any
+ * @PreviewTest marker that produced no entry (multi-line annotations,
+ * `private fun`, annotation on the same line as `fun`, …) adds a warning
+ * (audit phase-3 low: single-line assumption must be visible to users/agents).
+ */
+export function discoverPreviewTests(appDir, warnings = []) {
+  const entries = []
+  for (const moduleName of moduleNames(appDir)) {
+    const srcDir = path.join(appDir, moduleName, "src", "screenshotTest")
+    for (const file of ktFiles(srcDir)) {
+      let text
+      try { text = readFileSync(file, "utf8") } catch { continue }
+      const pkg = /package\s+([\w.]+)/.exec(text)?.[1] ?? ""
+      const lines = text.split(/\r?\n/)
+      let currentClass = ""
+      let pending = []
+      let markerLines = 0
+      for (const line of lines) {
+        const t = line.trim()
+        if (t === "" || t.startsWith("//") || t.startsWith("/*") || t.startsWith("*")) continue
+        if (t.startsWith("@")) { pending.push(t); if (t.startsWith("@PreviewTest")) markerLines += 1; continue }
+        const cm = /^class\s+(\w+)/.exec(t)
+        if (cm) { currentClass = cm[1]; pending = []; continue }
+        const fm = /^(?:public\s+|internal\s+)?fun\s+(\w+)\s*[<(]/.exec(t)
+        if (fm) {
+          if (pending.some((p) => p.startsWith("@PreviewTest"))) {
+            // single-line @Preview(...) only; "@Preview(" guard matters —
+            // plain startsWith("@Preview") would match @PreviewTest first
+            const previewAnn = pending.find((p) => p.startsWith("@Preview("))
+            entries.push({
+              module: moduleName,
+              package: pkg,
+              className: currentClass,
+              fqClass: pkg ? `${pkg}.${currentClass}` : currentClass,
+              method: fm[1],
+              previewName: previewAnn ? /name\s*=\s*"([^"]*)"/.exec(previewAnn)?.[1] ?? fm[1] : fm[1],
+              widthDp: previewAnn ? Number(/widthDp\s*=\s*([\d.]+)/.exec(previewAnn)?.[1]) || undefined : undefined,
+              sourceFile: file,
+              sourceMtime: safeMtime(file),
+            })
+          }
+          pending = []
+          continue
+        }
+        pending = []
+      }
+      const found = entries.filter((e) => e.sourceFile === file).length
+      if (markerLines > found) {
+        warnings.push(`${path.relative(appDir, file).replaceAll("\\", "/")}: ${markerLines} @PreviewTest marker(s) but ${found} parsed — unsupported shapes (multi-line @Preview(, annotations on the fun line, private fun) are NOT discovered; keep the common layout: each annotation alone on its line, @Preview(...) on one line`)
+      }
+    }
+  }
+  return entries
+}
+
+function safeMtime(p) { try { return statSync(p).mtimeMs } catch { return 0 } }
+
+/** Modules declared in settings.gradle(.kts) (fallback: app). */
+function moduleNames(appDir) {
+  for (const name of ["settings.gradle", "settings.gradle.kts"]) {
+    const file = path.join(appDir, name)
+    if (!existsSync(file)) continue
+    const includes = [...readFileSync(file, "utf8").matchAll(/include\s*\(?\s*["']:?([\w:.\-]+)["']/g)].map((m) => m[1].replaceAll(/[.:]/g, path.sep))
+    if (includes.length > 0) return [...new Set(includes)]
+  }
+  return ["app"]
+}
+
+/** Locate the recorded reference PNG for an entry (engine names <method>_<PreviewName>_<hash>_0.png). */
+export function referencePng(appDir, entry) {
+  const pkgPath = entry.package.replaceAll(".", path.sep)
+  const dir = path.join(appDir, entry.module, "src", `screenshotTestDebug${path.sep}reference${path.sep}${pkgPath}${path.sep}${entry.className}`)
+  if (!existsSync(dir)) return undefined
+  try {
+    const hit = readdirSync(dir).find((f) => f.startsWith(`${entry.method}_`) && f.endsWith(".png"))
+    if (!hit) return undefined
+    const p = path.join(dir, hit)
+    return { pngPath: p, mtime: safeMtime(p) }
+  } catch { return undefined }
+}
+
+/** Honest render state: PNG existence + manifest-based freshness (never timestamp-only). */
+export function renderState(appDir, entry, { fingerprint = null, manifestDir = defaultManifestDir() } = {}) {
+  const found = referencePng(appDir, entry)
+  if (!found) return { rendered: false, stale: true, freshness: "never_rendered" }
+  const m = readManifest(manifestDir, appDir, entry)
+  const f = readFailure(manifestDir, appDir, entry)
+  let freshness
+  if (m === undefined) freshness = "unknown" // legacy/external render — no manifest, no claim
+  else if (f !== undefined && f.at > (m.at ?? 0)) freshness = "last_run_failed"
+  else if (fingerprint === null) freshness = "unknown"
+  else freshness = fingerprint === m.inputsFingerprint ? "fresh_tracked_inputs" : "stale_inputs_changed"
+  return {
+    rendered: true, pngPath: found.pngPath, renderedAt: found.mtime,
+    stale: freshness !== "fresh_tracked_inputs",
+    freshness,
+    manifest: m,
+    limitations: freshness === "fresh_tracked_inputs"
+      ? ["fresh only for TRACKED inputs (module sources, build files, version catalog); external deps, JDK/layoutlib and fonts are NOT covered"]
+      : [],
+  }
+}
+
+// ── render manifest (audit §4: timestamp-only freshness is not a currency proof) ──
+
+export function defaultManifestDir() {
+  return path.join(os.homedir(), ".dsh", "mobilecode", "preview-manifests")
+}
+
+function keyFor(appDir, entry) {
+  return crypto.createHash("sha256").update(String(appDir)).digest("hex").slice(0, 16) + "--" + `${entry.fqClass}.${entry.method}`.replaceAll(/[^A-Za-z0-9_.]/g, "_")
+}
+
+/**
+ * Fingerprint of the render's relevant inputs: every file under the scanned
+ * module(s)' src trees (path+size+mtime), the module build files, settings
+ * files, gradle.properties and the version catalog. Shared-token / resource /
+ * build-config edits change it even when the preview's own file does not.
+ */
+export function inputsFingerprint(appDir) {
+  const hash = crypto.createHash("sha256")
+  const add = (file) => {
+    try { const st = statSync(file); hash.update(`${path.relative(appDir, file)}|${st.size}|${Math.round(st.mtimeMs)}\n`) } catch { /* missing file contributes nothing */ }
+  }
+  for (const moduleName of moduleNames(appDir)) {
+    const srcRoot = path.join(appDir, moduleName, "src")
+    if (existsSync(srcRoot)) for (const f of walkFiles(srcRoot)) add(f)
+    add(path.join(appDir, moduleName, "build.gradle.kts"))
+    add(path.join(appDir, moduleName, "build.gradle"))
+  }
+  for (const f of ["settings.gradle.kts", "settings.gradle", "gradle.properties", path.join("gradle", "libs.versions.toml")]) add(path.join(appDir, f))
+  return hash.digest("hex")
+}
+
+function walkFiles(dir) {
+  const out = []
+  let entries
+  try { entries = readdirSync(dir, { withFileTypes: true }) } catch { return out }
+  for (const e of entries) {
+    const p = path.join(dir, e.name)
+    if (e.isDirectory()) out.push(...walkFiles(p))
+    else if (e.isFile()) out.push(p)
+  }
+  return out.sort()
+}
+
+function manifestFile(dir, appDir, entry) { return path.join(dir, keyFor(appDir, entry) + ".json") }
+function failureFile(dir, appDir, entry) { return path.join(dir, keyFor(appDir, entry) + ".failure.json") }
+/** Exported so tools/tests can read or seed manifest state without reimplementing the key. */
+export function manifestPathFor(appDir, entry, dir = defaultManifestDir()) { return manifestFile(dir, appDir, entry) }
+export function failurePathFor(appDir, entry, dir = defaultManifestDir()) { return failureFile(dir, appDir, entry) }
+
+function readManifest(dir, appDir, entry) {
+  try { return JSON.parse(readFileSync(manifestFile(dir, appDir, entry), "utf8")) } catch { return undefined }
+}
+function readFailure(dir, appDir, entry) {
+  try { return JSON.parse(readFileSync(failureFile(dir, appDir, entry), "utf8")) } catch { return undefined }
+}
+function writeJsonFile(dir, appDir, entry, fileFn, payload) {
+  try { mkdirSync(dir, { recursive: true }); writeFileSync(fileFn(dir, appDir, entry), JSON.stringify(payload, null, 2) + "\n", "utf8") } catch { /* marker best-effort; missing manifest → unknown freshness */ }
+}
+
+/** Argument array for one-method render (no shell string anywhere). */
+export function buildRenderArgs(entry) {
+  return [`:${entry.module}:updateDebugScreenshotTest`, "--tests", `${entry.fqClass}.${entry.method}`, "--console=plain"]
+}
+
+function classifyFailure(lines, exitCode) {
+  const text = lines.join("\n")
+  if (exitCode === 124) return "timeout"
+  if (/No tests found for given includes|did not match any tests/i.test(text)) return "discovery"
+  if (/Compilation error|e: file:\/\//i.test(text)) return "compilation"
+  if (/There were failing tests|FAILED/i.test(text)) return "render"
+  return exitCode === 0 ? "none" : "unknown"
+}
+
+// one live gradle render per directory (a second concurrent invocation would
+// race the same task); ponytail: in-memory only — single-process server by design
+const liveRenders = new Map()
+
+/**
+ * Render one discovered preview. Resolves an envelope:
+ * {status: passed|failed|blocked, failureKind, tail, provenance}
+ * Never throws for operational failures; missing prerequisites → "blocked".
+ * A successful run records a manifest (inputs fingerprint + renderer + runId);
+ * a failed/cancelled run records a failure marker that IMMEDIATELY invalidates
+ * the previous success state (audit §4) while the older PNG stays visible,
+ * labeled.
+ */
+export async function renderPreviewTest(appDir, entry, { timeoutMs = RENDER_TIMEOUT_MS, onLine, manifestDir = defaultManifestDir() } = {}) {
+  const wrapper = DeviceBuild.gradleWrapper(appDir)
+  if (!wrapper) return { status: "blocked", reason: "no gradlew wrapper in directory — not a Gradle project", provenance: { directory: appDir } }
+  if (!existsSync(path.join(appDir, entry.module, "src", "screenshotTest"))) {
+    return { status: "blocked", reason: `module ${entry.module} has no screenshotTest source — apply the adapter first (docs/design/render-adapter-decision.md)`, provenance: { directory: appDir } }
+  }
+  const capped = Math.min(Math.max(timeoutMs || RENDER_TIMEOUT_MS, 10_000), MAX_RENDER_TIMEOUT_MS)
+  const args = buildRenderArgs(entry)
+  const startedAt = new Date().toISOString()
+  const tail = []
+  const push = (line) => { tail.push(line.slice(0, 300)); if (tail.length > MAX_TAIL_LINES) tail.shift(); onLine?.(line) }
+  if (liveRenders.has(appDir)) {
+    return { status: "blocked", reason: "another preview render is already running for this directory", provenance: { directory: appDir } }
+  }
+  liveRenders.set(appDir, args.join("\0"))
+  try {
+    const { child, exit } = DeviceBuild.exec(wrapper, args, { cwd: appDir }, push)
+    const exitCode = await new Promise((resolve) => {
+      const timer = setTimeout(() => { killTree(child); resolve(124) }, capped)
+      exit.then((code) => { clearTimeout(timer); resolve(code) })
+    })
+    const finishedAt = new Date().toISOString()
+    const state = renderState(appDir, entry, { manifestDir })
+    const failureKind = classifyFailure(tail, exitCode)
+    const passed = exitCode === 0 && state.rendered && !state.stale
+    const runId = crypto.randomBytes(8).toString("hex")
+    if (passed) {
+      writeJsonFile(manifestDir, appDir, entry, manifestFile, {
+        runId, at: finishedAt, exitCode,
+        inputsFingerprint: inputsFingerprint(appDir),
+        renderer: "com.android.compose.screenshot 0.0.1-alpha16 (layoutlib, host-rendered)",
+        command: args.join(" "),
+      })
+    } else {
+      // invalidate immediately — even a cancelled/timed-out run marks state untrusted
+      writeJsonFile(manifestDir, appDir, entry, failureFile, { at: finishedAt, exitCode, failureKind, runId })
+    }
+    return {
+      status: passed ? "passed" : "failed",
+      failureKind: exitCode === 0 ? (state.rendered ? (state.stale ? "stale-after-render" : "none") : "discovery") : failureKind,
+      exitCode,
+      tail: tail.slice(-40),
+      provenance: {
+        renderer: "compose-preview-screenshot-testing (layoutlib, host-rendered) — NOT device-verified",
+        command: `${path.basename(wrapper)} ${args.join(" ")}`,
+        argumentArray: args,
+        directory: appDir,
+        startedAt, finishedAt, runId: passed ? runId : undefined,
+        pngPath: state.pngPath,
+        renderedAt: state.renderedAt ? new Date(state.renderedAt).toISOString() : undefined,
+        freshness: state.freshness,
+        stale: state.stale,
+      },
+    }
+  } finally {
+    liveRenders.delete(appDir)
+  }
+}