ui-design-workbench-cli 0.5.0__py3-none-any.whl

ui_design_workbench_cli-0.5.0.data/data/share/ui-design-workbench/scripts/generate_interaction_matrix.py

@@ -0,0 +1,166 @@
+#!/usr/bin/env python3
+"""Generate a bounded interaction/state scenario plan from UI IR actions and states."""
+
+from __future__ import annotations
+
+import argparse
+import copy
+import re
+import sys
+from collections import defaultdict
+from pathlib import Path
+from typing import Any
+
+from quality_common import node_screen_map, profile_catalog, read_json, target_families, write_json
+
+
+def slug(value: str) -> str:
+    return re.sub(r"[^a-z0-9]+", "-", value.lower()).strip("-") or "item"
+
+
+def action_step(node_id: str, action: dict[str, Any]) -> dict[str, Any]:
+    return {
+        "type": "activate",
+        "nodeId": node_id,
+        "actionType": action.get("type"),
+        "target": action.get("target"),
+        "state": action.get("state"),
+        "offState": action.get("offState"),
+    }
+
+
+def expected_for(action: dict[str, Any]) -> list[str]:
+    kind = action.get("type")
+    if kind == "navigate":
+        return [f"active screen becomes {action.get('target')}", "browser history and screen tree agree"]
+    if kind == "back":
+        return ["previous reachable screen is restored", "focus returns predictably"]
+    if kind in {"toggle", "toggle-node-state"}:
+        return [f"target alternates between {action.get('state')} and {action.get('offState', 'default')}", "visible and semantic state stay synchronized"]
+    if kind == "set-node-state":
+        return [f"target state becomes {action.get('state')}", "dependent controls and visible values agree"]
+    if kind == "reset-state":
+        return ["affected state returns to its declared default", "visible value and internal state agree"]
+    return ["declared action produces visible feedback", "focus and geometry remain valid"]
+
+
+def build_matrix(ir: dict[str, Any], max_pairs: int = 24) -> dict[str, Any]:
+    nodes = ir.get("nodes", {})
+    screen_map = node_screen_map(ir)
+    by_screen: dict[str, list[tuple[str, dict[str, Any]]]] = defaultdict(list)
+    scenarios: list[dict[str, Any]] = []
+
+    for node_id, node in sorted(nodes.items()):
+        action = node.get("action") if isinstance(node.get("action"), dict) else {}
+        if not action.get("type"):
+            continue
+        screens = sorted(screen_map.get(str(node_id), [])) or [None]
+        for screen_id in screens:
+            by_screen[str(screen_id or "global")].append((str(node_id), action))
+            base = f"{screen_id or 'global'}-{node_id}-{action['type']}"
+            step = action_step(str(node_id), action)
+            scenarios.append({
+                "id": f"single-{slug(base)}",
+                "kind": "single",
+                "screenId": screen_id,
+                "nodeIds": [node_id],
+                "startState": "declared default",
+                "steps": [step],
+                "assertions": expected_for(action) + ["no clipping, overlap, or unexpected scroll jump"],
+            })
+            scenarios.append({
+                "id": f"repeat-{slug(base)}",
+                "kind": "repeated",
+                "screenId": screen_id,
+                "nodeIds": [node_id],
+                "startState": "declared default",
+                "steps": [step, step],
+                "assertions": expected_for(action) + ["second activation is deterministic and does not duplicate transient UI"],
+            })
+            if action.get("type") in {"toggle", "toggle-node-state", "set-node-state", "reset-state"}:
+                scenarios.append({
+                    "id": f"reverse-{slug(base)}",
+                    "kind": "reverse",
+                    "screenId": screen_id,
+                    "nodeIds": [node_id, str(action.get("target") or node_id)],
+                    "startState": "declared default",
+                    "steps": [step, {"type": "reverse-or-reset", "nodeId": node_id, "target": action.get("target")}],
+                    "assertions": ["initial visible, semantic, and geometry state is restored", "no stale labels, pressed states, or dependent values remain"],
+                })
+
+    pair_count = 0
+    for screen_id, controls in sorted(by_screen.items()):
+        for index, first in enumerate(controls):
+            for second in controls[index + 1:]:
+                if pair_count >= max_pairs:
+                    break
+                first_id, first_action = first
+                second_id, second_action = second
+                scenarios.append({
+                    "id": f"chain-{slug(screen_id)}-{slug(first_id)}-{slug(second_id)}",
+                    "kind": "chained",
+                    "screenId": None if screen_id == "global" else screen_id,
+                    "nodeIds": [first_id, second_id],
+                    "startState": "declared default",
+                    "steps": [action_step(first_id, first_action), action_step(second_id, second_action)],
+                    "assertions": ["the second control resolves or composes with the first state", "only one mutually exclusive surface remains open", "focus, history, visible values, and geometry remain consistent"],
+                })
+                pair_count += 1
+            if pair_count >= max_pairs:
+                break
+
+    for node_id, node in sorted(nodes.items()):
+        if node.get("type") != "input" or node.get("inputType") != "range":
+            continue
+        semantics = node.get("semantics", {})
+        minimum = node.get("min", semantics.get("min", 0))
+        maximum = node.get("max", semantics.get("max", 100))
+        midpoint = (minimum + maximum) / 2 if isinstance(minimum, (int, float)) and isinstance(maximum, (int, float)) else None
+        scenarios.append({
+            "id": f"boundary-{slug(str(node_id))}",
+            "kind": "boundary",
+            "screenId": next(iter(sorted(screen_map.get(str(node_id), []))), None),
+            "nodeIds": [node_id],
+            "startState": "declared default",
+            "steps": [{"type": "set-value", "nodeId": node_id, "value": value} for value in (minimum, midpoint, maximum) if value is not None],
+            "assertions": ["visible value matches the control value at min, midpoint, and max", "dependent geometry remains inside scroll bounds"],
+        })
+
+    profiles = profile_catalog().get("profiles", {})
+    required_states = sorted({state for profile in profiles.values() if profile.get("family") in target_families(ir) for state in profile.get("requiredInteractionStates", [])})
+    workbench = [
+        {"id": "workbench-zoom-cycle", "kind": "workbench", "steps": ["Fit", "20%", "100%", "200%", "Reset"], "assertions": ["one scale state drives geometry and label", "no card reflow or overlap", "scroll bounds match scaled canvas"]},
+        {"id": "workbench-menu-exclusivity", "kind": "workbench", "steps": ["open each menu", "click outside", "Escape", "change view"], "assertions": ["at most one menu is open", "focus returns to its trigger"]},
+        {"id": "workbench-panel-continuity", "kind": "workbench", "steps": ["select node", "resize panel", "hide panel", "restore panel", "change viewport"], "assertions": ["selection and scroll are preserved", "compact panels are mutually exclusive"]},
+    ]
+    return {
+        "version": 1,
+        "status": "ready" if scenarios else "empty",
+        "source": {"screens": len(ir.get("screens", [])), "actionNodes": sum(1 for node in nodes.values() if node.get("action", {}).get("type"))},
+        "requiredPlatformStates": required_states,
+        "scenarioCount": len(scenarios) + len(workbench),
+        "scenarios": scenarios + workbench,
+        "limits": {"maxCrossControlPairs": max_pairs, "generatedCrossControlPairs": pair_count},
+    }
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("ir", help="Path to ui-ir.json")
+    parser.add_argument("--output", required=True, help="Path for ui-interaction-matrix.json")
+    parser.add_argument("--merge-output", help="Optional new IR containing review.scenarioPlan")
+    parser.add_argument("--max-pairs", type=int, default=24, help="Maximum generated cross-control pairs")
+    args = parser.parse_args()
+    ir = read_json(args.ir)
+    matrix = build_matrix(ir, max(0, args.max_pairs))
+    write_json(args.output, matrix)
+    if args.merge_output:
+        merged = copy.deepcopy(ir)
+        merged.setdefault("review", {})["scenarioPlan"] = matrix
+        write_json(args.merge_output, merged)
+    print(f"Interaction matrix: {matrix['scenarioCount']} scenarios")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

ui_design_workbench_cli-0.5.0.data/data/share/ui-design-workbench/scripts/ir_contracts.py

@@ -0,0 +1,76 @@
+#!/usr/bin/env python3
+"""Canonical interaction and navigation contracts shared by UIDW stages."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+INTERACTION_CONTRACT_VERSION = 1
+DIAGNOSTICS_ENGINE_VERSION = 3
+
+NATIVE_INTERACTIVE_NODE_TYPES = frozenset({"button", "input"})
+INTERACTIVE_SEMANTIC_ROLES = frozenset(
+    {
+        "button",
+        "checkbox",
+        "combobox",
+        "gridcell",
+        "link",
+        "menuitem",
+        "option",
+        "radio",
+        "searchbox",
+        "slider",
+        "spinbutton",
+        "switch",
+        "tab",
+        "textbox",
+        "treeitem",
+    }
+)
+SUPPORTED_ACTION_TYPES = frozenset(
+    {
+        "navigate",
+        "back",
+        "set-node-state",
+        "toggle-node-state",
+        "toggle",
+        "reset-state",
+    }
+)
+
+
+def interaction_contract(node: dict[str, Any]) -> dict[str, Any]:
+    """Return the only supported interpretation of a node's interactivity."""
+
+    node_type = str(node.get("type", "")).strip().lower()
+    action_type = str(node.get("action", {}).get("type", "")).strip()
+    semantic_role = str(node.get("semantics", {}).get("role", "")).strip().lower()
+    sources: list[str] = []
+    if node_type in NATIVE_INTERACTIVE_NODE_TYPES:
+        sources.append("native-node")
+    if action_type in SUPPORTED_ACTION_TYPES:
+        sources.append("action")
+    if semantic_role in INTERACTIVE_SEMANTIC_ROLES:
+        sources.append("semantic-role")
+    return {
+        "version": INTERACTION_CONTRACT_VERSION,
+        "interactive": bool(sources),
+        "sources": sources,
+        "nodeType": node_type,
+        "actionType": action_type,
+        "semanticRole": semantic_role,
+        "keyboardExpected": bool(sources),
+    }
+
+
+def browser_interaction_contract() -> dict[str, Any]:
+    """Serializable constants embedded into the standalone workbench."""
+
+    return {
+        "version": INTERACTION_CONTRACT_VERSION,
+        "nativeNodeTypes": sorted(NATIVE_INTERACTIVE_NODE_TYPES),
+        "semanticRoles": sorted(INTERACTIVE_SEMANTIC_ROLES),
+        "actionTypes": sorted(SUPPORTED_ACTION_TYPES),
+    }

ui_design_workbench_cli-0.5.0.data/data/share/ui-design-workbench/scripts/merge_review_state.py

@@ -0,0 +1,267 @@
+#!/usr/bin/env python3
+"""Merge exported HTML review feedback into UI IR without touching app source."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+
+ALLOWED_STATUSES = {"new", "in-progress", "proposed", "accepted", "rejected", "resolved"}
+FIX_REQUEST_TYPES = {"ui-design-workbench-fix-request", "ui-code-preview-fix-request"}
+ALLOWED_DECISIONS = {"pending", "accepted", "rejected"}
+ALLOWED_FINDING_DECISIONS = {"accepted", "rejected", "deferred"}
+ALLOWED_SEVERITIES = {"blocker", "high", "medium", "low"}
+ALLOWED_CONFIDENCE = {"high", "medium", "low"}
+ALLOWED_EFFORT = {"small", "medium", "large"}
+ALLOWED_EVIDENCE = {
+    "requirement", "user-feedback", "research", "analytics", "source",
+    "project-pattern", "platform-standard", "accessibility-standard", "heuristic",
+}
+
+
+def load_object(path: Path, label: str) -> dict[str, Any]:
+    try:
+        value = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as exc:
+        raise ValueError(f"Cannot read {label}: {exc}") from exc
+    if not isinstance(value, dict):
+        raise ValueError(f"{label} must be a JSON object")
+    return value
+
+
+def validate_runtime_findings(
+    runtime_findings: Any,
+    *,
+    nodes: dict[str, Any],
+    screen_ids: set[Any],
+    existing_ids: set[Any],
+) -> tuple[list[str], set[str]]:
+    errors: list[str] = []
+    valid_ids: set[str] = set()
+    if runtime_findings is None:
+        return errors, valid_ids
+    if not isinstance(runtime_findings, list):
+        return ["Feedback runtimeFindings must be an array"], valid_ids
+    required = (
+        "id", "title", "category", "severity", "confidence", "screenId",
+        "observation", "impact", "recommendation", "effort",
+    )
+    for index, finding in enumerate(runtime_findings):
+        if not isinstance(finding, dict):
+            errors.append(f"runtimeFindings[{index}] must be an object")
+            continue
+        finding_id = finding.get("id")
+        for field in required:
+            if not finding.get(field):
+                errors.append(f"runtimeFindings[{index}] is missing {field}")
+        if finding_id in existing_ids or finding_id in valid_ids:
+            errors.append(f"Duplicate runtime finding id: {finding_id}")
+        elif finding_id:
+            valid_ids.add(finding_id)
+        if finding.get("severity") not in ALLOWED_SEVERITIES:
+            errors.append(f"Runtime finding {finding_id} has invalid severity")
+        if finding.get("confidence") not in ALLOWED_CONFIDENCE:
+            errors.append(f"Runtime finding {finding_id} has invalid confidence")
+        if finding.get("effort") not in ALLOWED_EFFORT:
+            errors.append(f"Runtime finding {finding_id} has invalid effort")
+        if finding.get("screenId") not in screen_ids:
+            errors.append(f"Runtime finding {finding_id} references a missing screen")
+        if finding.get("nodeId") and finding.get("nodeId") not in nodes:
+            errors.append(f"Runtime finding {finding_id} references a missing node")
+        if not finding.get("proposalVersionId") and not finding.get("noProposalReason"):
+            errors.append(f"Runtime finding {finding_id} needs noProposalReason")
+        evidence = finding.get("evidence")
+        if not isinstance(evidence, list) or not evidence:
+            errors.append(f"Runtime finding {finding_id} needs evidence")
+        else:
+            for evidence_index, item in enumerate(evidence):
+                if (
+                    not isinstance(item, dict)
+                    or item.get("type") not in ALLOWED_EVIDENCE
+                    or not item.get("ref")
+                    or not item.get("note")
+                ):
+                    errors.append(
+                        f"Runtime finding {finding_id} has invalid evidence[{evidence_index}]"
+                    )
+    return errors, valid_ids
+
+
+def validate_feedback(ir: dict[str, Any], feedback: dict[str, Any]) -> list[str]:
+    errors: list[str] = []
+    review = ir.get("review", {})
+    nodes = ir.get("nodes", {})
+    screen_ids = {item.get("id") for item in ir.get("screens", [])}
+    version_ids = {item.get("id") for item in review.get("versions", [])}
+    if feedback.get("version") not in {1, 2, 3}:
+        errors.append("Feedback version must be 1, 2, or 3")
+    if review.get("sessionId") and feedback.get("sessionId") != review.get("sessionId"):
+        errors.append("Feedback sessionId does not match this IR review session")
+    if feedback.get("activeVersion") not in version_ids:
+        errors.append("Feedback activeVersion is not present in the IR")
+    if feedback.get("versionDecision", "pending") not in ALLOWED_DECISIONS:
+        errors.append("Feedback versionDecision is invalid")
+    finding_ids = {
+        item.get("id") for item in review.get("audit", {}).get("findings", [])
+        if isinstance(item, dict) and item.get("id")
+    }
+    runtime_errors, runtime_finding_ids = validate_runtime_findings(
+        feedback.get("runtimeFindings", []),
+        nodes=nodes,
+        screen_ids=screen_ids,
+        existing_ids=finding_ids,
+    )
+    errors.extend(runtime_errors)
+    finding_ids.update(runtime_finding_ids)
+    finding_decisions = feedback.get("findingDecisions", {})
+    if not isinstance(finding_decisions, dict):
+        errors.append("Feedback findingDecisions must be an object")
+    else:
+        for finding_id, decision in finding_decisions.items():
+            if finding_id not in finding_ids:
+                errors.append(f"Feedback references missing finding {finding_id}")
+            if decision not in ALLOWED_FINDING_DECISIONS:
+                errors.append(f"Finding {finding_id} has invalid decision {decision}")
+    diagnostics = feedback.get("diagnostics")
+    if diagnostics is not None:
+        if not isinstance(diagnostics, dict):
+            errors.append("Feedback diagnostics must be an object or null")
+        else:
+            if diagnostics.get("version") not in {1, 2}:
+                errors.append("Feedback diagnostics version must be 1 or 2")
+            if diagnostics.get("status") != "complete":
+                errors.append("Feedback diagnostics status must be complete")
+            if not isinstance(diagnostics.get("summary"), dict):
+                errors.append("Feedback diagnostics summary must be an object")
+            if not isinstance(diagnostics.get("checks"), list):
+                errors.append("Feedback diagnostics checks must be an array")
+    annotation_ids: set[str] = set()
+    for index, item in enumerate(feedback.get("annotations", [])):
+        if not isinstance(item, dict):
+            errors.append(f"annotations[{index}] must be an object")
+            continue
+        annotation_id = item.get("id")
+        if not annotation_id:
+            errors.append(f"annotations[{index}] is missing id")
+        elif annotation_id in annotation_ids:
+            errors.append(f"Duplicate annotation id: {annotation_id}")
+        annotation_ids.add(annotation_id or "")
+        if not str(item.get("text", "")).strip():
+            errors.append(f"Annotation {annotation_id} has no text")
+        if item.get("nodeId") and item.get("nodeId") not in nodes:
+            errors.append(f"Annotation {annotation_id} references missing node {item.get('nodeId')}")
+        if item.get("screenId") and item.get("screenId") not in screen_ids:
+            errors.append(f"Annotation {annotation_id} references missing screen {item.get('screenId')}")
+        if item.get("versionId") and item.get("versionId") not in version_ids:
+            errors.append(f"Annotation {annotation_id} references missing version {item.get('versionId')}")
+        if item.get("status", "new") not in ALLOWED_STATUSES:
+            errors.append(f"Annotation {annotation_id} has invalid status {item.get('status')}")
+    return errors
+
+
+def validate_fix_request(ir: dict[str, Any], request: dict[str, Any]) -> list[str]:
+    if request.get("type") not in FIX_REQUEST_TYPES:
+        return []
+    errors: list[str] = []
+    accepted = request.get("acceptedFindingIds", [])
+    if request.get("version") not in {1, 2}:
+        errors.append("Fix request version must be 1 or 2")
+    if not isinstance(accepted, list) or not accepted:
+        errors.append("Fix request acceptedFindingIds must be a non-empty array")
+        accepted = []
+    if len(accepted) != len(set(accepted)):
+        errors.append("Fix request acceptedFindingIds contains duplicates")
+    finding_ids = {
+        item.get("id") for item in ir.get("review", {}).get("audit", {}).get("findings", [])
+        if isinstance(item, dict) and item.get("id")
+    }
+    review_feedback = request.get("reviewFeedback", {})
+    finding_ids.update(
+        item.get("id") for item in review_feedback.get("runtimeFindings", [])
+        if isinstance(item, dict) and item.get("id")
+    )
+    decisions = review_feedback.get("findingDecisions", {})
+    for finding_id in accepted:
+        if finding_id not in finding_ids:
+            errors.append(f"Fix request references missing finding {finding_id}")
+        if decisions.get(finding_id) != "accepted":
+            errors.append(f"Fix request finding {finding_id} is not accepted in reviewFeedback")
+    return errors
+
+
+def merge(ir: dict[str, Any], feedback: dict[str, Any]) -> dict[str, Any]:
+    review = ir.setdefault("review", {})
+    audit = review.setdefault("audit", {})
+    merged_findings = {
+        item.get("id"): item for item in audit.get("findings", [])
+        if isinstance(item, dict) and item.get("id")
+    }
+    for item in feedback.get("runtimeFindings", []):
+        merged_findings[item["id"]] = item
+    if merged_findings:
+        audit["findings"] = list(merged_findings.values())
+    existing = {
+        item.get("id"): item for item in review.get("annotations", [])
+        if isinstance(item, dict) and item.get("id")
+    }
+    for item in feedback.get("annotations", []):
+        existing[item["id"]] = item
+    review["annotations"] = list(existing.values())
+    review["activeVersion"] = feedback["activeVersion"]
+    review["versionDecision"] = feedback.get("versionDecision", "pending")
+    if feedback.get("findingDecisions"):
+        audit["findingDecisions"] = feedback["findingDecisions"]
+    if feedback.get("diagnostics"):
+        review["diagnosticsReport"] = feedback["diagnostics"]
+    review["feedbackExportedAt"] = feedback.get("exportedAt")
+    review["feedbackRevision"] = feedback.get("revision")
+    return ir
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="Merge exported ui-review-state.json or ui-fix-request.json into ui-ir.json.")
+    parser.add_argument("ir", type=Path, help="Existing ui-ir.json")
+    parser.add_argument("feedback", type=Path, help="Exported ui-review-state.json (legacy ui-review-feedback.json is accepted)")
+    parser.add_argument("--output", type=Path, required=True, help="Output IR; use a new file for auditability")
+    return parser.parse_args()
+
+
+def main() -> int:
+    args = parse_args()
+    try:
+        ir = load_object(args.ir, "IR")
+        payload = load_object(args.feedback, "feedback or fix request")
+    except ValueError as exc:
+        print(exc, file=sys.stderr)
+        return 2
+    is_fix_request = payload.get("type") in FIX_REQUEST_TYPES
+    feedback = payload.get("reviewFeedback") if is_fix_request else payload
+    if not isinstance(feedback, dict):
+        print("Fix request reviewFeedback must be an object", file=sys.stderr)
+        return 2
+    errors = validate_feedback(ir, feedback) + validate_fix_request(ir, payload)
+    if errors:
+        for error in errors:
+            print(error, file=sys.stderr)
+        return 2
+    output = args.output.resolve()
+    output.parent.mkdir(parents=True, exist_ok=True)
+    merged = merge(ir, feedback)
+    if is_fix_request:
+        merged.setdefault("review", {})["correctionRequest"] = {
+            "acceptedFindingIds": payload.get("acceptedFindingIds", []),
+            "existingProposalVersionIds": payload.get("existingProposalVersionIds", []),
+            "requestedAction": payload.get("requestedAction"),
+            "createdAt": payload.get("createdAt"),
+        }
+    output.write_text(json.dumps(merged, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+    print(str(output))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

ui_design_workbench_cli-0.5.0.data/data/share/ui-design-workbench/scripts/native_render_android.py

@@ -0,0 +1,160 @@
+#!/usr/bin/env python3
+"""Read-only Android native-render provider discovery.
+
+Discovery never invokes Gradle, starts an emulator, or edits the target repo.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import os
+import re
+import shutil
+from pathlib import Path
+from typing import Any, Iterator
+
+
+IGNORED_DIRS = {".git", ".gradle", ".idea", ".ui-design-workbench", "build", "dist", "node_modules", "out", "vendor"}
+TEXT_LIMIT = 2 * 1024 * 1024
+FILE_LIMIT = 30000
+
+
+def _relative(path: Path, root: Path) -> str:
+    return path.resolve().relative_to(root.resolve()).as_posix()
+
+
+def _files(root: Path) -> Iterator[Path]:
+    seen = 0
+    for directory, names, files in os.walk(root):
+        names[:] = [name for name in names if name not in IGNORED_DIRS and not name.startswith(".")]
+        for name in files:
+            seen += 1
+            if seen > FILE_LIMIT:
+                return
+            yield Path(directory) / name
+
+
+def _read(path: Path) -> str:
+    try:
+        if path.stat().st_size > TEXT_LIMIT:
+            return ""
+        return path.read_text(encoding="utf-8", errors="replace")
+    except OSError:
+        return ""
+
+
+def _fingerprint(root: Path, files: list[Path]) -> str:
+    digest = hashlib.sha256()
+    for path in sorted(set(files)):
+        try:
+            stat = path.stat()
+        except OSError:
+            continue
+        digest.update(f"{_relative(path, root)}\0{stat.st_size}\0{stat.st_mtime_ns}\n".encode("utf-8"))
+    return digest.hexdigest()
+
+
+def _settings_modules(text: str) -> set[str]:
+    modules: set[str] = set()
+    for match in re.finditer(r"(?ms)^\s*include\s*\((.*?)\)", text):
+        modules.update(re.findall(r"[\"'](:[^\"']+)[\"']", match.group(1)))
+    for match in re.finditer(r"(?m)^\s*include\s+([^\n]+)", text):
+        modules.update(re.findall(r"[\"'](:[^\"']+)[\"']", match.group(1)))
+    return modules
+
+
+def _provider(provider_id: str, configured: bool, reason: str, supports: list[str]) -> dict[str, Any]:
+    return {
+        "id": provider_id,
+        "platform": "android",
+        "status": "configured" if configured else "not-configured",
+        "availableFidelityTier": "native-preview",
+        "supports": supports,
+        "reason": reason,
+        "execution": "explicit-only",
+    }
+
+
+def discover_android(root: Path) -> dict[str, Any]:
+    root = root.resolve()
+    all_files = list(_files(root))
+    settings = [path for path in all_files if path.name in {"settings.gradle", "settings.gradle.kts"}]
+    build_files = [path for path in all_files if path.name in {"build.gradle", "build.gradle.kts", "libs.versions.toml", "gradle.properties"}]
+    manifests = [path for path in all_files if path.name == "AndroidManifest.xml"]
+    kotlin = [path for path in all_files if path.suffix.lower() in {".kt", ".kts"} and path.name not in {"build.gradle.kts", "settings.gradle.kts"}]
+    layouts = [
+        path for path in all_files
+        if path.suffix.lower() == ".xml" and any(part.startswith("layout") for part in path.parts) and "res" in path.parts
+    ]
+    resources = [path for path in all_files if "res" in path.parts and "src" in path.parts]
+    settings_text = {path: _read(path) for path in settings}
+    build_text = {path: _read(path) for path in build_files}
+    combined_build = "\n".join(build_text.values())
+    modules = sorted({module for text in settings_text.values() for module in _settings_modules(text)})
+    android_markers = (
+        "com.android.application",
+        "com.android.library",
+        "com.android.test",
+        "com.android.dynamic-feature",
+        "android {",
+    )
+    detected = bool(manifests or any(marker in combined_build for marker in android_markers))
+    wrapper = next((path for path in (root / "gradlew.bat", root / "gradlew") if path.is_file()), None)
+
+    preview_entries: list[dict[str, Any]] = []
+    compose_function_count = 0
+    screenshot_test_count = 0
+    for path in kotlin:
+        text = _read(path)
+        if not text:
+            continue
+        compose_function_count += len(re.findall(r"@Composable\b", text))
+        screenshot_test_count += len(re.findall(r"(?:Paparazzi|Roborazzi|PreviewTest|captureRoboImage|snapshot\s*\()", text))
+        for match in re.finditer(r"@(?:[\w.]*Preview)\b(?:\s*\([^)]*\))?[\s\S]{0,800}?\bfun\s+(\w+)\s*\(", text):
+            preview_entries.append({"symbol": match.group(1), "file": _relative(path, root)})
+
+    official = "com.android.compose.screenshot" in combined_build or "android.experimental.enableScreenshotTest" in combined_build
+    paparazzi = "app.cash.paparazzi" in combined_build or "paparazzi-gradle-plugin" in combined_build
+    roborazzi = "io.github.takahirom.roborazzi" in combined_build or re.search(r"\broborazzi\b", combined_build, re.I) is not None
+    providers = [
+        _provider("android-compose-screenshot", official, "Official Compose screenshot plugin marker found." if official else "Compose screenshot plugin is not configured.", ["compose"]),
+        _provider("paparazzi", paparazzi, "Paparazzi marker found; Layoutlib capture can run without an emulator." if paparazzi else "Paparazzi is not configured.", ["compose", "views"]),
+        _provider("roborazzi", roborazzi, "Roborazzi marker found." if roborazzi else "Roborazzi is not configured.", ["compose", "views"]),
+    ]
+    sdk_present = bool(os.environ.get("ANDROID_SDK_ROOT") or os.environ.get("ANDROID_HOME"))
+    emulator_ready = bool(detected and wrapper and sdk_present and (shutil.which("emulator") or shutil.which("emulator.exe")))
+    providers.append({
+        "id": "android-emulator",
+        "platform": "android",
+        "status": "configured" if emulator_ready else "available" if detected else "not-applicable",
+        "availableFidelityTier": "device-verified",
+        "supports": ["compose", "views", "runtime-state"],
+        "reason": "Gradle wrapper, Android SDK, and emulator executable are available." if emulator_ready else "Requires an explicit emulator run with a configured SDK and Gradle wrapper.",
+        "execution": "explicit-only",
+    })
+    configured = [provider["id"] for provider in providers if provider["status"] == "configured"]
+    inputs = settings + build_files + manifests + resources + kotlin
+    return {
+        "platform": "android",
+        "status": "detected" if detected else "not-applicable",
+        "sourceFingerprint": _fingerprint(root, inputs),
+        "project": {
+            "gradleWrapper": _relative(wrapper, root) if wrapper else None,
+            "settingsFiles": [_relative(path, root) for path in settings],
+            "modules": modules,
+            "manifestCount": len(manifests),
+            "composeFunctionCount": compose_function_count,
+            "previewEntryCount": len(preview_entries),
+            "layoutResourceCount": len(layouts),
+            "screenshotTestMarkerCount": screenshot_test_count,
+        },
+        "entryPoints": preview_entries[:200],
+        "providers": providers,
+        "recommendedProvider": configured[0] if configured else None,
+        "currentFidelityTier": "structural",
+        "nativeExecutionStarted": False,
+        "limitations": [
+            "Discovery does not execute Gradle or render a screen.",
+            "A configured provider is capability evidence, not visual fidelity evidence.",
+        ],
+    }