feat(sdk-android): snapshot property delegate + feature-scoped files + screen fix (#34)

* rename web to inspect ui

* feat(sdk-android): add camelToSnakeCase conversion

* feat(sdk-android): add snapshot() property delegate with tests

* feat(folio): add feature-scoped sanderling snapshot objects

* refactor(folio): slim FolioApplication to snapshot object references

* fix(folio): rename route snapshot to screen, update spec.ts

inspect-ui/src/hooks/useKeyboardNav.ts

@@ -0,0 +1,76 @@
+import { useEffect } from "react";
+
+export interface UseKeyboardNavOptions {
+  onPrev: () => void;
+  onNext: () => void;
+  onJumpStart: () => void;
+  onJumpEnd: () => void;
+  onJumpPrev10: () => void;
+  onJumpNext10: () => void;
+  onJumpNextViolation: () => void;
+}
+
+const NAVIGATION_TAGS = new Set(["INPUT", "TEXTAREA", "SELECT"]);
+const ARROW_OWNING_ROLES = new Set(["tab", "tablist", "option", "listbox", "menuitem", "menu"]);
+
+function targetOwnsArrowKeys(target: HTMLElement | null): boolean {
+  let node: HTMLElement | null = target;
+  while (node) {
+    const role = node.getAttribute?.("role");
+    if (role && ARROW_OWNING_ROLES.has(role)) return true;
+    node = node.parentElement;
+  }
+  return false;
+}
+
+export function useKeyboardNav(options: UseKeyboardNavOptions) {
+  useEffect(() => {
+    const handler = (event: KeyboardEvent) => {
+      const target = event.target as HTMLElement | null;
+      if (target && (NAVIGATION_TAGS.has(target.tagName) || target.isContentEditable)) {
+        return;
+      }
+      const isArrow = event.key.startsWith("Arrow");
+      if (isArrow && targetOwnsArrowKeys(target)) {
+        return;
+      }
+      if (event.metaKey || event.ctrlKey || event.altKey) {
+        return;
+      }
+      switch (event.key) {
+        case "ArrowLeft":
+        case "k":
+          if (event.shiftKey) {
+            options.onJumpPrev10();
+          } else {
+            options.onPrev();
+          }
+          event.preventDefault();
+          return;
+        case "ArrowRight":
+        case "j":
+          if (event.shiftKey) {
+            options.onJumpNext10();
+          } else {
+            options.onNext();
+          }
+          event.preventDefault();
+          return;
+        case "g":
+          options.onJumpStart();
+          event.preventDefault();
+          return;
+        case "G":
+          options.onJumpEnd();
+          event.preventDefault();
+          return;
+        case ".":
+          options.onJumpNextViolation();
+          event.preventDefault();
+          return;
+      }
+    };
+    window.addEventListener("keydown", handler);
+    return () => window.removeEventListener("keydown", handler);
+  }, [options]);
+}

inspect-ui/src/hooks/useSse.ts

@@ -0,0 +1,18 @@
+import { useEffect } from "react";
+
+export function useSse(eventName: string, onEvent: () => void) {
+  useEffect(() => {
+    if (typeof EventSource === "undefined") {
+      return;
+    }
+    const source = new EventSource("/api/events");
+    const messageHandler = () => {
+      onEvent();
+    };
+    source.addEventListener(eventName, messageHandler);
+    return () => {
+      source.removeEventListener(eventName, messageHandler);
+      source.close();
+    };
+  }, [eventName, onEvent]);
+}

inspect-ui/src/hooks/useStep.ts

@@ -0,0 +1,43 @@
+import { useEffect } from "react";
+import { useNavigate, useParams } from "react-router-dom";
+
+export interface UseStepResult {
+  runId: string;
+  stepIndex: number;
+  goTo: (index: number) => void;
+}
+
+export function useStep(maxIndex: number | undefined): UseStepResult {
+  const navigate = useNavigate();
+  const { id, step } = useParams<{ id: string; step: string }>();
+  const runId = id ?? "";
+  const parsed = Number(step ?? "1");
+  const stepIndex = Number.isFinite(parsed) && parsed > 0 ? parsed : 1;
+
+  const clamped = clampIndex(stepIndex, maxIndex);
+
+  useEffect(() => {
+    if (clamped !== stepIndex && runId !== "") {
+      navigate(`/runs/${runId}/steps/${clamped}`, { replace: true });
+    }
+  }, [clamped, stepIndex, runId, navigate]);
+
+  const goTo = (index: number) => {
+    const target = clampIndex(index, maxIndex);
+    if (target !== stepIndex && runId !== "") {
+      navigate(`/runs/${runId}/steps/${target}`);
+    }
+  };
+
+  return { runId, stepIndex: clamped, goTo };
+}
+
+function clampIndex(index: number, maxIndex: number | undefined): number {
+  if (index < 1) {
+    return 1;
+  }
+  if (maxIndex !== undefined && index > maxIndex) {
+    return maxIndex;
+  }
+  return index;
+}

inspect-ui/src/hooks/useTheme.ts

@@ -0,0 +1,39 @@
+import { useEffect, useState } from "react";
+
+export type ThemeMode = "light" | "dark";
+const STORAGE_KEY = "sanderling-inspect-theme";
+
+function detectInitial(): ThemeMode {
+  if (typeof window === "undefined") {
+    return "light";
+  }
+  const stored = window.localStorage.getItem(STORAGE_KEY);
+  if (stored === "light" || stored === "dark") {
+    return stored;
+  }
+  if (window.matchMedia && window.matchMedia("(prefers-color-scheme: dark)").matches) {
+    return "dark";
+  }
+  return "light";
+}
+
+export function useTheme(): { theme: ThemeMode; toggle: () => void } {
+  const [theme, setTheme] = useState<ThemeMode>(() => detectInitial());
+
+  useEffect(() => {
+    if (typeof document === "undefined") {
+      return;
+    }
+    document.documentElement.dataset.theme = theme;
+    try {
+      window.localStorage.setItem(STORAGE_KEY, theme);
+    } catch {
+      // private mode or storage disabled — theme still applies for the session.
+    }
+  }, [theme]);
+
+  return {
+    theme,
+    toggle: () => setTheme((current) => (current === "dark" ? "light" : "dark")),
+  };
+}