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

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),
+    }

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.",
+        ],
+    }

native_render_apple.py

@@ -0,0 +1,165 @@
+#!/usr/bin/env python3
+"""Read-only Apple native-render provider discovery."""
+
+from __future__ import annotations
+
+import hashlib
+import os
+import re
+import shutil
+import sys
+from pathlib import Path
+from typing import Any, Iterator
+
+
+IGNORED_DIRS = {".git", ".build", ".idea", ".ui-design-workbench", "build", "DerivedData", "node_modules", "Pods", "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 _bundles(root: Path) -> tuple[list[Path], list[Path]]:
+    projects: list[Path] = []
+    workspaces: list[Path] = []
+    for directory, names, _ in os.walk(root):
+        names[:] = [name for name in names if name not in IGNORED_DIRS and not name.startswith(".")]
+        current = Path(directory)
+        for name in list(names):
+            path = current / name
+            if name.endswith(".xcodeproj"):
+                projects.append(path)
+                names.remove(name)
+            elif name.endswith(".xcworkspace"):
+                workspaces.append(path)
+                names.remove(name)
+    return projects, workspaces
+
+
+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 discover_apple(root: Path, host_platform: str | None = None) -> dict[str, Any]:
+    root = root.resolve()
+    host = host_platform or sys.platform
+    all_files = list(_files(root))
+    swift_files = [path for path in all_files if path.suffix.lower() == ".swift"]
+    interfaces = [path for path in all_files if path.suffix.lower() in {".storyboard", ".xib"}]
+    package_files = [path for path in all_files if path.name in {"Package.swift", "Package.resolved", "Podfile"}]
+    projects, workspaces = _bundles(root)
+    detected = bool(swift_files or interfaces or projects or workspaces)
+    preview_entries: list[dict[str, Any]] = []
+    snapshot_markers = 0
+    swiftui_views = 0
+    source_inputs: list[Path] = []
+    for path in swift_files:
+        text = _read(path)
+        if not text:
+            continue
+        if "SwiftUI" in text or "#Preview" in text or "PreviewProvider" in text or "SnapshotTesting" in text:
+            source_inputs.append(path)
+        swiftui_views += len(re.findall(r"\bstruct\s+\w+\s*:\s*View\b", text))
+        snapshot_markers += len(re.findall(r"(?:SnapshotTesting|assertSnapshot|iOSSnapshotTestCase|FBSnapshotTestCase)", text))
+        for match in re.finditer(r"#Preview(?:\s*\(\s*[\"']([^\"']+)[\"'][^)]*\))?", text):
+            preview_entries.append({"symbol": match.group(1) or "#Preview", "file": _relative(path, root)})
+        for match in re.finditer(r"\bstruct\s+(\w+)\s*:\s*PreviewProvider\b", text):
+            preview_entries.append({"symbol": match.group(1), "file": _relative(path, root)})
+    package_text = "\n".join(_read(path) for path in package_files)
+    snapshot_configured = snapshot_markers > 0 or "swift-snapshot-testing" in package_text.lower()
+    mac_host = host == "darwin"
+    xcode_ready = bool(mac_host and shutil.which("xcodebuild"))
+    simulator_ready = bool(xcode_ready and shutil.which("xcrun"))
+
+    def status(configured: bool, requires_host: bool = True) -> str:
+        if not detected:
+            return "not-applicable"
+        if requires_host and not mac_host:
+            return "host-required"
+        return "configured" if configured else "not-configured"
+
+    providers = [
+        {
+            "id": "xcode-preview",
+            "platform": "apple",
+            "status": status(bool(preview_entries) and xcode_ready),
+            "availableFidelityTier": "native-preview",
+            "supports": ["swiftui"],
+            "reason": "Xcode and SwiftUI preview entries are available." if preview_entries and xcode_ready else "Requires a macOS Xcode worker and a SwiftUI Preview entry point.",
+            "execution": "explicit-only",
+        },
+        {
+            "id": "swift-snapshot-testing",
+            "platform": "apple",
+            "status": status(snapshot_configured and xcode_ready),
+            "availableFidelityTier": "native-preview",
+            "supports": ["swiftui", "uikit", "appkit"],
+            "reason": "Snapshot test markers and Xcode are available." if snapshot_configured and xcode_ready else "Requires a configured snapshot-test target on a macOS Xcode worker.",
+            "execution": "explicit-only",
+        },
+        {
+            "id": "apple-simulator",
+            "platform": "apple",
+            "status": status(simulator_ready),
+            "availableFidelityTier": "device-verified",
+            "supports": ["swiftui", "uikit", "appkit", "runtime-state"],
+            "reason": "Xcode simulator tooling is available." if simulator_ready else "Requires an explicit run on a macOS Xcode worker.",
+            "execution": "explicit-only",
+        },
+    ]
+    configured = [provider["id"] for provider in providers if provider["status"] == "configured"]
+    inputs = swift_files + interfaces + package_files
+    return {
+        "platform": "apple",
+        "status": "detected" if detected else "not-applicable",
+        "sourceFingerprint": _fingerprint(root, inputs),
+        "project": {
+            "hostPlatform": host,
+            "requiresMacOSWorker": bool(detected and not mac_host),
+            "xcodeProjectCount": len(projects),
+            "xcodeWorkspaceCount": len(workspaces),
+            "swiftFileCount": len(swift_files),
+            "swiftUIViewCount": swiftui_views,
+            "previewEntryCount": len(preview_entries),
+            "interfaceResourceCount": len(interfaces),
+            "snapshotTestMarkerCount": snapshot_markers,
+        },
+        "entryPoints": preview_entries[:200],
+        "providers": providers,
+        "recommendedProvider": configured[0] if configured else None,
+        "currentFidelityTier": "structural",
+        "nativeExecutionStarted": False,
+        "limitations": [
+            "Windows and Linux can discover Apple UI but cannot render it natively.",
+            "A configured provider is capability evidence, not visual fidelity evidence.",
+        ],
+    }

native_render_contracts.py

@@ -0,0 +1,148 @@
+#!/usr/bin/env python3
+"""Provider-neutral contracts for opt-in native UI rendering.
+
+Native artifacts are deliberately stored outside the baseline UI IR. Source
+adapters may reconstruct structure, but only a native provider can supply
+evidence for pixel appearance.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import re
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+from typing import Any, Protocol
+
+
+NATIVE_STATE_SCHEMA_VERSION = 1
+CAPTURE_STATUSES = {"ready", "blocked", "failed", "stale"}
+PROVIDER_STATUSES = {"configured", "available", "not-configured", "host-required", "not-applicable"}
+NATIVE_FIDELITY_TIERS = {"native-preview", "device-verified"}
+
+
+def _relative_artifact(value: str) -> str:
+    normalized = value.replace("\\", "/").strip()
+    if not normalized:
+        raise ValueError("native artifact reference must not be empty")
+    if normalized.startswith("/") or re.match(r"^[A-Za-z]:/", normalized):
+        raise ValueError(f"native artifact reference must be relative: {value}")
+    parts = [part for part in normalized.split("/") if part not in {"", "."}]
+    if not parts or ".." in parts:
+        raise ValueError(f"native artifact reference escapes its bundle: {value}")
+    return "/".join(parts)
+
+
+@dataclass(frozen=True)
+class NativeRenderRequest:
+    provider_id: str
+    platform: str
+    screen_id: str
+    state_id: str = "default"
+    variant: str = "default"
+    viewport: dict[str, Any] = field(default_factory=dict)
+    locale: str = ""
+    theme: str = ""
+
+    def cache_key(self, source_fingerprint: str, provider_version: str = "") -> str:
+        payload = {
+            **asdict(self),
+            "sourceFingerprint": source_fingerprint,
+            "providerVersion": provider_version,
+        }
+        encoded = json.dumps(payload, ensure_ascii=False, sort_keys=True, separators=(",", ":"))
+        return hashlib.sha256(encoded.encode("utf-8")).hexdigest()
+
+
+class NativeRenderProvider(Protocol):
+    id: str
+    platforms: tuple[str, ...]
+
+    def discover(self, root: Path) -> dict[str, Any]: ...
+
+    def capture(self, root: Path, request: NativeRenderRequest, output_dir: Path) -> dict[str, Any]: ...
+
+
+def empty_native_state(repo_root: Path) -> dict[str, Any]:
+    return {
+        "schemaVersion": NATIVE_STATE_SCHEMA_VERSION,
+        "type": "ui-design-workbench-native-render-state",
+        "repository": {"root": str(repo_root.resolve())},
+        "status": "not-applicable",
+        "currentFidelityTier": "structural",
+        "nativeExecutionStarted": False,
+        "platforms": [],
+        "providers": [],
+        "captures": [],
+    }
+
+
+def validate_native_state(state: dict[str, Any]) -> list[str]:
+    errors: list[str] = []
+    if state.get("schemaVersion") != NATIVE_STATE_SCHEMA_VERSION:
+        errors.append(f"schemaVersion must be {NATIVE_STATE_SCHEMA_VERSION}")
+    if state.get("type") != "ui-design-workbench-native-render-state":
+        errors.append("type must be ui-design-workbench-native-render-state")
+    if state.get("nativeExecutionStarted") not in {True, False}:
+        errors.append("nativeExecutionStarted must be boolean")
+    providers = state.get("providers", [])
+    if not isinstance(providers, list):
+        errors.append("providers must be an array")
+        providers = []
+    for index, provider in enumerate(providers):
+        if not isinstance(provider, dict):
+            errors.append(f"providers[{index}] must be an object")
+            continue
+        if not provider.get("id") or not provider.get("platform"):
+            errors.append(f"providers[{index}] requires id and platform")
+        if provider.get("status") not in PROVIDER_STATUSES:
+            errors.append(f"providers[{index}].status is invalid")
+    captures = state.get("captures", [])
+    if not isinstance(captures, list):
+        errors.append("captures must be an array")
+        captures = []
+    for index, capture in enumerate(captures):
+        if not isinstance(capture, dict):
+            errors.append(f"captures[{index}] must be an object")
+            continue
+        for key in ("id", "providerId", "platform", "screenId", "sourceFingerprint"):
+            if not capture.get(key):
+                errors.append(f"captures[{index}].{key} is required")
+        if capture.get("status") not in CAPTURE_STATUSES:
+            errors.append(f"captures[{index}].status is invalid")
+        if capture.get("fidelityTier") not in NATIVE_FIDELITY_TIERS:
+            errors.append(f"captures[{index}].fidelityTier is invalid")
+        for key in ("image", "semantics", "geometry"):
+            value = capture.get("artifacts", {}).get(key) if isinstance(capture.get("artifacts"), dict) else None
+            if value:
+                try:
+                    _relative_artifact(str(value))
+                except ValueError as exc:
+                    errors.append(f"captures[{index}].artifacts.{key}: {exc}")
+        if capture.get("status") == "ready" and not isinstance(capture.get("artifacts"), dict):
+            errors.append(f"captures[{index}].artifacts is required for a ready capture")
+    return errors
+
+
+def load_native_state(path: Path, repo_root: Path) -> dict[str, Any]:
+    try:
+        payload = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return empty_native_state(repo_root)
+    return payload if isinstance(payload, dict) and not validate_native_state(payload) else empty_native_state(repo_root)
+
+
+def write_native_state(path: Path, state: dict[str, Any]) -> None:
+    errors = validate_native_state(state)
+    if errors:
+        raise ValueError("; ".join(errors))
+    path.parent.mkdir(parents=True, exist_ok=True)
+    temporary = path.with_name(f".{path.name}.{os.getpid()}.tmp")
+    try:
+        temporary.write_text(json.dumps(state, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+        os.replace(temporary, path)
+    finally:
+        if temporary.exists():
+            temporary.unlink()

native_render_registry.py

@@ -0,0 +1,86 @@
+#!/usr/bin/env python3
+"""Native renderer discovery and cache-state orchestration."""
+
+from __future__ import annotations
+
+import copy
+from pathlib import Path
+from typing import Any
+
+from native_render_android import discover_android
+from native_render_apple import discover_apple
+from native_render_contracts import empty_native_state, load_native_state, write_native_state
+
+
+def discover_native_render(root: Path) -> dict[str, Any]:
+    platforms = [discover_android(root), discover_apple(root)]
+    detected = [item for item in platforms if item.get("status") == "detected"]
+    providers = [provider for item in platforms for provider in item.get("providers", [])]
+    configured = [provider for provider in providers if provider.get("status") == "configured"]
+    host_required = [provider for provider in providers if provider.get("status") == "host-required"]
+    if configured:
+        next_action = "Choose one configured provider and explicitly request a native capture."
+    elif host_required:
+        next_action = "Configure a macOS Xcode worker before requesting Apple native captures."
+    elif detected:
+        next_action = "Configure a supported screenshot provider; source projection remains structural-only."
+    else:
+        next_action = "No Android or Apple native project was detected."
+    return {
+        "schemaVersion": 1,
+        "type": "ui-design-workbench-native-render-state",
+        "repository": {"root": str(root.resolve())},
+        "status": "pass" if detected else "not-applicable",
+        "currentFidelityTier": "structural",
+        "nativeExecutionStarted": False,
+        "platforms": platforms,
+        "providers": providers,
+        "captures": [],
+        "summary": {
+            "detectedPlatforms": [item["platform"] for item in detected],
+            "configuredProviders": [item["id"] for item in configured],
+            "hostRequiredProviders": [item["id"] for item in host_required],
+            "nativeCaptureCount": 0,
+            "staleCaptureCount": 0,
+        },
+        "next": next_action,
+    }
+
+
+def native_render_status(root: Path, state_file: Path, platform: str = "all") -> dict[str, Any]:
+    root = root.resolve()
+    previous = load_native_state(state_file, root)
+    discovered = discover_native_render(root)
+    current_fingerprints = {
+        item.get("platform"): item.get("sourceFingerprint")
+        for item in discovered.get("platforms", [])
+        if item.get("platform")
+    }
+    captures: list[dict[str, Any]] = []
+    for original in previous.get("captures", []):
+        capture = copy.deepcopy(original)
+        platform_name = capture.get("platform")
+        if capture.get("status") == "ready" and current_fingerprints.get(platform_name) != capture.get("sourceFingerprint"):
+            capture["status"] = "stale"
+        captures.append(capture)
+    discovered["captures"] = captures
+    discovered["summary"]["nativeCaptureCount"] = sum(1 for item in captures if item.get("status") == "ready")
+    discovered["summary"]["staleCaptureCount"] = sum(1 for item in captures if item.get("status") == "stale")
+    comparable_previous = {key: value for key, value in previous.items() if key != "cache"}
+    cache_status = "reused" if comparable_previous == discovered else "updated" if state_file.is_file() else "created"
+    discovered["cache"] = {"status": cache_status, "stateFile": str(state_file.resolve())}
+    if cache_status != "reused":
+        write_native_state(state_file, {key: value for key, value in discovered.items() if key != "cache"})
+    if platform != "all":
+        selected = copy.deepcopy(discovered)
+        selected["platforms"] = [item for item in selected["platforms"] if item.get("platform") == platform]
+        selected["providers"] = [item for item in selected["providers"] if item.get("platform") == platform]
+        selected["captures"] = [item for item in selected["captures"] if item.get("platform") == platform]
+        selected["summary"]["detectedPlatforms"] = [item for item in selected["summary"]["detectedPlatforms"] if item == platform]
+        selected["summary"]["configuredProviders"] = [item["id"] for item in selected["providers"] if item.get("status") == "configured"]
+        selected["summary"]["hostRequiredProviders"] = [item["id"] for item in selected["providers"] if item.get("status") == "host-required"]
+        selected["summary"]["nativeCaptureCount"] = sum(1 for item in selected["captures"] if item.get("status") == "ready")
+        selected["summary"]["staleCaptureCount"] = sum(1 for item in selected["captures"] if item.get("status") == "stale")
+        selected["status"] = "pass" if selected["summary"]["detectedPlatforms"] else "not-applicable"
+        return selected
+    return discovered