dsh-mobilecode 0.11.9 → 0.12.0

package/lib/index.js

@@ -26,8 +26,16 @@ import * as Vision from './vision.js'
 import { DevicePreviewEngine } from './device-preview.js'
 import { MeshHub } from './mesh-hub.js'
 import * as Setup from './setup.js'
+import { ReferenceWorkspace } from './reference-workspace.js'
+import * as PreviewGallery from './preview-gallery.js'
+import * as ConfigMatrix from './config-matrix.js'
+import * as OpenPencil from './openpencil.js'
+import * as VisualCompare from './visual-compare.js'
+import { decodePngToRgba } from './png-decode.js'
 import { registerMobileSkill } from './skill.js'
-import { existsSync, readFileSync } from 'node:fs'
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs'
+import crypto from 'node:crypto'
+import path from 'node:path'
 import { tmpdir } from 'node:os'
 
 export const name = 'mobilecode'
@@ -60,12 +68,12 @@ function writeJson(res, status, body) {
   res.end(JSON.stringify(body))
 }
 
-async function readBody(req, res) {
+async function readBody(req, res, limit = 64 * 1024) {
   const chunks = []
   let size = 0
   for await (const chunk of req) {
     size += chunk.length
-    if (size > 64 * 1024) { writeJson(res, 413, { error: 'body too large' }); return undefined }
+    if (size > limit) { writeJson(res, 413, { error: 'body too large' }); return undefined }
     chunks.push(chunk)
   }
   try { return JSON.parse(Buffer.concat(chunks).toString('utf8')) } catch { return {} }
@@ -79,6 +87,7 @@ function resolveDirectory(body, config) {
 }
 
 function makeRoutes(engine, config, stream) {
+  const workspaceRef = sharedWorkspaceRef()
   const guard = (req, res) => {
     if (!isLoopbackRequest(req)) { writeJson(res, 403, { error: 'forbidden: loopback-only' }); return false }
     return true
@@ -93,6 +102,18 @@ function makeRoutes(engine, config, stream) {
     if ((req.method ?? 'GET') !== 'POST') { writeJson(res, 405, { error: 'method not allowed' }); return false }
     return true
   }
+  // Reference-store fence: a request that LOOKS like a browser call (carries
+  // Origin / Sec-Fetch-* — which web pages always do for cross-site POSTs) must
+  // pass the trusted-origin fence, so a random webpage cannot capture device
+  // screenshots or fill the store. Bare loopback HTTP clients (the panel's own
+  // same-origin fetches, local tooling, tests) keep the plain loopback guard.
+  const refGuard = (req, res) => {
+    if (!guard(req, res)) return false
+    if (req.headers.origin !== undefined || req.headers['sec-fetch-site'] !== undefined || req.headers['sec-fetch-mode'] !== undefined) {
+      return fence(req, res, false)
+    }
+    return true
+  }
   // Mesh fence: game clients are plain HTTP stacks (OkHttp/Unity/curl) that
   // never send browser headers — they must only prove a loopback peer plus a
   // Host the emulator NAT actually presents (10.0.2.2) or loopback. Anything
@@ -817,10 +838,460 @@ function makeRoutes(engine, config, stream) {
         writeJson(res, 200, { ok: true })
       },
     },
+
+    // ── reference-comparison workspace (Feature A vertical slice) ──────────────
+    {
+      kind: 'exact',
+      path: API_BASE + '/refs',
+      handler: async (req, res) => {
+        if (!guard(req, res)) return
+        const url = new URL(req.url ?? '/', 'http://localhost')
+        const project = url.searchParams.get('project') ?? undefined
+        const records = workspaceRef.list({ project })
+        writeJson(res, 200, { records, active: project === undefined ? undefined : workspaceRef.active(project) })
+      },
+    },
+    {
+      kind: 'exact',
+      path: API_BASE + '/refs/import',
+      handler: async (req, res) => {
+        if (!refGuard(req, res)) return
+        if (!isPost(req, res)) return
+        const body = await readBody(req, res, 40 * 1024 * 1024)
+        if (body === undefined) return
+        try {
+          const record = workspaceRef.import(body, body?.data)
+          writeJson(res, 201, { record })
+        } catch (error) {
+          writeJson(res, 400, { error: error instanceof Error ? error.message : String(error) })
+        }
+      },
+    },
+    {
+      kind: 'exact',
+      path: API_BASE + '/refs/capture',
+      handler: async (req, res) => {
+        if (!refGuard(req, res)) return
+        if (!isPost(req, res)) return
+        const body = await readBody(req, res)
+        if (body === undefined) return
+        try {
+          const serial = await requireAndroidDevice(body?.serial)
+          // defense-in-depth: screenCapture names its tmp file after the serial
+          if (!/^[A-Za-z0-9._:-]+$/.test(String(serial))) throw new Error('refused: unexpected device serial shape')
+          const png = await DeviceBuild.screenCapture(serial, undefined)
+          if (!png || typeof png !== 'string') throw new Error('screen capture failed (no screenshot produced)')
+          const [size, density] = await Promise.all([
+            captureScreenSize(serial).catch(() => undefined),
+            DeviceBuild.adbRun(serial, ['shell', 'wm', 'density'])
+              .then((text) => String(text ?? '').trim() || undefined)
+              .catch(() => undefined),
+          ])
+          const record = workspaceRef.capture({
+            project: body?.project,
+            screen: body?.screen,
+            stateId: body?.stateId,
+            pngPath: png,
+            device: { serial, ...(size ?? {}), density },
+          })
+          writeJson(res, 201, { record })
+        } catch (error) {
+          writeJson(res, 400, { error: error instanceof Error ? error.message : String(error) })
+        }
+      },
+    },
+    {
+      kind: 'exact',
+      path: API_BASE + '/refs/active',
+      handler: async (req, res) => {
+        if (!refGuard(req, res)) return
+        if (!isPost(req, res)) return
+        const body = await readBody(req, res)
+        if (body === undefined) return
+        try {
+          writeJson(res, 200, { record: workspaceRef.setActive(body?.id) })
+        } catch (error) {
+          writeJson(res, 400, { error: error instanceof Error ? error.message : String(error) })
+        }
+      },
+    },
+    {
+      kind: 'exact',
+      path: API_BASE + '/refs/approve',
+      handler: async (req, res) => {
+        if (!refGuard(req, res)) return
+        if (!isPost(req, res)) return
+        const body = await readBody(req, res)
+        if (body === undefined) return
+        try {
+          writeJson(res, 200, { record: workspaceRef.setApproved(body?.id, body?.approved !== false) })
+        } catch (error) {
+          writeJson(res, 400, { error: error instanceof Error ? error.message : String(error) })
+        }
+      },
+    },
+    {
+      kind: 'exact',
+      path: API_BASE + '/refs/remove',
+      handler: async (req, res) => {
+        if (!refGuard(req, res)) return
+        if (!isPost(req, res)) return
+        const body = await readBody(req, res)
+        if (body === undefined) return
+        writeJson(res, 200, { removed: body?.id ? workspaceRef.remove(body.id) : false })
+      },
+    },
+    {
+      kind: 'exact',
+      path: API_BASE + '/refs/compare',
+      handler: async (req, res) => {
+        if (!guard(req, res)) return
+        const url = new URL(req.url ?? '/', 'http://localhost')
+        const project = url.searchParams.get('project')
+        const screen = url.searchParams.get('screen') ?? ''
+        const stateId = url.searchParams.get('stateId') ?? ''
+        if (!project) { writeJson(res, 400, { error: 'project query parameter is required' }); return }
+        writeJson(res, 200, {
+          reference: workspaceRef.active(project) ?? workspaceRef.latest(project, screen, stateId, 'reference'),
+          capture: workspaceRef.latest(project, screen, stateId, 'capture'),
+        })
+      },
+    },
+    {
+      kind: 'exact',
+      path: API_BASE + '/refs/diff',
+      handler: async (req, res) => {
+        if (!refGuard(req, res)) return
+        if (!isPost(req, res)) return
+        const body = await readBody(req, res, 64 * 1024 * 1024) // two native RGBA frames at 1080x2400 ≈ 28 MB base64
+        if (body === undefined) return
+        // Native regression = server-decoded STORED originals (provenance,
+        // audit §3). Caller-posted raw RGBA is only for reduced-resolution
+        // TRIAGE (design-reference / non-PNG records); encoded images in the
+        // triage path are refused, never pixel-decoded from hostile input.
+        const frameOf = (f) => {
+          if (!f || typeof f.width !== 'number' || typeof f.height !== 'number' || typeof f.rgba !== 'string') return undefined
+          const buf = Buffer.from(f.rgba, 'base64')
+          if (buf.length !== f.width * f.height * 4) return undefined
+          return { width: f.width, height: f.height, rgba: buf }
+        }
+        const a = frameOf(body?.a)
+        const b = frameOf(body?.b)
+        if ((a === undefined || b === undefined) && !(body?.referenceId && body?.captureId)) {
+          writeJson(res, 400, {
+            error: 'triage comparisons need frames {width, height, rgba:base64} with exact byte counts (browser-canvas decoded); native regression needs referenceId+captureId of stored PNGs',
+            note: 'the server decodes only its own stored PNG originals; caller-posted pixels are never trusted for a native verdict',
+          })
+          return
+        }
+        const mode = body?.mode === 'regression' ? 'regression' : 'design-reference'
+        let masks
+        try { masks = VisualCompare.validateMasks(body?.masks) } catch (error) { writeJson(res, 400, { error: String(error instanceof Error ? error.message : error) }); return }
+        // BASELINE MODEL (corrected): the REFERENCE must carry a valid explicit
+        // approval bound to its current stored bytes + device config; the
+        // CANDIDATE never needs approval — a test must be able to detect its
+        // regression. Pixel equality can only `passed` when approval binds,
+        // dimensions match, and BOTH records carry equal capture configuration
+        // (serial/size/density/font-scale metadata). Anything less is capped
+        // at needs_review / blocked — never silently auto-approved.
+        const recA = body?.referenceId ? workspaceRef.get(String(body.referenceId)) : undefined
+        const recB = body?.captureId ? workspaceRef.get(String(body.captureId)) : undefined
+        const storedPng = (r) => r !== undefined && r.ext === '.png'
+        let native = null
+        if (recA && recB && storedPng(recA) && storedPng(recB)) {
+          try {
+            const bufA = workspaceRef.readImage(recA)
+            native = { a: decodePngToRgba(bufA), b: decodePngToRgba(workspaceRef.readImage(recB)), sha256A: crypto.createHash('sha256').update(bufA).digest('hex') }
+          } catch (error) {
+            native = { error: `stored original not decodable server-side: ${error instanceof Error ? error.message : error}` }
+          }
+        }
+        if (native && !native.error) {
+          const cfgKey = (r) => (r.device && Object.keys(r.device).length > 0 ? JSON.stringify(r.device, Object.keys(r.device).sort()) : null)
+          const cfgA = cfgKey(recA), cfgB = cfgKey(recB)
+          const dimsMatch = native.a.width === native.b.width && native.a.height === native.b.height
+          const approvalValid = recA.approved === true && recA.approval?.sha256 === native.sha256A
+          const diff = dimsMatch
+            ? VisualCompare.diffFrames(native.a, native.b, { threshold: Number(body?.threshold) || 24, masks })
+            : { status: 'blocked', reason: `stored originals differ in size (${native.a.width}x${native.a.height} vs ${native.b.width}x${native.b.height}) — no native verdict`, changedPixels: 0, totalPixels: 0 }
+          let ceiling = null
+          if (!approvalValid) ceiling = { status: 'blocked', reason: `reference ${recA.id} has no valid approval bound to its current bytes (${recA.approved === true ? 'stored bytes differ from the approved hash' : 'not approved'}) — approve the baseline via /refs/approve; candidates never require approval to be tested` }
+          else if (!dimsMatch) ceiling = { status: 'blocked', reason: 'stored sizes differ — incompatible capture configurations' }
+          else if (cfgA === null || cfgB === null) ceiling = { status: 'needs_review', reason: 'capture configuration not recorded on both records — pixel comparison ran on server-decoded stored bytes, but device/density/font-scale compatibility cannot be certified' }
+          else if (cfgA !== cfgB) ceiling = { status: 'needs_review', reason: `capture configurations differ (${cfgA} vs ${cfgB}) — pixel equality would not be meaningful; observed diff: ${diff.changedPixels} px` }
+          const envelope = VisualCompare.compareEnvelope({
+            runId: Date.now().toString(36) + '-' + Math.random().toString(36).slice(2, 8),
+            project: String(body?.project ?? recA.project), screen: String(body?.screen ?? recA.screen), stateId: String(body?.stateId ?? ''),
+            mode, diff, comparisonSpace: 'native',
+            observations: [{ source: 'store', finding: `decoded stored ${native.a.width}x${native.a.height} vs ${native.b.width}x${native.b.height}; baseline approval bound=${approvalValid}; config ${cfgA ?? 'unrecorded'} vs ${cfgB ?? 'unrecorded'}` }],
+            evidenceRefs: [recA.id, recB.id],
+            env: {
+              originals: { a: { width: native.a.width, height: native.a.height, id: recA.id }, b: { width: native.b.width, height: native.b.height, id: recB.id } },
+              approval: { referenceApproved: !!recA.approved, approvalBindsBytes: approvalValid, approvedAt: recA.approval?.approvedAt, candidateApprovalRequired: false },
+              configs: { reference: recA.device ?? null, candidate: recB.device ?? null }, masks,
+            },
+            limitations: [
+              'native space decodes SERVER-STORED PNG bytes only (8-bit grayscale/RGB/RGBA, non-interlaced; CRC-verified); anything else never claims native equality',
+              'caller-posted frames are ignored on this path — provenance is the store itself',
+            ],
+          })
+          envelope.provenance = 'server-decoded-stored-originals (caller-posted pixels ignored)'
+          if (ceiling !== null && mode === 'regression') {
+            // blocked ceilings invalidate the TEST itself (no valid baseline) even
+            // where pixels differ; needs_review ceilings only cap a would-be PASS —
+            // a detected inequality (changed>0) is never softened.
+            if (ceiling.status === 'blocked') envelope.checkStatus = 'blocked'
+            else if (envelope.checkStatus === 'passed') envelope.checkStatus = 'needs_review'
+            envelope.limitations.unshift(ceiling.reason)
+          }
+          try {
+            const evidenceDir = path.join(workspaceRef.root, 'evidence')
+            mkdirSync(evidenceDir, { recursive: true })
+            writeFileSync(path.join(evidenceDir, envelope.runId + '.json'), JSON.stringify(envelope, null, 2) + '\n', 'utf8')
+            envelope.evidenceFile = 'evidence/' + envelope.runId + '.json'
+          } catch { /* best-effort */ }
+          writeJson(res, 200, envelope)
+          return
+        }
+        // ── non-native path: caller-posted frames, triage only ──
+        if (a === undefined || b === undefined) {
+          writeJson(res, 400, { error: 'no native provenance available (stored originals missing or undecodable) and no valid triage frames were posted', ...(native?.error ? { note: native.error } : {}) })
+          return
+        }
+        const originals = {
+          a: recA ? { width: recA.width, height: recA.height, id: recA.id } : { width: a.width, height: a.height },
+          b: recB ? { width: recB.width, height: recB.height, id: recB.id } : { width: b.width, height: b.height },
+        }
+        const comparisonSpace = 'downsampled'
+        const blockedReason = native?.error ?? (recA && recB ? 'stored originals are not both PNG — server cannot establish pixel provenance; this is a caller-supplied-pixel comparison (triage), never a native pass' : undefined)
+        // Aspect mismatch with NO recorded transform → REJECT the screen-level
+        // comparison (a 1536x1024 board and a 1080x2400 capture are not valid
+        // screen comparators merely because both stretch into the panel).
+        const aspectA = a.width / a.height
+        const aspectB = b.width / b.height
+        const transform = body?.transform && typeof body.transform === 'object' ? body.transform : undefined
+        if (Math.abs(aspectA - aspectB) / Math.max(aspectA, aspectB) > 0.02 && transform === undefined) {
+          writeJson(res, 200, {
+            status: 'blocked', checkStatus: 'blocked', comparisonSpace, mode,
+            reason: `source aspect mismatch (${a.width}x${a.height} vs ${b.width}x${b.height}) — refusing implicit stretch; record an explicit transform or compare screen states captured at the same configuration`,
+            limitations: ['blocked comparisons are never downgraded into passes'],
+          })
+          return
+        }
+        try {
+          const diff = VisualCompare.diffFrames(a, b, { threshold: Number(body?.threshold) || 24, masks })
+          const envelope = VisualCompare.compareEnvelope({
+            runId: Date.now().toString(36) + '-' + Math.random().toString(36).slice(2, 8),
+            project: String(body?.project ?? 'unknown'), screen: String(body?.screen ?? ''), stateId: String(body?.stateId ?? ''),
+            mode, diff,
+            comparisonSpace,
+            transforms: transform ?? undefined,
+            observations: diff.status === 'ok' ? [{ source: 'diff', finding: `${diff.changedPixels} changed px (${diff.changePct}%) at threshold L1>${diff.threshold}; ${diff.clusterFilter.droppedClusters} sub-minimum cluster(s) counted in the verdict (${diff.clusterFilter.droppedPixels} px)` }] : [],
+            evidenceRefs: [body?.referenceId, body?.captureId].filter(Boolean),
+            env: { originals, postedFrames: { a: { width: a.width, height: a.height }, b: { width: b.width, height: b.height } }, masks },
+            limitations: ['regionsA/regionsB map comparison clusters back to stored-original pixel space', 'caller-supplied pixels — result compares what the client posted, NOT the stored originals; never an approved-baseline native pass',
+              ...(blockedReason ? [blockedReason] : [])],
+          })
+          if (diff.status === 'ok') {
+            envelope.regionsA = diff.clusters.map((c) => VisualCompare.mapRegionToFrame(c, transform?.a ?? {}))
+            envelope.regionsB = diff.clusters.map((c) => VisualCompare.mapRegionToFrame(c, transform?.b ?? {}))
+          }
+          try {
+            const evidenceDir = path.join(workspaceRef.root, 'evidence')
+            mkdirSync(evidenceDir, { recursive: true })
+            writeFileSync(path.join(evidenceDir, envelope.runId + '.json'), JSON.stringify(envelope, null, 2) + '\n', 'utf8')
+            envelope.evidenceFile = 'evidence/' + envelope.runId + '.json'
+          } catch { /* store best-effort; the response still carries the full envelope */ }
+          writeJson(res, 200, envelope)
+        } catch (error) {
+          writeJson(res, 500, { error: String(error instanceof Error ? error.message : error) })
+        }
+      },
+    },
+    {
+      kind: 'exact',
+      path: API_BASE + '/refs/image',
+      handler: async (req, res) => {
+        if (!guard(req, res)) return
+        const url = new URL(req.url ?? '/', 'http://localhost')
+        const record = workspaceRef.get(url.searchParams.get('id') ?? '')
+        if (!record) { writeJson(res, 404, { error: 'not found' }); return }
+        try {
+          const bytes = workspaceRef.readImage(record)
+          const mime = ({ '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.webp': 'image/webp' })[record.ext] ?? 'application/octet-stream'
+          res.writeHead(200, { 'content-type': mime, 'cache-control': 'no-store', 'x-content-type-options': 'nosniff' })
+          res.end(bytes)
+        } catch { writeJson(res, 500, { error: 'failed to read image' }) }
+      },
+    },
+
+    // ── Compose preview gallery (Feature B/T5) ────────────────────────────────
+    {
+      kind: 'exact',
+      path: API_BASE + '/preview/list',
+      handler: async (req, res) => {
+        if (!guard(req, res)) return
+        const url = new URL(req.url ?? '/', 'http://localhost')
+        const directory = url.searchParams.get('directory') ?? ''
+        const gradle = !!directory && PreviewGallery.previewSupportStatus(directory).wrapper
+        const warnings = []
+        const fingerprint = gradle ? PreviewGallery.inputsFingerprint(directory) : null
+        const entries = gradle ? PreviewGallery.discoverPreviewTests(directory, warnings).map((e) => ({ ...e, ...PreviewGallery.renderState(directory, e, { fingerprint }) })) : []
+        writeJson(res, 200, { directory, gradle, entries, ...(warnings.length ? { warnings } : {}) })
+      },
+    },
+    {
+      kind: 'exact',
+      path: API_BASE + '/preview/render',
+      handler: async (req, res) => {
+        if (!refGuard(req, res)) return
+        if (!isPost(req, res)) return
+        const body = await readBody(req, res)
+        if (body === undefined) return
+        const directory = String(body?.directory ?? '')
+        const className = String(body?.class ?? '')
+        const method = String(body?.method ?? '')
+        if (!directory || !/^[A-Za-z0-9_.]+$/.test(className) || !/^[A-Za-z0-9_]+$/.test(method)) {
+          writeJson(res, 400, { error: 'directory, class and method are required (identifier shapes only)' })
+          return
+        }
+        const entry = PreviewGallery.discoverPreviewTests(directory).find((e) => e.fqClass === className && e.method === method)
+        if (!entry) { writeJson(res, 400, { error: `not a discovered @PreviewTest in this project: ${className}.${method}` }); return }
+        const result = await PreviewGallery.renderPreviewTest(directory, entry, { timeoutMs: Number(body?.timeoutMs) || undefined })
+        writeJson(res, 200, result)
+      },
+    },
+    {
+      kind: 'exact',
+      path: API_BASE + '/preview/image',
+      handler: async (req, res) => {
+        if (!guard(req, res)) return
+        const url = new URL(req.url ?? '/', 'http://localhost')
+        const directory = url.searchParams.get('directory') ?? ''
+        const className = url.searchParams.get('class') ?? ''
+        const method = url.searchParams.get('method') ?? ''
+        if (!directory || !/^[A-Za-z0-9_.]+$/.test(className) || !/^[A-Za-z0-9_]+$/.test(method)) { writeJson(res, 400, { error: 'bad selector' }); return }
+        const entry = PreviewGallery.discoverPreviewTests(directory).find((e) => e.fqClass === className && e.method === method)
+        const state = entry ? PreviewGallery.renderState(directory, entry, { fingerprint: PreviewGallery.inputsFingerprint(directory) }) : undefined
+        if (state?.pngPath === undefined) { writeJson(res, 404, { error: 'no recorded reference for this preview' }); return }
+        try {
+          const bytes = readFileSync(state.pngPath)
+          res.writeHead(200, { 'content-type': 'image/png', 'cache-control': 'no-store', 'x-content-type-options': 'nosniff', 'x-preview-stale': state.stale ? 'true' : 'false', 'x-preview-freshness': state.freshness })
+          res.end(bytes)
+        } catch { writeJson(res, 500, { error: 'failed to read image' }) }
+      },
+    },
+
+    // ── configuration matrix (T7m/Feature F) ─────────────────────────────────
+    {
+      kind: 'exact',
+      path: API_BASE + '/matrix/capabilities',
+      handler: async (req, res) => {
+        if (!guard(req, res)) return
+        const url = new URL(req.url ?? '/', 'http://localhost')
+        const serial = url.searchParams.get('serial') ?? ''
+        try {
+          const actual = await ConfigMatrix.readConfig(serial)
+          writeJson(res, 200, { serial, emulator: ConfigMatrix.isEmulatorSerial(serial), actual, supported: ['widthPx/heightPx (wm size)', 'densityDpi (wm density)', 'fontScale (settings system)'], notSupportedHere: ['light/dark theme (app-owned; Trachtenberg is always dark)', 'orientation (app-owned)', 'insets/keyboard visibility (not settable)'] })
+        } catch (error) {
+          writeJson(res, 200, { serial, emulator: ConfigMatrix.isEmulatorSerial(serial), error: String(error instanceof Error ? error.message : error), actual: {} })
+        }
+      },
+    },
+    {
+      kind: 'exact',
+      path: API_BASE + '/matrix/run',
+      handler: async (req, res) => {
+        if (!refGuard(req, res)) return
+        if (!isPost(req, res)) return
+        const body = await readBody(req, res)
+        if (body === undefined) return
+        const invalid = validateMatrixBody(body)
+        if (invalid !== undefined) { writeJson(res, 400, { error: invalid }); return }
+        if (matrixRunning.has(body.serial)) { writeJson(res, 409, { error: `a matrix is already running on ${body.serial}` }); return }
+        matrixRunning.add(body.serial)
+        try {
+          const result = await ConfigMatrix.runMatrix({ serial: body.serial, workspace: workspaceRef, project: body.project, screen: body.screen, cases: body.cases })
+          writeJson(res, 200, result)
+        } catch (error) {
+          writeJson(res, 500, { error: String(error instanceof Error ? error.message : error), note: 'if the run was interrupted, check device settings were restored: adb shell wm size / wm density' })
+        } finally {
+          matrixRunning.delete(body.serial)
+        }
+      },
+    },
+    // ── OpenPencil narrow adapter (T7/Feature D — optional, degrades honestly) ─
+    {
+      kind: 'exact',
+      path: API_BASE + '/openpencil/status',
+      handler: async (req, res) => {
+        if (!guard(req, res)) return
+        const p = OpenPencil.probe()
+        writeJson(res, 200, {
+          status: p.installed ? 'available' : 'not_installed',
+          binary: p.resolved,
+          // Honesty (2026-09-15): binary FOUND is not CLI RESPONSIVENESS. On this
+          // host the resolved OpenPencil.exe is a GUI editor that did not answer
+          // `--help` within 60 s — treat inspect/export as not_run until a
+          // file-mode CLI demonstrably answers.
+          cliEvidence: p.installed ? 'unverified — resolved binary did not answer a documented CLI invocation within 60 s on this host; presence ≠ usable file-mode CLI' : undefined,
+          hint: p.installed ? 'binary resolved; export/inspect remain not_run until CLI responsiveness is proven — the reference workspace stays fully usable with manual image imports.' : 'install the OpenPencil file-mode CLI (openpencil.dev) to enable frame export; manual image import covers the workflow meanwhile.',
+          boundary: 'OpenPencil exports target PNG/JSX/HTML — no native Compose export is claimed or performed',
+        })
+      },
+    },
+    {
+      kind: 'exact',
+      path: API_BASE + '/openpencil/importFrame',
+      handler: async (req, res) => {
+        if (!refGuard(req, res)) return
+        if (!isPost(req, res)) return
+        const body = await readBody(req, res)
+        if (body === undefined) return
+        if (!OpenPencil.probe().installed) { writeJson(res, 200, { status: 'not_run', reason: 'openpencil CLI not on PATH; see /openpencil/status hint' }); return }
+        try {
+          const exported = await OpenPencil.exportFrame({ file: body.file, root: body.root, node: body.node, page: body.page, scale: body.scale, workspace: workspaceRef })
+          if (exported.status !== 'passed') { writeJson(res, 200, { status: 'failed', reason: 'export failed', ...exported }); return }
+          const record = workspaceRef.import({ project: body.project, screen: body.screen, stateId: body.stateId, filename: path.basename(String(body.file ?? 'frame'), '.fig') + '.png', provenance: `openpencil export: ${body.file}${body.node ? ` node ${body.node}` : ''}`, intendedUse: 'design-target' }, `data:image/png;base64,${readFileSync(exported.pngPath).toString('base64')}`)
+          writeJson(res, 201, { status: 'passed', record })
+        } catch (error) {
+          writeJson(res, 400, { status: 'failed', error: String(error instanceof Error ? error.message : error) })
+        }
+      },
+    },
   ]
   return routes
 }
 
+// one matrix at a time per device (reconfiguring while one runs would race settings)
+const matrixRunning = new Set()
+
+// ponytail: single shared store for routes + tools; root overridable for tests.
+// Per-workspace stores if multi-project isolation is ever needed.
+let workspaceSingleton
+function sharedWorkspaceRef() {
+  if (workspaceSingleton === undefined) workspaceSingleton = new ReferenceWorkspace(process.env.DSH_MOBILECODE_REF_ROOT ?? Setup.HOME)
+  return workspaceSingleton
+}
+
+/** Shared by the /matrix/run route and the config_matrix tool. Returns an error string or undefined. */
+function validateMatrixBody(body) {
+  const serial = typeof body?.serial === 'string' ? body.serial.trim() : ''
+  if (serial === '' || !/^[A-Za-z0-9:._-]+$/.test(serial)) return 'serial is required (safe characters only)'
+  if (typeof body?.project !== 'string' || typeof body?.screen !== 'string') return 'project and screen are required strings'
+  const cases = body?.cases
+  if (!Array.isArray(cases) || cases.length === 0 || cases.length > 8) return 'cases must be 1..8 risk-based entries (no uncontrolled products)'
+  for (const c of cases) {
+    if (typeof c?.id !== 'string' || c.id === '' || c.id.length > 80) return 'every case needs a short string id'
+    if (c.dims !== undefined && (!Array.isArray(c.dims) || c.dims.length !== 2 || !c.dims.every((n) => Number.isInteger(n) && n > 100 && n <= 8000))) return `case ${c.id}: dims must be two ints in 101..8000`
+    if (c.density !== undefined && (!Number.isInteger(c.density) || c.density < 80 || c.density > 800)) return `case ${c.id}: density must be an int 80..800`
+    if (c.fontScale !== undefined && (typeof c.fontScale !== 'number' || c.fontScale < 0.5 || c.fontScale > 3)) return `case ${c.id}: fontScale must be a number 0.5..3`
+    if (c.dims === undefined && c.density === undefined && c.fontScale === undefined) return `case ${c.id}: declares no dimensions`
+  }
+  body.serial = serial
+  return undefined
+}
+
 // ── agent tools ───────────────────────────────────────────────────────────────
 
 const label = (platform) => (platform === 'ios' ? 'iOS' : 'Android')
@@ -2925,6 +3396,185 @@ function deviceStreamTool(host, access) {
   })
 }
 
+/**
+ * Compose preview gallery (Feature B/T5): discover @PreviewTest composables of
+ * an app, render one through the Gradle adapter (argument arrays, capped
+ * timeout, cancellable kill), return the PNG attachment + provenance.
+ * Host-rendered (layoutlib) — NEVER claimed as device-verified.
+ */
+function previewGalleryTool(vision) {
+  const envelope = {
+    type: 'object',
+    additionalProperties: true,
+    description: 'Result envelope. status: passed|failed|blocked|not_run. Carries previews/provenance/tail ' +
+      'depending on action. A stale render is labeled stale; failures never masquerade as current.',
+    properties: {
+      status: { type: 'string', required: true },
+      error: { type: 'string' },
+      setupHint: { type: 'string' },
+      count: { type: 'number' },
+      previews: { type: 'array', items: { type: 'object', additionalProperties: true } },
+      provenance: { type: 'object', additionalProperties: true },
+      image: Vision.IMAGE_REF_SCHEMA,
+    },
+  }
+  return defineTool({
+    name: 'preview_gallery',
+    description: 'Compose preview gallery for an Android Gradle project using official Compose Preview Screenshot ' +
+      'Testing. action=list discovers @PreviewTest entries with render state (rendered/stale); action=render runs ' +
+      'ONE Gradle render and returns the PNG as an image attachment plus provenance (command, exit, timestamps, ' +
+      'stale flag); action=status reports adapter availability only. Host-rendered via layoutlib: NOT device ' +
+      'behavior (use device_screen for that). Failed renders report tail lines; stale PNGs are never labeled current.',
+    parameters: {
+      directory: { type: 'string', description: 'Gradle project root (contains gradlew + settings.gradle).' },
+      action: { type: 'string', description: 'list | render | status. Default list.' },
+      class: { type: 'string', description: 'render: fully-qualified class of a discovered @PreviewTest.' },
+      method: { type: 'string', description: 'render: the @PreviewTest method name.' },
+      timeoutMs: { type: 'number', description: 'render cap in ms (default 600000, max 1800000).' },
+    },
+    output: { schema: envelope },
+    async execute(args, exec) {
+      const directory = typeof args.directory === 'string' ? args.directory.trim() : ''
+      if (directory === '') return { status: 'failed', error: 'directory is required' }
+      const support = PreviewGallery.previewSupportStatus(directory)
+      if (!support.wrapper) return { status: 'not_run', error: `${directory} has no gradlew wrapper — not a Gradle project`, setupHint: 'point directory at the app project root' }
+      if (!support.screenshotTest) return { status: 'not_run', error: 'no src/screenshotTest source — Compose Preview Screenshot Testing adapter not set up', setupHint: 'see docs/design/render-adapter-decision.md (plugin apply + marker dep + @PreviewTest methods in a *Test class)' }
+      const discoveryWarnings = []
+      const entries = PreviewGallery.discoverPreviewTests(directory, discoveryWarnings)
+      const action = args.action ?? 'list'
+      if (action === 'status') return { status: 'passed', count: entries.length, previews: entries.map((e) => ({ class: e.fqClass, method: e.method })), ...(discoveryWarnings.length ? { warnings: discoveryWarnings } : {}), provenance: { renderer: 'com.android.compose.screenshot 0.0.1-alpha16 (layoutlib, host-rendered)', deviceVerified: false } }
+      if (action === 'render') {
+        const entry = entries.find((e) => e.fqClass === args.class && e.method === args.method)
+        if (!entry) return { status: 'blocked', error: `not a discovered @PreviewTest: ${String(args.class)}.${String(args.method)}`, previews: entries.map((e) => ({ class: e.fqClass, method: e.method })) }
+        const result = await PreviewGallery.renderPreviewTest(directory, entry, { timeoutMs: Number(args.timeoutMs) || undefined })
+        const envelopeOut = { status: result.status, failureKind: result.failureKind, exitCode: result.exitCode, tail: result.tail, provenance: result.provenance, limitations: ['host-rendered (layoutlib) — not device behavior'] }
+        if (result.status === 'passed' && typeof result.provenance?.pngPath === 'string') {
+          const image = await Vision.maybeAttachScreenshot(vision, result.provenance.pngPath, exec)
+          if (image !== undefined) envelopeOut.image = image
+        }
+        return envelopeOut
+      }
+      const previews = entries.map((e) => {
+        const s = PreviewGallery.renderState(directory, e, { fingerprint: PreviewGallery.inputsFingerprint(directory) })
+        return { class: e.fqClass, method: e.method, previewName: e.previewName, widthDp: e.widthDp, sourceFile: path.relative(directory, e.sourceFile).replaceAll('\\', '/'), rendered: s.rendered, stale: s.stale, freshness: s.freshness }
+      })
+      return { status: 'passed', count: previews.length, previews, ...(discoveryWarnings.length ? { warnings: discoveryWarnings } : {}), limitations: ['freshness=unknown means no render manifest exists — the PNG may be current or not; never treat unknown as fresh', 'host-rendered previews are not device verification'] }
+    },
+  })
+}
+
+/**
+ * Bounded configuration matrix (T7m): real device reconfiguration through the
+ * existing adb plumbing with snapshot/restore on ALL paths. Evidence lands in
+ * the reference workspace capture store. Physical devices are refused.
+ */
+function configMatrixTool() {
+  return defineTool({
+    name: 'config_matrix',
+    description: 'Run a bounded, risk-based Android configuration matrix on an EMULATOR (1..8 cases of ' +
+      'wm size / wm density / font scale). action=capabilities reads back the device actual config and ' +
+      'lists what is settable vs app-owned; action=run applies each case, CONFIRMS the actual resulting ' +
+      'configuration by reading it back (requested != actual is reported, not assumed), captures evidence ' +
+      'through the reference-workspace store, and restores the device to its found state on success, ' +
+      'failure and cancellation. Physical-device changes are refused. Browser pane scaling is NOT a ' +
+      'device configuration change and is never represented here.',
+    parameters: {
+      action: { type: 'string', description: 'capabilities | run' },
+      serial: { type: 'string', description: 'Device serial (emulator-* required for run).' },
+      project: { type: 'string', description: 'run: evidence project key (e.g. trachtenberg).' },
+      screen: { type: 'string', description: 'run: evidence screen key (e.g. practice).' },
+      cases: { type: 'string', description: 'run: JSON array of 1..8 cases: [{id, dims?, density?, fontScale?}] — dims=[w,h] px, density dpi, fontScale 0.5..3.' },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: true,
+        properties: {
+          status: { type: 'string', required: true },
+          reports: { type: 'array', items: { type: 'object', additionalProperties: true } },
+          restore: { type: 'object', additionalProperties: true },
+          snapshotBefore: { type: 'object', additionalProperties: true },
+          warnings: { type: 'array', items: { type: 'string' } },
+        },
+      },
+    },
+    async execute(args) {
+      const action = args.action ?? 'capabilities'
+      if (action === 'capabilities') {
+        const serial = String(args.serial ?? '')
+        const actual = await ConfigMatrix.readConfig(serial).catch((error) => ({ error: String(error instanceof Error ? error.message : error) }))
+        return { status: 'passed', serial, emulator: ConfigMatrix.isEmulatorSerial(serial), actual }
+      }
+      let parsed
+      try { parsed = JSON.parse(String(args.cases ?? '')) } catch { return { status: 'failed', error: 'cases must be a JSON array of {id, dims?, density?, fontScale?}' } }
+      const body = { serial: args.serial, project: args.project, screen: args.screen, cases: parsed }
+      const invalid = validateMatrixBody(body)
+      if (invalid !== undefined) return { status: 'failed', error: invalid }
+      return await ConfigMatrix.runMatrix({ serial: body.serial, workspace: sharedWorkspaceRef(), project: body.project, screen: body.screen, cases: body.cases })
+    },
+  })
+}
+
+/**
+ * OpenPencil design bridge (T7): optional local integration with the
+ * OpenPencil CLI for .fig documents — inspect frames, export a frame to PNG
+ * and import it into the reference workspace, read design variables.
+ * NEVER claims native Compose export (OpenPencil exports are PNG/JSX/HTML).
+ */
+function designBridgeTool() {
+  return defineTool({
+    name: 'design_bridge',
+    description: 'OpenPencil design-document bridge (file mode only — the editor owns edits). ' +
+      'action=status reports installation + what the adapter can do; action=inspect reads a .fig ' +
+      'document (info + pages, confined to root); action=variables lists design variables; ' +
+      'action=importFrame exports one frame/page to PNG via the OpenPencil CLI and registers it in ' +
+      'the reference-comparison workspace with provenance. OpenPencil has no native Compose export — ' +
+      'web-oriented outputs (JSX/HTML) are NOT produced here and never presented as Kotlin.',
+    parameters: {
+      action: { type: 'string', description: 'status | inspect | variables | importFrame' },
+      root: { type: 'string', description: 'Allowed project root directory the design file must live in.' },
+      file: { type: 'string', description: 'Path to the .fig document (inside root).' },
+      node: { type: 'string', description: 'importFrame: node id to export (e.g. 1:23). Omit for whole page.' },
+      page: { type: 'string', description: 'inspect/importFrame: page name.' },
+      scale: { type: 'number', description: 'importFrame: export scale 1..4 (default 2).' },
+      project: { type: 'string', description: 'importFrame: evidence project key.' },
+      screen: { type: 'string', description: 'importFrame: screen key.' },
+      stateId: { type: 'string', description: 'importFrame: state key.' },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: true,
+        properties: {
+          status: { type: 'string', required: true },
+          hint: { type: 'string' },
+        },
+      },
+    },
+    async execute(args) {
+      const action = args.action ?? 'status'
+      const p = OpenPencil.probe()
+      if (!p.installed) {
+        return { status: 'not_run', reason: 'openpencil CLI not on PATH', hint: 'install OpenPencil (openpencil.dev); manual reference imports into the workspace work without it' }
+      }
+      try {
+        if (action === 'status') return { status: 'passed', binary: p.resolved }
+        if (action === 'inspect') return await OpenPencil.inspect(args.file, args.root ?? args.directory ?? '')
+        if (action === 'variables') return await OpenPencil.variables(args.file, args.root ?? '')
+        if (action === 'importFrame') {
+          const exported = await OpenPencil.exportFrame({ file: args.file, root: args.root, node: args.node, page: args.page, scale: args.scale, workspace: sharedWorkspaceRef() })
+          if (exported.status !== 'passed') return { ...exported, status: 'failed' }
+          const record = sharedWorkspaceRef().import({ project: args.project, screen: args.screen, stateId: args.stateId, filename: path.basename(String(args.file ?? 'frame'), '.fig') + '.png', provenance: `openpencil export: ${args.file}${args.node ? ` node ${args.node}` : ''}`, intendedUse: 'design-target' }, `data:image/png;base64,${readFileSync(exported.pngPath).toString('base64')}`)
+          return { status: 'passed', record }
+        }
+        return { status: 'failed', error: `unknown action ${action}` }
+      } catch (error) {
+        return { status: 'failed', error: String(error instanceof Error ? error.message : error) }
+      }
+    },
+  })
+}
+
 function deviceScreenTool(engine, vision) {
   return defineTool({
     name: 'device_screen',
@@ -3517,6 +4167,9 @@ export function apply(ctx, config) {
         deviceRunTool(engine, config),
         deviceDetectTool(engine, config),
         deviceScreenTool(engine, vision),
+        previewGalleryTool(vision),
+        configMatrixTool(),
+        designBridgeTool(),
         deviceUiTreeTool(),
         deviceTapElementTool(),
         deviceWaitForTool(),