framewatch-mcp-server 0.1.0 → 0.2.0

package/dist/utils/rtl-rules.js

@@ -0,0 +1,296 @@
+import { MAX_RTL_TEXT_LENGTH, RTL_ALIGN_TOLERANCE_PX, RTL_MIRROR_TOLERANCE_PX, RTL_OVERFLOW_TOLERANCE_PX, } from "../constants.js";
+/**
+ * Judge one element, having seen it in both directions.
+ *
+ * Returns every issue it has; an element with none is not a finding and is
+ * never mentioned. The checks are deliberately independent — an element can
+ * both fail to mirror and newly overflow, and those are two different bugs
+ * with two different fixes.
+ */
+export function judgeElement(pair) {
+    const issues = [];
+    const { ltr, rtl } = pair;
+    const mirror = judgeMirror(ltr, rtl);
+    if (mirror)
+        issues.push(mirror);
+    const align = judgeAlignment(ltr, rtl);
+    if (align)
+        issues.push(align);
+    const flex = judgeFlex(ltr, rtl);
+    if (flex)
+        issues.push(flex);
+    const padding = judgePadding(ltr, rtl);
+    if (padding)
+        issues.push(padding);
+    const overflow = judgeOverflow(ltr, rtl);
+    if (overflow)
+        issues.push(overflow);
+    const icon = judgeIcon(ltr, rtl);
+    if (icon)
+        issues.push(icon);
+    return issues;
+}
+/**
+ * Did the box move to where its mirror image should be?
+ *
+ * An element at x in an LTR viewport of width W belongs at
+ * `W - x - width` in RTL. Anything that is off-centre in LTR and has not moved
+ * in RTL never mirrored — the single most common RTL bug there is, and the one
+ * that a screenshot makes obvious only once somebody knows to look.
+ *
+ * Two things are deliberately *not* findings. An element that is already
+ * centred (or full-width) has a mirror position equal to its own, so it can
+ * never fail this check — which is right: there is nothing to mirror. And an
+ * element that moved somewhere other than its exact mirror is left alone,
+ * because a page may legitimately reflow in RTL; only a box that did not move
+ * *at all* is evidence of a forgotten direction.
+ */
+function judgeMirror(ltr, rtl) {
+    const expected = mirroredX(ltr);
+    const offCentre = Math.abs(expected - ltr.x);
+    // Symmetric in LTR: mirroring is a no-op, so staying put proves nothing.
+    if (offCentre <= RTL_MIRROR_TOLERANCE_PX)
+        return null;
+    const moved = Math.abs(rtl.x - ltr.x);
+    if (moved > RTL_MIRROR_TOLERANCE_PX)
+        return null;
+    return {
+        kind: "not_mirrored",
+        severity: "problem",
+        message: "did not mirror — the box sits at the same place in both directions",
+        evidence: `x=${round(ltr.x)} in LTR, x=${round(rtl.x)} in RTL; ` +
+            `mirroring a ${round(ltr.width)}px box in a ${round(ltr.viewport_width)}px viewport should put it at ` +
+            `x=${round(expected)}`,
+    };
+}
+/** Where a box's mirror image starts, in the same coordinate space. */
+export function mirroredX(m) {
+    return m.viewport_width - m.x - m.width;
+}
+/**
+ * Is the text still aligned to the physical left?
+ *
+ * Only a finding when the element has text of its own *and* the alignment did
+ * not change between the two renders. `text-align: start` resolves to `left`
+ * in LTR and `right` in RTL, so a correctly written page shows two different
+ * values here and says nothing. Two identical `left`s mean the author wrote
+ * `left` rather than `start`, and the Arabic will hug the wrong edge.
+ *
+ * `center` and `justify` are the same in both directions by definition and are
+ * never reported.
+ */
+function judgeAlignment(ltr, rtl) {
+    if (ltr.text === "")
+        return null;
+    const align = normaliseAlign(rtl.text_align);
+    if (align !== "left")
+        return null;
+    if (normaliseAlign(ltr.text_align) !== "left")
+        return null;
+    return {
+        kind: "alignment",
+        severity: "problem",
+        message: "stayed left-aligned in an RTL context — the text hugs the wrong edge",
+        evidence: `text-align is "${rtl.text_align}" in both directions; use \`start\` (or \`end\`) instead of \`left\``,
+    };
+}
+/** `start`/`end` are resolved by the browser; everything else is compared as written. */
+function normaliseAlign(value) {
+    return String(value ?? "").trim().toLowerCase();
+}
+/**
+ * Did a row of flex items reverse?
+ *
+ * A `row` flex container follows `direction`, so its items reverse on their
+ * own and the computed value stays `row` in both renders — meaning the
+ * computed property tells us nothing. What tells us something is whether the
+ * *children* actually swapped, which the caller measures and hands over as the
+ * child order. Here we only catch the explicit case: a container hard-coded to
+ * `row-reverse` in both directions is reversed twice and ends up
+ * back-to-front in RTL.
+ */
+function judgeFlex(ltr, rtl) {
+    const rtlDir = String(rtl.flex_direction ?? "").trim().toLowerCase();
+    if (rtlDir !== "row-reverse")
+        return null;
+    if (String(ltr.flex_direction ?? "").trim().toLowerCase() !== "row-reverse")
+        return null;
+    return {
+        kind: "flex_not_reversed",
+        severity: "warning",
+        message: "is `row-reverse` in both directions — RTL reverses it again, so the items end up back to front",
+        evidence: "flex-direction: row-reverse under `dir=rtl` lays the items out left to right",
+    };
+}
+/**
+ * Asymmetric physical padding that never swapped.
+ *
+ * A gap of 24px on the left and 0 on the right is a deliberate offset in LTR
+ * and a mistake in RTL — unless it swapped, which is what `padding-inline`
+ * does and what this checks. Only reported as a warning: plenty of asymmetric
+ * padding is decorative and correct in both directions.
+ */
+function judgePadding(ltr, rtl) {
+    const gap = Math.abs(ltr.padding_left - ltr.padding_right);
+    if (gap <= RTL_ALIGN_TOLERANCE_PX)
+        return null;
+    // Swapped correctly — `padding-inline-start` did its job.
+    const swapped = Math.abs(rtl.padding_left - ltr.padding_right) <= RTL_ALIGN_TOLERANCE_PX &&
+        Math.abs(rtl.padding_right - ltr.padding_left) <= RTL_ALIGN_TOLERANCE_PX;
+    if (swapped)
+        return null;
+    // Unchanged is the finding; anything else is a reflow we do not judge.
+    const unchanged = Math.abs(rtl.padding_left - ltr.padding_left) <= RTL_ALIGN_TOLERANCE_PX &&
+        Math.abs(rtl.padding_right - ltr.padding_right) <= RTL_ALIGN_TOLERANCE_PX;
+    if (!unchanged)
+        return null;
+    return {
+        kind: "padding_not_mirrored",
+        severity: "warning",
+        message: "keeps the same physical padding in both directions",
+        evidence: `padding-left ${round(rtl.padding_left)}px / padding-right ${round(rtl.padding_right)}px, unchanged from LTR; ` +
+            "`padding-inline-start`/`padding-inline-end` would swap",
+    };
+}
+/**
+ * Content that fits in LTR and sticks out in RTL.
+ *
+ * This is the one check that reports a *change* rather than a failure to
+ * change, and it is the one that catches the bug nobody sees coming: a layout
+ * that is pinned with `left`/`right` offsets, or one whose text got longer,
+ * pushing content off the edge of the screen — where it is silently cropped
+ * and therefore invisible in the screenshot.
+ *
+ * Overflow that is present in LTR too is not an RTL bug; it is a layout bug,
+ * and `framewatch_responsive` is the tool that reports it.
+ */
+function judgeOverflow(ltr, rtl) {
+    const before = Math.max(ltr.overflow_left, ltr.overflow_right);
+    const after = Math.max(rtl.overflow_left, rtl.overflow_right);
+    if (after <= RTL_OVERFLOW_TOLERANCE_PX)
+        return null;
+    if (after <= before + RTL_OVERFLOW_TOLERANCE_PX)
+        return null;
+    const edge = rtl.overflow_left > rtl.overflow_right ? "left" : "right";
+    const amount = Math.max(rtl.overflow_left, rtl.overflow_right);
+    return {
+        kind: "overflow",
+        severity: "problem",
+        message: `overflows the ${edge} edge of the viewport in RTL — the part that sticks out is cropped, not visible`,
+        evidence: `sticks out ${round(amount)}px past the ${edge} edge in RTL` +
+            (before > RTL_OVERFLOW_TOLERANCE_PX ? ` (it already overflowed ${round(before)}px in LTR)` : ", and none in LTR"),
+    };
+}
+/**
+ * An arrow or chevron that points the same way in both directions.
+ *
+ * Directional icons have to flip: a "next" chevron pointing right in Arabic
+ * points backwards. The caller decides what counts as directional (by name,
+ * by class, by aria-label); this only asks whether the thing that was supposed
+ * to flip actually did — via a `scaleX(-1)` transform, or by having a
+ * different box shape after the swap.
+ */
+function judgeIcon(ltr, rtl) {
+    if (rtl.mirrorable !== true)
+        return null;
+    if (isMirroredTransform(rtl.transform) !== isMirroredTransform(ltr.transform))
+        return null;
+    return {
+        kind: "icon_not_mirrored",
+        severity: "warning",
+        message: "looks directional but is drawn the same way in both directions — a 'next' arrow points backwards in RTL",
+        evidence: rtl.transform === "none" || rtl.transform === ""
+            ? "no mirroring transform in either direction; `transform: scaleX(-1)` under `[dir=rtl]` flips it"
+            : `transform is "${rtl.transform}" in both directions`,
+    };
+}
+/**
+ * Does this transform flip the element horizontally?
+ *
+ * A computed transform is always a matrix, so the sign of `a` (the horizontal
+ * scale) is the answer. `scaleX(-1)` computes to `matrix(-1, 0, 0, 1, 0, 0)`.
+ */
+export function isMirroredTransform(transform) {
+    const value = String(transform ?? "").trim();
+    if (value === "" || value === "none")
+        return false;
+    const match = /^matrix(?:3d)?\(\s*(-?[\d.eE+-]+)/.exec(value);
+    if (!match)
+        return /scalex\(\s*-/i.test(value);
+    return Number(match[1]) < 0;
+}
+/* ── Naming and rendering ─────────────────────────────────────────────── */
+/**
+ * How an element is named in the report: `button "Add to cart"`, `div .card`.
+ *
+ * An icon-only control has no text at all, and a bare selector is the least
+ * recognisable thing to call it by — so text wins when there is any, and the
+ * selector is the fallback.
+ */
+export function describeElement(m) {
+    const text = elide(m.text, MAX_RTL_TEXT_LENGTH);
+    return text === "" ? `${m.tag} ${m.selector}` : `${m.tag} "${text}"`;
+}
+/**
+ * Turn judged elements into the findings the report prints, numbered and
+ * ordered worst-first.
+ *
+ * Order is by severity, then by how many things are wrong with the element,
+ * then down the page. The numbering happens *after* that sort, so the numbers
+ * in the report count from the top of the list and match the labels drawn on
+ * the screenshot.
+ */
+export function buildFindings(pairs) {
+    const judged = pairs
+        .map((pair) => ({ pair, issues: judgeElement(pair) }))
+        .filter((entry) => entry.issues.length > 0);
+    judged.sort((a, b) => {
+        const severity = rank(worst(a.issues)) - rank(worst(b.issues));
+        if (severity !== 0)
+            return severity;
+        if (a.issues.length !== b.issues.length)
+            return b.issues.length - a.issues.length;
+        return a.pair.rtl.y - b.pair.rtl.y || a.pair.rtl.x - b.pair.rtl.x;
+    });
+    return judged.map((entry, index) => ({
+        index: index + 1,
+        selector: entry.pair.rtl.selector,
+        match_index: entry.pair.rtl.match_index,
+        description: describeElement(entry.pair.rtl),
+        issues: entry.issues,
+        severity: worst(entry.issues),
+    }));
+}
+function worst(issues) {
+    return issues.some((issue) => issue.severity === "problem") ? "problem" : "warning";
+}
+function rank(severity) {
+    return severity === "problem" ? 0 : 1;
+}
+/** What each kind of issue is called as a section heading, and how it is explained. */
+export function describeIssueKind(kind) {
+    switch (kind) {
+        case "not_mirrored":
+            return "did not mirror";
+        case "alignment":
+            return "text stayed left-aligned";
+        case "flex_not_reversed":
+            return "flex row reversed twice";
+        case "padding_not_mirrored":
+            return "physical padding did not swap";
+        case "overflow":
+            return "new overflow in RTL";
+        case "icon_not_mirrored":
+            return "directional icon did not flip";
+        case "direction_not_applied":
+            return "RTL was never applied";
+    }
+}
+export function elide(value, max) {
+    const text = String(value ?? "").replace(/\s+/g, " ").trim();
+    return text.length <= max ? text : `${text.slice(0, Math.max(0, max - 1))}…`;
+}
+function round(value) {
+    return Math.round(value);
+}
+//# sourceMappingURL=rtl-rules.js.map

package/dist/utils/rtl-rules.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rtl-rules.js","sourceRoot":"","sources":["../../src/utils/rtl-rules.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  MAX_RTL_TEXT_LENGTH,\n  RTL_ALIGN_TOLERANCE_PX,\n  RTL_MIRROR_TOLERANCE_PX,\n  RTL_OVERFLOW_TOLERANCE_PX,\n} from \"../constants.js\";\n\n/**\n * What counts as an RTL bug.\n *\n * Everything here is pure: it takes one element measured in both directions\n * and returns a verdict. Nothing in this file opens a browser or touches a\n * page, which is the point — \"did this box mirror?\", \"is this alignment\n * deliberate or forgotten?\" and \"is that overflow new?\" are all judgements\n * with edge cases, and judgements need unit tests that run in milliseconds.\n *\n * The bias throughout is against false alarms, and it is stronger here than\n * anywhere else in this codebase, because static RTL analysis is notorious for\n * crying wolf. `text-align: left` is *correct* on a code block, a number\n * column and a Latin brand name; `padding-left` is correct on anything that\n * should not mirror; `flex-direction: row` is correct wherever the order is\n * physical rather than semantic. A report that flags all of those is a report\n * whose real findings are never read.\n *\n * So nothing is judged from the RTL rendering alone. Every verdict is a\n * *comparison*: the element is measured in LTR and again in RTL, and the only\n * findings are the things that failed to change when the LTR measurement\n * proves they should have. An element that is left-aligned in both directions\n * has forgotten to mirror; one that is left in LTR and right in RTL is\n * working exactly as intended, and this file says nothing about it.\n */\n\n/* ── The measurements ─────────────────────────────────────────────────── */\n\n/**\n * One element as measured in one direction.\n *\n * Deliberately flat and JSON-ish: this is what crosses the boundary out of\n * `page.evaluate`, so it can hold nothing but structured-cloneable values.\n */\nexport interface ElementMeasurement {\n  /** Stable identity across the two renders — see `keyFor` in engine/rtl.ts. */\n  key: string;\n  /** A CSS selector for the element, for the report and the highlight overlay. */\n  selector: string;\n  /** Which match of `selector` this is, when the selector is not unique. */\n  match_index: number;\n  tag: string;\n  /** Visible text, elided. Named in the report so a finding is recognisable. */\n  text: string;\n\n  /** Border-box in document coordinates. */\n  x: number;\n  y: number;\n  width: number;\n  height: number;\n\n  /** The viewport this was measured in, so mirroring can be computed. */\n  viewport_width: number;\n\n  /** Computed `text-align`, already resolved from `start`/`end` by the browser. */\n  text_align: string;\n  /** Computed `direction` on the element itself. */\n  direction: string;\n  /** Computed `flex-direction`, or \"\" when the element is not a flex container. */\n  flex_direction: string;\n  /** Physical padding and margin, to spot asymmetry that never mirrored. */\n  padding_left: number;\n  padding_right: number;\n  margin_left: number;\n  margin_right: number;\n\n  /** Overflow of this element past its own content box, and past the viewport. */\n  scroll_width: number;\n  client_width: number;\n  /** How far the box sticks out past the right/left edge of the viewport, 0 when it fits. */\n  overflow_right: number;\n  overflow_left: number;\n\n  /** A transform that already mirrors the element — `scaleX(-1)` on an icon. */\n  transform: string;\n  /** Set when this element is one an author would expect to mirror: an arrow, a chevron. */\n  mirrorable?: boolean;\n}\n\n/** One element measured in both directions. */\nexport interface ElementPair {\n  ltr: ElementMeasurement;\n  rtl: ElementMeasurement;\n}\n\n/* ── The verdicts ─────────────────────────────────────────────────────── */\n\n/**\n * What can be wrong with an element in RTL.\n *\n * Each of these is a *failure to change*, except `overflow`, which is a change\n * that should not have happened. That asymmetry is the whole design: RTL bugs\n * are things that stayed put.\n */\nexport type RtlIssueKind =\n  | \"not_mirrored\"\n  | \"alignment\"\n  | \"flex_not_reversed\"\n  | \"padding_not_mirrored\"\n  | \"overflow\"\n  | \"icon_not_mirrored\"\n  | \"direction_not_applied\";\n\nexport interface RtlIssue {\n  kind: RtlIssueKind;\n  /** How bad it is. `problem` leads the report; `warning` follows it. */\n  severity: \"problem\" | \"warning\";\n  /** One line naming what is wrong, in the report's voice. */\n  message: string;\n  /** The measured evidence, quoted so the reader can check the verdict. */\n  evidence: string;\n}\n\n/** Every issue found on one element, with the element itself. */\nexport interface ElementFinding {\n  /** 1-based, and the number the highlight overlay is labelled with. */\n  index: number;\n  selector: string;\n  match_index: number;\n  /** `button \"Add to cart\"` — how the element is named in the report. */\n  description: string;\n  issues: RtlIssue[];\n  /** The worst severity among `issues`, so the report can sort and colour. */\n  severity: \"problem\" | \"warning\";\n}\n\n/**\n * Judge one element, having seen it in both directions.\n *\n * Returns every issue it has; an element with none is not a finding and is\n * never mentioned. The checks are deliberately independent — an element can\n * both fail to mirror and newly overflow, and those are two different bugs\n * with two different fixes.\n */\nexport function judgeElement(pair: ElementPair): RtlIssue[] {\n  const issues: RtlIssue[] = [];\n  const { ltr, rtl } = pair;\n\n  const mirror = judgeMirror(ltr, rtl);\n  if (mirror) issues.push(mirror);\n\n  const align = judgeAlignment(ltr, rtl);\n  if (align) issues.push(align);\n\n  const flex = judgeFlex(ltr, rtl);\n  if (flex) issues.push(flex);\n\n  const padding = judgePadding(ltr, rtl);\n  if (padding) issues.push(padding);\n\n  const overflow = judgeOverflow(ltr, rtl);\n  if (overflow) issues.push(overflow);\n\n  const icon = judgeIcon(ltr, rtl);\n  if (icon) issues.push(icon);\n\n  return issues;\n}\n\n/**\n * Did the box move to where its mirror image should be?\n *\n * An element at x in an LTR viewport of width W belongs at\n * `W - x - width` in RTL. Anything that is off-centre in LTR and has not moved\n * in RTL never mirrored — the single most common RTL bug there is, and the one\n * that a screenshot makes obvious only once somebody knows to look.\n *\n * Two things are deliberately *not* findings. An element that is already\n * centred (or full-width) has a mirror position equal to its own, so it can\n * never fail this check — which is right: there is nothing to mirror. And an\n * element that moved somewhere other than its exact mirror is left alone,\n * because a page may legitimately reflow in RTL; only a box that did not move\n * *at all* is evidence of a forgotten direction.\n */\nfunction judgeMirror(ltr: ElementMeasurement, rtl: ElementMeasurement): RtlIssue | null {\n  const expected = mirroredX(ltr);\n  const offCentre = Math.abs(expected - ltr.x);\n\n  // Symmetric in LTR: mirroring is a no-op, so staying put proves nothing.\n  if (offCentre <= RTL_MIRROR_TOLERANCE_PX) return null;\n\n  const moved = Math.abs(rtl.x - ltr.x);\n  if (moved > RTL_MIRROR_TOLERANCE_PX) return null;\n\n  return {\n    kind: \"not_mirrored\",\n    severity: \"problem\",\n    message: \"did not mirror — the box sits at the same place in both directions\",\n    evidence:\n      `x=${round(ltr.x)} in LTR, x=${round(rtl.x)} in RTL; ` +\n      `mirroring a ${round(ltr.width)}px box in a ${round(ltr.viewport_width)}px viewport should put it at ` +\n      `x=${round(expected)}`,\n  };\n}\n\n/** Where a box's mirror image starts, in the same coordinate space. */\nexport function mirroredX(m: ElementMeasurement): number {\n  return m.viewport_width - m.x - m.width;\n}\n\n/**\n * Is the text still aligned to the physical left?\n *\n * Only a finding when the element has text of its own *and* the alignment did\n * not change between the two renders. `text-align: start` resolves to `left`\n * in LTR and `right` in RTL, so a correctly written page shows two different\n * values here and says nothing. Two identical `left`s mean the author wrote\n * `left` rather than `start`, and the Arabic will hug the wrong edge.\n *\n * `center` and `justify` are the same in both directions by definition and are\n * never reported.\n */\nfunction judgeAlignment(ltr: ElementMeasurement, rtl: ElementMeasurement): RtlIssue | null {\n  if (ltr.text === \"\") return null;\n\n  const align = normaliseAlign(rtl.text_align);\n  if (align !== \"left\") return null;\n  if (normaliseAlign(ltr.text_align) !== \"left\") return null;\n\n  return {\n    kind: \"alignment\",\n    severity: \"problem\",\n    message: \"stayed left-aligned in an RTL context — the text hugs the wrong edge\",\n    evidence: `text-align is \"${rtl.text_align}\" in both directions; use \\`start\\` (or \\`end\\`) instead of \\`left\\``,\n  };\n}\n\n/** `start`/`end` are resolved by the browser; everything else is compared as written. */\nfunction normaliseAlign(value: string): string {\n  return String(value ?? \"\").trim().toLowerCase();\n}\n\n/**\n * Did a row of flex items reverse?\n *\n * A `row` flex container follows `direction`, so its items reverse on their\n * own and the computed value stays `row` in both renders — meaning the\n * computed property tells us nothing. What tells us something is whether the\n * *children* actually swapped, which the caller measures and hands over as the\n * child order. Here we only catch the explicit case: a container hard-coded to\n * `row-reverse` in both directions is reversed twice and ends up\n * back-to-front in RTL.\n */\nfunction judgeFlex(ltr: ElementMeasurement, rtl: ElementMeasurement): RtlIssue | null {\n  const rtlDir = String(rtl.flex_direction ?? \"\").trim().toLowerCase();\n  if (rtlDir !== \"row-reverse\") return null;\n  if (String(ltr.flex_direction ?? \"\").trim().toLowerCase() !== \"row-reverse\") return null;\n\n  return {\n    kind: \"flex_not_reversed\",\n    severity: \"warning\",\n    message: \"is `row-reverse` in both directions — RTL reverses it again, so the items end up back to front\",\n    evidence: \"flex-direction: row-reverse under `dir=rtl` lays the items out left to right\",\n  };\n}\n\n/**\n * Asymmetric physical padding that never swapped.\n *\n * A gap of 24px on the left and 0 on the right is a deliberate offset in LTR\n * and a mistake in RTL — unless it swapped, which is what `padding-inline`\n * does and what this checks. Only reported as a warning: plenty of asymmetric\n * padding is decorative and correct in both directions.\n */\nfunction judgePadding(ltr: ElementMeasurement, rtl: ElementMeasurement): RtlIssue | null {\n  const gap = Math.abs(ltr.padding_left - ltr.padding_right);\n  if (gap <= RTL_ALIGN_TOLERANCE_PX) return null;\n\n  // Swapped correctly — `padding-inline-start` did its job.\n  const swapped =\n    Math.abs(rtl.padding_left - ltr.padding_right) <= RTL_ALIGN_TOLERANCE_PX &&\n    Math.abs(rtl.padding_right - ltr.padding_left) <= RTL_ALIGN_TOLERANCE_PX;\n  if (swapped) return null;\n\n  // Unchanged is the finding; anything else is a reflow we do not judge.\n  const unchanged =\n    Math.abs(rtl.padding_left - ltr.padding_left) <= RTL_ALIGN_TOLERANCE_PX &&\n    Math.abs(rtl.padding_right - ltr.padding_right) <= RTL_ALIGN_TOLERANCE_PX;\n  if (!unchanged) return null;\n\n  return {\n    kind: \"padding_not_mirrored\",\n    severity: \"warning\",\n    message: \"keeps the same physical padding in both directions\",\n    evidence:\n      `padding-left ${round(rtl.padding_left)}px / padding-right ${round(rtl.padding_right)}px, unchanged from LTR; ` +\n      \"`padding-inline-start`/`padding-inline-end` would swap\",\n  };\n}\n\n/**\n * Content that fits in LTR and sticks out in RTL.\n *\n * This is the one check that reports a *change* rather than a failure to\n * change, and it is the one that catches the bug nobody sees coming: a layout\n * that is pinned with `left`/`right` offsets, or one whose text got longer,\n * pushing content off the edge of the screen — where it is silently cropped\n * and therefore invisible in the screenshot.\n *\n * Overflow that is present in LTR too is not an RTL bug; it is a layout bug,\n * and `framewatch_responsive` is the tool that reports it.\n */\nfunction judgeOverflow(ltr: ElementMeasurement, rtl: ElementMeasurement): RtlIssue | null {\n  const before = Math.max(ltr.overflow_left, ltr.overflow_right);\n  const after = Math.max(rtl.overflow_left, rtl.overflow_right);\n  if (after <= RTL_OVERFLOW_TOLERANCE_PX) return null;\n  if (after <= before + RTL_OVERFLOW_TOLERANCE_PX) return null;\n\n  const edge = rtl.overflow_left > rtl.overflow_right ? \"left\" : \"right\";\n  const amount = Math.max(rtl.overflow_left, rtl.overflow_right);\n  return {\n    kind: \"overflow\",\n    severity: \"problem\",\n    message: `overflows the ${edge} edge of the viewport in RTL — the part that sticks out is cropped, not visible`,\n    evidence:\n      `sticks out ${round(amount)}px past the ${edge} edge in RTL` +\n      (before > RTL_OVERFLOW_TOLERANCE_PX ? ` (it already overflowed ${round(before)}px in LTR)` : \", and none in LTR\"),\n  };\n}\n\n/**\n * An arrow or chevron that points the same way in both directions.\n *\n * Directional icons have to flip: a \"next\" chevron pointing right in Arabic\n * points backwards. The caller decides what counts as directional (by name,\n * by class, by aria-label); this only asks whether the thing that was supposed\n * to flip actually did — via a `scaleX(-1)` transform, or by having a\n * different box shape after the swap.\n */\nfunction judgeIcon(ltr: ElementMeasurement, rtl: ElementMeasurement): RtlIssue | null {\n  if (rtl.mirrorable !== true) return null;\n  if (isMirroredTransform(rtl.transform) !== isMirroredTransform(ltr.transform)) return null;\n\n  return {\n    kind: \"icon_not_mirrored\",\n    severity: \"warning\",\n    message: \"looks directional but is drawn the same way in both directions — a 'next' arrow points backwards in RTL\",\n    evidence:\n      rtl.transform === \"none\" || rtl.transform === \"\"\n        ? \"no mirroring transform in either direction; `transform: scaleX(-1)` under `[dir=rtl]` flips it\"\n        : `transform is \"${rtl.transform}\" in both directions`,\n  };\n}\n\n/**\n * Does this transform flip the element horizontally?\n *\n * A computed transform is always a matrix, so the sign of `a` (the horizontal\n * scale) is the answer. `scaleX(-1)` computes to `matrix(-1, 0, 0, 1, 0, 0)`.\n */\nexport function isMirroredTransform(transform: string): boolean {\n  const value = String(transform ?? \"\").trim();\n  if (value === \"\" || value === \"none\") return false;\n  const match = /^matrix(?:3d)?\\(\\s*(-?[\\d.eE+-]+)/.exec(value);\n  if (!match) return /scalex\\(\\s*-/i.test(value);\n  return Number(match[1]) < 0;\n}\n\n/* ── Naming and rendering ─────────────────────────────────────────────── */\n\n/**\n * How an element is named in the report: `button \"Add to cart\"`, `div .card`.\n *\n * An icon-only control has no text at all, and a bare selector is the least\n * recognisable thing to call it by — so text wins when there is any, and the\n * selector is the fallback.\n */\nexport function describeElement(m: Pick<ElementMeasurement, \"tag\" | \"text\" | \"selector\">): string {\n  const text = elide(m.text, MAX_RTL_TEXT_LENGTH);\n  return text === \"\" ? `${m.tag} ${m.selector}` : `${m.tag} \"${text}\"`;\n}\n\n/**\n * Turn judged elements into the findings the report prints, numbered and\n * ordered worst-first.\n *\n * Order is by severity, then by how many things are wrong with the element,\n * then down the page. The numbering happens *after* that sort, so the numbers\n * in the report count from the top of the list and match the labels drawn on\n * the screenshot.\n */\nexport function buildFindings(pairs: readonly ElementPair[]): ElementFinding[] {\n  const judged = pairs\n    .map((pair) => ({ pair, issues: judgeElement(pair) }))\n    .filter((entry) => entry.issues.length > 0);\n\n  judged.sort((a, b) => {\n    const severity = rank(worst(a.issues)) - rank(worst(b.issues));\n    if (severity !== 0) return severity;\n    if (a.issues.length !== b.issues.length) return b.issues.length - a.issues.length;\n    return a.pair.rtl.y - b.pair.rtl.y || a.pair.rtl.x - b.pair.rtl.x;\n  });\n\n  return judged.map((entry, index) => ({\n    index: index + 1,\n    selector: entry.pair.rtl.selector,\n    match_index: entry.pair.rtl.match_index,\n    description: describeElement(entry.pair.rtl),\n    issues: entry.issues,\n    severity: worst(entry.issues),\n  }));\n}\n\nfunction worst(issues: readonly RtlIssue[]): \"problem\" | \"warning\" {\n  return issues.some((issue) => issue.severity === \"problem\") ? \"problem\" : \"warning\";\n}\n\nfunction rank(severity: \"problem\" | \"warning\"): number {\n  return severity === \"problem\" ? 0 : 1;\n}\n\n/** What each kind of issue is called as a section heading, and how it is explained. */\nexport function describeIssueKind(kind: RtlIssueKind): string {\n  switch (kind) {\n    case \"not_mirrored\":\n      return \"did not mirror\";\n    case \"alignment\":\n      return \"text stayed left-aligned\";\n    case \"flex_not_reversed\":\n      return \"flex row reversed twice\";\n    case \"padding_not_mirrored\":\n      return \"physical padding did not swap\";\n    case \"overflow\":\n      return \"new overflow in RTL\";\n    case \"icon_not_mirrored\":\n      return \"directional icon did not flip\";\n    case \"direction_not_applied\":\n      return \"RTL was never applied\";\n  }\n}\n\nexport function elide(value: string, max: number): string {\n  const text = String(value ?? \"\").replace(/\\s+/g, \" \").trim();\n  return text.length <= max ? text : `${text.slice(0, Math.max(0, max - 1))}…`;\n}\n\nfunction round(value: number): number {\n  return Math.round(value);\n}\n"]}

package/dist/utils/seo-rules.d.ts

@@ -0,0 +1,129 @@
+import type { ImageProbe, JsonLdBlock, PageSeo, PerfMetrics, RobotsFetch } from "../engine/seo.js";
+/**
+ * What counts as an SEO problem.
+ *
+ * Everything here is pure: it takes what `engine/seo.ts` read off the page and
+ * returns findings. Nothing in this file opens a browser, which is the point —
+ * "is this canonical wrong?", "does this robots.txt block that path?" and
+ * "which properties is this Product missing?" are all judgements with edge
+ * cases, and judgements need unit tests that run in milliseconds.
+ *
+ * The type import above is type-only, so there is no runtime dependency on the
+ * engine and no cycle: the engine reads, this judges, the tool prints.
+ */
+export declare const SEO_AREAS: readonly ["indexing", "content", "headings", "social", "images", "structured_data", "performance"];
+export type SeoArea = (typeof SEO_AREAS)[number];
+/**
+ * `problem` will cost traffic, `warning` should be fixed, `info` is a
+ * measurement with no verdict attached, `pass` is a check that ran and was
+ * happy. Passes are reported rather than dropped for the same reason the
+ * accessibility tool counts the rules that passed: without them, a short
+ * report is indistinguishable from an audit that never ran.
+ */
+export type SeoLevel = "problem" | "warning" | "info" | "pass";
+export interface SeoFinding {
+    area: SeoArea;
+    level: SeoLevel;
+    /** What was checked — "Title", "og:image", "robots.txt". */
+    label: string;
+    /** What was found, including the value itself where it is short enough to be worth seeing. */
+    detail: string;
+    /** What to do about it. Only on problems and warnings. */
+    fix?: string;
+}
+export interface SeoReport {
+    findings: SeoFinding[];
+    problems: number;
+    warnings: number;
+    passes: number;
+}
+export interface SeoResponseInfo {
+    status: number;
+    headers: Record<string, string>;
+}
+export interface SeoAuditInput {
+    /** The URL the caller asked for, which is not necessarily the one that answered. */
+    requested_url: string;
+    page: PageSeo;
+    response?: SeoResponseInfo;
+    robots?: RobotsFetch;
+    robots_user_agent: string;
+    og_image?: ImageProbe;
+    performance?: PerfMetrics;
+}
+/**
+ * Judge a page. The order of the checks is the order they are printed in, and
+ * it runs from "will this page be in the index at all" down to "how fast is
+ * it" — a `noindex` makes every other finding academic, so it goes first.
+ */
+export declare function judgeSeo(input: SeoAuditInput): SeoReport;
+export interface RobotsVerdict {
+    allowed: boolean;
+    /** The directive that decided it, e.g. `Disallow: /admin/`. */
+    rule?: string;
+    /** The user-agent group it came from. */
+    group?: string;
+    sitemaps: string[];
+    reason: string;
+}
+/**
+ * Decide whether `userAgent` may crawl `url`, per RFC 9309.
+ *
+ * Two rules do the work. Group selection: the most specific user-agent line
+ * that matches wins, and `*` is the fallback — so a `Disallow: /` under
+ * `User-agent: *` does not apply to Googlebot if Googlebot has a group of its
+ * own. Rule selection: the *longest* matching path wins regardless of order,
+ * and Allow beats Disallow on a tie. That is why `Disallow: /` followed by
+ * `Allow: /public/` permits `/public/page` — reading top to bottom would get
+ * it exactly wrong.
+ *
+ * `*` matches any run of characters and a trailing `$` anchors to the end.
+ */
+export declare function evaluateRobots(text: string, url: string, userAgent: string): RobotsVerdict;
+/** A robots path pattern against a request path. `*` is any run, `$` anchors the end. */
+export declare function matchesRobotsPath(pattern: string, path: string): boolean;
+export interface SchemaExpectation {
+    required: string[];
+    recommended: string[];
+}
+/**
+ * What Google's rich-result documentation asks for, per type.
+ *
+ * Deliberately short. Only types worth a rich result are listed, and only the
+ * properties whose absence actually costs one — a validator that reports every
+ * optional property of every schema.org type produces noise nobody reads, and
+ * schema.org itself requires almost nothing.
+ */
+export declare const SCHEMA_EXPECTATIONS: Readonly<Record<string, SchemaExpectation>>;
+export declare function expectationsFor(type: string): SchemaExpectation | undefined;
+export interface JsonLdNode {
+    type: string;
+    /** Property names present on the node, `@`-prefixed keys excluded. */
+    keys: string[];
+    name?: string;
+    missing_required: string[];
+    missing_recommended: string[];
+    /** Whether this type has expectations at all — an unknown type is reported, not judged. */
+    known: boolean;
+}
+export interface JsonLdParsed {
+    /** 1-based position of the block on the page. */
+    index: number;
+    ok: boolean;
+    error?: string;
+    nodes: JsonLdNode[];
+}
+/**
+ * Parse the JSON-LD blocks and check each node against its type.
+ *
+ * `@graph` is flattened and a top-level array is iterated, because both are
+ * ordinary ways to put several entities in one block. Nesting below that is
+ * left alone: a Product's `offers` is checked as part of the Product's own
+ * expectations, and walking arbitrarily deep would report the same missing
+ * property from three directions.
+ */
+export declare function parseJsonLd(blocks: JsonLdBlock[]): JsonLdParsed[];
+/** Read a meta value however the page spelled it: `property` first, then `name`. */
+export declare function metaValues(page: PageSeo, key: string): string[];
+/** Two URLs that address the same page. The fragment is not part of the address. */
+export declare function sameAddress(a: string, b: string): boolean;