androidctl 0.1.0__py3-none-any.whl

androidctld/actions/focus_confirmation.py

@@ -0,0 +1,177 @@
+"""Focus confirmation helpers for post-action validation."""
+
+from __future__ import annotations
+
+from copy import deepcopy
+from dataclasses import dataclass
+
+from androidctld.actions.type_confirmation import (
+    TypeConfirmationContext,
+    fingerprint_rematch_confirmation_node,
+    resolved_target_handle,
+    reused_ref_confirmation_node,
+    snapshot_node_for_handle,
+)
+from androidctld.commands.command_models import FocusCommand
+from androidctld.device.types import ResolvedTarget
+from androidctld.errors import DaemonError, DaemonErrorCode
+from androidctld.refs.models import NodeHandle, RefBinding
+from androidctld.runtime.models import WorkspaceRuntime
+from androidctld.snapshots.models import RawNode, RawSnapshot
+
+
+@dataclass(frozen=True)
+class FocusConfirmationCandidate:
+    strategy: str
+    node: RawNode
+
+
+@dataclass(frozen=True)
+class FocusConfirmationOutcome:
+    strategy: str
+    node: RawNode
+    target_handle: NodeHandle
+
+
+@dataclass(frozen=True)
+class FocusConfirmationContext:
+    request_handle: NodeHandle | None
+    binding: RefBinding | None
+    resolved_target: ResolvedTarget | None
+
+
+def build_focus_confirmation_context(
+    session: WorkspaceRuntime,
+    command: FocusCommand,
+    request_handle: NodeHandle | None,
+) -> FocusConfirmationContext:
+    binding = session.ref_registry.get(command.ref)
+    return FocusConfirmationContext(
+        request_handle=request_handle,
+        binding=None if binding is None else deepcopy(binding),
+        resolved_target=None,
+    )
+
+
+def validate_focus_confirmation(
+    *,
+    session: WorkspaceRuntime,
+    previous_snapshot: RawSnapshot | None,
+    snapshot: RawSnapshot,
+    context: FocusConfirmationContext,
+) -> FocusConfirmationOutcome:
+    previous_candidates = focus_confirmation_candidates(
+        session=session,
+        snapshot=previous_snapshot,
+        context=context,
+    )
+    candidates = focus_confirmation_candidates(
+        session=session,
+        snapshot=snapshot,
+        context=context,
+    )
+    candidate = first_valid_focus_candidate(candidates)
+    if candidate is None and not candidates:
+        raise DaemonError(
+            code=DaemonErrorCode.TARGET_NOT_ACTIONABLE,
+            message="focus did not expose a resolvable target handle",
+            retryable=True,
+            details={},
+            http_status=200,
+        )
+    previous_candidate = previous_candidate_for_strategy(
+        previous_candidates,
+        strategy=None if candidate is None else candidate.strategy,
+    )
+    if previous_candidate is not None and previous_candidate.node.focused:
+        raise DaemonError(
+            code=DaemonErrorCode.TARGET_NOT_ACTIONABLE,
+            message="focus target was already focused before refresh",
+            retryable=True,
+            details={"reason": "already_focused"},
+            http_status=200,
+        )
+    if candidate is None:
+        raise DaemonError(
+            code=DaemonErrorCode.TARGET_NOT_ACTIONABLE,
+            message="focus did not land on the requested input target",
+            retryable=True,
+            details={},
+            http_status=200,
+        )
+    return FocusConfirmationOutcome(
+        strategy=candidate.strategy,
+        node=candidate.node,
+        target_handle=NodeHandle(
+            snapshot_id=snapshot.snapshot_id,
+            rid=candidate.node.rid,
+        ),
+    )
+
+
+def focus_confirmation_candidates(
+    *,
+    session: WorkspaceRuntime,
+    snapshot: RawSnapshot | None,
+    context: FocusConfirmationContext,
+) -> list[FocusConfirmationCandidate]:
+    if snapshot is None:
+        return []
+    type_context = TypeConfirmationContext(
+        ref=None if context.binding is None else context.binding.ref,
+        request_handle=context.request_handle,
+        binding=context.binding,
+    )
+    candidates: list[FocusConfirmationCandidate] = []
+    seen_rids: set[str] = set()
+
+    def add_candidate(strategy: str, node: RawNode | None) -> None:
+        if node is None or node.rid in seen_rids:
+            return
+        seen_rids.add(node.rid)
+        candidates.append(FocusConfirmationCandidate(strategy=strategy, node=node))
+
+    add_candidate(
+        "resolvedTarget",
+        snapshot_node_for_handle(
+            snapshot,
+            (
+                None
+                if context.resolved_target is None
+                else resolved_target_handle(context.resolved_target)
+            ),
+        ),
+    )
+    add_candidate(
+        "requestTarget", snapshot_node_for_handle(snapshot, context.request_handle)
+    )
+    add_candidate(
+        "reusedRef", reused_ref_confirmation_node(session, snapshot, type_context)
+    )
+    add_candidate(
+        "fingerprintRematch",
+        fingerprint_rematch_confirmation_node(session, snapshot, type_context),
+    )
+    return candidates
+
+
+def first_valid_focus_candidate(
+    candidates: list[FocusConfirmationCandidate],
+) -> FocusConfirmationCandidate | None:
+    for candidate in candidates:
+        if candidate.node.focused and candidate.node.editable:
+            return candidate
+    return None
+
+
+def previous_candidate_for_strategy(
+    candidates: list[FocusConfirmationCandidate],
+    *,
+    strategy: str | None,
+) -> FocusConfirmationCandidate | None:
+    if strategy is None:
+        return None
+    for candidate in candidates:
+        if candidate.strategy == strategy:
+            return candidate
+    return None

androidctld/actions/focused_input_admissibility.py

@@ -0,0 +1,120 @@
+"""Pure focused-input admission predicates for action validation."""
+
+from __future__ import annotations
+
+from androidctld.semantics.compiler import CompiledScreen, SemanticNode
+from androidctld.semantics.public_models import PublicNode, PublicScreen
+
+
+def public_focused_input_ref(screen: PublicScreen) -> str | None:
+    return screen.surface.focus.input_ref
+
+
+def semantic_focused_input_ref(screen: CompiledScreen) -> str | None:
+    return screen.focused_input_ref()
+
+
+def public_node_is_focused_input(
+    screen: PublicScreen,
+    node: PublicNode,
+) -> bool:
+    return (
+        node.role == "input"
+        and node.ref is not None
+        and public_focused_input_ref(screen) == node.ref
+    )
+
+
+def semantic_node_is_focused_input(
+    screen: CompiledScreen,
+    node: SemanticNode,
+) -> bool:
+    focused_node = screen.focused_input_node()
+    return (
+        node.role == "input"
+        and focused_node is not None
+        and focused_node.raw_rid == node.raw_rid
+    )
+
+
+def submit_subject_is_cross_checked_focused_input(
+    public_screen: PublicScreen,
+    compiled_screen: CompiledScreen,
+    public_node: PublicNode,
+    semantic_node: SemanticNode,
+) -> bool:
+    return public_node_is_focused_input(
+        public_screen,
+        public_node,
+    ) and semantic_node_is_focused_input(compiled_screen, semantic_node)
+
+
+def keyboard_blocker_allows_public_type(
+    *,
+    blocking_group: str | None,
+    action: str,
+    screen: PublicScreen,
+    node: PublicNode,
+) -> bool:
+    return (
+        blocking_group == "keyboard"
+        and action == "type"
+        and public_node_is_focused_input(screen, node)
+    )
+
+
+def keyboard_blocker_allows_semantic_type(
+    *,
+    blocking_group: str | None,
+    action: str,
+    screen: CompiledScreen,
+    node: SemanticNode,
+) -> bool:
+    return (
+        blocking_group == "keyboard"
+        and action == "type"
+        and semantic_node_is_focused_input(screen, node)
+    )
+
+
+def keyboard_blocker_allows_submit_subject(
+    *,
+    blocking_group: str | None,
+    public_screen: PublicScreen,
+    compiled_screen: CompiledScreen,
+    public_node: PublicNode,
+    semantic_node: SemanticNode,
+) -> bool:
+    return (
+        blocking_group == "keyboard"
+        and submit_subject_is_cross_checked_focused_input(
+            public_screen,
+            compiled_screen,
+            public_node,
+            semantic_node,
+        )
+    )
+
+
+def blocked_by_group_fields(
+    *,
+    blocking_group: str,
+    ref: str | None,
+) -> dict[str, object]:
+    return {
+        "reason": f"blocked_by_{blocking_group}",
+        "ref": ref,
+        "blockingGroup": blocking_group,
+    }
+
+
+def focus_mismatch_fields(
+    *,
+    ref: str | None,
+    focused_input_ref: str | None,
+) -> dict[str, object]:
+    return {
+        "reason": "focus_mismatch",
+        "ref": ref,
+        "focusedInputRef": focused_input_ref,
+    }

androidctld/actions/fresh_current.py

@@ -0,0 +1,176 @@
+"""Fresh-current evidence checks for post-dispatch global actions."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from androidctld.errors import DaemonError, DaemonErrorCode
+from androidctld.semantics.compiler import CompiledScreen, SemanticNode
+from androidctld.snapshots.models import RawSnapshot
+from androidctld.text_equivalence import canonical_text_key, searchable_raw_node_texts
+
+_SYSTEMUI_PACKAGE_PREFIX = "com.android.systemui"
+_SYSTEM_EVIDENCE_REQUIRED_ACTIONS = frozenset({"recents", "notifications"})
+_APP_SURFACE_GROUPS = ("targets", "context", "dialog", "keyboard")
+
+
+@dataclass(frozen=True)
+class GlobalFreshCurrentBaseline:
+    action: str
+    snapshot_identity: tuple[int, str] | None
+    app_signature: tuple[Any, ...] | None
+
+
+def capture_global_fresh_current_baseline(
+    *,
+    action: str,
+    snapshot: RawSnapshot | None,
+    compiled_screen: CompiledScreen | None,
+) -> GlobalFreshCurrentBaseline:
+    return GlobalFreshCurrentBaseline(
+        action=action,
+        snapshot_identity=None if snapshot is None else _snapshot_identity(snapshot),
+        app_signature=(
+            None
+            if snapshot is None
+            else _fresh_current_app_signature(compiled_screen, snapshot)
+        ),
+    )
+
+
+def validate_global_fresh_current_evidence(
+    baseline: GlobalFreshCurrentBaseline,
+    *,
+    snapshot: RawSnapshot,
+    compiled_screen: CompiledScreen,
+) -> None:
+    if baseline.snapshot_identity is None:
+        return
+    if baseline.snapshot_identity == _snapshot_identity(snapshot):
+        raise _fresh_current_error(
+            baseline.action,
+            reason="post_action_snapshot_identity_unchanged",
+        )
+    if baseline.action not in _SYSTEM_EVIDENCE_REQUIRED_ACTIONS:
+        return
+    candidate_signature = _fresh_current_app_signature(compiled_screen, snapshot)
+    if (
+        baseline.app_signature is not None
+        and candidate_signature != baseline.app_signature
+    ):
+        return
+    if _has_real_systemui_entry(snapshot, compiled_screen):
+        return
+    raise _fresh_current_error(
+        baseline.action,
+        reason="post_action_system_evidence_missing",
+    )
+
+
+def _snapshot_identity(snapshot: RawSnapshot) -> tuple[int, str]:
+    return snapshot.snapshot_id, snapshot.captured_at
+
+
+def _fresh_current_app_signature(
+    compiled_screen: CompiledScreen | None,
+    snapshot: RawSnapshot,
+) -> tuple[Any, ...]:
+    if compiled_screen is None:
+        return _raw_app_surface_signature(snapshot)
+
+    raw_actions_by_rid = {
+        node.rid: tuple(node.actions)
+        for node in snapshot.nodes
+        if not _is_systemui_package(node.package_name)
+    }
+    return (
+        compiled_screen.package_name,
+        compiled_screen.activity_name,
+        compiled_screen.keyboard_visible,
+        tuple(
+            _compiled_app_node_signature(
+                group_name,
+                node,
+                raw_actions=raw_actions_by_rid.get(node.raw_rid),
+            )
+            for group_name in _APP_SURFACE_GROUPS
+            for node in getattr(compiled_screen, group_name)
+        ),
+    )
+
+
+def _compiled_app_node_signature(
+    group_name: str,
+    node: SemanticNode,
+    *,
+    raw_actions: tuple[str, ...] | None,
+) -> tuple[Any, ...]:
+    return (
+        group_name,
+        node.role,
+        canonical_text_key(node.label),
+        tuple(canonical_text_key(value) for value in node.state),
+        tuple(node.actions) if raw_actions is None else raw_actions,
+        None if node.bounds is None else tuple(node.bounds),
+    )
+
+
+def _raw_app_surface_signature(snapshot: RawSnapshot) -> tuple[Any, ...]:
+    return (
+        snapshot.package_name,
+        snapshot.activity_name,
+        snapshot.ime.visible,
+        tuple(
+            (
+                node.class_name,
+                canonical_text_key(node.resource_id),
+                tuple(
+                    canonical_text_key(value)
+                    for value in searchable_raw_node_texts(node)
+                ),
+                (
+                    node.enabled,
+                    node.editable,
+                    node.focusable,
+                    node.focused,
+                    node.checkable,
+                    node.checked,
+                    node.selected,
+                    node.scrollable,
+                ),
+                tuple(node.actions),
+                tuple(node.bounds),
+            )
+            for node in snapshot.nodes
+            if node.visible_to_user and not _is_systemui_package(node.package_name)
+        ),
+    )
+
+
+def _has_real_systemui_entry(
+    snapshot: RawSnapshot,
+    compiled_screen: CompiledScreen,
+) -> bool:
+    if _is_systemui_package(compiled_screen.package_name):
+        return True
+    return _is_systemui_package(snapshot.package_name)
+
+
+def _is_systemui_package(package_name: str | None) -> bool:
+    return isinstance(package_name, str) and package_name.startswith(
+        _SYSTEMUI_PACKAGE_PREFIX
+    )
+
+
+def _fresh_current_error(action: str, *, reason: str) -> DaemonError:
+    return DaemonError(
+        code=DaemonErrorCode.SCREEN_NOT_READY,
+        message="No fresh current screen observation is available after global action.",
+        retryable=True,
+        details={
+            "reason": reason,
+            "globalAction": action,
+        },
+        http_status=200,
+    )