test(contracts): enumerate the macOS emitter's real vocabulary

Review found the table claimed to pin "the vocabulary each backend actually
emits" while omitting most of it. `normalizedSnapshotType` has three output
classes and only two were represented:

  1. thirteen roles mapped to fixed short names — six were missing
     (StaticText, TextField, TextArea, MenuBarItem, Menu, MenuItem);
  2. AXWindow, whose output is the SUBROLE unless it is AXStandardWindow;
  3. the `default:` arm, `subrole ?? role`, emitting the raw AX-prefixed
     value for every unmapped role.

All three are now enumerated, and the table asserts its own completeness
against the emitter's fixed-output set — a role added to that switch without
being added here fails, which is the emitter-drift protection the docblock
was promising but not delivering.

Re-measuring over the complete tables also corrected the header's own
numbers. The claim was "71 of 73 agree, 2 disagree"; over 75 names it is 71
agree and FOUR disagree, because AXSystemDialog and AXUnknown were absent
from the old table. Those two are the behavioral delta of this PR — an
AXWindow whose subrole is emitted as the type, invisible to the six
type-only spellings and named exactly by `role` — so the incomplete table
had been hiding the very rows that justify reading role/subrole. The other
two (AXFloatingWindow, AXSystemFloatingWindow) remain inert: only the `===`
spelling misses them and its platform union is `android | ios`.

Author: thymikee

packages/contracts/src/snapshot-viewport-root.test.ts

@@ -6,17 +6,30 @@ import { isViewportRootNode } from './snapshot-visibility.ts';
  * into `node.type`/`role`/`subrole` — not over fixture strings.
  *
  * Nine hand-rolled spellings of this predicate existed before #1592's method was
- * applied here: three normalizing `type|role|subrole`, five lowercasing `type`
- * alone, and one comparing the normalized type for EQUALITY. Measured over these
- * tables they agreed on 71 of 73 emitted names, so collapsing them onto one
- * definition was a no-op everywhere except the two macOS window subroles the
- * type-only spellings could not see. Grounding the comparison in emitted
- * vocabulary is what made that provable; a fixture-string comparison would have
- * reported a divergence that no backend can produce (#1592, second commit).
+ * applied here: three normalizing `type|role|subrole`, five lowercasing or
+ * normalizing `type` alone, and one comparing the normalized type for EQUALITY.
+ * Measured over the 75 names in the three tables below they agree on 71. All
+ * four disagreements are macOS windows, and they split two ways:
  *
- * Keep these tables honest against their emitters. If a backend grows a type
- * name, add it here — a predicate that silently stops matching the root is
- * invisible in every other test, because the root node is scenery in all of them.
+ *  - `AXFloatingWindow` / `AXSystemFloatingWindow`: only the `===` spelling
+ *    (maestro) misses them, and its platform union is `android | ios`, so it
+ *    can never see a macOS node. Inert — the same shape #1592 found for its
+ *    own role/subrole arm.
+ *  - `AXSystemDialog` / `AXUnknown`: an `AXWindow` whose subrole is emitted AS
+ *    the type, so the six type-only spellings cannot see they are windows while
+ *    `role` names it exactly. These two are the entire behavioral delta of the
+ *    consolidation, and they are windows by role.
+ *
+ * Grounding this in emitted vocabulary is what made the collapse provable; a
+ * fixture-string comparison would have reported divergences no backend can
+ * produce (#1592, second commit).
+ *
+ * Keep these tables honest against their emitters — a predicate that silently
+ * stops matching the root is invisible in every other test, because the root
+ * node is scenery in all of them. The macOS table asserts its own completeness
+ * against the emitter's fixed-output set below; iOS and Android do not, so a
+ * new `elementTypeName` case or a new Android container class still has to be
+ * added here by hand.
  */
 
 // apple/runner/.../RunnerTests+Snapshot.swift `elementTypeName` — a closed set.
@@ -78,22 +91,66 @@ const ANDROID_EMITTED_TYPES = [
   'androidx.core.widget.NestedScrollView',
 ] as const;
 
-// apple/macos-helper/.../SnapshotTraversal.swift `normalizedSnapshotType`: mapped
-// short names, else the raw subrole, else the raw role — so unmapped forms keep
-// their `AX` prefix, and only this backend populates `role`/`subrole` at all.
+// apple/macos-helper/.../SnapshotTraversal.swift `normalizedSnapshotType`. Three
+// output classes, all represented below:
+//  1. every one of the 13 roles the switch maps to a fixed short name;
+//  2. `AXWindow`, whose output is the SUBROLE unless that subrole is
+//     `AXStandardWindow` — so a window's `type` can be any subrole string;
+//  3. the `default:` arm, `subrole ?? role`, which emits the raw `AX`-prefixed
+//     value for every unmapped role.
+// This backend is the only one that populates `role`/`subrole` at all.
 const MACOS_EMITTED_NODES = [
+  // 1. the complete fixed-output set.
   { type: 'Application', role: 'AXApplication' },
-  { type: 'Window', role: 'AXWindow', subrole: 'AXStandardWindow' },
-  { type: 'AXFloatingWindow', role: 'AXWindow', subrole: 'AXFloatingWindow' },
-  { type: 'AXSystemDialog', role: 'AXWindow', subrole: 'AXSystemDialog' },
-  { type: 'AXUnknown', role: 'AXWindow', subrole: 'AXUnknown' },
   { type: 'Sheet', role: 'AXSheet' },
   { type: 'Dialog', role: 'AXDialog' },
   { type: 'Button', role: 'AXButton' },
-  { type: 'Group', role: 'AXGroup' },
+  { type: 'StaticText', role: 'AXStaticText' },
+  { type: 'TextField', role: 'AXTextField' },
+  { type: 'TextArea', role: 'AXTextArea' },
   { type: 'ScrollArea', role: 'AXScrollArea' },
-  { type: 'AXWebArea', role: 'AXWebArea' },
+  { type: 'Group', role: 'AXGroup' },
   { type: 'MenuBar', role: 'AXMenuBar' },
+  { type: 'MenuBarItem', role: 'AXMenuBarItem' },
+  { type: 'Menu', role: 'AXMenu' },
+  { type: 'MenuItem', role: 'AXMenuItem' },
+  // 2. AXWindow: standard subrole collapses to "Window", every other subrole
+  //    is emitted verbatim as the type.
+  { type: 'Window', role: 'AXWindow', subrole: 'AXStandardWindow' },
+  { type: 'AXFloatingWindow', role: 'AXWindow', subrole: 'AXFloatingWindow' },
+  { type: 'AXSystemFloatingWindow', role: 'AXWindow', subrole: 'AXSystemFloatingWindow' },
+  { type: 'AXSystemDialog', role: 'AXWindow', subrole: 'AXSystemDialog' },
+  { type: 'AXUnknown', role: 'AXWindow', subrole: 'AXUnknown' },
+  // 3. the raw `subrole ?? role` fallback for unmapped roles.
+  { type: 'AXWebArea', role: 'AXWebArea' },
+  { type: 'AXList', role: 'AXList' },
+  { type: 'AXTable', role: 'AXTable' },
+  { type: 'AXOutline', role: 'AXOutline' },
+  { type: 'AXScrollBar', role: 'AXScrollBar' },
+  { type: 'AXSplitGroup', role: 'AXSplitGroup' },
+  { type: 'AXToolbar', role: 'AXToolbar' },
+  { type: 'AXSearchField', role: 'AXTextField', subrole: 'AXSearchField' },
+] as const;
+
+/**
+ * The 13 fixed outputs above are the complete set `normalizedSnapshotType`'s
+ * switch can return, so a role added to that switch without being added here
+ * is the drift this table exists to catch. Asserted rather than trusted.
+ */
+const MACOS_FIXED_OUTPUTS = [
+  'Application',
+  'Sheet',
+  'Dialog',
+  'Button',
+  'StaticText',
+  'TextField',
+  'TextArea',
+  'ScrollArea',
+  'Group',
+  'MenuBar',
+  'MenuBarItem',
+  'Menu',
+  'MenuItem',
 ] as const;
 
 describe('isViewportRootNode over emitted backend vocabulary', () => {
@@ -123,11 +180,20 @@ describe('isViewportRootNode over emitted backend vocabulary', () => {
       'Application',
       'Window',
       'AXFloatingWindow',
+      'AXSystemFloatingWindow',
       'AXSystemDialog',
       'AXUnknown',
     ]);
   });
 
+  // The table's own completeness claim, asserted rather than trusted: every
+  // fixed output the emitter's switch can return appears above, so adding a
+  // role to that switch without adding it here fails.
+  test('macOS: the table covers every fixed output normalizedSnapshotType returns', () => {
+    const covered = new Set(MACOS_EMITTED_NODES.map((node) => node.type));
+    expect(MACOS_FIXED_OUTPUTS.filter((name) => !covered.has(name))).toEqual([]);
+  });
+
   // Why the canonical predicate reads role/subrole and not `type` alone: these
   // two are windows that no type-only spelling could see.
   test('macOS: role rescues the two window subroles `type` alone cannot name', () => {