framewatch-mcp-server 0.1.0 → 0.2.0

package/dist/engine/mocks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mocks.js","sourceRoot":"","sources":["../../src/engine/mocks.ts"],"names":[],"mappings":"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","sourcesContent":["import type { Page, Request, Route } from \"playwright\";\nimport { MAX_MOCK_URLS_LISTED, MAX_UNMATCHED_TRACKED } from \"../constants.js\";\nimport { shortenUrl } from \"./layers/network.js\";\nimport {\n  installOrder,\n  type MockActivity,\n  type ResolvedMock,\n  type UnmatchedRequest,\n} from \"../utils/mock-rules.js\";\n\n/**\n * Request interception for `framewatch_api_mock`.\n *\n * Installs one Playwright route per mock, answers the requests they match,\n * and keeps the tally the report is built from: what each mock served, what it\n * never served, and what the page asked for that no mock had an opinion about.\n *\n * Two rules do most of the work here:\n *\n * The page's own navigation is never mocked. A catch-all pattern is a\n * perfectly reasonable thing to write, and if the main document went through\n * the mock the page under test would be replaced by a JSON body — there would\n * be nothing left to photograph. The document is how the page got here, not\n * something the page asked for, so it is passed through untouched and left out\n * of the unmatched tally as well. Sub-resources and everything an iframe or the\n * app itself fetches are fair game.\n *\n * `times` is counted here rather than handed to Playwright. Playwright spends a\n * route's remaining uses whenever the pattern matches, which would let the\n * document request consume a `times: 1` mock before the app ever fetched\n * anything.\n */\n\nexport interface MockRouterOptions {\n  /** The mocks in the order the caller wrote them; the first match wins. */\n  mocks: ResolvedMock[];\n  /** Abort anything no mock matched instead of letting it reach the network. */\n  block_unmatched: boolean;\n}\n\nexport class MockRouter {\n  readonly #blockUnmatched: boolean;\n  readonly #activity: MockActivity[];\n  /** Unmatched requests keyed by identity, so a response can fill in its status later. */\n  readonly #unmatched = new Map<Request, UnmatchedRequest>();\n  #page: Page | null = null;\n  /** Sleeping delays, so a recording that ends first does not leave timers behind. */\n  readonly #waits = new Set<{ timer: NodeJS.Timeout; resolve: () => void }>();\n  #disposed = false;\n\n  readonly #onResponse = (response: { request(): Request; status(): number }): void => {\n    const record = this.#unmatched.get(response.request());\n    if (record && record.blocked !== true) record.status = response.status();\n  };\n\n  constructor(options: MockRouterOptions) {\n    this.#blockUnmatched = options.block_unmatched;\n    this.#activity = options.mocks.map((mock) => ({ mock, hits: 0, answered: 0, urls: [] }));\n  }\n\n  /**\n   * Install the routes. Call before the page navigates.\n   *\n   * The catch-all goes on first *because* Playwright checks routes\n   * last-registered-first: registering it before the mocks is what puts it\n   * behind them. The mocks themselves go on in reverse (see `installOrder`),\n   * which leaves the first one the caller wrote at the front of the queue.\n   */\n  async install(page: Page): Promise<void> {\n    this.#page = page;\n    page.on(\"response\", this.#onResponse);\n\n    await page.route(\"**/*\", (route, request) => this.#handleUnmatched(route, request));\n\n    for (const entry of installOrder(this.#activity)) {\n      await page.route(entry.mock.url_pattern, (route, request) => this.#handleMock(entry, route, request));\n    }\n  }\n\n  /** What each mock did, in the order the caller wrote them. */\n  get activity(): MockActivity[] {\n    return this.#activity;\n  }\n\n  /** Requests no mock matched, in the order the page made them. */\n  get unmatched(): UnmatchedRequest[] {\n    return [...this.#unmatched.values()];\n  }\n\n  /**\n   * Stop answering. Called once the recording is over and before the page is\n   * closed: a mock still sleeping out a long delay has nothing left to answer,\n   * and its timer would otherwise outlive the tool call.\n   */\n  dispose(): void {\n    if (this.#disposed) return;\n    this.#disposed = true;\n    this.#page?.off(\"response\", this.#onResponse);\n    for (const wait of this.#waits) {\n      clearTimeout(wait.timer);\n      wait.resolve();\n    }\n    this.#waits.clear();\n  }\n\n  /** One mock's turn at a request. */\n  async #handleMock(entry: MockActivity, route: Route, request: Request): Promise<void> {\n    const { mock } = entry;\n\n    // Not ours: the page's own document, or a mock that has already been spent.\n    if (this.#isMainDocument(request) || (mock.times !== undefined && entry.hits >= mock.times)) {\n      await this.#safely(() => route.fallback());\n      return;\n    }\n\n    entry.hits++;\n    if (entry.urls.length < MAX_MOCK_URLS_LISTED) entry.urls.push(shortenUrl(request.url()));\n\n    if (mock.kind === \"abort\") {\n      if (await this.#safely(() => route.abort(mock.reason))) entry.answered++;\n      return;\n    }\n\n    if (mock.delay_ms > 0) await this.#wait(mock.delay_ms);\n    // The recording ended while this was sleeping; there is nobody left to answer.\n    if (this.#disposed) return;\n\n    const answered = await this.#safely(() =>\n      route.fulfill({ status: mock.status, headers: mock.headers, body: mock.body }),\n    );\n    if (answered) entry.answered++;\n  }\n\n  /** Everything no mock wanted. */\n  async #handleUnmatched(route: Route, request: Request): Promise<void> {\n    if (this.#isMainDocument(request)) {\n      await this.#safely(() => route.continue());\n      return;\n    }\n\n    if (this.#unmatched.size < MAX_UNMATCHED_TRACKED) {\n      this.#unmatched.set(request, {\n        method: request.method(),\n        url: shortenUrl(request.url()),\n        ...(this.#blockUnmatched ? { blocked: true } : {}),\n      });\n    }\n\n    await this.#safely(() => (this.#blockUnmatched ? route.abort(\"failed\") : route.continue()));\n  }\n\n  /**\n   * The page's own navigation, which is never mocked and never counted. A\n   * request whose frame has already gone cannot be the main document any more,\n   * so a throw here means \"no\".\n   */\n  #isMainDocument(request: Request): boolean {\n    try {\n      return request.resourceType() === \"document\" && request.frame() === this.#page?.mainFrame();\n    } catch {\n      return false;\n    }\n  }\n\n  /** A delay that a `dispose()` can cut short. */\n  #wait(ms: number): Promise<void> {\n    if (this.#disposed) return Promise.resolve();\n    return new Promise<void>((resolve) => {\n      const wait = {\n        timer: setTimeout(() => {\n          this.#waits.delete(wait);\n          resolve();\n        }, ms),\n        resolve,\n      };\n      this.#waits.add(wait);\n    });\n  }\n\n  /**\n   * Run one route call, swallowing the failure.\n   *\n   * A route whose page has navigated away, closed or crashed rejects, and none\n   * of that is worth failing a recording over — the frames are the point. It\n   * also has to be caught rather than left floating: an unhandled rejection\n   * from a route handler would surface as a crash somewhere unrelated.\n   */\n  async #safely(run: () => Promise<void>): Promise<boolean> {\n    try {\n      await run();\n      return true;\n    } catch {\n      return false;\n    }\n  }\n}\n"]}

package/dist/engine/rtl.d.ts

@@ -0,0 +1,129 @@
+import type { Page } from "playwright";
+import type { ElementMeasurement, ElementPair } from "../utils/rtl-rules.js";
+/**
+ * RTL engine.
+ *
+ * Puts a page into RTL, optionally replaces its text with Arabic, and measures
+ * every laid-out element. Nothing here decides what is *wrong*; that is
+ * `utils/rtl-rules.ts`, which is pure and unit-tested without a browser.
+ *
+ * The whole design rests on one idea: an RTL bug is something that failed to
+ * change. So the same page is measured twice — once as it ships, once flipped
+ * — and the two measurements are paired element by element. That pairing is
+ * the hard part, because the two renders are two separate page loads: element
+ * identity has to survive a reload, and it cannot be an ElementHandle, an
+ * index, or a position (position is precisely the thing under test).
+ *
+ * `keyFor` solves that with a structural key — tag, id, class, and the
+ * element's path among its siblings — computed identically in both passes.
+ * Anything that does not appear in both is simply dropped: an element that
+ * exists in only one direction is a page that renders differently, which is
+ * interesting but is not a mirroring bug, and guessing at a pairing would
+ * invent findings.
+ */
+/**
+ * How to make the page render right-to-left.
+ *
+ * Four triggers, because apps do this four different ways and picking the
+ * wrong one silently measures the page twice in LTR — which reports no
+ * findings at all and looks exactly like a page with no RTL bugs. That failure
+ * is why `verifyDirection` exists.
+ */
+export type RtlTrigger = {
+    type: "attribute";
+    attr: string;
+    value: string;
+    target: string;
+} | {
+    type: "class";
+    class: string;
+    target: string;
+} | {
+    type: "locale";
+    locale: string;
+} | {
+    type: "url";
+    rtl_url: string;
+};
+/** The trigger used when the caller names none: the way the platform itself defines RTL. */
+export declare const DEFAULT_RTL_TRIGGER: RtlTrigger;
+/**
+ * Apply the trigger to an already-loaded page.
+ *
+ * `url` is not applied here — it is a different page and is navigated to by
+ * the caller before this is reached. `locale` likewise is a context option,
+ * fixed when the browser context is created; what this does for it is set
+ * `dir` as well, because a locale alone changes number and date formatting but
+ * does not flip the layout: `Accept-Language: ar` does not put a page in RTL,
+ * and a tool that assumed it did would report a clean bill of health on a
+ * completely broken page.
+ */
+export declare function applyRtlTrigger(page: Page, trigger: RtlTrigger): Promise<void>;
+/**
+ * Check that the page really is rendering right-to-left.
+ *
+ * The single most damaging way this tool can fail is quietly: a trigger that
+ * does not match the app under test measures LTR twice, finds every element
+ * identical, and reports that the page has no RTL problems. That is worse than
+ * an error, because it is a confident wrong answer. So the direction that
+ * actually took effect is read back off the document and the body, and the
+ * caller refuses to report anything if it is still `ltr`.
+ */
+export declare function readDirection(page: Page): Promise<{
+    html: string;
+    body: string;
+}>;
+/**
+ * Replace every visible text node with Arabic of about the same length.
+ *
+ * Run in *both* passes, not just the RTL one. That is not obvious and it is
+ * essential: the two passes are compared to each other, so they have to differ
+ * in exactly one variable. If only the RTL pass got Arabic, every box on the
+ * page would change width for reasons of text metrics rather than direction,
+ * and the mirroring comparison — which asks whether a box moved — would be
+ * measuring the font, not the layout.
+ *
+ * Text inside `<script>`, `<style>` and friends is left alone, as is anything
+ * inside an element the caller excluded. Input `value`s and `placeholder`s are
+ * replaced too, since a form is where RTL text is most likely to be mishandled.
+ */
+export declare function injectArabic(page: Page, exclude?: string): Promise<InjectionResult>;
+/** What an injection did, or why it did nothing. */
+export interface InjectionResult {
+    replaced: number;
+    /** Set when the injection could not run at all — never confused with "no text to replace". */
+    error?: string;
+}
+export interface MeasureOptions {
+    /** Only measure inside this. Defaults to the whole document. */
+    selector?: string;
+    /** Never measure this, or anything inside it. */
+    exclude?: string;
+    /** Stop after this many elements. */
+    max_elements?: number;
+}
+/**
+ * Measure every laid-out element on the page.
+ *
+ * "Laid out" is doing a lot of work: elements with no box, no size, or no
+ * visibility are skipped, because an element that is not rendered cannot have
+ * mirrored and reporting it would be noise. So are the structural wrappers
+ * that carry no text and exactly one child — a `<div>` whose only job is to
+ * hold another `<div>` has no independent layout to get wrong, and including
+ * them would multiply every real finding by the depth of the tree it sits in.
+ */
+export declare function measureElements(page: Page, options?: MeasureOptions): Promise<ElementMeasurement[]>;
+/**
+ * Pair up two measurements of the same page.
+ *
+ * An element is only paired when its structural key appears exactly once in
+ * each pass. A key that appears twice in either pass is ambiguous — pairing it
+ * by order would be a guess, and a wrong guess invents a mirroring bug out of
+ * two different elements — so it is dropped along with anything that appears
+ * in only one direction. `unpaired` counts what was dropped so the report can
+ * say so rather than silently measuring less than it claims.
+ */
+export declare function pairMeasurements(ltr: readonly ElementMeasurement[], rtl: readonly ElementMeasurement[]): {
+    pairs: ElementPair[];
+    unpaired: number;
+};