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.ymlindex ff45c55997..7f2ea0aeb9 100644--- a/.github/workflows/ci.yml+++ b/.github/workflows/ci.yml@@ -442,3 +442,135 @@ jobs:name: a11y-reportpath: a11y-report.jsonretention-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: 1diff --git a/.gitignore b/.gitignoreindex a6813c5560..af7661aacc 100644--- a/.gitignore+++ b/.gitignore@@ -11,6 +11,9 @@ storybook-static/# Test coveragecoverage/+# 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.jsonindex 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.mdnew file mode 100644index 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.mjsnew file mode 100644index 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.jsonnew file mode 100644index 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