@skyramp/mcp 0.3.7 → 0.3.9-rc.1

package/build/utils/removedUiElements.js

@@ -0,0 +1,153 @@
+/**
+ * Removed UI elements (SKYR-4305) — grounding for the removal guard.
+ *
+ * The recommendation prompt already requires a candidate for every element a PR
+ * removes ("the removal is what this PR ships, so the removal is what gets tested").
+ * A blueprint can never contain a removed element, so this module supplies what the
+ * agent otherwise has to guess: WHICH identifying `data-*` attributes (`data-testid`,
+ * `data-cy`, `data-qa`, `data-test-id`, or another static `data-*`) the diff removed and
+ * on WHICH page they used to render. `data-testid` is asserted with `getByTestId`; every
+ * other attribute with `page.locator('[<attribute>="<value>"]')`, so the guard never
+ * silently resolves against the wrong attribute. It drafts nothing and gates nothing — it reduces noise:
+ *
+ *   - an id is reported only when its file survives the change (not in
+ *     `deletedFiles`) — a deleted route/component is maintenance of the tests that
+ *     covered it, not a page to assert on;
+ *   - a file the integration check marked `integrated: false` is skipped; when the
+ *     check produced no record for a file (it did not run, or failed), the file is
+ *     kept — fail-open, logged at debug;
+ *   - renames, moves and extractions to another file are excluded by
+ *     `extractRemovedAttributes` (added values are collected across the WHOLE diff);
+ *   - a value an existing discovered test already references is skipped — that test is
+ *     the one to update or delete, a new guard would duplicate it. The match is on the
+ *     VALUE regardless of attribute (a test naming `user-menu-row` as a testid also
+ *     suppresses a `data-section="user-menu-row"` guard) — deliberate over-suppression,
+ *     the safe direction, even though entries are keyed on attribute + value elsewhere. When discovery
+ *     itself failed the list is empty and nothing is reported (fail-closed), because
+ *     "no test references it" cannot be known;
+ *   - the page comes from `candidateUiPages` sourced from the file, or one hop via
+ *     the files that import it (a shared navbar maps to no route itself). This is a
+ *     static import-graph attribution, not evidence the element rendered there —
+ *     which is why the playbook demands a positive assertion on a retained element
+ *     of the same page next to every `toBeHidden()`.
+ *
+ * Every skip is logged at debug with its reason so a missing guard is diagnosable.
+ */
+import * as fs from "fs";
+import { extractAddedAttributeValues, extractRemovedAttributes } from "./frontendSelectors.js";
+import { escapeRegExp } from "./regex.js";
+import { logger } from "./logger.js";
+/**
+ * Bound the list: each entry is a guard assertion the agent records on one page, and
+ * the plan budget is small (`MAX_TESTS_TO_GENERATE`), so a large cleanup PR gets its
+ * first few ids, not a flood. Truncation is logged at info with the dropped count.
+ */
+export const MAX_REMOVED_UI_ELEMENTS = 5;
+function defaultReadFile(absPath) {
+    try {
+        return fs.readFileSync(absPath, "utf8");
+    }
+    catch (err) {
+        logger.warning("removedUiElements: could not read existing test (treated as not referencing any removed id)", {
+            file: absPath,
+            error: err instanceof Error ? err.message : String(err),
+        });
+        return undefined;
+    }
+}
+/**
+ * Whole-literal match: `order-total` must not be satisfied by `order-total-row`, and
+ * `foo:bar` not by `foo:bar:baz`. The identifier alphabet mirrors the extractor's
+ * value grammar (`[\w:-]`), so every character a value may contain is a
+ * non-boundary here.
+ */
+function referencesLiteral(content, value) {
+    return new RegExp(`(^|[^\\w:-])${escapeRegExp(value)}(?![\\w:-])`).test(content);
+}
+export function collectRemovedUiElements(input) {
+    if (input.discoveryFailed) {
+        logger.warning("removedUiElements: test discovery failed — cannot tell whether an existing test covers a removed id; reporting none");
+        return [];
+    }
+    const readFile = input.readFile ?? defaultReadFile;
+    const deleted = new Set(input.deletedFiles);
+    const integration = new Map((input.frontendFileIntegration ?? []).map((r) => [r.file, r]));
+    const skip = (file, reason, extra = {}) => logger.debug(`removedUiElements: skipped ${file} — ${reason}`, extra);
+    // Added values across the ENTIRE diff, so an element extracted into another file is a
+    // move, not a removal.
+    const addedAcrossDiff = new Set();
+    for (const slice of input.diffByFile.values()) {
+        for (const v of extractAddedAttributeValues(slice))
+            addedAcrossDiff.add(v);
+    }
+    const pagesSourcedFrom = (files) => {
+        const urls = new Set();
+        for (const p of input.candidateUiPages) {
+            if (files.some((f) => p.sourcedFrom.includes(f)))
+                urls.add(p.url);
+        }
+        return [...urls];
+    };
+    // Existing-test contents are read lazily and once: most PRs remove nothing.
+    let testContents;
+    const referencedByExistingTest = (value) => {
+        if (!testContents) {
+            testContents = input.existingTestFiles
+                .map((f) => readFile(f) ?? "")
+                .filter((c) => c.length > 0);
+        }
+        return testContents.some((c) => referencesLiteral(c, value));
+    };
+    const out = [];
+    const seen = new Set();
+    let dropped = 0;
+    for (const file of input.changedFrontendFiles) {
+        if (deleted.has(file)) {
+            skip(file, "file deleted by the diff (whole surface removed)");
+            continue;
+        }
+        const integ = integration.get(file);
+        if (integ && !integ.integrated) {
+            skip(file, "no production importer", { reason: integ.reason });
+            continue;
+        }
+        if (!integ && input.frontendFileIntegration)
+            skip(file, "no integration record — kept (fail-open)");
+        const slice = input.diffByFile.get(file);
+        if (!slice) {
+            skip(file, "no diff slice");
+            continue;
+        }
+        const attrs = extractRemovedAttributes(slice, addedAcrossDiff);
+        if (attrs.length === 0)
+            continue;
+        let pageUrls = pagesSourcedFrom([file]);
+        if (pageUrls.length === 0 && integ?.importers?.length)
+            pageUrls = pagesSourcedFrom(integ.importers);
+        if (pageUrls.length === 0) {
+            skip(file, "no candidate page sourced from the file or its importers", { removed: attrs.map((a) => `${a.attribute}="${a.value}"`) });
+            continue;
+        }
+        for (const { attribute, value } of attrs) {
+            const key = `${attribute}=${value}`;
+            if (seen.has(key))
+                continue;
+            if (referencedByExistingTest(value)) {
+                skip(file, `${attribute}="${value}" already referenced by an existing test (maintenance, not a guard)`);
+                continue;
+            }
+            // Mark the key seen whether reported or dropped, so a repeat of a dropped
+            // element is not counted twice in the cap log.
+            seen.add(key);
+            if (out.length >= MAX_REMOVED_UI_ELEMENTS) {
+                dropped++;
+                continue;
+            }
+            out.push({ attribute, value, file, pageUrls });
+        }
+    }
+    if (dropped > 0) {
+        logger.info(`removedUiElements: cap reached — ${dropped} removed element(s) not reported`, { cap: MAX_REMOVED_UI_ELEMENTS });
+    }
+    return out;
+}

package/build/utils/reportVerification.d.ts

@@ -1,4 +1,4 @@
-import { DriftAction } from "../types/TestAnalysis.js";
+import { MaintenanceActionCore } from "../types/TestAnalysis.js";
 /**
  * Enumerate every path that differs from HEAD in the working tree — staged,
  * unstaged, or untracked — as repo-relative paths, via `git status --porcelain`.
@@ -42,14 +42,15 @@ export interface UnchangedFileClaimsInput {
     }[];
     /** Maintenance verdicts (server-derived from skyramp_actions). `pomFile`, when set, is
      *  the file the edit actually lands in — see the UPDATE rule below. */
-    verdicts: {
-        action: DriftAction;
-        testFilePath: string;
-        pomFile?: string;
-    }[];
+    verdicts: Pick<MaintenanceActionCore, "action" | "testFilePath" | "pomFile" | "rebaselineSnapshots" | "rebaselineOnly">[];
     /** owner/repo of the primary repo — used to exempt cross-repo newTest claims
      *  whose files live in a different checkout. */
     primaryRepository?: string;
+    /** SKYR-4250: a plan-only eval run generates nothing — `newTestsCreated`
+     *  declares the approved GENERATE list — so no declaration can be backed by
+     *  a working-tree change. Exempts the declaration half only; a maintenance
+     *  UPDATE still claims a real edit and is still verified. */
+    planOnly?: boolean;
 }
 /**
  * Cross-check report claims against files that actually changed in the working

package/build/utils/reportVerification.js

@@ -1,9 +1,11 @@
 import path from "path";
 import * as fs from "fs/promises";
+import { existsSync } from "fs";
 import { execFile } from "child_process";
 import { promisify } from "util";
 import { testFileMatches } from "./utils.js";
 import { DriftAction } from "../types/TestAnalysis.js";
+import { baselineFileMatchesStem, baselineStem } from "./rebaselineSnapshots.js";
 const execFileAsync = promisify(execFile);
 /**
  * Enumerate every path that differs from HEAD in the working tree — staged,
@@ -124,7 +126,7 @@ export async function listChangedFiles(repoRoot) {
  *    absolute path resolving outside `repoRoot`) — a different checkout owns them.
  */
 export function findUnchangedFileClaims(input) {
-    const { repoRoot, changedFiles, newTests, verdicts, primaryRepository } = input;
+    const { repoRoot, changedFiles, newTests, verdicts, primaryRepository, planOnly, } = input;
     const unbacked = [];
     const isBacked = (claimedPath) => {
         let candidate = claimedPath;
@@ -137,7 +139,46 @@ export function findUnchangedFileClaims(input) {
         }
         return changedFiles.some((c) => testFileMatches(c, candidate));
     };
-    for (const t of newTests) {
+    // A visual-baseline UPDATE (SKYR-4298) edits no source: SmartPlaywright rewrites
+    // the PNG Playwright keeps beside the spec, `<spec>-snapshots/<name>-<project>-
+    // <platform>.png` (the default layout — see baselineFileMatchesStem for why that
+    // is safe to assume). Backed when one of the named baselines changed there AND
+    // still exists: `git status` lists a deleted file as changed too, and a destroyed
+    // baseline is the opposite of a refreshed one. Scoped to the spec's own snapshot
+    // directory so a refreshed baseline of some other spec cannot vouch for this one.
+    const isBackedBySnapshot = (specPath, baselines) => {
+        let specRel = specPath;
+        if (path.isAbsolute(specPath)) {
+            const rel = path.relative(repoRoot, specPath);
+            if (!rel || rel.startsWith("..") || path.isAbsolute(rel))
+                return true;
+            specRel = rel;
+        }
+        // git reports paths with "/" on every platform; path.relative uses the host
+        // separator, so a Windows run would otherwise never match its own snapshot dir.
+        specRel = specRel.split(path.sep).join("/");
+        const snapshotDir = `${specRel}-snapshots/`;
+        const stems = baselines.map(baselineStem).filter(Boolean);
+        return changedFiles.some((c) => {
+            // Same anchoring as testFileMatches: a path-qualified spec must match as a
+            // path segment; a bare basename can only match by directory basename.
+            const inDir = specRel.includes("/")
+                ? c.startsWith(snapshotDir) || c.includes("/" + snapshotDir)
+                : path.basename(path.dirname(c)) === snapshotDir.slice(0, -1);
+            if (!inDir)
+                return false;
+            const base = path.basename(c);
+            if (!stems.some((stem) => baselineFileMatchesStem(base, stem)))
+                return false;
+            return existsSync(path.resolve(repoRoot, c));
+        });
+    };
+    // A plan-only run declares its GENERATE list instead of writing files, so
+    // skip the claim scan wholesale rather than per-claim: checking it rejects
+    // every declaration the guard can see, and the ones it CANNOT see (cross-repo
+    // claims, exempted below) would pass — demoting the primary repo's items
+    // alone. Uneven enforcement is worse than none here.
+    for (const t of planOnly ? [] : newTests) {
         if (!t.fileName)
             continue;
         // Cross-repo finding — its file lives in a different checkout, not this tree.
@@ -160,9 +201,32 @@ export function findUnchangedFileClaims(input) {
         // The edit target, not the spec: for a POM-based test the page object is what
         // gets patched while testFilePath stays the spec (SKYR-4129).
         const editTarget = v.pomFile ?? v.testFilePath;
-        if (!isBacked(editTarget)) {
-            unbacked.push(`testMaintenance ${v.action} claims an edit to "${path.basename(editTarget)}", but that file has no working-tree change`);
+        // Baseline refresh (SKYR-4298): the verdict promises a replaced PNG next to the
+        // spec, and the report says "visual baseline refreshed" on its strength. Two rules:
+        //  - The PNG must have been rewritten. An edit to the spec does not stand in for
+        //    it, otherwise a run that forgot rebaselineSnapshots (or loosened
+        //    maxDiffPixelRatio instead) would report a refresh that never happened.
+        //  - Listing a baseline never exempts the edit the same verdict claimed. Unless the
+        //    verdict is rebaselineOnly (no updateInstructions), the edit target — the POM
+        //    when named, else the spec — still needs its own working-tree change; a
+        //    baseline attached to a selector-rename UPDATE cannot wave the rename through.
+        // A plan-only run executes nothing, so no PNG can be rewritten there; the edit
+        // half is still verified, as for every other UPDATE (SKYR-4250).
+        const baselines = v.rebaselineSnapshots ?? [];
+        if (baselines.length > 0) {
+            const editOk = v.rebaselineOnly === true || isBacked(editTarget);
+            const pngOk = planOnly || isBackedBySnapshot(v.testFilePath, baselines);
+            if (!pngOk) {
+                unbacked.push(`testMaintenance ${v.action} claims a refreshed visual baseline (${baselines.join(", ")}) for "${path.basename(v.testFilePath)}", but no matching PNG was rewritten under its -snapshots directory — the final skyramp_execute_test run must pass rebaselineSnapshots and report it as refreshed; editing the spec does not stand in for the refresh`);
+            }
+            if (!editOk) {
+                unbacked.push(`testMaintenance ${v.action} claims an edit to "${path.basename(editTarget)}" alongside a baseline refresh, but that file has no working-tree change — listing a baseline does not exempt the edit`);
+            }
+            continue;
         }
+        if (isBacked(editTarget))
+            continue;
+        unbacked.push(`testMaintenance ${v.action} claims an edit to "${path.basename(editTarget)}", but that file has no working-tree change`);
     }
     return unbacked;
 }

package/build/utils/scenarioDrafting.d.ts

@@ -46,7 +46,7 @@ export declare function draftScenariosFromEndpoints(endpoints: Array<EndpointInp
 /**
  * Enforce a global cap on drafted scenarios while preserving category diversity.
  *
- * 1. CRITICAL (bug_caught) scenarios prioritized first.
+ * 1. CRITICAL (bug_caught, requirement_conflict) scenarios prioritized first.
  * 2. One scenario per non-empty category guaranteed (breadth).
  * 3. Remaining budget filled by priority tier (HIGH > MEDIUM > LOW).
  * 4. Hard cap at MAX_TOTAL_SCENARIOS — applied to the combined output.

package/build/utils/scenarioDrafting.js

@@ -226,7 +226,7 @@ const TIER_ORDER = { CRITICAL: 4, HIGH: 3, MEDIUM: 2, LOW: 1 };
 /**
  * Enforce a global cap on drafted scenarios while preserving category diversity.
  *
- * 1. CRITICAL (bug_caught) scenarios prioritized first.
+ * 1. CRITICAL (bug_caught, requirement_conflict) scenarios prioritized first.
  * 2. One scenario per non-empty category guaranteed (breadth).
  * 3. Remaining budget filled by priority tier (HIGH > MEDIUM > LOW).
  * 4. Hard cap at MAX_TOTAL_SCENARIOS — applied to the combined output.

package/build/utils/versions.d.ts

@@ -1,4 +1,4 @@
-export declare const SKYRAMP_IMAGE_VERSION = "v1.3.40";
-export declare const EXECUTOR_DOCKER_IMAGE = "skyramp/executor:v1.3.40";
-export declare const WORKER_DOCKER_IMAGE = "skyramp/worker:v1.3.40";
+export declare const SKYRAMP_IMAGE_VERSION = "v1.3.42";
+export declare const EXECUTOR_DOCKER_IMAGE = "skyramp/executor:v1.3.42";
+export declare const WORKER_DOCKER_IMAGE = "skyramp/worker:v1.3.42";
 export declare const WORKER_CONTROL_PORT = 35142;

package/build/utils/versions.js

@@ -1,4 +1,4 @@
-export const SKYRAMP_IMAGE_VERSION = "v1.3.40";
+export const SKYRAMP_IMAGE_VERSION = "v1.3.42";
 export const EXECUTOR_DOCKER_IMAGE = `skyramp/executor:${SKYRAMP_IMAGE_VERSION}`;
 export const WORKER_DOCKER_IMAGE = `skyramp/worker:${SKYRAMP_IMAGE_VERSION}`;
 // Control port the Skyramp worker listens on (SDK `CONTAINER_PORT`).

package/node_modules/playwright/lib/mcp/skyramp/assertHiddenTool.js

@@ -0,0 +1,56 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var assertHiddenTool_exports = {};
+__export(assertHiddenTool_exports, {
+  assertHiddenMcpTool: () => assertHiddenMcpTool,
+  assertHiddenToolSchema: () => assertHiddenToolSchema
+});
+module.exports = __toCommonJS(assertHiddenTool_exports);
+var import_mcpBundle = require("playwright-core/lib/mcpBundle");
+var import_tool = require("../sdk/tool");
+const assertHiddenToolSchema = {
+  name: "browser_assert_hidden",
+  title: "Assert element absent or hidden",
+  description: [
+    "Assert that an element is absent from the page or not visible \u2014 the recorded form of expect(locator).toBeHidden().",
+    "Use it for an element a change removed, after navigating to the page that used to show it.",
+    "Takes exactly one target: testId, or role + name, or text, or attribute + value. There is no snapshot ref (a removed element has none).",
+    "role + name and text match EXACTLY (case-sensitive, whole string): the values come verbatim from the removed source, not from snapshot text.",
+    "The tool refuses to record on a page that is not a loaded http(s) application page (about:blank, an error page, a data: URL),",
+    "where every absence would be vacuously true. Only a passing assertion is recorded in the trace."
+  ].join(" "),
+  inputSchema: import_mcpBundle.z.object({
+    element: import_mcpBundle.z.string().describe("Human-readable description of the element that must be absent or not visible"),
+    testId: import_mcpBundle.z.string().optional().describe("The data-testid of the element that must be absent or not visible. Pass exactly one of testId, role (+ name), text, or attribute (+ value)."),
+    role: import_mcpBundle.z.string().optional().describe('ARIA role of the element that must be absent or not visible (button, link, heading, textbox, \u2026). Requires "name".'),
+    name: import_mcpBundle.z.string().optional().describe('Accessible name that goes with "role"; matched exactly (case-sensitive, whole string).'),
+    text: import_mcpBundle.z.string().optional().describe("Exact visible text of the element that must be absent or not visible (whole string, case-sensitive)."),
+    attribute: import_mcpBundle.z.string().optional().describe("A `data-*` attribute name (e.g. `data-cy`, `data-qa`, `data-test-id`) identifying the removed element; pair with `value`. Use `testId` instead when the attribute is `data-testid`."),
+    value: import_mcpBundle.z.string().optional().describe("The literal value of `attribute`.")
+  }),
+  type: "readOnly"
+};
+function assertHiddenMcpTool() {
+  return (0, import_tool.toMcpTool)(assertHiddenToolSchema);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  assertHiddenMcpTool,
+  assertHiddenToolSchema
+});

package/node_modules/playwright/lib/mcp/skyramp/assertTool.js

@@ -35,7 +35,8 @@ const assertToolSchema = {
     '"checked" checks checkbox/radio state, "disabled" checks disabled/enabled state,',
     '"visible" checks the element is visible,',
     `"count" counts elements sharing the referenced element's role (or exact text)`,
-    "across the page, e.g. ref one option of an open dropdown to assert the number of options."
+    "across the page, e.g. ref one option of an open dropdown to assert the number of options.",
+    "To assert an element is absent or not visible, use `browser_assert_hidden`."
   ].join(" "),
   inputSchema: import_mcpBundle.z.object({
     type: import_mcpBundle.z.enum(["text", "value", "checked", "disabled", "visible", "count"]).describe(`Type of assertion: "text" for text content, "value" for input field value, "checked" for checkbox/radio state, "disabled" for disabled/enabled state ("false" asserts the element is enabled), "visible" for element visibility, "count" for the number of elements with the referenced element's role`),

package/node_modules/playwright/lib/mcp/skyramp/loadTraceTool.js

@@ -378,6 +378,16 @@ async function performClientAction(page, actionInContext) {
         throw new Error(`assertDisabled failed: expected disabled=${action.disabled}, got ${disabled}`);
       return;
     }
+    case "assertHidden": {
+      try {
+        await locator.waitFor({ ...opts, state: "hidden" });
+      } catch (e) {
+        if (e?.name === "TimeoutError")
+          throw new Error(`assertHidden failed: element is still visible (${e.message})`);
+        throw e;
+      }
+      return;
+    }
     case "assertCount": {
       await locator.first().waitFor(opts).catch(() => {
       });

package/node_modules/playwright/lib/mcp/skyramp/skyRampImport.js

@@ -63,6 +63,7 @@ const ACTION_NAMES = /* @__PURE__ */ new Set([
   "assertVisible",
   "assertDisabled",
   "assertCount",
+  "assertHidden",
   "assertSnapshot",
   "visualSnapshot",
   "assertTableCell",
@@ -138,7 +139,9 @@ function parseLine(line) {
   }
   if (!entry.name || !isActionName(entry.name))
     return null;
-  const { pageGuid, pageAlias, framePath, locator: _locator, ...actionFields } = entry;
+  const { pageGuid, pageAlias, framePath, locator, ...actionFields } = entry;
+  if (entry.name === "assertHidden" && locator && typeof locator === "object")
+    actionFields.locator = locator;
   const frame = {
     pageGuid: pageGuid ?? "",
     pageAlias: pageAlias ?? "page",

package/node_modules/playwright/lib/mcp/skyramp/traceRecordingBackend.js

@@ -45,6 +45,7 @@ var import_log = require("../log");
 var import_skyRampExport = require("../test/skyRampExport");
 var import_exportTool = require("./exportTool");
 var import_assertTool = require("./assertTool");
+var import_assertHiddenTool = require("./assertHiddenTool");
 var import_assertApiRequestTool = require("./assertApiRequestTool");
 var import_loadTraceTool = require("./loadTraceTool");
 var import_skyRampImport = require("./skyRampImport");
@@ -186,7 +187,7 @@ class TraceRecordingBackend {
   }
   async listTools() {
     const browserTools = await this._browserBackend.listTools();
-    return [...browserTools, (0, import_exportTool.exportZipMcpTool)(), (0, import_assertTool.assertMcpTool)(), (0, import_assertApiRequestTool.assertApiRequestMcpTool)(), (0, import_loadTraceTool.loadTraceMcpTool)(), (0, import_mouseActionTool.mouseActionMcpTool)(), (0, import_tableAssertTool.tableAssertMcpTool)(), (0, import_visualSnapshotTool.visualSnapshotMcpTool)(), (0, import_gojsTool.gojsAddNodeMcpTool)(), (0, import_gojsTool.gojsLinkMcpTool)()];
+    return [...browserTools, (0, import_exportTool.exportZipMcpTool)(), (0, import_assertTool.assertMcpTool)(), (0, import_assertHiddenTool.assertHiddenMcpTool)(), (0, import_assertApiRequestTool.assertApiRequestMcpTool)(), (0, import_loadTraceTool.loadTraceMcpTool)(), (0, import_mouseActionTool.mouseActionMcpTool)(), (0, import_tableAssertTool.tableAssertMcpTool)(), (0, import_visualSnapshotTool.visualSnapshotMcpTool)(), (0, import_gojsTool.gojsAddNodeMcpTool)(), (0, import_gojsTool.gojsLinkMcpTool)()];
   }
   async callTool(name, args, progress) {
     if (!this._initialized)
@@ -238,6 +239,10 @@ class TraceRecordingBackend {
       const parsed = import_assertTool.assertToolSchema.inputSchema.parse(args || {});
       return this._handleAssert(parsed);
     }
+    if (name === import_assertHiddenTool.assertHiddenToolSchema.name) {
+      const parsed = import_assertHiddenTool.assertHiddenToolSchema.inputSchema.parse(args || {});
+      return this._handleAssertHidden(parsed, Date.now());
+    }
     if (name === import_assertApiRequestTool.assertApiRequestSchema.name) {
       this._trackedActions.push({
         toolName: "browser_assert_api_request",
@@ -855,6 +860,14 @@ Continue recording with browser_* tools, then call skyramp_export_zip to write t
         return { toolName: "browser_assert", code: `assertChecked:${a.selector}:${!!a.checked}`, args: { type: "checked", selector: a.selector, checked: !!a.checked } };
       case "assertVisible":
         return { toolName: "browser_assert", code: `assertVisible:${a.selector}`, args: { type: "visible", selector: a.selector } };
+      case "assertHidden": {
+        if (typeof a.selector !== "string" || !a.selector)
+          return null;
+        const args = { type: "hidden", selector: a.selector };
+        if (a.locator && typeof a.locator === "object")
+          args.locator = a.locator;
+        return { toolName: "browser_assert", code: `assertHidden:${a.selector}`, args };
+      }
       case "assertDisabled":
         if (typeof a.disabled !== "boolean")
           return null;
@@ -1365,6 +1378,9 @@ Role "${refRole}" is not countable \u2014 reference an exemplar with a semantic
       if (!tab) {
         return { content: [{ type: "text", text: "### Assertion Failed\nNo active page." }], isError: true };
       }
+      const notReady = await this._requireLoadedPage(tab, "domcontentloaded");
+      if (notReady)
+        return notReady;
       countSelector = `internal:role=${refRole}`;
       let countActual;
       try {
@@ -1520,6 +1536,149 @@ Cell row ${params.row}, column ${params.column} equals "${params.expected}".` :
 Cell row ${params.row}, column ${params.column} has "${actual}", expected "${params.expected}".` }]
     };
   }
+  static {
+    /**
+     * How long a still-present browser_assert_hidden target may take to disappear
+     * before the check reports "still visible". Short on purpose: the agent
+     * asserts after the page has settled, so a longer wait only delays a genuine
+     * failure verdict.
+     */
+    this.HIDDEN_WAIT_TIMEOUT_MS = 2e3;
+  }
+  /**
+   * Page-readiness guard shared by the checks whose live query passes
+   * vacuously on a page that has not loaded the application:
+   * browser_assert_hidden (waitFor({ state: 'hidden' }) resolves instantly for
+   * zero matches) and browser_assert type:"count" (getByRole().count() is 0 on
+   * an empty page).
+   *
+   * What it checks: only the URL scheme. about:blank, chrome-error:// and
+   * data: URLs are refused with an error; an http(s)/file: page is then given
+   * up to 5 s to reach the load event (best-effort — a slow page is not an
+   * error, the caller's own wait/timeout decides).
+   *
+   * What it does NOT catch: a typo'd or stale target on a correctly loaded
+   * page still passes here — this guard cannot tell "removed" from "never
+   * existed". There is deliberately no rendered-element check either: a
+   * text-only page or a canvas/Flutter app has few or no elements under <body>
+   * and is still a loaded page. The defence against a wrong target lives on the
+   * mcp side, which enforces (as a lint) that every absence assertion is paired
+   * with a positive assertion on the same page.
+   *
+   * `loadState` is the readiness bar after the URL check: `hidden` waits for
+   * `load` (an absence verdict wants the page fully settled), `count` only for
+   * `domcontentloaded` — a streaming or long-polling SPA may never fire `load`,
+   * and a live count should not pay up to 5 s of latency for that.
+   *
+   * Returns the isError result to hand back, or null when the page is ready.
+   */
+  async _requireLoadedPage(tab, loadState = "load") {
+    const url = tab.page.url();
+    if (!/^(?:https?|file):/.test(url))
+      return { content: [{ type: "text", text: `### Error
+The current page (${url}) is not a loaded application page; navigate to the app before asserting on it.` }], isError: true };
+    await tab.page.waitForLoadState(loadState, { timeout: 5e3 }).catch(() => {
+    });
+    return null;
+  }
+  /**
+   * browser_assert_hidden (SKYR-4305): the element is absent from the page or
+   * not visible — the recorded form of expect(locator).toBeHidden().
+   * Targets are named (testId | role+name | text | attribute+value) rather than
+   * referenced by a snapshot ref because the typical subject no longer exists
+   * at all (a change removed it), and the browser_assert path resolves refs via
+   * browser_hover, which fails actionability on a hidden element anyway.
+   *
+   * Exactness: role+name and text are both recorded EXACT (`s` suffix /
+   * exact: true) — one rule for this tool. The other producers
+   * (_codeToLocator, _extractLocatorForRef) record `i` because their values come
+   * from snapshot text, which may be trimmed or partially rendered; here the
+   * values come verbatim from the deleted source, so exact is both safe and
+   * needed: a substring "Session" match would keep failing until every
+   * "Session…" occurrence on the page is gone.
+   *
+   * The locator object is built here next to the selector and recorded on the
+   * tracked action (args.locator), so the exporter never has to regex-parse a
+   * JSON-quoted value back out of the selector string.
+   *
+   * Verification is live: locator.waitFor({ state: 'hidden' }) has exactly
+   * toBeHidden's contract — resolves for zero matches or one non-visible match,
+   * times out while the match is visible, and strict-fails on multiple matches
+   * (no `.first()`, so the recorder can never record a pass the generated
+   * expect(locator).toBeHidden() would throw on). Because zero matches passes,
+   * _requireLoadedPage runs first.
+   *
+   * Recorded as toolName 'browser_assert' with args.type 'hidden', so
+   * assertActionToJsonl and the re-seed path share one shape with the other
+   * assertions.
+   */
+  async _handleAssertHidden(params, timestamp) {
+    const err = (text) => ({ content: [{ type: "text", text: `### Error
+${text}` }], isError: true });
+    const given = [params.testId, params.role, params.text, params.attribute].filter((v) => typeof v === "string" && v.trim() !== "");
+    if (given.length !== 1)
+      return err('Pass exactly one target: "testId", or "role" together with "name", or "text", or "attribute" together with "value". There is no "ref" \u2014 a removed element has no snapshot ref.');
+    if (!params.role?.trim() && typeof params.name === "string")
+      return err('"name" only goes with "role" (the ARIA role of the element it names).');
+    if (!params.attribute?.trim() && typeof params.value === "string")
+      return err('"value" only goes with "attribute" (the data-* attribute name it is the value of).');
+    let selector;
+    let locator;
+    if (params.testId?.trim()) {
+      const testId = params.testId.trim();
+      selector = `internal:testid=[data-testid=${JSON.stringify(testId)}s]`;
+      locator = { kind: "test-id", body: testId, options: {} };
+    } else if (params.role?.trim()) {
+      const role = params.role.trim();
+      if (!TraceRecordingBackend.ASSERTABLE_ROLES.has(role))
+        return err(`Role "${role}" is not assertable \u2014 use a semantic role (button, link, heading, textbox, \u2026) or pass "testId"/"text" instead.`);
+      const name = params.name?.trim() ?? "";
+      if (!name)
+        return err('By role, "name" is required \u2014 a bare role would assert that no such element exists anywhere on the page.');
+      selector = `internal:role=${role}[name=${JSON.stringify(name)}s]`;
+      locator = { kind: "role", body: role, options: { attrs: [], exact: true, name } };
+    } else if (params.attribute?.trim()) {
+      const attribute = params.attribute.trim().toLowerCase();
+      if (!/^data-[a-z0-9]+(?:-[a-z0-9]+)*$/.test(attribute))
+        return err(`Attribute "${params.attribute.trim()}" is not a data-* attribute. "attribute" accepts only data-* attributes (data-cy, data-qa, data-test-id, \u2026); target other elements by role + name or text instead.`);
+      const value = params.value?.trim() ?? "";
+      if (!value)
+        return err('By attribute, a non-empty "value" is required \u2014 a bare attribute would assert that no element carries it anywhere on the page.');
+      selector = `[${attribute}=${JSON.stringify(value)}]`;
+      locator = { kind: "default", body: selector, options: {} };
+    } else {
+      const text = params.text.trim();
+      selector = `internal:text=${JSON.stringify(text)}s`;
+      locator = { kind: "text", body: text, options: { exact: true } };
+    }
+    const tab = this._browserBackend.context?.currentTab();
+    if (!tab)
+      return err("No active page.");
+    const notReady = await this._requireLoadedPage(tab);
+    if (notReady)
+      return notReady;
+    let passed = true;
+    try {
+      await tab.page.locator(selector).waitFor({ state: "hidden", timeout: TraceRecordingBackend.HIDDEN_WAIT_TIMEOUT_MS });
+    } catch (e) {
+      if (/strict mode violation/i.test(String(e?.message ?? "")))
+        return err(`Target ${selector} matches multiple elements, so toBeHidden() would fail strict mode. Use a more specific target (a data-testid, or role + exact name). ${String(e.message).split("\n")[0]}`);
+      if (e?.name !== "TimeoutError")
+        return err(`Could not verify absence of "${params.element}": ${e?.message ?? e}`);
+      passed = false;
+    }
+    let details;
+    if (passed) {
+      details = `Hidden assertion passed: "${params.element}" is absent or not visible.`;
+      this._trackedActions.push({ toolName: "browser_assert", args: { type: "hidden", selector, locator }, code: `assertHidden:${selector}`, timestamp });
+      traceDebug(`Assert: assertHidden with selector ${selector}`);
+    } else {
+      const count = await tab.page.locator(selector).count().catch(() => -1);
+      details = `Hidden assertion FAILED: "${params.element}" is still visible (${count < 0 ? "unknown" : count} element(s) match ${selector}).`;
+    }
+    return { content: [{ type: "text", text: `### ${passed ? "Assertion Passed" : "Assertion Failed"}
+${details}` }] };
+  }
   /** Convert a Playwright locator expression to a selector + locator object for JSONL. */
   _codeToLocator(expr) {
     const testidMatch = expr.match(/getByTestId\(\s*['"]([^'"]+)['"]\s*\)/);