feat: --clear-data flag + typed attribute selectors (#48)

* feat(test): add --clear-data flag to clear app data on launch

* test+docs: cover --clear-data flag in CLI parser test and reference

* feat(spec): type AttrSelector with known attribute names

Replace AttrSelector = Record<string, string> with KnownAttrSelectors
plus a string|boolean index signature, so authors get autocomplete and
type-checking on testTag / focused / clickable / etc. while raw driver
attributes still type-check via the fallback. Boolean state attributes
accept native booleans; goja stringifies them at the marshal boundary.

AccessibilityElement.attrs becomes RawAttrs (typed string-valued shape
of the same canonical names) so element.attrs.testTag autocompletes.

* test(verifier): native boolean selector value matches focused=true

* docs+folio: use native boolean for focused selector and document typed attrs

pkg/spec/src/index.ts

@@ -3,15 +3,18 @@ export type {
   AccessibilityTree,
   Action,
   ActionGenerator,
+  AttrSelector,
   EventuallyFormula,
   ExceptionRecord,
   Extracted,
   Formula,
   InputTextAction,
   Key,
+  KnownAttrSelectors,
   LogEntry,
   Point,
   PressKeyAction,
+  RawAttrs,
   Sampler,
   SelectorPath,
   Snapshots,

pkg/spec/src/types.ts

@@ -1,8 +1,58 @@
 export type Snapshots = Record<string, unknown>;
-export type AttrSelector = Record<string, string>;
+
+/**
+ * Attribute names with known canonical types. Cross-platform aliases (e.g.
+ * `testTag` -> resource-id / accessibilityIdentifier) are listed so authors
+ * get autocomplete on whichever name they prefer.
+ *
+ * Boolean state attributes accept a native boolean; the runtime stringifies
+ * to "true"/"false" before matching.
+ */
+export interface KnownAttrSelectors {
+  testTag?: string;
+  identifier?: string;
+  accessibilityIdentifier?: string;
+  "resource-id"?: string;
+
+  "content-desc"?: string;
+  accessibilityText?: string;
+  accessibilityLabel?: string;
+  label?: string;
+
+  text?: string;
+  class?: string;
+  elementType?: string;
+  package?: string;
+  placeholderValue?: string;
+  hintText?: string;
+
+  clickable?: boolean;
+  enabled?: boolean;
+  focused?: boolean;
+  checked?: boolean;
+  selected?: boolean;
+}
+
+/**
+ * Object-form selector for `find` / `findAll`. Known attributes are typed
+ * via `KnownAttrSelectors`; arbitrary string keys are still allowed for
+ * raw driver attributes the typed surface doesn't yet cover.
+ */
+export type AttrSelector = KnownAttrSelectors & {
+  [key: string]: string | boolean | undefined;
+};
 
 export type SelectorPath = readonly AttrSelector[];
 
+/** String-valued attribute names with known canonical keys. */
+export type RawAttrs = {
+  [K in keyof KnownAttrSelectors]?: KnownAttrSelectors[K] extends boolean | undefined
+    ? "true" | "false"
+    : string;
+} & {
+  [key: string]: string | undefined;
+};
+
 export interface AccessibilityElement {
   id?: string;
   text?: string;
@@ -16,7 +66,7 @@ export interface AccessibilityElement {
   bounds?: { left: number; top: number; right: number; bottom: number };
   x?: number;
   y?: number;
-  attrs?: Record<string, string>;
+  attrs?: RawAttrs;
   find(selector: string | AttrSelector | SelectorPath): AccessibilityElement | undefined;
   findAll(selector: string | AttrSelector | SelectorPath): AccessibilityElement[];
 }