styleproof 3.11.0 → 3.12.0

package/CHANGELOG.md

@@ -7,6 +7,29 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## [Unreleased]
 
+## [3.12.0] - 2026-07-05
+
+### Changed
+
+- **Inventory guard: target-based keying.** Source-of-truth step 4 (keying honesty).
+  Tabs / menu items / nav buttons now key by the most stable identity the element
+  exposes — a developer-authored `data-testid`, else a non-generated `id` /
+  `aria-controls` — falling back to the label slug only when there's none. Previously
+  they always keyed by `slug(accessible-name)`, so a wobble in the **label** (a live
+  count badge like "COMMAND 5" → "COMMAND 3", a re-word) faked a `removed` + `added`
+  pair. Links were already immune (they key by href); this extends the same
+  target-based principle to the rest.
+
+  Framework-generated ids (React `useId` `:r0:`, Headless UI `headlessui-…`, Radix,
+  hashes) are rejected so keying on them can't _add_ churn. The design keeps the
+  guard's safe failure direction: the label-slug fallback turns a wobble into a
+  **surfaced** removed+added (a red you see and acknowledge), never a hidden real
+  removal. Give a nav item a `data-testid` to key it immune to its own text.
+
+  Note: an id-bearing affordance's key changes from `<role>:<slug>` to
+  `<role>:#<id>`, so existing `styleproof.inventory.json` acknowledgements for such
+  items need re-keying once (the guard names the new key).
+
 ## [3.11.0] - 2026-07-06
 
 ### Added

package/dist/inventory.d.ts

@@ -35,9 +35,23 @@ export type RawAffordance = {
     name: string;
     /** pathname+search for a same-origin `<a href>`; null otherwise. Resolved in-page. */
     internalPath: string | null;
+    /** `data-testid` — developer-authored, trusted as a stable identity when present. */
+    testId: string | null;
+    /** `id` — used as a stable identity only when it doesn't look framework-generated. */
+    domId: string | null;
+    /** `aria-controls` (a tab's panel) — a stable identity when not framework-generated. */
+    controls: string | null;
 };
 /** In-page: collect visible navigable affordances. No classification. */
 export declare function collectNavAffordances(): RawAffordance[];
+/**
+ * Whether an `id` / `aria-controls` value is a STABLE identity worth keying on, vs a
+ * framework-generated one (React useId `:r0:`, Headless UI `headlessui-tabs-tab-3`,
+ * Radix `radix-:r1:`, Emotion hashes) that wobbles across renders/builds. Keying by a
+ * generated id would ADD churn, so those fall back to the label slug. (`data-testid` is
+ * developer-authored by definition, so it's trusted without this check.)
+ */
+export declare function isStableId(id: string | null | undefined): id is string;
 /** Pure: turn raw affordances into keyed, deduped, sorted navigable items. */
 export declare function classifyInventory(raw: RawAffordance[]): NavigableItem[];
 /** Harvest a page's inventory: thin in-page collect + pure classify. */

package/dist/inventory.js

@@ -75,6 +75,9 @@ export function collectNavAffordances() {
         role: (el.getAttribute('role') || '').toLowerCase(),
         name: nameOf(el),
         internalPath: el.tagName === 'A' ? internalPath(el) : null,
+        testId: el.getAttribute('data-testid'),
+        domId: el.getAttribute('id'),
+        controls: el.getAttribute('aria-controls'),
     }));
 }
 const slug = (s) => s
@@ -82,6 +85,48 @@ const slug = (s) => s
     .replace(/[^a-z0-9]+/g, '-')
     .replace(/^-+|-+$/g, '')
     .slice(0, 60);
+/**
+ * Whether an `id` / `aria-controls` value is a STABLE identity worth keying on, vs a
+ * framework-generated one (React useId `:r0:`, Headless UI `headlessui-tabs-tab-3`,
+ * Radix `radix-:r1:`, Emotion hashes) that wobbles across renders/builds. Keying by a
+ * generated id would ADD churn, so those fall back to the label slug. (`data-testid` is
+ * developer-authored by definition, so it's trusted without this check.)
+ */
+export function isStableId(id) {
+    if (!id)
+        return false;
+    const v = id.trim();
+    if (!v || v.length > 80)
+        return false;
+    if (v.includes(':'))
+        return false; // React useId / Radix scoped ids
+    if (/^(headlessui|radix|mui|chakra|reach|react-aria|floating-ui|downshift)-/i.test(v))
+        return false;
+    if (/^[0-9a-f]{8,}$/i.test(v))
+        return false; // hash-like
+    return true;
+}
+// A tab/menuitem/button's stable identity, if it exposes one: a data-testid (trusted),
+// else a non-generated id or aria-controls. Preferred over the label so a count badge
+// or re-label in the text doesn't move the key. (Links already key by href, the most
+// stable target of all.) When absent, we fall back to the label slug — the wobble is a
+// false removed+added, which the guard SURFACES; it never hides a real removal.
+function stableIdOf(c) {
+    if (c.testId && c.testId.trim())
+        return c.testId.trim();
+    if (isStableId(c.domId))
+        return c.domId.trim();
+    if (isStableId(c.controls))
+        return c.controls.trim();
+    return null;
+}
+// `<role>:#<stable-id>` when the affordance exposes a stable identity, else
+// `<role>:<slug(name)>`. The `#` marker keeps id-keys from colliding with slug-keys
+// (a slug never contains `#`).
+function affordanceKey(role, c) {
+    const id = stableIdOf(c);
+    return id ? `${role}:#${id}` : `${role}:${slug(c.name)}`;
+}
 /** Pure: turn raw affordances into keyed, deduped, sorted navigable items. */
 export function classifyInventory(raw) {
     const items = new Map();
@@ -94,13 +139,13 @@ export function classifyInventory(raw) {
             add(`route:${c.internalPath}`, 'link', c.name || c.internalPath, c.internalPath);
         }
         else if (c.name && c.role === 'tab') {
-            add(`tab:${slug(c.name)}`, 'tab', c.name);
+            add(affordanceKey('tab', c), 'tab', c.name);
         }
         else if (c.name && c.role.startsWith('menuitem')) {
-            add(`menuitem:${slug(c.name)}`, 'menuitem', c.name);
+            add(affordanceKey('menuitem', c), 'menuitem', c.name);
         }
         else if (c.name && c.tag === 'button') {
-            add(`nav-button:${slug(c.name)}`, 'nav-button', c.name);
+            add(affordanceKey('nav-button', c), 'nav-button', c.name);
         }
     }
     return Array.from(items.values()).sort((a, b) => a.key.localeCompare(b.key));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "styleproof",
-  "version": "3.11.0",
+  "version": "3.12.0",
   "description": "Catch every CSS change before it ships — review PRs and certify refactors by the browser's computed styles, not pixels. Works with any styling system.",
   "keywords": [
     "playwright",