@harmonyos-arkts/d2h 0.1.3 → 0.1.6

package/skills/d2h-utg-ai-generate/scripts/build_utg.py

@@ -0,0 +1,123 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import argparse
+import subprocess
+import sys
+from pathlib import Path
+
+from utg_common import (
+    UtgError,
+    atomic_write_json,
+    build_click_paths,
+    load_json,
+    normalize_facts,
+    summary,
+    validate_pair,
+)
+from build_page_json import build_page_plan, validate_page_plan
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Build normalized utg.json and deterministic click_paths.json from AI source facts."
+    )
+    parser.add_argument("--facts", required=True, type=Path)
+    parser.add_argument("--project-root", required=True, type=Path)
+    parser.add_argument("--workspace", required=True, type=Path)
+    parser.add_argument("--force", action="store_true", help="replace existing generated outputs")
+    return parser.parse_args()
+
+
+def main() -> int:
+    args = parse_args()
+    workspace = args.workspace.resolve()
+    project_root = args.project_root.resolve()
+    if not project_root.is_dir():
+        print(f"ERROR: project root is not a directory: {project_root}", file=sys.stderr)
+        return 2
+    outputs = [
+        workspace / "utg.json",
+        workspace / "click_paths.json",
+        workspace / "page.json",
+    ]
+    existing = [path for path in outputs if path.exists()]
+    if existing and not args.force:
+        print(
+            "ERROR: generated output already exists; use --force only for an authorized regeneration: "
+            + ", ".join(str(path) for path in existing),
+            file=sys.stderr,
+        )
+        return 2
+    try:
+        facts = load_json(args.facts.resolve())
+        utg, normalizations, unresolved = normalize_facts(facts, project_root)
+        click_paths = build_click_paths(utg)
+        errors = validate_pair(utg, click_paths, project_root)
+        if errors:
+            raise UtgError("generated pair failed validation:\n- " + "\n- ".join(errors))
+        page_plan = build_page_plan(
+            utg,
+            click_paths,
+            utg_path=str(outputs[0]),
+            click_paths_path=str(outputs[1]),
+        )
+        page_errors = validate_page_plan(
+            page_plan,
+            utg,
+            click_paths,
+            utg_path=str(outputs[0]),
+            click_paths_path=str(outputs[1]),
+        )
+        if page_errors:
+            raise UtgError("generated page plan failed validation:\n- " + "\n- ".join(page_errors))
+        report = {
+            "schema_version": "d2h-utg-ai-generation-report/v1",
+            "status": "valid",
+            "method": facts.get('graph', {}).get('method', 'ai-source-analysis'),
+            "facts": str(args.facts.resolve()),
+            "project_root": str(project_root),
+            "summary": summary(utg, click_paths),
+            "page_plan": page_plan["summary"],
+            "normalizations": normalizations,
+            "unresolved": unresolved,
+        }
+        if 'projection_summary' in facts.get('graph', {}):
+            report['projection'] = facts['graph']['projection_summary']
+        atomic_write_json(outputs[0], utg)
+        atomic_write_json(outputs[1], click_paths)
+        atomic_write_json(outputs[2], page_plan)
+        atomic_write_json(workspace / "generation-report.json", report)
+        # Interactive visualization — same renderer android-utg-static ships
+        # (extended for reconciliation semantics), so the output is comparable.
+        # It reads <workspace>/utg.json and writes <workspace>/utg.html. Best
+        # effort: a visualization failure must not fail the build.
+        html_script = Path(__file__).resolve().parent / "utg_html.py"
+        if html_script.exists():
+            result = subprocess.run(
+                [sys.executable, str(html_script), str(workspace)],
+                capture_output=True,
+                text=True,
+            )
+            if result.returncode != 0:
+                print(
+                    f"WARN: utg.html generation failed: {result.stderr.strip()}",
+                    file=sys.stderr,
+                )
+    except UtgError as exc:
+        print(f"ERROR: {exc}", file=sys.stderr)
+        return 2
+
+    counts = report["summary"]
+    print(
+        f"valid: nodes={counts['nodes']} edges={counts['edges']} "
+        f"reachable={counts['reachable']} unreachable={counts['unreachable']}"
+    )
+    print(outputs[0])
+    print(outputs[1])
+    print(outputs[2])
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/skills/d2h-utg-ai-generate/scripts/capture_from_page_json.ts

@@ -0,0 +1,280 @@
+#!/usr/bin/env node
+/** Standalone Android page-plan replay and capture using only Node and ADB. */
+
+import { spawnSync, type SpawnSyncReturns } from 'node:child_process';
+import { createHash, randomUUID } from 'node:crypto';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+type JsonObject = Record<string, unknown>;
+interface Selector { text?: string; text_any?: string[]; content_desc?: string; content_desc_any?: string[]; resource_id?: string; resource_id_any?: string[]; normalized_point?: [number, number] }
+interface Expected { text_any?: string[]; text_all?: string[]; content_desc_any?: string[]; resource_id_any?: string[]; activity_any?: string[] }
+interface PlanStep {
+  component?: string;
+  action: string; label?: string | null; label_source?: string | null; label_ambiguous?: boolean; nl_hint?: string;
+  selector?: Selector; direction?: string; distance?: number; duration_ms?: number; max_scrolls?: number;
+  target_id?: string; target_kind?: string; guard?: { kind?: string; text?: string } | null; mechanism?: string;
+}
+interface PlanPage {
+  node_id: string; kind: string; label: string; declared_at: string; required_state: string[]; expected: Expected;
+  reachable: boolean; capture: boolean; capture_key: string | null; depth: number | null; ui_sequence: string;
+  path_text: string | null; steps: PlanStep[]; skip_reason: string | null;
+}
+interface PagePlan {
+  schema_version: string;
+  source: { utg: string; click_paths: string; root: string; app: string; package: string; architecture: string; version_name: string; build_variant: string };
+  summary: { nodes: number; capture_planned: number; unreachable: number; excluded_by_kind: Record<string, number> };
+  pages: PlanPage[];
+}
+interface UiNode {
+  attrs: Record<string, string>; children: UiNode[]; parent: UiNode | null; text: string; desc: string; rid: string;
+  bounds: string; clickable: boolean; longClickable: boolean; scrollable: boolean; enabled: boolean; center: [number, number] | null;
+}
+interface CliArgs {
+  pageJson: string; outputWorkspace: string; packageName: string; device: string | null; adbPath: string;
+  only: Set<string> | null; satisfiedState: Set<string>; dryRun: boolean; allowPartial: boolean;
+  allowCoordinateFallback: boolean; settleMs: number; maxScrolls: number;
+}
+
+const SCHEMA_VERSION = 'd2h-page-plan/v1';
+const NON_CAPTURE_KINDS = new Set(['nav-graph', 'sentinel', 'host-activity']);
+const CONTAINMENT_MECHANISMS = new Set(['navhost-start', 'nav-graph-start', 'nav-component-start', 'fragment-embed']);
+
+function sleep(ms: number): void { if (ms > 0) Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms); }
+function asObject(value: unknown, where: string): JsonObject {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) throw new Error(`${where} must be an object`);
+  return value as JsonObject;
+}
+function readJson(file: string): JsonObject {
+  try { return asObject(JSON.parse(fs.readFileSync(file, 'utf-8')), file); }
+  catch (error) { throw new Error(`cannot read JSON ${file}: ${error instanceof Error ? error.message : error}`); }
+}
+function atomicWriteJson(file: string, value: unknown): void {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const temp = path.join(path.dirname(file), `.${path.basename(file)}.${process.pid}.${Date.now()}`);
+  fs.writeFileSync(temp, `${JSON.stringify(value, null, 2)}\n`, 'utf-8'); fs.renameSync(temp, file);
+}
+function slug(nodeId: string): string {
+  const readable = nodeId.replace(/[^A-Za-z0-9._-]+/g, '_').replace(/^[._-]+|[._-]+$/g, '') || 'page';
+  return `${readable.slice(0, 72)}-${createHash('sha256').update(nodeId).digest('hex').slice(0, 8)}`;
+}
+function resolveSource(planFile: string, value: string): string { return path.resolve(path.isAbsolute(value) ? value : path.join(path.dirname(planFile), value)); }
+function nonCaptureReason(node: JsonObject, links: JsonObject[], steps: PlanStep[] = []): string | null {
+  const kind = String(node.kind ?? '');
+  if (NON_CAPTURE_KINDS.has(kind)) return `non-capture-kind:${kind}`;
+  if (kind === 'activity' && links.some((e) => e.source === node.id && CONTAINMENT_MECHANISMS.has(String(e.mechanism ?? '')))) return 'container-node:activity';
+  if ((node.extra as JsonObject | null)?.capture_policy === 'strict') {
+    const expected = (node.expected ?? {}) as JsonObject;
+    if (!['text_any', 'text_all', 'content_desc_any', 'resource_id_any', 'activity_any'].some((key) => Array.isArray(expected[key]) && (expected[key] as unknown[]).length)) return 'missing-arrival-rules';
+    for (const step of steps) {
+      const selector = (step.selector ?? {}) as JsonObject;
+      const selectorReady = ['text', 'text_any', 'content_desc', 'content_desc_any', 'resource_id', 'resource_id_any'].some((key) => (typeof selector[key] === 'string' && Boolean(selector[key])) || (Array.isArray(selector[key]) && (selector[key] as unknown[]).length > 0 && (selector[key] as unknown[]).every((value) => typeof value === 'string' && value.length > 0)));
+      if (['tap', 'long-press'].includes(step.action) && !selectorReady && !(step.label && ['string', 'content-description', 'system'].includes(step.label_source ?? '') && !step.label_ambiguous)) return 'missing-executable-selector';
+      if (!['launch', 'start-activity', 'deep-link', 'home', 'back', 'default', 'tap', 'swipe', 'long-press'].includes(step.action)) return 'unsupported-replay-action';
+      if (step.action === 'start-activity' && !/^[\w.]+\/[\w.$]+$/.test(step.component ?? '')) return 'missing-launch-component';
+      if (step.action === 'deep-link' && !/^[a-z][a-z0-9+.-]*:/i.test(step.label ?? '')) return 'missing-entry-uri';
+      if (step.action === 'swipe' && !step.direction) return 'missing-swipe-direction';
+    }
+  }
+  return null;
+}
+
+function validatePlan(planFile: string, raw: JsonObject): PagePlan {
+  if (raw.schema_version !== SCHEMA_VERSION) throw new Error(`page.json schema_version must be ${JSON.stringify(SCHEMA_VERSION)}`);
+  const source = asObject(raw.source, 'page.source'); const summary = asObject(raw.summary, 'page.summary');
+  if (!Array.isArray(raw.pages)) throw new Error('page.pages must be an array');
+  for (const key of ['utg', 'click_paths', 'root', 'app', 'architecture']) if (typeof source[key] !== 'string' || source[key] === '') throw new Error(`page.source.${key} must be a non-empty string`);
+  for (const key of ['package', 'version_name', 'build_variant']) if (typeof source[key] !== 'string') throw new Error(`page.source.${key} must be a string`);
+  const utgFile = resolveSource(planFile, String(source.utg)); const clickFile = resolveSource(planFile, String(source.click_paths));
+  if (!fs.existsSync(utgFile) || !fs.existsSync(clickFile)) throw new Error('page.source.utg/click_paths must reference existing files');
+  const utg = readJson(utgFile); const clickPaths = readJson(clickFile);
+  if (!Array.isArray(utg.nodes) || !Array.isArray(utg.links)) throw new Error('source UTG has invalid nodes/links');
+  const graph = asObject(utg.graph, 'utg.graph');
+  if (clickPaths.root !== source.root || graph.root !== source.root) throw new Error('page root disagrees with UTG/click_paths');
+  const paths = asObject(clickPaths.paths, 'click_paths.paths');
+  if (!Array.isArray(clickPaths.unreachable)) throw new Error('click_paths.unreachable must be an array');
+  const nodes = new Map<string, JsonObject>();
+  for (const item of utg.nodes) {
+    const node = asObject(item, 'utg.nodes[]');
+    if (typeof node.id !== 'string' || nodes.has(node.id)) throw new Error(`invalid or duplicate UTG node id: ${String(node.id)}`);
+    nodes.set(node.id, node);
+  }
+  const links = utg.links.map((item) => asObject(item, 'utg.links[]'));
+  const pages = raw.pages.map((item, index) => {
+    const page = asObject(item, `page.pages[${index}]`) as unknown as PlanPage;
+    if (typeof page.node_id !== 'string' || !nodes.has(page.node_id)) throw new Error(`page.pages[${index}] references a missing node`);
+    if (!Array.isArray(page.steps) || !Array.isArray(page.required_state) || page.expected === null || typeof page.expected !== 'object') throw new Error(`page.pages[${index}] has invalid steps/required_state/expected`);
+    return page;
+  });
+  if (pages.length !== nodes.size || new Set(pages.map((p) => p.node_id)).size !== nodes.size) throw new Error('page.pages must cover every UTG node exactly once');
+  let captureIndex = 0, unreachable = 0; const excluded: Record<string, number> = {};
+  for (const page of pages) {
+    const node = nodes.get(page.node_id)!; const clickPath = paths[page.node_id] as JsonObject | undefined; const reachable = clickPath !== undefined;
+    if (!reachable) unreachable += 1; const reason = nonCaptureReason(node, links, ((paths[page.node_id] as JsonObject | undefined)?.steps ?? []) as PlanStep[]); const capture = reachable && reason === null;
+    if (reason !== null) { const key = reason.startsWith('container-node') ? `${String(node.kind)}(container)` : String(node.kind); excluded[key] = (excluded[key] ?? 0) + 1; }
+    if (capture) captureIndex += 1;
+    const expectedKey = capture ? `page_${String(captureIndex).padStart(4, '0')}_${slug(page.node_id)}` : null;
+    const expectedSteps = reachable && Array.isArray(clickPath!.steps) ? clickPath!.steps : [];
+    const expectedSkip = capture ? null : !reachable ? 'unreachable-from-root' : reason;
+    if (page.reachable !== reachable || page.capture !== capture || page.capture_key !== expectedKey || JSON.stringify(page.steps) !== JSON.stringify(expectedSteps) || JSON.stringify(page.expected) !== JSON.stringify(node.expected ?? {}) || page.skip_reason !== expectedSkip) throw new Error('page.json is not the deterministic plan for this UTG pair');
+  }
+  if (summary.nodes !== nodes.size || summary.capture_planned !== captureIndex || summary.unreachable !== unreachable || JSON.stringify(summary.excluded_by_kind) !== JSON.stringify(Object.fromEntries(Object.entries(excluded).sort()))) throw new Error('page.json is not the deterministic plan for this UTG pair');
+  return raw as unknown as PagePlan;
+}
+
+function decodeXml(value: string): string {
+  return value.replace(/&(#x?[0-9a-fA-F]+|amp|lt|gt|quot|apos);/g, (whole, entity: string) => {
+    const named: Record<string, string> = { amp: '&', lt: '<', gt: '>', quot: '"', apos: "'" }; if (entity in named) return named[entity];
+    const code = Number.parseInt(entity.startsWith('#x') ? entity.slice(2) : entity.slice(1), entity.startsWith('#x') ? 16 : 10);
+    return Number.isFinite(code) ? String.fromCodePoint(code) : whole;
+  });
+}
+function parseUiTree(xml: string): UiNode {
+  const stack: UiNode[] = []; let root: UiNode | null = null; const token = /<\/?node\b[^>]*>|<hierarchy\b[^>]*>|<\/hierarchy>/g;
+  for (const match of xml.matchAll(token)) {
+    const raw = match[0]; if (raw.startsWith('</')) { if (raw.startsWith('</node')) stack.pop(); continue; } if (!raw.startsWith('<node')) continue;
+    const attrs: Record<string, string> = {}; for (const attr of raw.matchAll(/([^\s=/>]+)="([^"]*)"/g)) attrs[attr[1]] = decodeXml(attr[2]);
+    const nums = (attrs.bounds ?? '').match(/\d+/g)?.map(Number) ?? []; const parent = stack.length ? stack[stack.length - 1] : null;
+    const node: UiNode = { attrs, children: [], parent, text: attrs.text ?? '', desc: attrs['content-desc'] ?? '', rid: attrs['resource-id'] ?? '', bounds: attrs.bounds ?? '', clickable: attrs.clickable === 'true', longClickable: attrs['long-clickable'] === 'true', scrollable: attrs.scrollable === 'true', enabled: attrs.enabled !== 'false', center: nums.length === 4 ? [Math.trunc((nums[0] + nums[2]) / 2), Math.trunc((nums[1] + nums[3]) / 2)] : null };
+    if (parent) parent.children.push(node); else if (!root) root = node; if (!raw.endsWith('/>')) stack.push(node);
+  }
+  if (!root) throw new Error('uiautomator XML has no node root'); return root;
+}
+function flatten(root: UiNode): UiNode[] { const out: UiNode[] = []; const walk = (n: UiNode): void => { out.push(n); n.children.forEach(walk); }; walk(root); return out; }
+function list(value?: string, values?: string[]): string[] { return [...(value ? [value] : []), ...(Array.isArray(values) ? values : [])].filter(Boolean); }
+function fieldScore(actual: string, wanted: string): number {
+  if (!actual) return -1; if (actual === wanted) return 120; if (actual.endsWith(`/${wanted}`) || actual.endsWith(`:${wanted}`)) return 110;
+  if (actual.toLocaleLowerCase() === wanted.toLocaleLowerCase()) return 100; return actual.toLocaleLowerCase().includes(wanted.toLocaleLowerCase()) ? 70 : -1;
+}
+function semanticScore(node: UiNode, selector: Selector | undefined, label: string | null): number {
+  if (!node.enabled || node.center === null) return -1; let score = -1;
+  const pairs: Array<[string, string[], number]> = [[node.text, list(selector?.text, selector?.text_any), 30], [node.desc, list(selector?.content_desc, selector?.content_desc_any), 25], [node.rid, list(selector?.resource_id, selector?.resource_id_any), 20]];
+  const explicit = pairs.some(([, wanted]) => wanted.length > 0);
+  for (const [actual, wanted, bonus] of pairs) for (const value of wanted) { const base = fieldScore(actual, value); if (base >= 0) score = Math.max(score, base + bonus); }
+  if (!explicit && label) for (const actual of [node.text, node.desc, node.rid]) score = Math.max(score, fieldScore(actual, label)); return score;
+}
+function clickableTarget(node: UiNode): UiNode { let current: UiNode | null = node; while (current) { if ((current.clickable || current.longClickable) && current.center) return current; current = current.parent; } return node; }
+function verification(expected: Expected, xml: string, activity: Record<string, string>): { ok: boolean; checks: JsonObject[]; reason?: string } {
+  const recognized = ['text_any', 'text_all', 'content_desc_any', 'resource_id_any', 'activity_any'].some((key) => Array.isArray((expected as JsonObject)[key]) && ((expected as JsonObject)[key] as unknown[]).length > 0);
+  if (!recognized) return { ok: false, checks: [], reason: 'arrival verification missing: node.expected has no supported non-empty rule' };
+  const nodes = flatten(parseUiTree(xml)); const checks: JsonObject[] = [];
+  const any = (name: string, wanted: string[] | undefined, actual: string[]): boolean => { if (!wanted?.length) return true; const hits = wanted.filter((v) => actual.some((a) => a === v || a.includes(v))); checks.push({ rule: name, wanted, hits, passed: hits.length > 0 }); return hits.length > 0; };
+  const all = (name: string, wanted: string[] | undefined, actual: string[]): boolean => { if (!wanted?.length) return true; const missing = wanted.filter((v) => !actual.some((a) => a === v || a.includes(v))); checks.push({ rule: name, wanted, missing, passed: !missing.length }); return !missing.length; };
+  const texts = nodes.map((n) => n.text).filter(Boolean), descs = nodes.map((n) => n.desc).filter(Boolean), rids = nodes.map((n) => n.rid).filter(Boolean);
+  const ok = any('text_any', expected.text_any, texts) && all('text_all', expected.text_all, texts) && any('content_desc_any', expected.content_desc_any, descs) && any('resource_id_any', expected.resource_id_any, rids) && any('activity_any', expected.activity_any, Object.values(activity));
+  return { ok, checks, ...(ok ? {} : { reason: 'arrival verification failed' }) };
+}
+
+class Adb {
+  executable: string; serial: string | null; settleMs: number; maxScrolls: number; allowCoordinateFallback: boolean;
+  private screen = { width: 1080, height: 1920 };
+  constructor(executable: string, serial: string | null, settleMs: number, maxScrolls: number, allowCoordinateFallback: boolean) { this.executable = executable; this.serial = serial; this.settleMs = settleMs; this.maxScrolls = maxScrolls; this.allowCoordinateFallback = allowCoordinateFallback; }
+  private args(args: string[]): string[] { return this.serial ? ['-s', this.serial, ...args] : args; }
+  run(args: string[], binary = false, timeoutSec = 25): Buffer {
+    const result = spawnSync(this.executable, this.args(args), { timeout: timeoutSec * 1000, maxBuffer: 128 * 1024 * 1024, windowsHide: true }) as SpawnSyncReturns<Buffer>;
+    if (result.error) throw new Error(`adb ${args.join(' ')} failed: ${result.error.message}`);
+    if (result.status !== 0) { const detail = (result.stderr ?? Buffer.alloc(0)).toString('utf-8').trim(); throw new Error(`adb ${args.join(' ')} exited ${result.status}${detail ? `: ${detail}` : ''}`); }
+    const output = result.stdout ?? Buffer.alloc(0); return binary ? output : Buffer.from(output.toString('utf-8').trim(), 'utf-8');
+  }
+  text(args: string[], timeoutSec = 25): string { return this.run(args, false, timeoutSec).toString('utf-8'); }
+  shell(args: string[], timeoutSec = 25): string { return this.text(['shell', ...args], timeoutSec); }
+  selectDevice(): void {
+    const online = this.text(['devices']).split(/\r?\n/).slice(1).map((l) => l.trim()).filter((l) => /\sdevice(?:\s|$)/.test(l)).map((l) => l.split(/\s+/)[0]);
+    if (!online.length) throw new Error('no online ADB device'); if (this.serial && !online.includes(this.serial)) throw new Error(`ADB device is not online: ${this.serial}`); if (!this.serial) this.serial = online[0];
+  }
+  launch(pkg: string): void { this.shell(['pm', 'path', pkg]); this.shell(['am', 'force-stop', pkg]); this.shell(['monkey', '-p', pkg, '-c', 'android.intent.category.LAUNCHER', '1']); sleep(this.settleMs); }
+  dumpXml(): string { const remote = '/sdcard/d2h_utg_ai_window.xml'; this.shell(['uiautomator', 'dump', remote], 30); const xml = this.shell(['cat', remote], 20); if (!xml.includes('<hierarchy')) throw new Error('uiautomator dump did not return a hierarchy'); return xml; }
+  activityInfo(): Record<string, string> { return { current_focus: this.shell(['dumpsys', 'window', 'displays']).split(/\r?\n/).find((l) => l.includes('mCurrentFocus'))?.trim() ?? '', resumed_activity: this.shell(['dumpsys', 'activity', 'activities']).split(/\r?\n/).find((l) => /ResumedActivity|topResumedActivity/.test(l))?.trim() ?? '' }; }
+  packageInfo(pkg: string): JsonObject { const raw = this.shell(['dumpsys', 'package', pkg], 30); return { version_name: /versionName=([^\s]+)/.exec(raw)?.[1] ?? '', version_code: /versionCode=(\d+)/.exec(raw)?.[1] ?? '', raw_excerpt: raw.split(/\r?\n/).filter((l) => /version(Name|Code)=|codePath=/.test(l)).slice(0, 6) }; }
+  deviceInfo(): JsonObject {
+    const densityRaw = this.shell(['wm', 'density']), sizeRaw = this.shell(['wm', 'size']); const od = /Override density:\s*(\d+)/.exec(densityRaw), pd = /Physical density:\s*(\d+)/.exec(densityRaw); const dpi = Number((od ?? pd)?.[1] ?? 0) || null;
+    const os = /Override size:\s*(\d+)x(\d+)/.exec(sizeRaw), ps = /Physical size:\s*(\d+)x(\d+)/.exec(sizeRaw), size = os ?? ps; if (size) this.screen = { width: Number(size[1]), height: Number(size[2]) };
+    return { serial: this.serial, dpi, density: dpi === null ? null : Math.round((dpi / 160) * 1000) / 1000, density_source: dpi === null ? 'unavailable' : od ? 'wm density (override)' : 'wm density (physical)', width_px: size ? Number(size[1]) : null, height_px: size ? Number(size[2]) : null, locale: this.shell(['getprop', 'persist.sys.locale']), raw: { wm_density: densityRaw, wm_size: sizeRaw } };
+  }
+  swipe(direction = 'up', distance = 0.45, durationMs = 350, bounds?: string): void {
+    const nums = bounds?.match(/\d+/g)?.map(Number) ?? [0, 0, this.screen.width, this.screen.height]; const [x1, y1, x2, y2] = nums.length === 4 ? nums : [0, 0, this.screen.width, this.screen.height];
+    const cx = Math.trunc((x1 + x2) / 2), cy = Math.trunc((y1 + y2) / 2), dx = Math.trunc((x2 - x1) * Math.min(Math.max(distance, .1), .8)), dy = Math.trunc((y2 - y1) * Math.min(Math.max(distance, .1), .8));
+    const points: Record<string, [number, number, number, number]> = { up: [cx, Math.min(y2 - 10, cy + dy / 2), cx, Math.max(y1 + 10, cy - dy / 2)], down: [cx, Math.max(y1 + 10, cy - dy / 2), cx, Math.min(y2 - 10, cy + dy / 2)], left: [Math.min(x2 - 10, cx + dx / 2), cy, Math.max(x1 + 10, cx - dx / 2), cy], right: [Math.max(x1 + 10, cx - dx / 2), cy, Math.min(x2 - 10, cx + dx / 2), cy] };
+    if (!(direction in points)) throw new Error(`unsupported swipe direction: ${direction}`); this.shell(['input', 'swipe', ...points[direction].map((v) => String(Math.trunc(v))), String(durationMs)]); sleep(this.settleMs);
+  }
+  findTarget(step: PlanStep): { target: UiNode; semantic: UiNode; score: number; scrolls: number } | null {
+    const limit = step.max_scrolls ?? this.maxScrolls;
+    for (let attempt = 0; attempt <= limit; attempt += 1) {
+      const nodes = flatten(parseUiTree(this.dumpXml())); const candidates = nodes.map((semantic) => ({ semantic, target: clickableTarget(semantic), score: semanticScore(semantic, step.selector, step.label ?? null) })).filter((i) => i.score >= 0 && i.target.center !== null);
+      const dedup = new Map<string, typeof candidates[number]>(); for (const item of candidates) if (!dedup.has(item.target.bounds) || dedup.get(item.target.bounds)!.score < item.score) dedup.set(item.target.bounds, item);
+      const ranked = [...dedup.values()].sort((a, b) => b.score - a.score);
+      if (ranked.length) { if (ranked.length > 1 && ranked[0].score === ranked[1].score && ranked[0].target.bounds !== ranked[1].target.bounds) throw new Error(`multiple clickable targets equally match ${JSON.stringify(step.label ?? step.selector ?? '')}`); return { ...ranked[0], scrolls: attempt }; }
+      if (attempt < limit) { const area = (n: UiNode): number => { const v = n.bounds.match(/\d+/g)?.map(Number) ?? []; return v.length === 4 ? (v[2] - v[0]) * (v[3] - v[1]) : 0; }; const scrollable = nodes.filter((n) => n.scrollable && n.center).sort((a, b) => area(b) - area(a))[0]; this.swipe('up', .5, 350, scrollable?.bounds); }
+    }
+    return null;
+  }
+  replay(step: PlanStep): JsonObject {
+    const action = String(step.action ?? 'tap').toLocaleLowerCase();
+    if (['launch', 'default', 'noop', 'none'].includes(action)) return { action, status: 'no-op' };
+    if (action === 'start-activity') {
+      if (!/^[\w.]+\/[\w.$]+$/.test(step.component ?? '')) throw new Error('start-activity requires a source-proven component');
+      this.shell(['am', 'start', '-n', step.component!]); sleep(this.settleMs);
+      return { action, status: 'ok', component: step.component };
+    }
+    if (['back', 'navigate-back'].includes(action)) { this.shell(['input', 'keyevent', 'KEYCODE_BACK']); sleep(this.settleMs); return { action, status: 'ok' }; }
+    if (action === 'home') { this.shell(['input', 'keyevent', 'KEYCODE_HOME']); sleep(this.settleMs); return { action, status: 'ok' }; }
+    if (action === 'swipe') { this.swipe(step.direction ?? 'up', step.distance ?? .45, step.duration_ms ?? 350); return { action, status: 'ok', direction: step.direction ?? 'up' }; }
+    if (['deep-link', 'deeplink', 'app-link'].includes(action)) { const uri = step.label; if (!uri || !/^[a-z][a-z0-9+.-]*:/i.test(uri)) throw new Error(`deep-link step has no URI: ${step.target_id ?? ''}`); this.shell(['am', 'start', '-a', 'android.intent.action.VIEW', '-d', uri]); sleep(this.settleMs); return { action, status: 'ok', uri }; }
+    const isLong = ['long-press', 'longpress', 'long-tap'].includes(action); if (!(isLong || ['tap', 'click', 'open', 'navigate', 'select'].includes(action))) throw new Error(`unsupported deterministic ADB action: ${action}`);
+    if (step.label_ambiguous) throw new Error(`ambiguous label cannot be replayed safely: ${step.label ?? step.target_id ?? ''}`); const explicit = step.selector && Object.keys(step.selector).length > 0;
+    if (!step.label && !explicit) throw new Error(`ADB ${action} step has no deterministic selector: ${step.target_id ?? ''}; nl_hint is not executable`);
+    const found = this.findTarget(step); let center: [number, number], bounds = ''; let matched: JsonObject = {};
+    if (found) { center = found.target.center!; bounds = found.target.bounds; matched = { semantic_bounds: found.semantic.bounds, text: found.semantic.text, content_desc: found.semantic.desc, resource_id: found.semantic.rid, scrolls: found.scrolls }; }
+    else if (step.selector?.normalized_point) { if (!this.allowCoordinateFallback) throw new Error('normalized_point selector requires --allow-coordinate-fallback'); const [nx, ny] = step.selector.normalized_point; if (!(nx >= 0 && nx <= 1 && ny >= 0 && ny <= 1)) throw new Error('normalized_point values must be in [0,1]'); center = [Math.round(nx * this.screen.width), Math.round(ny * this.screen.height)]; matched = { normalized_point: [nx, ny] }; }
+    else throw new Error(`no UIAutomator target matches ${JSON.stringify(step.selector ?? step.label)}`);
+    const [x, y] = center; if (isLong) this.shell(['input', 'swipe', String(x), String(y), String(x), String(y), '1000']); else this.shell(['input', 'tap', String(x), String(y)]); sleep(this.settleMs);
+    return { action, status: 'ok', selector: step.selector ?? step.label, bounds, center, matched };
+  }
+  screenshot(): Buffer { const raw = this.run(['exec-out', 'screencap', '-p'], true, 30), magic = Buffer.from([0x89, 0x50, 0x4e, 0x47]), at = raw.indexOf(magic); if (at < 0) throw new Error('adb screencap output contains no PNG'); return raw.subarray(at); }
+}
+
+function parseArgs(argv: string[]): CliArgs {
+  const args: CliArgs = { pageJson: '', outputWorkspace: '', packageName: '', device: null, adbPath: 'adb', only: null, satisfiedState: new Set(), dryRun: false, allowPartial: false, allowCoordinateFallback: false, settleMs: 800, maxScrolls: 4 };
+  for (let i = 0; i < argv.length; i += 1) {
+    const flag = argv[i], next = (): string => { if (i + 1 >= argv.length) throw new Error(`missing value for ${flag}`); return argv[++i]; };
+    if (flag === '--page-json') args.pageJson = next(); else if (flag === '--output-workspace') args.outputWorkspace = next(); else if (flag === '--package') args.packageName = next(); else if (flag === '--device') args.device = next(); else if (flag === '--adb-path') args.adbPath = next();
+    else if (flag === '--only') args.only = new Set(next().split(',').map((v) => v.trim()).filter(Boolean)); else if (flag === '--satisfied-state') args.satisfiedState = new Set(next().split(',').map((v) => v.trim()).filter(Boolean));
+    else if (flag === '--settle-ms') args.settleMs = Number.parseInt(next(), 10); else if (flag === '--max-scrolls') args.maxScrolls = Number.parseInt(next(), 10); else if (flag === '--dry-run') args.dryRun = true; else if (flag === '--allow-partial') args.allowPartial = true; else if (flag === '--allow-coordinate-fallback') args.allowCoordinateFallback = true;
+    else if (flag === '--help' || flag === '-h') { console.log('Usage: node capture_from_page_json.ts --page-json <page.json> --output-workspace <dir> [--package <pkg>] [--device <serial>] [--adb-path <adb>] [--only <id,...>] [--satisfied-state <kind,...>] [--max-scrolls 4] [--settle-ms 800] [--allow-coordinate-fallback] [--dry-run] [--allow-partial]'); process.exit(0); }
+    else throw new Error(`unknown argument: ${flag}`);
+  }
+  if (!args.pageJson || !args.outputWorkspace) throw new Error('--page-json and --output-workspace are required'); if (!Number.isFinite(args.settleMs) || args.settleMs < 0 || !Number.isInteger(args.maxScrolls) || args.maxScrolls < 0) throw new Error('--settle-ms/--max-scrolls must be non-negative integers'); return args;
+}
+function requiredStates(page: PlanPage): string[] { return [...new Set([...page.required_state, ...page.steps.map((s) => s.guard?.kind).filter((v): v is string => Boolean(v))])]; }
+function replaceCaptureDir(temp: string, finalDir: string): void {
+  const backup = `${finalDir}.previous.${process.pid}`; if (fs.existsSync(backup)) fs.rmSync(backup, { recursive: true, force: true }); if (fs.existsSync(finalDir)) fs.renameSync(finalDir, backup);
+  try { fs.renameSync(temp, finalDir); if (fs.existsSync(backup)) fs.rmSync(backup, { recursive: true, force: true }); } catch (error) { if (!fs.existsSync(finalDir) && fs.existsSync(backup)) fs.renameSync(backup, finalDir); throw error; }
+}
+function main(): number {
+  const args = parseArgs(process.argv.slice(2)), planFile = path.resolve(args.pageJson), plan = validatePlan(planFile, readJson(planFile)), eligible = plan.pages.filter((p) => p.capture);
+  if (args.only) { const known = new Set(eligible.map((p) => p.node_id)), missing = [...args.only].filter((id) => !known.has(id)); if (missing.length) throw new Error(`--only contains nodes not eligible for capture: ${missing.join(', ')}`); }
+  const selected = eligible.filter((p) => args.only === null || args.only.has(p.node_id)); if (!selected.length && !args.dryRun) throw new Error('page.json selects no runtime pages');
+  const packageName = args.packageName || plan.source.package; if (!packageName) throw new Error('Android package is missing; pass --package or set graph.package');
+  const preview = { page_json: planFile, output_workspace: path.resolve(args.outputWorkspace), package: packageName, expected_version: plan.source.version_name, capture_mode: 'adb-deterministic-replay', selected_count: selected.length, nodes: selected.map((p) => p.node_id), required_states: Object.fromEntries(selected.map((p) => [p.node_id, requiredStates(p)])) };
+  if (args.dryRun) { console.log(JSON.stringify(preview, null, 2)); return 0; }
+  const workspace = path.resolve(args.outputWorkspace); fs.mkdirSync(workspace, { recursive: true }); const adb = new Adb(args.adbPath, args.device, args.settleMs, args.maxScrolls, args.allowCoordinateFallback); adb.selectDevice();
+  const deviceInfo = adb.deviceInfo(), packageInfo = adb.packageInfo(packageName); if (plan.source.version_name && packageInfo.version_name !== plan.source.version_name) throw new Error(`installed package version ${String(packageInfo.version_name)} does not match analyzed source version ${plan.source.version_name}`);
+  const selectedIds = new Set(selected.map((p) => p.node_id)), outcomes = new Map<string, JsonObject>(), runId = `${new Date().toISOString().replace(/[:.]/g, '-')}-${randomUUID().slice(0, 8)}`;
+  for (const page of selected) {
+    const trace: JsonObject[] = [], missingState = requiredStates(page).filter((s) => !args.satisfiedState.has(s)); if (missingState.length) { outcomes.set(page.node_id, { node_id: page.node_id, status: 'blocked', reason: `state requirements not asserted: ${missingState.join(', ')}`, required_state: missingState }); continue; }
+    let tempDir = '';
+    try {
+      adb.launch(packageName); for (const step of page.steps) trace.push(adb.replay(step)); const activity = adb.activityInfo(); if (!Object.values(activity).some((v) => v.includes(packageName))) throw new Error(`target package is not foreground after replay: ${packageName}`);
+      const xml = adb.dumpXml(), verified = verification(page.expected, xml, activity); if (!verified.ok) throw new Error(`${verified.reason}: ${JSON.stringify(verified.checks)}`); const screenshot = adb.screenshot();
+      tempDir = fs.mkdtempSync(path.join(workspace, `._capture_${page.capture_key}_`)); fs.writeFileSync(path.join(tempDir, 'screenshot.png'), screenshot); fs.writeFileSync(path.join(tempDir, 'view.xml'), xml, 'utf-8');
+      atomicWriteJson(path.join(tempDir, 'meta.json'), { schema_version: 'd2h-adb-page-capture/v2', run_id: runId, node_id: page.node_id, label: page.label, kind: page.kind, capture_mode: 'adb-deterministic-replay', captured_at: new Date().toISOString(), breadcrumb: page.path_text, ui_sequence: page.ui_sequence, required_state: requiredStates(page), expected: page.expected, verification: verified, screenshot: `${page.capture_key}/screenshot.png`, screenshots: [`${page.capture_key}/screenshot.png`], view_xml: `${page.capture_key}/view.xml`, view_xmls: [`${page.capture_key}/view.xml`], activity_info: activity, device_info: deviceInfo, package_info: packageInfo, replay_trace: trace });
+      const finalDir = path.join(workspace, page.capture_key!); replaceCaptureDir(tempDir, finalDir); tempDir = ''; outcomes.set(page.node_id, { node_id: page.node_id, status: 'captured', page_dir: finalDir, verification: verified, screenshot: path.join(finalDir, 'screenshot.png'), view_tree: path.join(finalDir, 'view.xml'), metadata: path.join(finalDir, 'meta.json') });
+    } catch (error) { if (tempDir && fs.existsSync(tempDir)) fs.rmSync(tempDir, { recursive: true, force: true }); const stale = page.capture_key ? path.join(workspace, page.capture_key) : ''; outcomes.set(page.node_id, { node_id: page.node_id, status: 'failed', reason: error instanceof Error ? error.message : String(error), replay_trace: trace, ...(stale && fs.existsSync(stale) ? { stale_artifact_dir: stale } : {}) }); }
+  }
+  const results: JsonObject[] = [], counts = { captured: 0, failed: 0, blocked: 0, skipped: 0, not_requested: 0 };
+  for (const page of plan.pages) { let result: JsonObject; if (!page.capture) result = { node_id: page.node_id, status: 'skipped', reason: page.skip_reason }; else if (!selectedIds.has(page.node_id)) result = { node_id: page.node_id, status: 'not_requested' }; else result = outcomes.get(page.node_id)!; counts[result.status as keyof typeof counts] += 1; results.push(result); }
+  const capturedPages = selected.filter((p) => outcomes.get(p.node_id)?.status === 'captured').map((p) => ({ page_dir: String(outcomes.get(p.node_id)!.page_dir), ui_sequence: p.ui_sequence })); atomicWriteJson(path.join(workspace, 'pages.json'), { run_id: runId, pages: capturedPages });
+  const report = { schema_version: 'd2h-page-capture-report/v2', run_id: runId, status: counts.failed === 0 && counts.blocked === 0 ? 'complete' : 'partial', capture_mode: 'adb-deterministic-replay', workspace, device: adb.serial, device_info: deviceInfo, package_info: packageInfo, summary: counts, pages: results }; atomicWriteJson(path.join(workspace, 'capture-report.json'), report);
+  console.log(JSON.stringify(counts)); console.log(path.join(workspace, 'capture-report.json')); return (counts.failed > 0 || counts.blocked > 0) && !args.allowPartial ? 1 : 0;
+}
+try { process.exitCode = main(); } catch (error) { console.error(`ERROR: ${error instanceof Error ? error.message : error}`); process.exitCode = 2; }