framewatch-mcp-server 0.1.1 → 0.2.0

package/dist/utils/mock-rules.js

@@ -0,0 +1,224 @@
+import { MAX_MOCK_URLS_LISTED, MAX_UNMATCHED_LISTED, MOCK_SLOW_DELAY_MS, } from "../constants.js";
+/**
+ * What a mock means, and what one run of them is worth reporting.
+ *
+ * Everything here is pure: no Playwright, no page, no socket. The engine turns
+ * a `ResolvedMock` into a real route and counts what happened; this file
+ * decides what a scenario expands to, how a body is encoded, which mock wins
+ * when two patterns match, and how the result reads.
+ */
+/* ── Scenarios ────────────────────────────────────────────────────────── */
+/**
+ * The shorthands. Each expands to a response the caller can then override
+ * field by field, which is what makes them worth having: `slow` with your own
+ * body is one word plus a body, not a hand-written response.
+ */
+export const MOCK_SCENARIOS = [
+    "empty",
+    "error",
+    "unauthorized",
+    "not_found",
+    "slow",
+    "malformed",
+    "offline",
+];
+/**
+ * Failures the browser can be told to report. These four are the ones a
+ * developer actually means: the request failed, it hung, nothing was
+ * listening, or there is no network at all.
+ */
+export const ABORT_REASONS = ["failed", "timedout", "connectionrefused", "internetdisconnected"];
+/** What each scenario means, before the caller's own `response` is laid over it. */
+const SCENARIOS = {
+    // An empty array, not `{ items: [] }`: no shape is right for every API, so
+    // the shorthand covers the common one and the report prints what it served,
+    // which is how a mismatch becomes visible instead of mysterious.
+    empty: { status: 200, body: [] },
+    error: { status: 500, body: { error: "Internal server error" } },
+    unauthorized: { status: 401, body: { error: "Unauthorized" } },
+    not_found: { status: 404, body: { error: "Not found" } },
+    slow: { status: 200, delay_ms: MOCK_SLOW_DELAY_MS },
+    // Deliberately not JSON, deliberately served as JSON. See `encodeBody`.
+    malformed: { status: 200, body: "not json" },
+    offline: { abort: "failed" },
+};
+/**
+ * Turn one written mock into one the engine can install.
+ *
+ * The scenario supplies defaults and the caller's own fields win one at a
+ * time, so `{ scenario: "slow", response: { body } }` keeps the delay and takes
+ * the body. An explicit `abort` beats a scenario that would have answered: a
+ * caller who asked for a dead request means it.
+ */
+export function resolveMock(spec) {
+    const scenario = spec.scenario;
+    const preset = scenario ? SCENARIOS[scenario] : {};
+    const response = spec.response ?? {};
+    const reason = spec.abort ?? preset.abort;
+    if (reason !== undefined) {
+        return {
+            kind: "abort",
+            url_pattern: spec.url_pattern ?? "",
+            reason,
+            ...(spec.times !== undefined ? { times: spec.times } : {}),
+            ...(scenario !== undefined ? { scenario } : {}),
+        };
+    }
+    const body = response.body !== undefined ? response.body : preset.body;
+    const encoded = encodeBody(body);
+    const headers = {};
+    if (encoded.content_type !== undefined)
+        headers["content-type"] = encoded.content_type;
+    // The caller's headers land last and are lower-cased on the way in, so a
+    // `Content-Type` of their own replaces the one the body implied rather than
+    // sitting next to it as a second header.
+    for (const [name, value] of Object.entries(response.headers ?? {})) {
+        headers[name.toLowerCase()] = value;
+    }
+    return {
+        kind: "fulfill",
+        url_pattern: spec.url_pattern ?? "",
+        status: response.status ?? preset.status ?? 200,
+        body: encoded.body,
+        headers,
+        delay_ms: response.delay_ms ?? preset.delay_ms ?? 0,
+        ...(spec.times !== undefined ? { times: spec.times } : {}),
+        ...(scenario !== undefined ? { scenario } : {}),
+    };
+}
+/**
+ * Encode a body into the bytes the page will actually receive.
+ *
+ * A string is sent verbatim. This is the whole reason the malformed scenario
+ * works: `JSON.stringify("not json")` is `"not json"`, which parses perfectly,
+ * so encoding a string would make a broken API impossible to simulate. It goes
+ * out as `application/json` because these stand in for API responses — anyone
+ * mocking a page or a script says so in `headers`.
+ *
+ * Anything else is JSON, including `null`. Only an absent body means "no body",
+ * and it carries no content type at all.
+ */
+export function encodeBody(body) {
+    if (body === undefined)
+        return { body: "" };
+    if (typeof body === "string")
+        return { body, content_type: "application/json" };
+    return { body: JSON.stringify(body), content_type: "application/json" };
+}
+/**
+ * The order to hand mocks to Playwright.
+ *
+ * Playwright checks routes last-registered-first; a caller reads their list
+ * top-down and expects the first pattern that matches to win. Reversing on the
+ * way in is what reconciles the two, and is the only reason this is not just a
+ * loop in the engine.
+ */
+export function installOrder(mocks) {
+    return [...mocks].reverse();
+}
+/**
+ * The advice for a pattern that matched nothing, when the pattern itself looks
+ * like the reason.
+ *
+ * Patterns are matched against the whole URL, so `/api/orders` matches nothing
+ * on a page served from `http://localhost:3000` — by far the most common way
+ * to write a mock that silently does nothing. A pattern that already starts
+ * with a wildcard, or that is a full URL, is left alone: a wrong guess here is
+ * worse than no guess.
+ */
+export function patternHint(pattern) {
+    if (pattern.startsWith("*") || pattern.includes("://"))
+        return undefined;
+    const path = pattern.startsWith("/") ? pattern : `/${pattern}`;
+    const suggestion = `**${path}${path.endsWith("*") ? "" : "*"}`;
+    return `patterns are matched against the whole URL, so a path needs a leading \`**\` — try \`${suggestion}\``;
+}
+/**
+ * The mock report, as lines for the capture summary.
+ *
+ * A mock that never matched leads, because it is the finding this tool exists
+ * to surface: mock the products endpoint, watch the app call `/api/product-list`,
+ * see a page that looks perfectly fine, and learn nothing at all. The same
+ * reasoning puts the unmatched requests in — a run that quietly used the real
+ * backend for half its data is not the test anybody thought they ran.
+ */
+export function formatMockReport(input) {
+    const { activity, unmatched, block_unmatched, duration_ms } = input;
+    const served = activity.filter((entry) => entry.hits > 0);
+    const missed = activity.filter((entry) => entry.hits === 0);
+    const requests = served.reduce((total, entry) => total + entry.hits, 0);
+    const headline = `API mocks — ${activity.length} declared, ` +
+        `${served.length} served ${count(requests, "request")}` +
+        (missed.length > 0 ? `, ${missed.length} never matched.` : ".");
+    const lines = [headline];
+    for (const entry of activity) {
+        lines.push(`  ${formatActivity(entry, duration_ms)}`);
+    }
+    if (unmatched.length > 0) {
+        lines.push(block_unmatched
+            ? "  Unmatched, blocked before they left the browser:"
+            : "  Unmatched, answered by the real server:");
+        for (const request of unmatched.slice(0, MAX_UNMATCHED_LISTED)) {
+            const outcome = request.blocked ? "" : request.status !== undefined ? ` → ${request.status}` : " → no response";
+            lines.push(`    ${request.method} ${request.url}${outcome}`);
+        }
+        if (unmatched.length > MAX_UNMATCHED_LISTED) {
+            lines.push(`    … and ${unmatched.length - MAX_UNMATCHED_LISTED} more`);
+        }
+    }
+    else {
+        lines.push("  Every request the page made was matched by a mock.");
+    }
+    return lines;
+}
+/** One mock's line in the report: the mark, the pattern, what it serves, and what it did. */
+function formatActivity(entry, duration_ms) {
+    const { mock, hits, answered, urls } = entry;
+    if (hits === 0) {
+        const hint = patternHint(mock.url_pattern);
+        return `✗ ${mock.url_pattern} — no request matched it${hint ? ` (${hint})` : ""}.`;
+    }
+    const late = mock.kind === "fulfill" && answered < hits && mock.delay_ms >= duration_ms;
+    const mark = late ? "!" : "✓";
+    let line = `${mark} ${mock.url_pattern} → ${describeMock(mock)} ×${hits}`;
+    if (late && mock.kind === "fulfill") {
+        line +=
+            ` — delayed ${mock.delay_ms}ms, longer than the ${duration_ms}ms recording, ` +
+                `so ${hits === 1 ? "the request" : `${hits - answered} of them`} never got an answer.`;
+    }
+    else if (urls.length > 0) {
+        // Only a handful of URLs are ever kept, so the remainder is counted off the
+        // hits — a mock that answered fifty polls must not report "and 1 more"
+        // simply because three is all the sample it has.
+        const listed = urls.slice(0, MAX_MOCK_URLS_LISTED);
+        const more = hits > listed.length ? `, … and ${hits - listed.length} more` : "";
+        line += ` (${listed.join(", ")}${more})`;
+    }
+    return line;
+}
+/**
+ * What a mock serves, in a few words. Names the scenario when there was one —
+ * "200 empty" says more than "200" and is what the caller wrote.
+ */
+export function describeMock(mock) {
+    const parts = [];
+    if (mock.kind === "abort") {
+        parts.push(`abort ${mock.reason}`);
+    }
+    else {
+        parts.push(String(mock.status));
+        if (mock.scenario !== undefined && mock.scenario !== "slow")
+            parts.push(mock.scenario);
+        if (mock.delay_ms > 0)
+            parts.push(`after ${mock.delay_ms}ms`);
+    }
+    let text = parts.join(" ");
+    if (mock.times !== undefined) {
+        text += mock.times === 1 ? ", first request only" : `, first ${mock.times} requests only`;
+    }
+    return text;
+}
+function count(n, noun) {
+    return `${n} ${noun}${n === 1 ? "" : "s"}`;
+}
+//# sourceMappingURL=mock-rules.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"mock-rules.js","sourceRoot":"","sources":["../../src/utils/mock-rules.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  MAX_MOCK_URLS_LISTED,\n  MAX_UNMATCHED_LISTED,\n  MOCK_SLOW_DELAY_MS,\n} from \"../constants.js\";\n\n/**\n * What a mock means, and what one run of them is worth reporting.\n *\n * Everything here is pure: no Playwright, no page, no socket. The engine turns\n * a `ResolvedMock` into a real route and counts what happened; this file\n * decides what a scenario expands to, how a body is encoded, which mock wins\n * when two patterns match, and how the result reads.\n */\n\n/* ── Scenarios ────────────────────────────────────────────────────────── */\n\n/**\n * The shorthands. Each expands to a response the caller can then override\n * field by field, which is what makes them worth having: `slow` with your own\n * body is one word plus a body, not a hand-written response.\n */\nexport const MOCK_SCENARIOS = [\n  \"empty\",\n  \"error\",\n  \"unauthorized\",\n  \"not_found\",\n  \"slow\",\n  \"malformed\",\n  \"offline\",\n] as const;\n\nexport type MockScenario = (typeof MOCK_SCENARIOS)[number];\n\n/**\n * Failures the browser can be told to report. These four are the ones a\n * developer actually means: the request failed, it hung, nothing was\n * listening, or there is no network at all.\n */\nexport const ABORT_REASONS = [\"failed\", \"timedout\", \"connectionrefused\", \"internetdisconnected\"] as const;\n\nexport type AbortReason = (typeof ABORT_REASONS)[number];\n\n/** One mock exactly as the caller wrote it. */\nexport interface MockSpec {\n  url_pattern?: string;\n  scenario?: MockScenario;\n  response?: {\n    status?: number;\n    body?: unknown;\n    delay_ms?: number;\n    headers?: Record<string, string>;\n  };\n  abort?: AbortReason;\n  times?: number;\n}\n\n/** A mock with every question answered, ready for the engine to install. */\nexport type ResolvedMock =\n  | {\n      kind: \"abort\";\n      url_pattern: string;\n      reason: AbortReason;\n      times?: number;\n      scenario?: MockScenario;\n    }\n  | {\n      kind: \"fulfill\";\n      url_pattern: string;\n      status: number;\n      /** Already encoded — the exact bytes the page will receive. */\n      body: string;\n      /** Header names lower-cased, so `content-type` can only be set once. */\n      headers: Record<string, string>;\n      delay_ms: number;\n      times?: number;\n      scenario?: MockScenario;\n    };\n\n/** What each scenario means, before the caller's own `response` is laid over it. */\nconst SCENARIOS: Readonly<Record<MockScenario, { status?: number; body?: unknown; delay_ms?: number; abort?: AbortReason }>> =\n  {\n    // An empty array, not `{ items: [] }`: no shape is right for every API, so\n    // the shorthand covers the common one and the report prints what it served,\n    // which is how a mismatch becomes visible instead of mysterious.\n    empty: { status: 200, body: [] },\n    error: { status: 500, body: { error: \"Internal server error\" } },\n    unauthorized: { status: 401, body: { error: \"Unauthorized\" } },\n    not_found: { status: 404, body: { error: \"Not found\" } },\n    slow: { status: 200, delay_ms: MOCK_SLOW_DELAY_MS },\n    // Deliberately not JSON, deliberately served as JSON. See `encodeBody`.\n    malformed: { status: 200, body: \"not json\" },\n    offline: { abort: \"failed\" },\n  };\n\n/**\n * Turn one written mock into one the engine can install.\n *\n * The scenario supplies defaults and the caller's own fields win one at a\n * time, so `{ scenario: \"slow\", response: { body } }` keeps the delay and takes\n * the body. An explicit `abort` beats a scenario that would have answered: a\n * caller who asked for a dead request means it.\n */\nexport function resolveMock(spec: MockSpec): ResolvedMock {\n  const scenario = spec.scenario;\n  const preset = scenario ? SCENARIOS[scenario] : {};\n  const response = spec.response ?? {};\n\n  const reason = spec.abort ?? preset.abort;\n  if (reason !== undefined) {\n    return {\n      kind: \"abort\",\n      url_pattern: spec.url_pattern ?? \"\",\n      reason,\n      ...(spec.times !== undefined ? { times: spec.times } : {}),\n      ...(scenario !== undefined ? { scenario } : {}),\n    };\n  }\n\n  const body = response.body !== undefined ? response.body : preset.body;\n  const encoded = encodeBody(body);\n  const headers: Record<string, string> = {};\n  if (encoded.content_type !== undefined) headers[\"content-type\"] = encoded.content_type;\n  // The caller's headers land last and are lower-cased on the way in, so a\n  // `Content-Type` of their own replaces the one the body implied rather than\n  // sitting next to it as a second header.\n  for (const [name, value] of Object.entries(response.headers ?? {})) {\n    headers[name.toLowerCase()] = value;\n  }\n\n  return {\n    kind: \"fulfill\",\n    url_pattern: spec.url_pattern ?? \"\",\n    status: response.status ?? preset.status ?? 200,\n    body: encoded.body,\n    headers,\n    delay_ms: response.delay_ms ?? preset.delay_ms ?? 0,\n    ...(spec.times !== undefined ? { times: spec.times } : {}),\n    ...(scenario !== undefined ? { scenario } : {}),\n  };\n}\n\n/**\n * Encode a body into the bytes the page will actually receive.\n *\n * A string is sent verbatim. This is the whole reason the malformed scenario\n * works: `JSON.stringify(\"not json\")` is `\"not json\"`, which parses perfectly,\n * so encoding a string would make a broken API impossible to simulate. It goes\n * out as `application/json` because these stand in for API responses — anyone\n * mocking a page or a script says so in `headers`.\n *\n * Anything else is JSON, including `null`. Only an absent body means \"no body\",\n * and it carries no content type at all.\n */\nexport function encodeBody(body: unknown): { body: string; content_type?: string } {\n  if (body === undefined) return { body: \"\" };\n  if (typeof body === \"string\") return { body, content_type: \"application/json\" };\n  return { body: JSON.stringify(body), content_type: \"application/json\" };\n}\n\n/**\n * The order to hand mocks to Playwright.\n *\n * Playwright checks routes last-registered-first; a caller reads their list\n * top-down and expects the first pattern that matches to win. Reversing on the\n * way in is what reconciles the two, and is the only reason this is not just a\n * loop in the engine.\n */\nexport function installOrder<T>(mocks: readonly T[]): T[] {\n  return [...mocks].reverse();\n}\n\n/**\n * The advice for a pattern that matched nothing, when the pattern itself looks\n * like the reason.\n *\n * Patterns are matched against the whole URL, so `/api/orders` matches nothing\n * on a page served from `http://localhost:3000` — by far the most common way\n * to write a mock that silently does nothing. A pattern that already starts\n * with a wildcard, or that is a full URL, is left alone: a wrong guess here is\n * worse than no guess.\n */\nexport function patternHint(pattern: string): string | undefined {\n  if (pattern.startsWith(\"*\") || pattern.includes(\"://\")) return undefined;\n  const path = pattern.startsWith(\"/\") ? pattern : `/${pattern}`;\n  const suggestion = `**${path}${path.endsWith(\"*\") ? \"\" : \"*\"}`;\n  return `patterns are matched against the whole URL, so a path needs a leading \\`**\\` — try \\`${suggestion}\\``;\n}\n\n/* ── The report ───────────────────────────────────────────────────────── */\n\n/** What one mock did during a run. */\nexport interface MockActivity {\n  mock: ResolvedMock;\n  /** Requests this mock intercepted. */\n  hits: number;\n  /**\n   * Requests it actually answered. Lower than `hits` when a delayed response\n   * outlived the recording — the request was caught but the page never got a\n   * reply, which is a finding rather than a bug in the count.\n   */\n  answered: number;\n  /** The first few URLs it intercepted, for the report. */\n  urls: string[];\n}\n\n/** A request no mock matched. */\nexport interface UnmatchedRequest {\n  method: string;\n  url: string;\n  /** What the real server answered, when it was allowed to. */\n  status?: number;\n  /** Set when `block_unmatched` killed it before it left the browser. */\n  blocked?: boolean;\n}\n\nexport interface MockReportInput {\n  activity: MockActivity[];\n  unmatched: UnmatchedRequest[];\n  block_unmatched: boolean;\n  /** The recording length, so a delay that outlives it can be named. */\n  duration_ms: number;\n}\n\n/**\n * The mock report, as lines for the capture summary.\n *\n * A mock that never matched leads, because it is the finding this tool exists\n * to surface: mock the products endpoint, watch the app call `/api/product-list`,\n * see a page that looks perfectly fine, and learn nothing at all. The same\n * reasoning puts the unmatched requests in — a run that quietly used the real\n * backend for half its data is not the test anybody thought they ran.\n */\nexport function formatMockReport(input: MockReportInput): string[] {\n  const { activity, unmatched, block_unmatched, duration_ms } = input;\n  const served = activity.filter((entry) => entry.hits > 0);\n  const missed = activity.filter((entry) => entry.hits === 0);\n  const requests = served.reduce((total, entry) => total + entry.hits, 0);\n\n  const headline =\n    `API mocks — ${activity.length} declared, ` +\n    `${served.length} served ${count(requests, \"request\")}` +\n    (missed.length > 0 ? `, ${missed.length} never matched.` : \".\");\n  const lines = [headline];\n\n  for (const entry of activity) {\n    lines.push(`  ${formatActivity(entry, duration_ms)}`);\n  }\n\n  if (unmatched.length > 0) {\n    lines.push(\n      block_unmatched\n        ? \"  Unmatched, blocked before they left the browser:\"\n        : \"  Unmatched, answered by the real server:\",\n    );\n    for (const request of unmatched.slice(0, MAX_UNMATCHED_LISTED)) {\n      const outcome = request.blocked ? \"\" : request.status !== undefined ? ` → ${request.status}` : \" → no response\";\n      lines.push(`    ${request.method} ${request.url}${outcome}`);\n    }\n    if (unmatched.length > MAX_UNMATCHED_LISTED) {\n      lines.push(`    … and ${unmatched.length - MAX_UNMATCHED_LISTED} more`);\n    }\n  } else {\n    lines.push(\"  Every request the page made was matched by a mock.\");\n  }\n\n  return lines;\n}\n\n/** One mock's line in the report: the mark, the pattern, what it serves, and what it did. */\nfunction formatActivity(entry: MockActivity, duration_ms: number): string {\n  const { mock, hits, answered, urls } = entry;\n\n  if (hits === 0) {\n    const hint = patternHint(mock.url_pattern);\n    return `✗ ${mock.url_pattern} — no request matched it${hint ? ` (${hint})` : \"\"}.`;\n  }\n\n  const late = mock.kind === \"fulfill\" && answered < hits && mock.delay_ms >= duration_ms;\n  const mark = late ? \"!\" : \"✓\";\n  let line = `${mark} ${mock.url_pattern} → ${describeMock(mock)} ×${hits}`;\n\n  if (late && mock.kind === \"fulfill\") {\n    line +=\n      ` — delayed ${mock.delay_ms}ms, longer than the ${duration_ms}ms recording, ` +\n      `so ${hits === 1 ? \"the request\" : `${hits - answered} of them`} never got an answer.`;\n  } else if (urls.length > 0) {\n    // Only a handful of URLs are ever kept, so the remainder is counted off the\n    // hits — a mock that answered fifty polls must not report \"and 1 more\"\n    // simply because three is all the sample it has.\n    const listed = urls.slice(0, MAX_MOCK_URLS_LISTED);\n    const more = hits > listed.length ? `, … and ${hits - listed.length} more` : \"\";\n    line += ` (${listed.join(\", \")}${more})`;\n  }\n\n  return line;\n}\n\n/**\n * What a mock serves, in a few words. Names the scenario when there was one —\n * \"200 empty\" says more than \"200\" and is what the caller wrote.\n */\nexport function describeMock(mock: ResolvedMock): string {\n  const parts: string[] = [];\n\n  if (mock.kind === \"abort\") {\n    parts.push(`abort ${mock.reason}`);\n  } else {\n    parts.push(String(mock.status));\n    if (mock.scenario !== undefined && mock.scenario !== \"slow\") parts.push(mock.scenario);\n    if (mock.delay_ms > 0) parts.push(`after ${mock.delay_ms}ms`);\n  }\n\n  let text = parts.join(\" \");\n  if (mock.times !== undefined) {\n    text += mock.times === 1 ? \", first request only\" : `, first ${mock.times} requests only`;\n  }\n  return text;\n}\n\nfunction count(n: number, noun: string): string {\n  return `${n} ${noun}${n === 1 ? \"\" : \"s\"}`;\n}\n"]}

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

@@ -0,0 +1,142 @@
+/**
+ * What counts as an RTL bug.
+ *
+ * Everything here is pure: it takes one element measured in both directions
+ * and returns a verdict. Nothing in this file opens a browser or touches a
+ * page, which is the point — "did this box mirror?", "is this alignment
+ * deliberate or forgotten?" and "is that overflow new?" are all judgements
+ * with edge cases, and judgements need unit tests that run in milliseconds.
+ *
+ * The bias throughout is against false alarms, and it is stronger here than
+ * anywhere else in this codebase, because static RTL analysis is notorious for
+ * crying wolf. `text-align: left` is *correct* on a code block, a number
+ * column and a Latin brand name; `padding-left` is correct on anything that
+ * should not mirror; `flex-direction: row` is correct wherever the order is
+ * physical rather than semantic. A report that flags all of those is a report
+ * whose real findings are never read.
+ *
+ * So nothing is judged from the RTL rendering alone. Every verdict is a
+ * *comparison*: the element is measured in LTR and again in RTL, and the only
+ * findings are the things that failed to change when the LTR measurement
+ * proves they should have. An element that is left-aligned in both directions
+ * has forgotten to mirror; one that is left in LTR and right in RTL is
+ * working exactly as intended, and this file says nothing about it.
+ */
+/**
+ * One element as measured in one direction.
+ *
+ * Deliberately flat and JSON-ish: this is what crosses the boundary out of
+ * `page.evaluate`, so it can hold nothing but structured-cloneable values.
+ */
+export interface ElementMeasurement {
+    /** Stable identity across the two renders — see `keyFor` in engine/rtl.ts. */
+    key: string;
+    /** A CSS selector for the element, for the report and the highlight overlay. */
+    selector: string;
+    /** Which match of `selector` this is, when the selector is not unique. */
+    match_index: number;
+    tag: string;
+    /** Visible text, elided. Named in the report so a finding is recognisable. */
+    text: string;
+    /** Border-box in document coordinates. */
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    /** The viewport this was measured in, so mirroring can be computed. */
+    viewport_width: number;
+    /** Computed `text-align`, already resolved from `start`/`end` by the browser. */
+    text_align: string;
+    /** Computed `direction` on the element itself. */
+    direction: string;
+    /** Computed `flex-direction`, or "" when the element is not a flex container. */
+    flex_direction: string;
+    /** Physical padding and margin, to spot asymmetry that never mirrored. */
+    padding_left: number;
+    padding_right: number;
+    margin_left: number;
+    margin_right: number;
+    /** Overflow of this element past its own content box, and past the viewport. */
+    scroll_width: number;
+    client_width: number;
+    /** How far the box sticks out past the right/left edge of the viewport, 0 when it fits. */
+    overflow_right: number;
+    overflow_left: number;
+    /** A transform that already mirrors the element — `scaleX(-1)` on an icon. */
+    transform: string;
+    /** Set when this element is one an author would expect to mirror: an arrow, a chevron. */
+    mirrorable?: boolean;
+}
+/** One element measured in both directions. */
+export interface ElementPair {
+    ltr: ElementMeasurement;
+    rtl: ElementMeasurement;
+}
+/**
+ * What can be wrong with an element in RTL.
+ *
+ * Each of these is a *failure to change*, except `overflow`, which is a change
+ * that should not have happened. That asymmetry is the whole design: RTL bugs
+ * are things that stayed put.
+ */
+export type RtlIssueKind = "not_mirrored" | "alignment" | "flex_not_reversed" | "padding_not_mirrored" | "overflow" | "icon_not_mirrored" | "direction_not_applied";
+export interface RtlIssue {
+    kind: RtlIssueKind;
+    /** How bad it is. `problem` leads the report; `warning` follows it. */
+    severity: "problem" | "warning";
+    /** One line naming what is wrong, in the report's voice. */
+    message: string;
+    /** The measured evidence, quoted so the reader can check the verdict. */
+    evidence: string;
+}
+/** Every issue found on one element, with the element itself. */
+export interface ElementFinding {
+    /** 1-based, and the number the highlight overlay is labelled with. */
+    index: number;
+    selector: string;
+    match_index: number;
+    /** `button "Add to cart"` — how the element is named in the report. */
+    description: string;
+    issues: RtlIssue[];
+    /** The worst severity among `issues`, so the report can sort and colour. */
+    severity: "problem" | "warning";
+}
+/**
+ * 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 declare function judgeElement(pair: ElementPair): RtlIssue[];
+/** Where a box's mirror image starts, in the same coordinate space. */
+export declare function mirroredX(m: ElementMeasurement): number;
+/**
+ * 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 declare function isMirroredTransform(transform: string): boolean;
+/**
+ * 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 declare function describeElement(m: Pick<ElementMeasurement, "tag" | "text" | "selector">): string;
+/**
+ * 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 declare function buildFindings(pairs: readonly ElementPair[]): ElementFinding[];
+/** What each kind of issue is called as a section heading, and how it is explained. */
+export declare function describeIssueKind(kind: RtlIssueKind): string;
+export declare function elide(value: string, max: number): string;