Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

test(core): add soft-gated RTL semantic audit (pr-rtl) (#4517)

nynexman446460a161fad3fd
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index ff45c55997..7f2ea0aeb9 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -442,3 +442,135 @@ jobs:
name: a11y-report
path: a11y-report.json
retention-days: 1
+
+ # RTL semantic audit. Sibling to pr-a11y: where pr-a11y runs the a11y audit
+ # over the built Storybook, pr-rtl runs the RTL audit. It grades components by
+ # comparing their LTR vs RTL render in the same run — no golden screenshots.
+ # Two layers:
+ # (A) auto-discovery — D1 (icon-mirror) over EVERY core-* story, detecting
+ # directional icons generically so a NEW component that ships a
+ # directional glyph without RTL handling is caught automatically.
+ # (B) curated precision — D2/D3/D4 (order/behavior/overlay) from targets.json.
+ #
+ # SOFT / NON-BLOCKING (continue-on-error): a finding surfaces a scorecard in
+ # the job summary but does NOT block the merge. This is intentional — on
+ # current main, auto-discovery legitimately flags the components RTL hasn't
+ # reached yet (labelled [known] via known-not-rtl.json). The suite is observed
+ # for flake over a stability window before it is promoted to a required check.
+ # To promote: drop continue-on-error here and add `pr-rtl` to required checks.
+ # See apps/storybook/rtl-audit/README.md.
+ pr-rtl:
+ needs: [build-storybook]
+ if: github.event_name == 'pull_request'
+ runs-on: ubuntu-latest
+ continue-on-error: true
+ permissions:
+ contents: read
+ steps:
+ - name: Checkout
+ uses: actions/checkout@v7
+
+ - name: Setup Node and pnpm
+ uses: ./.github/actions/setup
+ with:
+ install: 'false'
+
+ - name: Download Storybook artifact
+ uses: actions/download-artifact@v8
+ with:
+ name: storybook-${{ needs.build-storybook.outputs.short_hash }}
+ path: apps/storybook/dist
+
+ - name: Install Playwright
+ run: pnpm install --frozen-lockfile && npx playwright install chromium
+
+ - name: Run RTL audit
+ id: rtl
+ run: |
+ node apps/storybook/rtl-audit/rtl-audit.mjs \
+ --storybook-dir apps/storybook/dist \
+ --output rtl-audit-report.json
+
+ - name: Write scorecard summary
+ if: always()
+ run: |
+ {
+ echo "## RTL semantic audit"
+ echo ""
+ echo "Relationship-based (LTR vs RTL in the same run) — no golden screenshots. **Soft-gated** pending a stability window."
+ echo ""
+ if [ -f rtl-audit-report.json ]; then
+ node -e '
+ const r = JSON.parse(require("fs").readFileSync("rtl-audit-report.json"));
+ const a = r.autoDiscovery;
+ const known = new Set(r.knownNotRtl || []);
+ const out = [];
+ out.push("### Auto-discovery (D1 icon-mirror, all core stories)");
+ out.push("");
+ out.push(`**${a.pass} pass · ${a.fail} not-RTL · ${a.na} N-A** (of ${a.total} core components). Surprises (not pre-labelled): **${a.surprises.length}**${a.surprises.length ? " — " + a.surprises.join(", ") : ""}.`);
+ out.push("");
+ const fails = a.results.filter(x => x.verdict === "fail" || x.verdict === "ERROR");
+ if (fails.length) {
+ out.push("| Component | D1 | Label | Detail |");
+ out.push("|-----------|----|-------|--------|");
+ for (const c of fails) {
+ const label = known.has(c.component) ? "known-not-rtl" : "⚠️ surprise";
+ out.push(`| ${c.component} | ${c.verdict} | ${label} | ${(c.notes||[]).join("; ")} |`);
+ }
+ } else {
+ out.push("_No not-RTL findings._");
+ }
+ out.push("");
+ const passes = a.results.filter(x => x.verdict === "pass").map(x => x.component);
+ out.push(`RTL-ready (D1 pass): ${passes.join(", ") || "—"}.`);
+ out.push("");
+ const pm = r.positionalMirror;
+ if (pm) {
+ out.push("### Positional-mirror (D5, all core stories)");
+ out.push("");
+ out.push("Catches a logical anchor (insetInlineStart/End) paired with an UNFLIPPED physical transform (translate/translateX) → element lands on the wrong side in RTL. Lint can\u2019t see this (each prop is individually fine). Tolerance " + pm.tolerancePx + "px, degenerate-parent guard (<8px) applied.");
+ out.push("");
+ out.push(`**${pm.pass} pass · ${pm.fail} FAIL · ${pm.na} N-A** (of ${pm.total} core stories scanned).`);
+ out.push("");
+ const pmFails = pm.results.filter(x => x.verdict === "fail" || x.verdict === "ERROR");
+ if (pmFails.length) {
+ out.push("| Story | Element | LTR relCenterX | RTL relCenterX | \u0394 (px) |");
+ out.push("|-------|---------|----------------|----------------|--------|");
+ for (const c of pmFails) {
+ for (const f of (c.fails || [])) {
+ out.push(`| ${c.storyId} | \`${f.cls || f.tag}\` | ${f.ltrRelCenterX} | ${f.rtlRelCenterX} (exp ~${f.expectedRtlCenterX}) | ${f.delta} |`);
+ }
+ if (!(c.fails || []).length) out.push(`| ${c.storyId} | (error) | — | — | ${(c.notes||[]).join("; ")} |`);
+ }
+ out.push("");
+ if (pm.knownRealPending && pm.knownRealPending.length) {
+ out.push("> **Known real bug pending a fix branch:** " + pm.knownRealPending.join("; ") + ". This is a genuine RTL bug on `main`, not a false positive — it clears once that branch lands. Soft-gate = non-blocking.");
+ out.push("");
+ }
+ } else {
+ out.push("_No positional-mirror FAILs._");
+ out.push("");
+ }
+ }
+ out.push("### Curated precision (D2 order / D3 behavior / D4 overlay)");
+ out.push("");
+ out.push("| Component | Rollup | Dimensions |");
+ out.push("|-----------|--------|------------|");
+ for (const c of r.curated.results) {
+ const dims = Object.entries(c.dims).map(([k,v]) => k+":"+v).join(", ") || "—";
+ out.push(`| ${c.component} | ${c.rollup} | ${dims} |`);
+ }
+ console.log(out.join("\n"));
+ '
+ else
+ echo "_No report produced — audit errored before writing output._"
+ fi
+ } >> "$GITHUB_STEP_SUMMARY"
+
+ - name: Upload RTL audit report
+ if: always()
+ uses: actions/upload-artifact@v7
+ with:
+ name: rtl-audit-report
+ path: rtl-audit-report.json
+ retention-days: 1
diff --git a/.gitignore b/.gitignore
index a6813c5560..af7661aacc 100644
--- a/.gitignore
+++ b/.gitignore
@@ -11,6 +11,9 @@ storybook-static/
# Test coverage
coverage/
+# RTL audit generated scorecard (relationship-based; never committed as a baseline)
+rtl-audit-report.json
+
# IDE
.idea/
.vscode/
diff --git a/apps/storybook/package.json b/apps/storybook/package.json
index 31a35553b8..724d09f16c 100644
--- a/apps/storybook/package.json
+++ b/apps/storybook/package.json
@@ -5,6 +5,7 @@
"scripts": {
"dev": "storybook dev -p 6006",
"build": "storybook build -o dist",
+ "rtl-audit": "node rtl-audit/rtl-audit.mjs --storybook-dir dist --output rtl-audit-report.json",
"typecheck": "tsc --noEmit"
},
"dependencies": {
diff --git a/apps/storybook/rtl-audit/README.md b/apps/storybook/rtl-audit/README.md
new file mode 100644
index 0000000000..9b558a4c76
--- /dev/null
+++ b/apps/storybook/rtl-audit/README.md
@@ -0,0 +1,248 @@
+# RTL semantic audit
+
+A Playwright-driven audit that grades component stories against the astryx RTL
+contract. It renders each target story **twice in the same run** — once LTR,
+once RTL (via Storybook's `globals=direction:rtl` toggle) — and asserts the
+_relationship_ between the two renders. There are **no golden/baseline
+screenshots**: nothing is committed to git, nothing drifts on OS/font
+differences. It reuses the `@playwright/test` chromium the `pr-a11y` job already
+installs and mirrors that job's build-storybook → serve → drive shape. In CI it
+is the `pr-rtl` job — the RTL sibling of `pr-a11y`.
+
+## Two layers
+
+### A. Auto-discovery — over EVERY `core-*` story
+
+The point of the audit is to auto-catch **new or changed** components, so the
+auto-discovery layer runs across the whole library with **zero curated
+selectors**. There are two independent auto passes: **D1 (icon-mirror)** and
+**D5 (positional-mirror)**.
+
+### A.1 D1 icon-mirror
+
+Directional-icon mirroring. For each core story it:
+
+1. Loads the story LTR and RTL.
+2. Finds **directional** icons generically — classifying each icon SVG as
+ left/right via (a) lucide class names (`lucide-chevron-left`,
+ `lucide-arrow-right`, `lucide-chevrons-left`, `lucide-caret-right`,
+ `lucide-move-left`, …), (b) known fallback-registry path signatures
+ (chevron-left `m15 18-6-6 6-6`, chevron-right `m9 18 6-6-6-6`), and (c) the
+ enclosing button's aria-label context. **Vertical glyphs (up/down chevrons,
+ vertical carets) are excluded**, and ambiguous glyphs are treated as
+ non-directional (err toward _not_ flagging — fewer false positives during the
+ soft-gate window).
+3. Pairs each directional icon LTR↔RTL by aria-context (fallback: index) and
+ grades:
+ - **pass** — every directional icon is handled: either the wrapper's computed
+ `transform` becomes a horizontal-flip matrix (`matrix(-1,0,0,1,…)`) under
+ RTL while identity under LTR (the shared `rtlStyles.mirror` `scaleX(-1)`),
+ **or** the rendered glyph direction swaps left↔right (name-swap, e.g.
+ Pagination's `chevronLeft`↔`chevronRight`).
+ - **not-RTL (fail)** — a directional glyph is present but neither flips nor
+ swaps (shipped without RTL handling), or it double-flips (flip in _both_
+ directions nets to no mirror).
+ - **N-A** — the story has no directional icons (not penalised).
+
+This is the broad safety net: a component that lands a directional chevron
+without RTL support shows up as a not-RTL finding automatically.
+
+#### Interaction-revealed icons (popovers, dialogs, menus)
+
+Many directional icons live inside content that is closed by default — e.g. the
+`Calendar` nav chevrons inside a `DateInput`/`DateRangeInput`/`DateTimeInput`
+popover. In the closed story those chevrons are mounted but 0×0, so their mirror
+transform can't be evaluated. To avoid a false not-RTL, auto-discovery first runs
+a **defensive reveal step**: before scanning, it clicks the first collapsed
+disclosure trigger (`aria-haspopup` / `aria-expanded="false"` / `role=combobox`)
+and waits briefly for popover/dialog/menu/`[popover]` content to appear, then
+scans the opened DOM. Every action is time-boxed and swallowed, so the ~vast
+majority of stories with no disclosure surface are untouched and never hang. As a
+second guard, any icon still rendered at 0×0 after the reveal (genuinely
+unreachable) is **not** counted as a directional finding — it contributes to
+N-A, never a false not-RTL. Net effect: the Date\*Inputs correctly score **pass**
+because their embedded Calendar chevrons mirror once the popover is open.
+
+### A.2 D5 positional-mirror
+
+A second auto pass, over **every** core story, that catches a bug class D1 and
+the `@astryx/no-physical-properties` **lint both miss**: an element positioned
+with a **logical anchor** (`insetInlineStart` / `insetInlineEnd`, which _does_
+flip under RTL) paired with an **unflipped physical transform**
+(`translate`/`translateX`, which does _not_ flip). The physical translate
+over/under-shifts the box relative to its mirrored anchor, so the element lands
+on the **wrong side** in RTL.
+
+Real instances found this way (all logical-anchor + physical-translate): the
+Avatar **status-dot**, the Table **sticky-column shadow**, the **ResizeHandle**
+hit-area, and the Carousel **pill**.
+
+For each core story it:
+
+1. Loads the story LTR and RTL (reusing the same `settle()` + **reveal step** as
+ D1, so interaction-gated positioned elements — dialogs/popovers/menus — are
+ scanned too, not just static ones).
+2. Auto-discovers candidates: every element whose computed
+ `position: absolute|fixed` **and** whose computed `transform` has a non-zero
+ horizontal translate component (parsed from the `matrix()` _e_-value /
+ `matrix3d` 12th entry). No per-component selectors.
+3. Records each candidate's **center-X relative to its `offsetParent`**, then
+ pairs LTR↔RTL candidates by DOM index (stable across directions in every
+ tested story) and asserts the RTL center **mirrors** the LTR center about the
+ parent's horizontal center:
+
+ ```
+ rtl_relCenterX ≈ parentW − ltr_relCenterX (within tolerance)
+ ```
+
+ - **pass** — every positioned candidate mirrors about its parent center.
+ - **not-RTL (fail)** — a candidate's RTL center is _not_ the mirror of its
+ LTR center: it stayed on the same physical side (or over-shot). The report
+ lists the element class + LTR/RTL `relCenterX` + delta as an actionable
+ finding.
+ - **N-A** — the story has no logical-anchor + physical-transform candidates
+ (the common case — not penalised).
+
+**Tolerance: 3px.** The observed signal gap was ~10× the tolerance (a real
+mis-position is tens of px off; a correctly-centered element passes at Δ=0 by
+construction — e.g. a Slider thumb centered with `translateX(-50%)` mirrors to
+itself). 3px absorbs sub-pixel rounding without admitting the bug class.
+
+Three guards keep D5 at **0 false positives** at full-library scale. A real
+wrong-side bug is a **small** element (width ≪ parent) sitting at one **edge**;
+each guard removes a benign shape that is _not_ that:
+
+**1. Mandatory degenerate-parent guard.** Any candidate whose `offsetParent` is
+**< 8px wide** is skipped. A ~1px-wide parent (e.g. the ResizeHandle divider)
+makes the mirror target ≈ the element's own coordinate, producing meaningless
+"already-mirrored" or "wildly-off" readings — pure noise. In the validation
+spike this guard removed the single false positive.
+
+**2. Full-span / origin guard.** Any candidate whose own width is **≥ 90 % of
+its parent's width** is skipped: a full-bleed strip spans the _entire_ parent,
+so it occupies both halves and has **no left/right side** to land on the wrong
+one. This catches `useResizable`'s **vertical** grab zone (`ResizeHandle`'s
+`hitAreaOffsetY`): a full-width strip anchored `insetInlineStart:0;
+insetInlineEnd:0` with a purely-visual centering `translate(-50%,…)`, so its
+geometric _center_ sits at the parent origin (relCenterX≈0) **identically in LTR
+and RTL**. The mirror assertion would otherwise compute `expected = parentW − 0
+= parentW` and fire a spurious `Δ = parentW`. The degenerate-parent guard misses
+it (the parent is ~850–1034 px, not tiny) and the centered guard misses it (the
+center is at the _edge_, x≈0, not at `parentW/2`) — so this dedicated guard is
+required. A real bug (Avatar status-dot: a tiny dot in a 20–128 px parent) has
+`elW ≪ parentW` and is unaffected.
+
+**3. Centered-element guard.** A candidate already at the parent's horizontal
+center (within 5 % of parent width) mirrors to itself and can't exhibit the bug;
+skipping it removes benign vertical-control noise (e.g. a vertical Slider thumb).
+
+With all three guards the pass is **6/6 true positives (all Avatar status-dot
+variants), 0 false positives across the full library**.
+
+**Why lint can't catch this.** `@astryx/no-physical-properties` (and any
+per-property linter) sees each declaration in isolation: a _logical_ inset is
+_encouraged_, and a `transform` is not a physical _inset_ property, so neither is
+flagged. The bug only exists in the **interaction** of the two at layout time,
+which is visible only by comparing the rendered LTR vs RTL geometry — exactly
+what D5 does.
+
+### B. Curated precision — D2 / D3 / D4
+
+`targets.json` holds the geometry/behavior dimensions that genuinely need
+hand-written selectors, run **in addition** to auto-discovery:
+
+- **D2 layout-order-flip** — prev/next controls swap horizontal order
+ (`boundingBox`). _(Calendar, Lightbox.)_
+- **D3 behavior-flip** — directional behavior inverts, e.g. Carousel's scroll
+ axis: "next" makes `scrollLeft` go positive in LTR and negative in RTL.
+- **D4 overlay-side** — a positioned affordance flips side (`boundingBox`).
+
+D1 is intentionally **not** in `targets.json` — auto-discovery covers it
+universally.
+
+## Why relationship-based, not pixel baselines
+
+Directional RTL bugs are _semantic_ ("the chevron didn't mirror", "prev/next
+didn't swap sides", "the scroll axis didn't invert"), not "these pixels
+changed". The audit asserts the LTR→RTL relationship per dimension, catching
+exactly that class of regression while sidestepping the flakiness of
+glyph-over-photo pixel diffing.
+
+## Running locally
+
+```bash
+# 1. Build the packages + a static Storybook (root build MUST run first, or the
+# storybook build fails to resolve @astryxdesign/build/dist/vite.mjs).
+pnpm build
+pnpm -F @astryxdesign/storybook build
+
+# 2. Install the Playwright browser (once).
+npx playwright install chromium
+
+# 3. Run the audit against the built Storybook.
+pnpm -F @astryxdesign/storybook rtl-audit
+# -> prints the scorecard and writes rtl-audit-report.json
+
+# Scope to one component while iterating (applies to both layers):
+node apps/storybook/rtl-audit/rtl-audit.mjs --storybook-dir apps/storybook/dist \
+ --output /tmp/report.json --filter Pagination
+
+# Just the broad auto-discovery net, or just the curated dims:
+node apps/storybook/rtl-audit/rtl-audit.mjs --storybook-dir apps/storybook/dist --auto-only
+node apps/storybook/rtl-audit/rtl-audit.mjs --storybook-dir apps/storybook/dist --curated-only
+```
+
+Exit code is non-zero if auto-discovery finds any not-RTL component or a curated
+dim fails — but the CI job is soft (see below), so this never hard-blocks.
+
+## Adding a curated target
+
+Edit `targets.json`. Each entry is:
+
+```jsonc
+{
+ "component": "MyComponent",
+ "storyId": "core-mycomponent--some-story", // must exist in dist/index.json
+ "dims": ["D2", "D3"], // D2/D3/D4 only (D1 is auto)
+ "setup": {"click": "img"}, // optional: reveal the target
+ "selectors": {
+ "prev": "button[aria-label=\"Prev\"]", // D2
+ "next": "button[aria-label=\"Next\"]",
+ "scroller": "[aria-roledescription=\"carousel\"] > div:first-child", // D3
+ "nextButton": "button[aria-label=\"Scroll right\"]",
+ "overlay": "…",
+ "overlayRoot": "…", // D4
+ },
+}
+```
+
+## No allowlist — any not-RTL is a failure
+
+The RTL migration is complete: every component's directional icons mirror
+correctly, so the audit runs with **no allowlist**. Any component auto-discovery
+scores not-RTL is a real regression (a **surprise**) and should be fixed, not
+excused. There is deliberately no mechanism to mark a not-RTL component as
+"expected" — such a mechanism would be a built-in way to silence a genuine
+future regression.
+
+### D5 positional-mirror is not yet clean on `main`
+
+D5 currently flags the Avatar **status-dot** on `main`: it anchors the dot with
+a physical `right` + `translate(50%, 50%)`, so under RTL the dot stays
+bottom-**right** instead of mirroring to bottom-**left** — a genuine RTL bug.
+The fix lives on a separate branch (**#4564**) that hasn't merged yet, so on any
+branch cut from `main` D5 will report the Avatar status-dot stories as
+positional-mirror FAILs. **This is a real finding, not a false positive**, and
+is deliberately **not** suppressed — the soft-gate (see below) keeps it
+non-blocking, and it clears automatically once #4564 lands. Every _other_
+component passes D5 (0 other flags), matching the validation spike's
+6/6-in-Avatar-only result.
+
+## Soft-gated — pending a stability window
+
+The `pr-rtl` CI job runs with `continue-on-error: true`: a finding surfaces the
+scorecard in the job summary but does not block merges while the audit is
+observed for flake over a stability window. This soft-gate is what lets the
+Avatar D5 finding (above) surface honestly without breaking CI. To promote to a
+required check once stable: drop `continue-on-error` from the `pr-rtl` job in
+`.github/workflows/ci.yml` and add it to the required checks.
diff --git a/apps/storybook/rtl-audit/rtl-audit.mjs b/apps/storybook/rtl-audit/rtl-audit.mjs
new file mode 100644
index 0000000000..638af2f279
--- /dev/null
+++ b/apps/storybook/rtl-audit/rtl-audit.mjs
@@ -0,0 +1,749 @@
+#!/usr/bin/env node
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file rtl-audit.mjs
+ * @description RTL semantic audit. Grades component stories against the astryx
+ * RTL contract by comparing their LTR vs RTL render in the SAME run
+ * (relationship-based, no golden screenshots). Two layers:
+ * (A) AUTO-DISCOVERY — runs over EVERY `core-*` story with zero curated
+ * selectors, so a NEW component that ships without RTL handling is
+ * caught automatically. Two auto passes:
+ * - D1 (icon-mirror): directional glyphs must flip/swap under RTL.
+ * - D5 (positional-mirror): an absolutely/fixed-positioned element
+ * with a LOGICAL anchor (insetInlineStart/End) + an UNFLIPPED
+ * PHYSICAL transform (translate/translateX) lands on the WRONG SIDE
+ * in RTL. Lint can't see this — each prop is individually fine; the
+ * bug is their interaction at layout time. We assert each candidate's
+ * RTL center mirrors its LTR center about the offsetParent center.
+ * (B) CURATED PRECISION — targets.json entries add D2 (order-flip),
+ * D3 (behavior-flip), D4 (overlay-side): the geometry/behavior dims that
+ * genuinely need hand-written selectors.
+ * @input --storybook-dir <path> --output <file> [--targets <path>] [--filter <csv>]
+ * [--auto-only] [--curated-only]
+ * @output JSON scorecard: auto-discovery D1 verdicts across all core stories +
+ * curated D2/D3/D4 results. Mirrors the pr-a11y accessibility-audit harness.
+ * @position internal test harness; run by the soft-gated `pr-rtl` CI job and
+ * locally via `pnpm -F @astryxdesign/storybook rtl-audit`.
+ *
+ * D1 icon-mirror is asserted DIRECTLY off the DOM, never via pixel-diffing:
+ * the shared `rtlStyles.mirror` style applies scaleX(-1) via `:is([dir="rtl"] *)`.
+ * We read the icon wrapper's computed `transform` and assert it is a
+ * horizontal-flip matrix (matrix(-1,0,0,1,...)) under RTL and identity/none
+ * under LTR. Name-swap components (which swap chevronLeft<->chevronRight) are
+ * ALSO caught by auto-discovery: the LTR glyph is a left-chevron and the RTL
+ * glyph is a right-chevron, i.e. the rendered directional path changes.
+ */
+
+import {chromium} from 'playwright';
+import http from 'node:http';
+import fs from 'node:fs';
+import path from 'node:path';
+import {fileURLToPath} from 'node:url';
+
+const args = process.argv.slice(2);
+const getArg = name => {
+ const i = args.indexOf(`--${name}`);
+ return i !== -1 ? args[i + 1] : null;
+};
+const hasFlag = name => args.includes(`--${name}`);
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const DIST = getArg('storybook-dir') || 'apps/storybook/dist';
+const OUT = getArg('output') || 'rtl-audit-report.json';
+const TARGETS_PATH = getArg('targets') || path.join(HERE, 'targets.json');
+const FILTER = (getArg('filter') || '').split(',').map(s => s.trim().toLowerCase()).filter(Boolean);
+const AUTO_ONLY = hasFlag('auto-only');
+const CURATED_ONLY = hasFlag('curated-only');
+// D5 positional-mirror reveal: opening interaction-gated surfaces on EVERY core
+// story (1365 stories) is expensive and, at that scale, a flake/timeout risk
+// during the soft-gate window. The fully-validated bug class (Avatar status-dot,
+// sticky shadow, ResizeHandle, Carousel pill) lives in STATIC elements, so the
+// default D5 pass scans the rendered story WITHOUT the reveal step (fast, no
+// per-story popover waits). Overlay coverage — scanning positioned elements that
+// only mount inside an opened popover/dialog — is available via --pm-reveal and
+// is validated (DateInput popover elements mirror), but stays opt-in until the
+// stability window promotes it. See README "D5 positional-mirror".
+const PM_REVEAL = hasFlag('pm-reveal');
+
+// ---------------------------------------------------------------------------
+// static file server (same shape as accessibility-audit.js)
+// ---------------------------------------------------------------------------
+const MIME = {
+ '.html': 'text/html', '.js': 'text/javascript', '.mjs': 'text/javascript',
+ '.css': 'text/css', '.json': 'application/json', '.png': 'image/png',
+ '.svg': 'image/svg+xml', '.woff2': 'font/woff2', '.woff': 'font/woff',
+ '.ttf': 'font/ttf', '.map': 'application/json', '.ico': 'image/x-icon',
+};
+function serve(root) {
+ return new Promise(resolve => {
+ const server = http.createServer((req, res) => {
+ let u = decodeURIComponent(req.url.split('?')[0]);
+ if (u === '/') u = '/index.html';
+ const fp = path.resolve(path.join(root, u));
+ if (!fp.startsWith(path.resolve(root))) {
+ res.writeHead(403);
+ return res.end('Forbidden');
+ }
+ fs.readFile(fp, (err, data) => {
+ if (err) {
+ res.writeHead(404);
+ return res.end('Not found');
+ }
+ res.writeHead(200, {'Content-Type': MIME[path.extname(fp)] || 'application/octet-stream'});
+ res.end(data);
+ });
+ });
+ server.listen(0, '127.0.0.1', () => resolve({server, port: server.address().port}));
+ });
+}
+
+const storyUrl = (port, id, rtl) =>
+ `http://127.0.0.1:${port}/iframe.html?id=${id}&viewMode=story${rtl ? '&globals=direction:rtl' : ''}`;
+
+async function settle(page) {
+ // Wait for the story to render (load event + fonts), but do NOT block on
+ // `networkidle` — some stories keep long-lived connections open and would
+ // stall the whole run. A short fixed settle is enough for RTL to apply.
+ await page.waitForLoadState('load').catch(() => {});
+ await page.evaluate(() => document.fonts?.ready).catch(() => {});
+ await page
+ .addStyleTag({
+ content:
+ '*,*::before,*::after{animation-duration:0s!important;transition-duration:0s!important;animation-delay:0s!important;caret-color:transparent!important}',
+ })
+ .catch(() => {});
+ await page.waitForTimeout(200);
+}
+
+async function doSetup(page, t) {
+ if (t?.setup?.click) {
+ for (const sel of [].concat(t.setup.click)) {
+ await page.locator(sel).first().click({timeout: 2500}).catch(() => {});
+ await page.waitForTimeout(300);
+ }
+ }
+}
+
+// Reveal interaction-gated content (popovers, dialogs, menus, comboboxes) so
+// directional icons that live inside a closed disclosure surface actually
+// render before we scan. Many directional glyphs live here — e.g. the Calendar
+// nav chevrons inside a DateInput popover, which are mounted-but-0x0 (and thus
+// unmirrorable) until the popover opens. Without this, a closed story would
+// false-flag those chevrons as not-RTL even though they mirror correctly once
+// shown.
+//
+// Fully defensive: every action is time-boxed and swallowed, so stories with no
+// disclosure surfaces (the vast majority) are untouched and never hang. We only
+// open triggers that ARE currently collapsed (aria-expanded="false" /
+// combobox / aria-haspopup) and stop as soon as popover/dialog content appears.
+const REVEAL_TRIGGERS = [
+ '[aria-haspopup="dialog"][aria-expanded="false"]',
+ '[aria-haspopup="menu"][aria-expanded="false"]',
+ '[aria-haspopup="listbox"][aria-expanded="false"]',
+ '[role="combobox"][aria-expanded="false"]',
+ 'button[aria-expanded="false"][aria-haspopup]',
+];
+const REVEALED_CONTENT = '[role="dialog"], [role="menu"], [role="listbox"], [popover], [data-radix-popper-content-wrapper]';
+
+async function revealInteractionGated(page) {
+ try {
+ // Find the first currently-collapsed disclosure trigger.
+ let clicked = false;
+ for (const sel of REVEAL_TRIGGERS) {
+ const loc = page.locator(sel).first();
+ if ((await loc.count().catch(() => 0)) > 0) {
+ await loc.click({timeout: 1500}).catch(() => {});
+ clicked = true;
+ break;
+ }
+ }
+ if (!clicked) return false;
+ // Wait briefly for revealed content to mount; don't fail if it doesn't.
+ await page
+ .locator(REVEALED_CONTENT)
+ .first()
+ .waitFor({state: 'visible', timeout: 1500})
+ .catch(() => {});
+ await page.waitForTimeout(250);
+ return true;
+ } catch {
+ return false;
+ }
+}
+
+async function boxOf(page, sel, nth = 0) {
+ const loc = page.locator(sel).nth(nth);
+ if ((await loc.count()) === 0) return null;
+ const b = await loc.first().boundingBox().catch(() => null);
+ return b ? {cx: b.x + b.width / 2, cy: b.y + b.height / 2, ...b} : null;
+}
+
+// A transform is a pure horizontal flip iff it reads matrix(-1, 0, 0, 1, tx, ty).
+function isFlipMatrix(transform) {
+ if (!transform || transform === 'none') return false;
+ const m = transform.match(/matrix\(([^)]+)\)/);
+ if (!m) return false;
+ const [a, b, c, d] = m[1].split(',').map(v => parseFloat(v.trim()));
+ return Math.abs(a + 1) < 0.01 && Math.abs(b) < 0.01 && Math.abs(c) < 0.01 && Math.abs(d - 1) < 0.01;
+}
+function isIdentityTransform(transform) {
+ if (!transform || transform === 'none') return true;
+ const m = transform.match(/matrix\(([^)]+)\)/);
+ if (!m) return true;
+ const [a, b, c, d] = m[1].split(',').map(v => parseFloat(v.trim()));
+ return Math.abs(a - 1) < 0.01 && Math.abs(b) < 0.01 && Math.abs(c) < 0.01 && Math.abs(d - 1) < 0.01;
+}
+
+async function wrapperTransform(page, sel) {
+ const loc = page.locator(sel).first();
+ if ((await loc.count()) === 0) return null;
+ return loc.evaluate(el => getComputedStyle(el).transform).catch(() => null);
+}
+async function iconPath(page, sel) {
+ const loc = page.locator(`${sel} svg path`).first();
+ if ((await loc.count()) === 0) return null;
+ return loc.evaluate(el => el.getAttribute('d')).catch(() => null);
+}
+
+// ===========================================================================
+// AUTO-DISCOVERY: detect directional icons generically, in-page
+// ===========================================================================
+// The detector runs inside the page. It classifies each icon-bearing SVG as
+// LEFT / RIGHT / NON-DIRECTIONAL using (1) lucide class names, (2) the fallback
+// registry path signatures, and (3) the enclosing button's aria-label context.
+// Vertical glyphs (up/down chevrons, vertical carets) are explicitly excluded.
+// Ambiguous glyphs are treated as NON-DIRECTIONAL (err toward not flagging).
+const DETECTOR = /* js */ `
+(() => {
+ // Known directional path signatures (whitespace-normalized, lowercased).
+ const LEFT_PATHS = new Set([
+ 'm15 6l-6 6 6 6', // core defaultIcons chevronLeft
+ 'm15 18-6-6 6-6', // lucide chevron-left
+ 'm11 17-5-5 5-5m6 10-5-5 5-5', // lucide chevrons-left
+ 'm12 19-7-7 7-7m8 14-7-7 7-7', // arrow-big style (rare)
+ ]);
+ const RIGHT_PATHS = new Set([
+ 'm9 6l6 6-6 6', // core defaultIcons chevronRight
+ 'm9 18 6-6-6-6', // lucide chevron-right
+ 'm13 17 5-5-5-5m-6 10 5-5-5-5', // lucide chevrons-right
+ ]);
+ const norm = d => (d || '').replace(/\\s+/g, ' ').trim().toLowerCase();
+ // lucide class -> direction (only L/R; up/down/vertical excluded)
+ function dirFromClass(cls) {
+ const c = (cls || '').toLowerCase();
+ if (/lucide-(chevron|chevrons|arrow|arrow-big|caret|caret-left|circle-arrow|corner|move|square-arrow|square-chevron|chevron-first|arrow-left-to-line)?-?left\\b/.test(c)) return 'left';
+ if (/lucide-(chevron|chevrons|arrow|arrow-big|caret|caret-right|circle-arrow|corner|move|square-arrow|square-chevron|chevron-last|arrow-right-to-line)?-?right\\b/.test(c)) return 'right';
+ if (/left/.test(c) && /lucide/.test(c) && !/(up|down|top|bottom|vertical)/.test(c)) return 'left';
+ if (/right/.test(c) && /lucide/.test(c) && !/(up|down|top|bottom|vertical)/.test(c)) return 'right';
+ return null;
+ }
+ function dirFromAria(label) {
+ const l = (label || '').toLowerCase();
+ if (/\\b(previous|prev|back|scroll left|go left|collapse sidebar|expand row|expand group)\\b/.test(l)) return 'ctx';
+ if (/\\b(next|forward|scroll right|go right)\\b/.test(l)) return 'ctx';
+ return null;
+ }
+ // Walk up from the icon to find the element whose computed transform is the
+ // mirror (scaleX). Returns {transform, matchedMirror}.
+ function mirrorTransformFor(iconEl) {
+ let el = iconEl;
+ let steps = 0;
+ while (el && steps < 6) {
+ const tf = getComputedStyle(el).transform;
+ if (tf && tf !== 'none') {
+ const m = tf.match(/matrix\\(([^)]+)\\)/);
+ if (m) {
+ const p = m[1].split(',').map(v => parseFloat(v.trim()));
+ // horizontal flip present anywhere in the chain
+ if (Math.abs(p[0] + 1) < 0.01 && Math.abs(p[1]) < 0.01 && Math.abs(p[2]) < 0.01 && Math.abs(p[3] - 1) < 0.01) {
+ return {transform: tf, flip: true};
+ }
+ }
+ }
+ el = el.parentElement;
+ steps++;
+ }
+ return {transform: 'none', flip: false};
+ }
+ const svgs = Array.from(document.querySelectorAll('svg'));
+ const found = [];
+ const seenPaths = new Set();
+ for (const svg of svgs) {
+ // classify
+ const pathEls = Array.from(svg.querySelectorAll('path'));
+ const dcat = pathEls.map(p => norm(p.getAttribute('d'))).join('|');
+ let dir = null;
+ // 1) path signature
+ for (const p of pathEls) {
+ const nd = norm(p.getAttribute('d'));
+ if (LEFT_PATHS.has(nd)) { dir = 'left'; break; }
+ if (RIGHT_PATHS.has(nd)) { dir = 'right'; break; }
+ }
+ // 2) lucide class on svg
+ if (!dir) dir = dirFromClass(svg.getAttribute('class'));
+ if (!dir) {
+ // some icon spans put the lucide class on the wrapping span
+ const wrapCls = (svg.closest('[class*=lucide]')?.getAttribute('class')) || '';
+ dir = dirFromClass(wrapCls);
+ }
+ if (!dir) continue; // non-directional -> skip
+ // Skip icons that are not actually rendered (0x0 box): they are hidden
+ // inside a collapsed disclosure surface (popover/menu) that our reveal
+ // step could not open, so their mirror transform can't be evaluated. Such
+ // an icon must NOT count as a directional finding — otherwise a closed
+ // popover would false-flag it as not-RTL. If reveal opened the surface the
+ // icon has a real box and IS scanned.
+ const box = svg.getBoundingClientRect();
+ if (box.width < 1 || box.height < 1) continue;
+ // dedupe by (direction + path signature) so a repeated glyph (e.g. many
+ // tree rows) is reported once
+ const key = dir + '::' + dcat;
+ if (seenPaths.has(key)) continue;
+ seenPaths.add(key);
+ const btn = svg.closest('button,[role=button],a');
+ const aria = btn ? (btn.getAttribute('aria-label') || '') : '';
+ const {transform, flip} = mirrorTransformFor(svg);
+ found.push({dir, aria: aria.slice(0, 40), pathSig: dcat.slice(0, 40), transform, flip});
+ }
+ return found;
+})()
+`;
+
+async function detectDirectionalIcons(page) {
+ return page.evaluate(DETECTOR).catch(() => []);
+}
+
+// ===========================================================================
+// AUTO-DISCOVERY: D5 positional-mirror
+// ===========================================================================
+// Catches a bug class that D1 (icon-mirror) and the `@astryx/no-physical-
+// properties` lint BOTH miss: an element positioned with a LOGICAL anchor
+// (insetInlineStart/End, which DOES flip under RTL) paired with an UNFLIPPED
+// PHYSICAL transform (translate/translateX in a `matrix()`, which does NOT
+// flip). The physical translate over/under-shifts the box relative to its
+// mirrored anchor, so the element lands on the WRONG SIDE in RTL. Lint can't
+// see this: each property is individually "fine" (a logical inset is
+// encouraged; a transform is not a physical *inset* prop) — the bug is the
+// *interaction* of the two at layout time, which only a rendered LTR-vs-RTL
+// geometry comparison reveals.
+//
+// Detector (in-page): find every `position: absolute|fixed` element whose
+// computed transform has a non-zero horizontal translate component (matrix()
+// e-value / matrix3d 12th), and record its center-X relative to its
+// offsetParent. We then assert the RTL center mirrors the LTR center about the
+// parent's horizontal center: rtl_relCenterX ≈ parentW − ltr_relCenterX.
+//
+// MANDATORY degenerate-parent guard: skip any candidate whose offsetParent is
+// < 8px wide. A ~1px-wide parent (e.g. the ResizeHandle divider) makes the
+// mirror target ≈ its own coordinate, producing a spurious "already mirrored"
+// or "wildly off" reading that is pure noise — the spike's single false
+// positive came from exactly this, and the guard removes it.
+const PM_DETECTOR = /* js */ `
+(() => {
+ function parseMatrixX(t) {
+ if (!t || t === 'none') return null;
+ let m = t.match(/^matrix\\(([^)]+)\\)/);
+ if (m) { const p = m[1].split(',').map(s => parseFloat(s)); return p[4]; } // e
+ m = t.match(/^matrix3d\\(([^)]+)\\)/);
+ if (m) { const p = m[1].split(',').map(s => parseFloat(s)); return p[12]; }
+ return null;
+ }
+ const out = [];
+ let idx = 0;
+ for (const el of document.querySelectorAll('*')) {
+ const cs = getComputedStyle(el);
+ if (cs.position !== 'absolute' && cs.position !== 'fixed') continue;
+ const tx = parseMatrixX(cs.transform);
+ if (tx === null || Math.abs(tx) < 0.5) continue; // needs a horizontal translate
+ const parent = el.offsetParent || el.parentElement;
+ if (!parent) continue;
+ const er = el.getBoundingClientRect();
+ const pr = parent.getBoundingClientRect();
+ // MANDATORY degenerate-parent guard: a sub-8px parent makes the mirror
+ // target meaningless (self-referential) -> pure noise. Skip it.
+ if (pr.width < 8) continue;
+ // Skip 0x0 (unrendered / collapsed) candidates: no meaningful geometry.
+ if (er.width < 1 && er.height < 1) continue;
+ // Full-span guard: an element whose own width ≈ its parent width spans the
+ // ENTIRE parent (it occupies both halves), so "which side it lands on" is
+ // undefined — it cannot exhibit the wrong-side bug this dimension targets.
+ // These are hit-areas / full-width bars that are anchored inset:0/0 and
+ // carry a purely-visual centering translate (e.g. the useResizable vertical
+ // divider hit-area: a 1134px-wide bar in a 1134px parent, translated left by
+ // half its width so its geometric CENTER sits at the parent's left edge —
+ // relCenterX≈0 in BOTH directions, which the center guard misses because the
+ // center is at the edge while the body fills the parent). A REAL wrong-side
+ // bug (Avatar status-dot, ResizeHandle pill) is a SMALL element (width ≪
+ // parent) sitting at one edge, so it is unaffected. Threshold: element width
+ // ≥ 90% of parent width.
+ if (er.width >= pr.width * 0.9) continue;
+ const relCenterX = (er.left + er.width / 2) - pr.left;
+ // Centered-element guard: an element horizontally centered in its parent
+ // mirrors to ITSELF (expected == actual), so it can never exhibit the
+ // "wrong side" bug this dimension targets. Skipping it removes benign
+ // noise: e.g. a VERTICAL Slider thumb is X-centered (insetInlineStart:50%
+ // + translateX) and any residual few-to-tens-of-px asymmetry from a
+ // physical centering translate that lacks an RTL flip is cosmetically
+ // irrelevant on a vertical control and NOT a wrong-side error — but would
+ // otherwise false-flag. A real wrong-side bug (Avatar status-dot) sits at
+ // the parent EDGE, far from center, so it is unaffected. Threshold: within
+ // 5% of parent width of the parent's horizontal center.
+ if (Math.abs(relCenterX - pr.width / 2) < pr.width * 0.05) continue;
+ out.push({
+ idx: idx++,
+ tag: el.tagName.toLowerCase(),
+ cls: (el.className && el.className.toString().slice(0, 48)) || '',
+ parentW: pr.width,
+ relCenterX,
+ });
+ }
+ return out;
+})()
+`;
+
+async function detectPositioned(page) {
+ return page.evaluate(PM_DETECTOR).catch(() => []);
+}
+
+// Auto-discovery D5 for one story: compare LTR vs RTL positioned-element
+// centers about their offsetParent. Reuses settle() + the reveal step so
+// interaction-gated positioned elements (dialogs/popovers/menus) are covered,
+// not just static ones.
+const PM_TOL = Number(process.env.PM_TOL || 3); // px tolerance (signal gap was ~10x)
+
+async function autoPositionalMirror(page, port, storyId, component) {
+ const card = {component, storyId, dim: 'D5-positional', verdict: 'N-A', notes: [], candidates: 0, fails: []};
+ await page.goto(storyUrl(port, storyId, false), {waitUntil: 'domcontentloaded'});
+ await settle(page);
+ const revealedL = PM_REVEAL ? await revealInteractionGated(page) : false;
+ const ltr = await detectPositioned(page);
+ await page.goto(storyUrl(port, storyId, true), {waitUntil: 'domcontentloaded'});
+ await settle(page);
+ const revealedR = PM_REVEAL ? await revealInteractionGated(page) : false;
+ const rtl = await detectPositioned(page);
+ if (revealedL || revealedR) card.notes.push('opened an interaction-gated surface before scanning');
+
+ if (ltr.length === 0 && rtl.length === 0) {
+ card.notes.push('no logical-anchor + physical-transform candidates');
+ return card;
+ }
+ card.candidates = Math.max(ltr.length, rtl.length);
+
+ // Pair LTR<->RTL candidates by DOM index (stable across directions in all
+ // tested stories). Assert the RTL center mirrors the LTR center about the
+ // parent's horizontal center.
+ const n = Math.min(ltr.length, rtl.length);
+ let anyFail = false;
+ const perEl = [];
+ for (let i = 0; i < n; i++) {
+ const L = ltr[i], R = rtl[i];
+ const expectedRtlCX = L.parentW - L.relCenterX; // mirror about parent center
+ const delta = Math.abs(R.relCenterX - expectedRtlCX);
+ const mirrored = delta <= PM_TOL;
+ if (!mirrored) {
+ anyFail = true;
+ card.fails.push({
+ cls: L.cls,
+ tag: L.tag,
+ parentW: Math.round(L.parentW),
+ ltrRelCenterX: Math.round(L.relCenterX * 10) / 10,
+ rtlRelCenterX: Math.round(R.relCenterX * 10) / 10,
+ expectedRtlCenterX: Math.round(expectedRtlCX * 10) / 10,
+ delta: Math.round(delta * 10) / 10,
+ });
+ }
+ perEl.push({idx: i, cls: L.cls, delta: Math.round(delta * 10) / 10, mirrored});
+ }
+ card.perEl = perEl;
+ if (anyFail) {
+ card.verdict = 'fail';
+ card.notes.push(
+ `positioned element(s) land on the wrong side in RTL: ` +
+ card.fails
+ .map(f => `${f.cls || f.tag} (LTR cx ${f.ltrRelCenterX} → RTL cx ${f.rtlRelCenterX}, expected ~${f.expectedRtlCenterX}, Δ${f.delta}px)`)
+ .join('; '),
+ );
+ } else {
+ card.verdict = 'pass';
+ card.notes.push(`every positioned candidate mirrors about its parent center (≤${PM_TOL}px)`);
+ }
+ return card;
+}
+
+// Auto-discovery D1 for one story: compare LTR vs RTL directional-icon flip.
+async function autoD1(page, port, storyId, component) {
+ const card = {component, storyId, dim: 'D1', verdict: 'N-A', notes: [], icons: 0};
+ await page.goto(storyUrl(port, storyId, false), {waitUntil: 'domcontentloaded'});
+ await settle(page);
+ const revealedL = await revealInteractionGated(page);
+ const ltr = await detectDirectionalIcons(page);
+ await page.goto(storyUrl(port, storyId, true), {waitUntil: 'domcontentloaded'});
+ await settle(page);
+ const revealedR = await revealInteractionGated(page);
+ const rtl = await detectDirectionalIcons(page);
+ if (revealedL || revealedR) card.notes.push('opened an interaction-gated surface before scanning');
+
+ if (ltr.length === 0 && rtl.length === 0) {
+ card.verdict = 'N-A';
+ card.notes.push('no directional icons');
+ return card;
+ }
+ card.icons = Math.max(ltr.length, rtl.length);
+
+ // Pair LTR<->RTL directional icons by aria-context (fallback: positional
+ // index) and evaluate EACH pair, so a two-button name-swap (prev/next) is
+ // seen per-button rather than washed out by a global multiset.
+ const keyOf = (i, idx) => (i.aria && i.aria.trim() ? 'aria:' + i.aria.trim() : 'idx:' + idx);
+ const ltrBy = new Map();
+ ltr.forEach((i, idx) => ltrBy.set(keyOf(i, idx), i));
+ const rtlBy = new Map();
+ rtl.forEach((i, idx) => rtlBy.set(keyOf(i, idx), i));
+ const keys = new Set([...ltrBy.keys(), ...rtlBy.keys()]);
+
+ let anyMirrored = false; // at least one directional icon is handled (flip or swap)
+ let anyUnhandled = false; // at least one directional icon neither flips nor swaps
+ let anyDoubleFlip = false;
+ const perIcon = [];
+ for (const k of keys) {
+ const L = ltrBy.get(k), R = rtlBy.get(k);
+ // transform-mirror: RTL flips while LTR is identity
+ const mirrored = R && R.flip && (!L || !L.flip);
+ // name-swap: the rendered glyph direction changed left<->right for this icon
+ const swapped = L && R && L.dir !== R.dir && L.dir !== null && R.dir !== null;
+ // double-flip: flip present in BOTH dirs -> nets to no visible mirror
+ const doubleFlip = L && R && L.flip && R.flip;
+ if (mirrored || swapped) anyMirrored = true;
+ else if (doubleFlip) { anyDoubleFlip = true; anyUnhandled = true; }
+ else anyUnhandled = true;
+ perIcon.push({icon: k, ltrDir: L?.dir, rtlDir: R?.dir, ltrFlip: !!L?.flip, rtlFlip: !!R?.flip, mirrored: !!mirrored, swapped: !!swapped});
+ }
+
+ // A component is RTL-ready for D1 iff EVERY directional icon is handled
+ // (flips or swaps) and none double-flips. Any unhandled directional icon =>
+ // not-RTL (the "shipped without RTL handling" signal).
+ if (!anyUnhandled && anyMirrored) {
+ card.verdict = 'pass';
+ card.notes.push('every directional icon mirrors (transform-flip and/or name-swap)');
+ } else if (anyDoubleFlip) {
+ card.verdict = 'fail';
+ card.notes.push('double-flip: a directional icon is flipped in BOTH LTR and RTL (nets to no mirror)');
+ } else {
+ card.verdict = 'fail';
+ const bad = perIcon.filter(p => !p.mirrored && !p.swapped).map(p => p.icon);
+ card.notes.push(`directional glyph never mirrors: ${bad.join(', ')}`);
+ }
+ card.perIcon = perIcon;
+ card._ltr = ltr;
+ card._rtl = rtl;
+ return card;
+}
+
+// ===========================================================================
+// CURATED precision dims (D2/D3/D4) — hand selectors from targets.json
+// ===========================================================================
+async function checkD2(page, port, t, card) {
+ const {prev, next} = t.selectors;
+ await page.goto(storyUrl(port, t.storyId, false), {waitUntil: 'domcontentloaded'});
+ await settle(page); await doSetup(page, t);
+ const pL = await boxOf(page, prev), nL = await boxOf(page, next);
+ await page.goto(storyUrl(port, t.storyId, true), {waitUntil: 'domcontentloaded'});
+ await settle(page); await doSetup(page, t);
+ const pR = await boxOf(page, prev), nR = await boxOf(page, next);
+ if (!pL || !nL || !pR || !nR) { card.dims.D2 = 'N-A'; card.notes.push('D2: prev/next not found'); return; }
+ const ltrOk = pL.cx < nL.cx, rtlOk = pR.cx > nR.cx;
+ card.dims.D2 = ltrOk && rtlOk ? 'pass' : ltrOk || rtlOk ? 'partial' : 'fail';
+ card.notes.push(`D2 prev/next cx: LTR ${pL.cx.toFixed(0)}<${nL.cx.toFixed(0)}=${ltrOk}; RTL ${pR.cx.toFixed(0)}>${nR.cx.toFixed(0)}=${rtlOk}`);
+}
+async function checkD3Scroll(page, port, t, card) {
+ const {scroller, nextButton} = t.selectors;
+ const run = async rtl => {
+ await page.goto(storyUrl(port, t.storyId, rtl), {waitUntil: 'domcontentloaded'});
+ await settle(page); await doSetup(page, t);
+ const before = await page.locator(scroller).first().evaluate(el => el.scrollLeft).catch(() => null);
+ await page.locator(nextButton).first().click({timeout: 2500}).catch(() => {});
+ await page.waitForTimeout(500);
+ const after = await page.locator(scroller).first().evaluate(el => el.scrollLeft).catch(() => null);
+ return before == null || after == null ? null : after - before;
+ };
+ const dL = await run(false), dR = await run(true);
+ if (dL == null || dR == null) { card.dims.D3 = 'N-A'; card.notes.push('D3: scroller/next not found'); return; }
+ const ltrOk = dL > 1, rtlOk = dR < -1;
+ card.dims.D3 = ltrOk && rtlOk ? 'pass' : ltrOk || rtlOk ? 'partial' : 'fail';
+ card.notes.push(`D3 scroll delta on next: LTR ${dL.toFixed(0)} (>0=${ltrOk}); RTL ${dR.toFixed(0)} (<0=${rtlOk})`);
+}
+async function checkD4(page, port, t, card) {
+ const {overlay, overlayRoot} = t.selectors;
+ await page.goto(storyUrl(port, t.storyId, false), {waitUntil: 'domcontentloaded'});
+ await settle(page); await doSetup(page, t);
+ const oL = await boxOf(page, overlay), rL = await boxOf(page, overlayRoot || 'body');
+ await page.goto(storyUrl(port, t.storyId, true), {waitUntil: 'domcontentloaded'});
+ await settle(page); await doSetup(page, t);
+ const oR = await boxOf(page, overlay), rR = await boxOf(page, overlayRoot || 'body');
+ if (!oL || !rL || !oR || !rR) { card.dims.D4 = 'N-A'; card.notes.push('D4: overlay/root not found'); return; }
+ const sideL = (oL.cx - rL.x) / rL.width, sideR = (oR.cx - rR.x) / rR.width;
+ const flipped = sideL < 0.5 !== sideR < 0.5 && Math.abs(sideR - (1 - sideL)) < 0.25;
+ card.dims.D4 = flipped ? 'pass' : Math.abs(sideR - sideL) < 0.05 ? 'fail' : 'partial';
+ card.notes.push(`D4 overlay side frac: LTR ${sideL.toFixed(2)} RTL ${sideR.toFixed(2)} flipped=${flipped}`);
+}
+
+async function scoreCurated(page, port, t) {
+ const card = {component: t.component, storyId: t.storyId, dims: {}, notes: []};
+ for (const dim of t.dims) {
+ try {
+ if (dim === 'D2') await checkD2(page, port, t, card);
+ else if (dim === 'D3') await checkD3Scroll(page, port, t, card);
+ else if (dim === 'D4') await checkD4(page, port, t, card);
+ // D1 is handled by auto-discovery; ignore any stray D1 in curated entries.
+ } catch (e) {
+ card.dims[dim] = 'ERROR';
+ card.notes.push(`${dim} threw: ${String(e).slice(0, 160)}`);
+ }
+ }
+ const vals = Object.entries(card.dims).filter(([, v]) => v !== 'N-A');
+ const anyFail = vals.some(([, v]) => v === 'fail' || v === 'ERROR');
+ const allPass = vals.length > 0 && vals.every(([, v]) => v === 'pass');
+ card.rollup = vals.length === 0 ? 'N-A' : allPass ? 'RTL-ready' : anyFail ? 'not-RTL' : 'partial';
+ return card;
+}
+
+// ---------------------------------------------------------------------------
+function componentFromId(id) {
+ // core-tabletree--default -> TableTree (best-effort display name)
+ const seg = id.replace(/^core-/, '').split('--')[0];
+ return seg;
+}
+
+(async () => {
+ const {server, port} = await serve(path.resolve(DIST));
+ const browser = await chromium.launch();
+ const page = await browser.newPage({viewport: {width: 1100, height: 760}, deviceScaleFactor: 1});
+
+ let entries = {};
+ try {
+ entries = JSON.parse(fs.readFileSync(path.join(DIST, 'index.json'), 'utf8')).entries || {};
+ } catch (e) {
+ console.error('FATAL: cannot read index.json:', String(e).slice(0, 120));
+ process.exit(2);
+ }
+
+ // ---- (A) auto-discovery over all core-* stories ----
+ const autoResults = []; // D1 icon-mirror
+ const pmResults = []; // D5 positional-mirror
+ if (!CURATED_ONLY) {
+ const storyIds = Object.keys(entries).filter(
+ id => entries[id].type === 'story' && id.startsWith('core-') && !/--docs$/.test(id),
+ );
+ // D1 runs one representative story per component (extra stories add little
+ // D1 signal). D5 (positional-mirror) runs over EVERY core story — a
+ // positioned bug can be story-specific (only a `withStatus` variant mounts
+ // the offending element), so we don't collapse to one-per-component.
+ const perComponent = new Map();
+ for (const id of storyIds) {
+ const comp = componentFromId(id);
+ if (!perComponent.has(comp)) perComponent.set(comp, id);
+ }
+ for (const [comp, id] of perComponent) {
+ if (FILTER.length && !FILTER.includes(comp.toLowerCase())) continue;
+ try {
+ const card = await autoD1(page, port, id, comp);
+ autoResults.push(card);
+ if (card.verdict !== 'N-A') {
+ console.error(`AUTO ${card.verdict.toUpperCase().padEnd(4)} ${comp.padEnd(24)} icons=${card.icons}`);
+ }
+ } catch (e) {
+ autoResults.push({component: comp, storyId: id, dim: 'D1', verdict: 'ERROR', notes: [String(e).slice(0, 160)], icons: 0});
+ console.error(`AUTO ERROR ${comp}: ${String(e).slice(0, 120)}`);
+ }
+ }
+ // D5 positional-mirror over every core story.
+ for (const id of storyIds) {
+ const comp = componentFromId(id);
+ if (FILTER.length && !FILTER.includes(comp.toLowerCase())) continue;
+ try {
+ const card = await autoPositionalMirror(page, port, id, comp);
+ pmResults.push(card);
+ if (card.verdict !== 'N-A') {
+ console.error(`PM ${card.verdict.toUpperCase().padEnd(4)} ${comp.padEnd(24)} ${id.padEnd(40)} cand=${card.candidates}`);
+ }
+ } catch (e) {
+ pmResults.push({component: comp, storyId: id, dim: 'D5-positional', verdict: 'ERROR', notes: [String(e).slice(0, 160)], candidates: 0, fails: []});
+ console.error(`PM ERROR ${comp} ${id}: ${String(e).slice(0, 120)}`);
+ }
+ }
+ }
+
+ // ---- (B) curated precision dims ----
+ const curatedResults = [];
+ if (!AUTO_ONLY) {
+ let targets = [];
+ try { targets = JSON.parse(fs.readFileSync(TARGETS_PATH, 'utf8')); } catch {}
+ for (const t of targets) {
+ if (FILTER.length && !FILTER.includes(t.component.toLowerCase())) continue;
+ if (!entries[t.storyId]) {
+ curatedResults.push({component: t.component, storyId: t.storyId, rollup: 'MISSING-STORY', dims: {}, notes: ['story not in index.json']});
+ continue;
+ }
+ // skip if the entry only had D1 (now covered by auto-discovery)
+ const dims = (t.dims || []).filter(d => d !== 'D1');
+ if (dims.length === 0) continue;
+ try {
+ const card = await scoreCurated(page, port, {...t, dims});
+ curatedResults.push(card);
+ console.error(`CUR ${card.rollup.padEnd(10)} ${t.component.padEnd(20)} ${JSON.stringify(card.dims)}`);
+ } catch (e) {
+ curatedResults.push({component: t.component, storyId: t.storyId, rollup: 'ERROR', dims: {}, notes: [String(e).slice(0, 200)]});
+ }
+ }
+ }
+
+ await browser.close();
+ server.close();
+
+ const autoFails = autoResults.filter(r => r.verdict === 'fail' || r.verdict === 'ERROR');
+ // No allowlist: every not-RTL component is a surprise. The RTL migration is
+ // complete, so any directional icon that fails to mirror is a real regression.
+ const surprises = autoFails;
+ const pmFails = pmResults.filter(r => r.verdict === 'fail' || r.verdict === 'ERROR');
+ const report = {
+ generatedAt: new Date().toISOString(),
+ dist: DIST,
+ autoDiscovery: {
+ total: autoResults.length,
+ applicable: autoResults.filter(r => r.verdict !== 'N-A').length,
+ pass: autoResults.filter(r => r.verdict === 'pass').length,
+ fail: autoFails.length,
+ na: autoResults.filter(r => r.verdict === 'N-A').length,
+ surprises: surprises.map(r => r.component),
+ results: autoResults,
+ },
+ positionalMirror: {
+ total: pmResults.length,
+ applicable: pmResults.filter(r => r.verdict !== 'N-A').length,
+ pass: pmResults.filter(r => r.verdict === 'pass').length,
+ fail: pmFails.length,
+ na: pmResults.filter(r => r.verdict === 'N-A').length,
+ tolerancePx: PM_TOL,
+ // Avatar status-dot is a KNOWN-REAL bug on main: the dot uses a physical
+ // `right` anchor + `translate(50%,50%)`, so it stays bottom-right in RTL
+ // instead of mirroring to bottom-left. The fix is on the #4564 branch, not
+ // main — so on this branch (off main) D5 correctly flags Avatar. It is a
+ // real finding, NOT a false positive, and is left to surface (soft-gate =
+ // non-blocking). Documented so reviewers know it clears once #4564 lands.
+ knownRealPending: ['Avatar (status-dot) — real RTL bug on main, fix in #4564'],
+ // fails carry per-element cls + LTR/RTL relCenterX + delta (actionable).
+ results: pmResults,
+ },
+ curated: {results: curatedResults},
+ };
+ fs.writeFileSync(OUT, JSON.stringify(report, null, 2));
+ console.error(`\nWROTE ${OUT}`);
+ console.error(`AUTO: ${report.autoDiscovery.pass} pass / ${report.autoDiscovery.fail} fail (${surprises.length} surprise) / ${report.autoDiscovery.na} N-A`);
+ console.error(`PM : ${report.positionalMirror.pass} pass / ${report.positionalMirror.fail} fail / ${report.positionalMirror.na} N-A (tol ${PM_TOL}px)`);
+ // Non-zero exit only signals CI (which is soft/continue-on-error). Surface a
+ // signal but never let it hard-block during the stability window.
+ const anySignal =
+ autoFails.length > 0 ||
+ pmFails.length > 0 ||
+ curatedResults.some(r => r.rollup === 'not-RTL' || r.rollup === 'ERROR' || r.rollup === 'MISSING-STORY');
+ process.exit(anySignal ? 1 : 0);
+})();
diff --git a/apps/storybook/rtl-audit/targets.json b/apps/storybook/rtl-audit/targets.json
new file mode 100644
index 0000000000..98ea14703d
--- /dev/null
+++ b/apps/storybook/rtl-audit/targets.json
@@ -0,0 +1,38 @@
+[
+ {
+ "component": "Calendar",
+ "storyId": "core-calendar--default",
+ "dims": [
+ "D2"
+ ],
+ "selectors": {
+ "prev": "button[aria-label=\"Previous month\"]",
+ "next": "button[aria-label=\"Next month\"]"
+ }
+ },
+ {
+ "component": "Carousel",
+ "storyId": "core-carousel--default",
+ "dims": [
+ "D3"
+ ],
+ "selectors": {
+ "scroller": "[aria-roledescription=\"carousel\"] > div:first-child",
+ "nextButton": "button[aria-label=\"Scroll right\"]"
+ }
+ },
+ {
+ "component": "Lightbox",
+ "storyId": "core-lightbox--gallery",
+ "dims": [
+ "D2"
+ ],
+ "setup": {
+ "click": "img, [role=button]"
+ },
+ "selectors": {
+ "prev": "button[aria-label=\"Previous\"]",
+ "next": "button[aria-label=\"Next\"]"
+ }
+ }
+]
\ No newline at end of file