@skyramp/mcp 0.3.8 → 0.3.9-rc.1

package/build/tools/test-management/analyzeChangesTool.js

@@ -33,6 +33,7 @@ import { detectProjectMetadata } from "../../utils/projectMetadata.js";
 import { draftScenariosFromEndpoints, draftResponseShapeScenarios, capScenarios } from "../../utils/scenarioDrafting.js";
 import { mapUnmatchedFilesToImporterEndpoints, buildHopResponseShapeInputs, deriveResourceTokensForFile, deriveResourceToken, extractChangedSymbols, sliceDiffByFile } from "../../utils/importerHop.js";
 import { extractChangedSelectors, MAX_CHANGED_SELECTORS } from "../../utils/frontendSelectors.js";
+import { collectRemovedUiElements, MAX_REMOVED_UI_ELEMENTS } from "../../utils/removedUiElements.js";
 import { buildAnalysisOutputText } from "../../prompts/test-recommendation/analysisOutputPrompt.js";
 import { parseTraceFile, discoverTraceFiles, discoverPlaywrightZips, } from "../../utils/trace-parser.js";
 import { TestSource } from "../../types/TestAnalysis.js";
@@ -359,6 +360,39 @@ If a candidate URL 404s or redirects unexpectedly, navigate from the frontend ba
 
 If \`browser_blueprint\` fails on every candidate URL (app unreachable, all 404s), proceed and log an \`issuesFound\` info entry. Recommendations will be source-grounded; non-UI work is unaffected.`;
 }
+/**
+ * Instruction block for data-testids the diff removed from pages that survive
+ * (SKYR-4305). The UI analog of the `[removed]` endpoint 404 guard: one UI
+ * candidate per element, asserting the element is gone plus a positive check on a
+ * retained element of the same page. Whole-feature removals never reach here —
+ * collectRemovedUiElements drops elements whose file was deleted or whose page
+ * could not be resolved.
+ */
+export function buildRemovedElementsInstructions(elements) {
+    const byPage = new Map();
+    for (const e of elements) {
+        for (const url of e.pageUrls) {
+            if (!byPage.has(url))
+                byPage.set(url, []);
+            byPage.get(url).push(e);
+        }
+    }
+    const target = (e) => e.attribute === "data-testid" ? `testId: "${e.value}"` : `attribute: "${e.attribute}", value: "${e.value}"`;
+    const pageLines = [...byPage.entries()]
+        .map(([url, els], i) => `  ${i + 1}. ${url}\n` + els.map((e) => `       - \`${e.attribute}="${e.value}"\`  (removed from ${e.file}; browser_assert_hidden target: ${target(e)})`).join("\n"))
+        .join("\n");
+    const capNote = elements.length >= MAX_REMOVED_UI_ELEMENTS
+        ? `\n(The list is capped at ${MAX_REMOVED_UI_ELEMENTS} elements; the analyze log records how many were dropped.)`
+        : "";
+    return `**Removed UI elements — grounding for the removal test.** This diff deletes the elements below (identified by a \`data-*\` attribute) from pages that still exist after the change. The budget rule already requires a test asserting a removed element is absent; this list tells you WHICH elements and on WHICH page, which no blueprint can (the elements are gone). Renames, moved/extracted elements, elements in deleted files, files with no production importer, and values an existing test already references were filtered out server-side; the page is attributed through the import graph (the file, or one hop via the files that import it), not observed.
+
+**Removed elements by page:**
+${pageLines}${capNote}
+
+**How to record (Task 2), per page — not per element:** if the plan already has a UI candidate on that page, record the guard inside that trace; otherwise register ONE UI candidate \`verify-removed-ui-<page-slug>\` (\`testType: "ui"\`, category \`breaking_change\`; \`skyramp_register_test_plan\` requires at least one step, so use a placeholder \`GET <page path>\` → 200). \`browser_navigate\` to the page and let the app render, then one \`browser_assert_hidden\` call per element using the target shown above — \`testId\` when the attribute is \`data-testid\`, otherwise \`attribute\` + \`value\` (the generated test then uses \`getByTestId(...)\` or \`page.locator('[data-cy="..."]')\` respectively; no \`ref\` — a removed element has no snapshot ref; the tool checks the live page and refuses to record on a blank or un-rendered page), then at least one \`browser_assert\` on a RETAINED element of the same page verifying its text, value or state — the generated \`toBeHidden()\` assertions must never stand alone. Then \`skyramp_export_zip\` and \`skyramp_ui_test_generation\` as usual.
+
+**Blueprint Citation for these recommendations:** the removed elements will not appear in any blueprint you capture — that is expected. For a \`data-testid\` element set \`targetElements[].testId\` to the value; for any other attribute leave \`testId\` null and name the \`attribute="value"\` pair in \`reasoning\`. Take \`role\`/\`accessibleName\` from the deleted JSX in the diff, set \`pageContext.url\` to the page above, and prefix the recommendation's \`reasoning\` with \`[removed-element]\`.`;
+}
 /**
  * Instruction block for changed frontend files the server determined have no
  * production importer (SKYR-3855) — dead/orphaned components. Used both to
@@ -775,6 +809,7 @@ export function registerAnalyzeChangesTool(server) {
             }
             let existingTests = [];
             let discoveredRelevantExternalPaths = [];
+            let testDiscoveryFailed = false;
             try {
                 const testDiscoveryService = new TestDiscoveryService();
                 // Run-scoped: only the primary call carries testsRepoDir, so never
@@ -799,6 +834,7 @@ export function registerAnalyzeChangesTool(server) {
                 });
             }
             catch (err) {
+                testDiscoveryFailed = true;
                 logger.warning("Test discovery failed, continuing with empty list", {
                     error: err instanceof Error ? err.message : String(err),
                 });
@@ -1379,10 +1415,44 @@ export function registerAnalyzeChangesTool(server) {
                 // the pages that import them.
                 const frontendFileIntegration = checkFrontendFileIntegration(params.repositoryPath, changedFrontendFiles);
                 const candidateUiPages = await enumerateCandidateUiPages(params.repositoryPath, changedFrontendFiles, frontendFileIntegration);
+                // SKYR-4305: data-testids the diff removed from a page that survives —
+                // grounding for the removal test the budget rule requires (a removed
+                // element appears in no blueprint). Purely additive: a failure here must
+                // never cost the analyze call.
+                let removedElements = [];
+                if (diffData?.diffContent) {
+                    try {
+                        removedElements = collectRemovedUiElements({
+                            changedFrontendFiles,
+                            deletedFiles: diffData.deletedFiles ?? [],
+                            diffByFile: getDiffByFile(),
+                            frontendFileIntegration,
+                            candidateUiPages,
+                            existingTestFiles: [
+                                ...existingTests.map((t) => t.testFile),
+                                ...discoveredRelevantExternalPaths,
+                            ],
+                            discoveryFailed: testDiscoveryFailed,
+                        });
+                    }
+                    catch (err) {
+                        logger.warning("removedUiElements: collection failed, continuing without removal-guard grounding", {
+                            error: err instanceof Error ? err.message : String(err),
+                        });
+                        removedElements = [];
+                    }
+                }
+                if (removedElements.length > 0) {
+                    logger.info("Removed UI elements detected (removal-guard grounding)", {
+                        count: removedElements.length,
+                        removed: removedElements.map((e) => `${e.attribute}="${e.value}"`),
+                    });
+                }
                 return {
                     changedFrontendFiles,
                     candidateUiPages,
                     frontendFileIntegration,
+                    ...(removedElements.length > 0 ? { removedElements } : {}),
                 };
             })();
             // Derive the UI blueprint-capture instructions the agent acts on after
@@ -1407,6 +1477,9 @@ export function registerAnalyzeChangesTool(server) {
                         : buildCaptureInstructions(uiContext.candidateUiPages)) +
                         (unintegratedFrontendFiles.length > 0
                             ? `\n\n${buildUnintegratedInstructions(unintegratedFrontendFiles)}`
+                            : "") +
+                        (uiContext.removedElements?.length
+                            ? `\n\n${buildRemovedElementsInstructions(uiContext.removedElements)}`
                             : "");
             // ── SKYR-3879 Path B: budget context + pre-seeded approved plan ──
             // Computed BEFORE the state write (not after, alongside the

package/build/types/TestAnalysis.d.ts

@@ -41,6 +41,18 @@ export interface MaintenanceActionCore {
      *  downstream stage that reasons about the edit needs both — notably the report-time
      *  working-tree check, which otherwise calls a POM-backed UPDATE unbacked (SKYR-4129). */
     pomFile?: string;
+    /** Visual-snapshot baselines (toHaveScreenshot filenames, e.g. "page-001.png") an UPDATE
+     *  refreshes because the diff changed how the captured page/element looks (SKYR-4298).
+     *  The edit lands in the PNG under `<spec>-snapshots/`, not in the spec, so the
+     *  report-time working-tree check must accept that PNG as the UPDATE's backing, and
+     *  the final `skyramp_execute_test` must receive the list as `rebaselineSnapshots`. */
+    rebaselineSnapshots?: string[];
+    /** True when the UPDATE carries rebaselineSnapshots and no updateInstructions: the
+     *  refresh is its whole maintenance, so no edit to the spec/POM is expected. When false
+     *  (or absent) with baselines listed, the report-time check requires BOTH the edit and
+     *  the rewritten PNG — a listed baseline must never exempt the selector edit the same
+     *  verdict claimed (SKYR-3883 stays in force). */
+    rebaselineOnly?: boolean;
 }
 /** Normalized internal recommendation built from LLM-supplied args.recommendations. */
 export interface DriftRecommendation extends MaintenanceActionCore {

package/build/types/TestExecution.d.ts

@@ -60,6 +60,10 @@ export interface TestExecutionOptions {
     playwrightSaveStoragePath?: string;
     dockerNetwork?: string;
     useHostNetwork?: boolean;
+    /** Visual-snapshot baselines (toHaveScreenshot filenames, e.g. "page-001.png") this run
+     *  replaces instead of comparing against — forwarded to SmartPlaywright as
+     *  SKYRAMP_UPDATE_SNAPSHOTS (SKYR-4298). Only for an intended UI change the diff explains. */
+    rebaselineSnapshots?: string[];
 }
 /**
  * Progress callback for reporting execution status

package/build/utils/AnalysisStateManager.d.ts

@@ -5,6 +5,7 @@ import { RepositoryAnalysis, AnalysisScope } from "../types/RepositoryAnalysis.j
 import { PRTestContext } from "./pr-comment-parser.js";
 import { ParsedDiffEndpoint } from "./routeParsers.js";
 import type { CandidateUiPage } from "./uiPageEnumerator.js";
+import type { RemovedUiElement } from "./removedUiElements.js";
 import type { FrontendFileIntegration } from "../types/FrontendIntegration.js";
 import type { ApprovedPlanItem } from "../types/Recommendation.js";
 import type { ExternalTestRunRecord } from "../types/ExternalTestExecution.js";
@@ -135,6 +136,12 @@ export interface UiAnalysisContext {
      * the agent running its own grep mid-task. Same order as changedFrontendFiles.
      */
     frontendFileIntegration?: FrontendFileIntegration[];
+    /**
+     * data-testids the diff removed from files whose page survives (SKYR-4305).
+     * Present only when non-empty. The testbot records a removal guard
+     * (`toBeHidden()` on the id + a positive sibling assertion) for each entry.
+     */
+    removedElements?: RemovedUiElement[];
 }
 /**
  * SKYR-3879 Path B — the server-side selection checkpoint's persisted result.

package/build/utils/assertion-verify/ui-lints.d.ts

@@ -1,8 +1,3 @@
 import type { AssertionLanguage } from "./metrics.js";
 import { type LintFinding, type LintOptions } from "./lint-types.js";
-/** UI (Playwright) lints. Python (playwright-python) UI specs deliberately get
- *  the site-scoped lints only: the structural rules' patterns and accept-lists
- *  are JS/TS-specific (imports, waitForResponse shapes, expect matcher accept
- *  forms), and porting them without a python golden corpus to validate against
- *  would recreate the false-block class review round 2 removed. Pinned by test. */
 export declare function lintUiSpec(raw: string, language: AssertionLanguage, opts?: LintOptions): LintFinding[];

package/build/utils/assertion-verify/ui-lints.js

@@ -222,6 +222,36 @@ function lintUnassertedTrailingAction(stripped) {
  *  are JS/TS-specific (imports, waitForResponse shapes, expect matcher accept
  *  forms), and porting them without a python golden corpus to validate against
  *  would recreate the false-block class review round 2 removed. Pinned by test. */
+// SKYR-4305 — a removal guard (`toBeHidden()` / `not.toBeVisible()` on an element a
+// PR removed) is only meaningful next to a positive assertion on the same page: alone
+// it passes on a blank page, a 404, a typo'd testid, or a page the element never
+// rendered on. `toBeHidden` is a PARTIAL_MATCHER (weight 2), so the strength gate does
+// not catch a negative-only spec; this lint does.
+const ABSENCE_ASSERT_RE = /\.\s*(?:toBeHidden|to_be_hidden)\s*\(|\.\s*not\s*\.\s*(?:toBeVisible|toBeAttached)\s*\(|\.\s*not_to_be_(?:visible|attached)\s*\(/g;
+// Only Playwright LOCATOR/page matchers count as the positive half of the pair —
+// they prove something rendered. Generic Jest matchers (toBe/toEqual/toHaveLength)
+// are deliberately absent: `expect(resp.status()).toBe(200)` next to a lone
+// toBeHidden() proves nothing about the page.
+const POSITIVE_ASSERT_RE = /\.\s*(?:toHaveText|toContainText|toHaveValue|toHaveValues|toHaveAttribute|toHaveCount|toHaveURL|toHaveTitle|toHaveId|toHaveClass|toHaveCSS|toHaveJSProperty|toHaveAccessibleName|toHaveAccessibleDescription|toHaveRole|toHaveScreenshot|toBeVisible|toBeChecked|toBeEnabled|toBeDisabled|toBeEditable|toBeEmpty|toBeFocused|toBeInViewport|toContainClass|to_have_text|to_contain_text|to_have_value|to_have_values|to_have_attribute|to_have_count|to_have_url|to_have_title|to_have_id|to_have_class|to_have_css|to_have_js_property|to_have_accessible_name|to_have_accessible_description|to_have_role|to_have_screenshot|to_be_visible|to_be_checked|to_be_enabled|to_be_disabled|to_be_editable|to_be_empty|to_be_focused|to_be_in_viewport|to_contain_class)\s*\(/;
+function lintNegativeOnlySpec(commentless) {
+    ABSENCE_ASSERT_RE.lastIndex = 0;
+    const first = ABSENCE_ASSERT_RE.exec(commentless);
+    if (!first)
+        return [];
+    // Strip the absence assertions themselves, then look for a Playwright matcher
+    // on a rendered element (generic Jest matchers do not count — see POSITIVE_ASSERT_RE).
+    const remainder = commentless.replace(ABSENCE_ASSERT_RE, "");
+    ABSENCE_ASSERT_RE.lastIndex = 0;
+    if (POSITIVE_ASSERT_RE.test(remainder))
+        return [];
+    return [{
+            rule: "negative-only-spec",
+            severity: "hard",
+            line: lineOfOffset(commentless, first.index),
+            message: "Every locator assertion in this spec asserts absence (toBeHidden / not.toBeVisible); nothing proves the page rendered, so it passes on a blank page, a 404 or a typo'd selector.",
+            remediation: "Add at least one positive assertion on a retained element of the same page (toHaveText / toHaveValue / toHaveCount / toHaveURL) next to the absence assertions.",
+        }];
+}
 export function lintUiSpec(raw, language, opts) {
     if (language === "java")
         return [];
@@ -240,5 +270,7 @@ export function lintUiSpec(raw, language, opts) {
         findings.push(...lintUnassertedTrailingAction(stripped));
     }
     findings.push(...lintTautologies(commentless, opts));
+    if (!maintenance)
+        findings.push(...lintNegativeOnlySpec(commentless));
     return findings;
 }

package/build/utils/frontendSelectors.d.ts

@@ -32,3 +32,36 @@ export declare const MAX_CHANGED_SELECTORS = 80;
  *      `ads-button--primary`).
  */
 export declare function extractChangedSelectors(fileDiff: string): string[];
+/** A removed element's identity: the `data-*` attribute and its literal value. */
+export interface RemovedAttribute {
+    /** Lower-cased attribute name, e.g. `data-testid`, `data-cy`, `data-section`. */
+    attribute: string;
+    value: string;
+}
+/** Identifying attribute VALUES that appear on `+` lines of a diff (any number of files). */
+export declare function extractAddedAttributeValues(diff: string): string[];
+/**
+ * Identifying `data-*` attributes one file's diff REMOVED: literals on `-` lines, minus the
+ * cases where the element still renders somewhere:
+ *
+ *   - **moved / extracted** — the same value appears on a `+` line of this file or, via
+ *     `addedValuesElsewhere`, anywhere else in the diff (a component extracted into a new
+ *     file is the common shape);
+ *   - **not an element** — a `-` line counts only when it opens a JSX/HTML tag or is a
+ *     wrapped attribute line of a tag opened above it (the tag is carried until the `>`
+ *     that closes it). A deleted comment, docs snippet, story arg or page-object
+ *     `getByTestId(...)` call that merely mentions the attribute is not an element
+ *     removal — the element itself may well survive on an unchanged context line;
+ *   - **renamed** — a rename cannot be told apart by literal identity (old and new
+ *     value differ by definition), so it is paired structurally: within the same hunk,
+ *     each `-` line is paired with AT MOST ONE `+` line carrying a NEW identifying
+ *     attribute — first by identical shape with the values blanked, else by the same
+ *     opening tag — and a paired `+` line is consumed. So one added element suppresses
+ *     one removal, not every removal in the hunk. This still errs toward suppressing a
+ *     guard when one same-tag element is swapped for an unrelated new one.
+ *
+ * Feeds `uiContext.removedElements` (SKYR-4305) — the grounding for a removal guard
+ * (`toBeHidden()` on `getByTestId(value)` for `data-testid`, on
+ * `locator('[<attribute>="<value>"]')` for any other `data-*`).
+ */
+export declare function extractRemovedAttributes(fileDiff: string, addedValuesElsewhere?: Iterable<string>): RemovedAttribute[];

package/build/utils/frontendSelectors.js

@@ -52,6 +52,28 @@ function isDistinctiveSelector(token, trusted) {
     }
     return hasBEM || (hyphens >= 2 && !COMMON_CSS_SELECTOR_TOKENS.test(token));
 }
+/**
+ * The test-facing selector grammar, shared by every extractor in this module so the
+ * two cannot drift: `data-testid` / `data-test` / `data-test-id` / `data-cy` / `data-qa`
+ * attribute values (string literals only) and `getByTestId(...)` arguments.
+ * Case-insensitive on purpose: JSX authors write `data-testId` (demoshop) and the
+ * browser lowercases attribute names, so `getByTestId` matches either spelling.
+ */
+const TESTID_ATTR_RE = /\b(data-(?:test-?id|test|cy|qa))\b\s*=\s*\{?\s*[`'"]([A-Za-z][\w:-]{2,})[`'"]/gi;
+const GET_BY_TEST_ID_RE = /getByTestId\(\s*[`'"]([A-Za-z][\w:-]{2,})[`'"]/gi;
+/**
+ * Any other `data-*` attribute with a static string value (`data-section="session-id-debug"`).
+ * Untrusted: the value must pass the stricter distinctiveness rule, and attributes that carry
+ * component STATE rather than identity are excluded — they flip at runtime, so "absent" is
+ * meaningless for them.
+ */
+const GENERIC_DATA_ATTR_RE = /\b(data-[a-z][a-z0-9]*(?:-[a-z0-9]+)*)\s*=\s*\{?\s*[`'"]([A-Za-z][\w:-]{2,})[`'"]/gi;
+const STATE_DATA_ATTRS = new Set([
+    "data-state", "data-theme", "data-orientation", "data-side", "data-align", "data-value",
+    "data-index", "data-slot", "data-disabled", "data-checked", "data-active", "data-open",
+    "data-loading", "data-size", "data-variant", "data-selected", "data-highlighted",
+    "data-focus", "data-hover", "data-pressed", "data-expanded", "data-placeholder", "data-status",
+]);
 /**
  * Extract selector literals added or removed in a single file's diff slice.
  *
@@ -74,8 +96,8 @@ export function extractChangedSelectors(fileDiff) {
     // `data-testid="x"`, `data-testid={'x'}`, `data-testid={`x`}`. The closing delimiter
     // deliberately rejects interpolated template literals (`data-testid={`members-${id}`}`),
     // which would otherwise leak a partial prefix (`members-`) into the selector set.
-    const ATTR = /\bdata-(?:test-?id|test|cy|qa)\b\s*=\s*\{?\s*[`'"]([A-Za-z][\w:-]{2,})[`'"]/g;
-    const GET_BY_TEST_ID = /getByTestId\(\s*[`'"]([A-Za-z][\w:-]{2,})[`'"]/g;
+    const ATTR = TESTID_ATTR_RE;
+    const GET_BY_TEST_ID = GET_BY_TEST_ID_RE;
     const KEBAB = /[a-z][a-z0-9]*(?:-{1,2}[a-z0-9]+)+/g;
     // BEM base whose modifier is composed DYNAMICALLY, so no concrete class literal exists
     // in the diff to grep: `ads-button--${kind}`, "ads-button--" + kind, clsx(base && `x--${y}`).
@@ -92,12 +114,12 @@ export function extractChangedSelectors(fileDiff) {
         if (raw.startsWith("+++") || raw.startsWith("---"))
             continue;
         const line = raw.slice(1);
-        for (const re of [ATTR, GET_BY_TEST_ID]) {
+        for (const [re, valueGroup] of [[ATTR, 2], [GET_BY_TEST_ID, 1]]) {
             re.lastIndex = 0;
             let m;
             while ((m = re.exec(line)) !== null) {
-                if (isDistinctiveSelector(m[1], true))
-                    out.add(m[1]);
+                if (isDistinctiveSelector(m[valueGroup], true))
+                    out.add(m[valueGroup]);
                 if (out.size >= MAX_CHANGED_SELECTORS)
                     return [...out];
             }
@@ -121,3 +143,172 @@ export function extractChangedSelectors(fileDiff) {
     }
     return [...out];
 }
+/**
+ * Identifying `data-*` attributes on one source line: the trusted test-facing set (any
+ * casing), `getByTestId(...)` arguments (attributed to `data-testid`), and any other
+ * static `data-*` whose value is distinctive and whose attribute is not a state carrier.
+ */
+function attributesOnLine(line) {
+    const out = [];
+    const seen = new Set();
+    const push = (attribute, value) => {
+        const key = `${attribute}=${value}`;
+        if (!seen.has(key)) {
+            seen.add(key);
+            out.push({ attribute, value });
+        }
+    };
+    let m;
+    TESTID_ATTR_RE.lastIndex = 0;
+    while ((m = TESTID_ATTR_RE.exec(line)) !== null) {
+        if (isDistinctiveSelector(m[2], true))
+            push(m[1].toLowerCase(), m[2]);
+    }
+    GET_BY_TEST_ID_RE.lastIndex = 0;
+    while ((m = GET_BY_TEST_ID_RE.exec(line)) !== null) {
+        if (isDistinctiveSelector(m[1], true))
+            push("data-testid", m[1]);
+    }
+    GENERIC_DATA_ATTR_RE.lastIndex = 0;
+    while ((m = GENERIC_DATA_ATTR_RE.exec(line)) !== null) {
+        const attribute = m[1].toLowerCase();
+        if (STATE_DATA_ATTRS.has(attribute))
+            continue;
+        if (seen.has(`${attribute}=${m[2]}`))
+            continue; // already captured by the trusted pass
+        if (isDistinctiveSelector(m[2], false))
+            push(attribute, m[2]);
+    }
+    return out;
+}
+/**
+ * Tag name of the JSX/HTML element a diff line opens, or "" — also "" for a comment
+ * line (`//`, `/*`, `*`, `{/*`, `<!--`), whose `<div …>` is text, not an element.
+ */
+function openingTagOf(line) {
+    const t = line.trim();
+    if (/^(?:\/\/|\/\*|\*|\{\s*\/\*|<!--)/.test(t))
+        return "";
+    return /<\s*([A-Za-z][\w.-]*)/.exec(t)?.[1]?.toLowerCase() ?? "";
+}
+/** Identifying attribute VALUES that appear on `+` lines of a diff (any number of files). */
+export function extractAddedAttributeValues(diff) {
+    const out = new Set();
+    for (const raw of diff.split("\n")) {
+        if (!raw.startsWith("+") || raw.startsWith("+++"))
+            continue;
+        for (const a of attributesOnLine(raw.slice(1)))
+            out.add(a.value);
+    }
+    return [...out];
+}
+/**
+ * Identifying `data-*` attributes one file's diff REMOVED: literals on `-` lines, minus the
+ * cases where the element still renders somewhere:
+ *
+ *   - **moved / extracted** — the same value appears on a `+` line of this file or, via
+ *     `addedValuesElsewhere`, anywhere else in the diff (a component extracted into a new
+ *     file is the common shape);
+ *   - **not an element** — a `-` line counts only when it opens a JSX/HTML tag or is a
+ *     wrapped attribute line of a tag opened above it (the tag is carried until the `>`
+ *     that closes it). A deleted comment, docs snippet, story arg or page-object
+ *     `getByTestId(...)` call that merely mentions the attribute is not an element
+ *     removal — the element itself may well survive on an unchanged context line;
+ *   - **renamed** — a rename cannot be told apart by literal identity (old and new
+ *     value differ by definition), so it is paired structurally: within the same hunk,
+ *     each `-` line is paired with AT MOST ONE `+` line carrying a NEW identifying
+ *     attribute — first by identical shape with the values blanked, else by the same
+ *     opening tag — and a paired `+` line is consumed. So one added element suppresses
+ *     one removal, not every removal in the hunk. This still errs toward suppressing a
+ *     guard when one same-tag element is swapped for an unrelated new one.
+ *
+ * Feeds `uiContext.removedElements` (SKYR-4305) — the grounding for a removal guard
+ * (`toBeHidden()` on `getByTestId(value)` for `data-testid`, on
+ * `locator('[<attribute>="<value>"]')` for any other `data-*`).
+ */
+export function extractRemovedAttributes(fileDiff, addedValuesElsewhere = []) {
+    const addedAnywhere = new Set(addedValuesElsewhere);
+    for (const v of extractAddedAttributeValues(fileDiff))
+        addedAnywhere.add(v);
+    // Split into hunks so rename pairing stays local.
+    const hunks = [];
+    for (const raw of fileDiff.split("\n")) {
+        if (raw.startsWith("@@")) {
+            hunks.push([]);
+            continue;
+        }
+        if (hunks.length === 0)
+            hunks.push([]);
+        hunks[hunks.length - 1].push(raw);
+    }
+    const shapeOf = (line, attrs) => {
+        let shape = line.trim();
+        for (const a of attrs)
+            shape = shape.split(a.value).join("\u0000");
+        return shape;
+    };
+    const out = [];
+    const seen = new Set();
+    for (const hunk of hunks) {
+        const removedLines = [];
+        const addedNew = [];
+        // A JSX attribute wrapped onto its own line (`+  data-testid="x"`) belongs to the
+        // element opened on an earlier line of the same side; carry that tag forward
+        // until the `>` that closes the opening tag, so a later comment or unrelated
+        // line in the hunk does not inherit it.
+        let lastMinusTag = "";
+        let lastPlusTag = "";
+        for (const raw of hunk) {
+            if (raw.startsWith("+++") || raw.startsWith("---"))
+                continue;
+            if (!(raw.startsWith("+") || raw.startsWith("-")))
+                continue;
+            const line = raw.slice(1);
+            const ownTag = openingTagOf(line);
+            const minus = raw.startsWith("-");
+            if (ownTag) {
+                if (minus)
+                    lastMinusTag = ownTag;
+                else
+                    lastPlusTag = ownTag;
+            }
+            const tag = ownTag || (minus ? lastMinusTag : lastPlusTag);
+            if (line.includes(">")) {
+                if (minus)
+                    lastMinusTag = "";
+                else
+                    lastPlusTag = "";
+            }
+            const attrs = attributesOnLine(line);
+            if (attrs.length === 0)
+                continue;
+            // Only an element (a tag opened on this line or carried from above) can be a
+            // removed element; a bare mention in a comment / docs / page object is not.
+            if (minus && tag === "")
+                continue;
+            if (minus)
+                removedLines.push({ attrs, tag, shape: shapeOf(line, attrs) });
+            else
+                addedNew.push({ tag, shape: shapeOf(line, attrs), consumed: false });
+        }
+        // Pair each removed line with at most ONE new-side line: identical blanked shape
+        // first, else the same opening tag. A paired + line is consumed, so one added
+        // element suppresses one removal (a moved value is handled by addedAnywhere).
+        for (const r of removedLines) {
+            const partner = addedNew.find((a) => !a.consumed && a.shape === r.shape)
+                ?? addedNew.find((a) => !a.consumed && a.tag === r.tag);
+            if (partner) {
+                partner.consumed = true;
+                continue;
+            }
+            for (const a of r.attrs) {
+                const key = `${a.attribute}=${a.value}`;
+                if (!addedAnywhere.has(a.value) && !seen.has(key)) {
+                    seen.add(key);
+                    out.push(a);
+                }
+            }
+        }
+    }
+    return out;
+}

package/build/utils/rebaselineSnapshots.d.ts

@@ -0,0 +1,24 @@
+import { z } from "zod";
+/**
+ * Visual-snapshot baseline names as a Skyramp test passes them to
+ * `toHaveScreenshot()` — e.g. `page-001.png` — and as `skyramp_actions` and
+ * `skyramp_execute_test` accept them in `rebaselineSnapshots` (SKYR-4298).
+ *
+ * Bare filename only: no path separators, and no commas or whitespace, because the
+ * list is joined with commas into `SKYRAMP_UPDATE_SNAPSHOTS` and split again in the
+ * executor, where `a,b.png` would read as two baselines. One definition shared by
+ * both tools so they can never drift apart.
+ */
+export declare const REBASELINE_SNAPSHOT_NAME_RE: RegExp;
+export declare const rebaselineSnapshotNameSchema: z.ZodString;
+/** `page-001.png` → `page-001`. */
+export declare function baselineStem(name: string): string;
+export declare function baselineFileMatchesStem(fileBasename: string, stem: string): boolean;
+/** The directory Playwright keeps a spec's baselines in under the default layout. */
+export declare function snapshotDirFor(specFile: string): string;
+/** Looks like an on-disk baseline filename (`page-001-chromium-linux.png`) rather than the
+ *  name the test passes (`page-001.png`) — the likeliest wrong input, and one the name
+ *  schema accepts. Advisory only: `hero-linux.png` is also a perfectly valid name a test
+ *  can pass, so callers warn and keep the entry; execution authorizes it against the
+ *  verdict and reports whether anything was actually rewritten. */
+export declare function looksLikeOnDiskBaselineName(name: string): boolean;

package/build/utils/rebaselineSnapshots.js

@@ -0,0 +1,65 @@
+import path from "path";
+import { z } from "zod";
+/**
+ * Visual-snapshot baseline names as a Skyramp test passes them to
+ * `toHaveScreenshot()` — e.g. `page-001.png` — and as `skyramp_actions` and
+ * `skyramp_execute_test` accept them in `rebaselineSnapshots` (SKYR-4298).
+ *
+ * Bare filename only: no path separators, and no commas or whitespace, because the
+ * list is joined with commas into `SKYRAMP_UPDATE_SNAPSHOTS` and split again in the
+ * executor, where `a,b.png` would read as two baselines. One definition shared by
+ * both tools so they can never drift apart.
+ */
+export const REBASELINE_SNAPSHOT_NAME_RE = /^[^/\\,\s]+\.png$/i;
+export const rebaselineSnapshotNameSchema = z
+    .string()
+    .trim()
+    .regex(REBASELINE_SNAPSHOT_NAME_RE, {
+    message: 'rebaselineSnapshots entries must be bare .png filenames as passed to toHaveScreenshot(), e.g. "page-001.png" — no path, commas, or whitespace',
+});
+/** `page-001.png` → `page-001`. */
+export function baselineStem(name) {
+    return path.basename(name).replace(/\.png$/i, "");
+}
+/**
+ * Playwright's default snapshot layout, which is what the executor produces: the
+ * baseline for `<stem>.png` lives in `<spec>-snapshots/` as `<stem>-<project>-<platform>.png`
+ * (or `<stem>-<platform>.png` with no project, or `<stem>.png` under a custom
+ * `snapshotPathTemplate`). Safe to assume here because TestExecutionService mounts
+ * its own generated Playwright config over any the repo carries, so a repo cannot
+ * relocate its snapshots out from under this rule.
+ *
+ * The executor's generated config declares no `projects`, but runner.sh passes
+ * `--browser=chromium`, so Playwright names the implicit project "chromium" and a
+ * refresh writes `<stem>-chromium-linux.png` (observed end to end on demoshop).
+ * Baselines the Skyramp executor produced therefore round-trip exactly. A baseline
+ * a repo's own CI wrote under another project name (`<stem>-Desktop-Chrome-linux.png`)
+ * is a different file: the executor's refresh adds its own and leaves that one as
+ * it was — the tool reports what it rewrote, and the repo's own suite is out of
+ * scope for skyramp_execute_test (which never runs it).
+ *
+ * Anchored so a longer baseline cannot vouch for a shorter one: `page-001-wide-chromium-linux.png`
+ * belongs to `page-001-wide.png` and must not satisfy a claim on `page-001.png`.
+ */
+const SNAPSHOT_PLATFORMS = "(?:darwin|linux|win32)";
+export function baselineFileMatchesStem(fileBasename, stem) {
+    // A degenerate stem ("" or dots only, from a name like "..png") would match a wide
+    // set of files; nothing legitimate has one.
+    if (!stem || /^\.+$/.test(stem))
+        return false;
+    const escaped = stem.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const re = new RegExp(`^${escaped}(?:-[^-]+-${SNAPSHOT_PLATFORMS}|-${SNAPSHOT_PLATFORMS})?\\.png$`, "i");
+    return re.test(fileBasename);
+}
+/** The directory Playwright keeps a spec's baselines in under the default layout. */
+export function snapshotDirFor(specFile) {
+    return `${specFile}-snapshots`;
+}
+/** Looks like an on-disk baseline filename (`page-001-chromium-linux.png`) rather than the
+ *  name the test passes (`page-001.png`) — the likeliest wrong input, and one the name
+ *  schema accepts. Advisory only: `hero-linux.png` is also a perfectly valid name a test
+ *  can pass, so callers warn and keep the entry; execution authorizes it against the
+ *  verdict and reports whether anything was actually rewritten. */
+export function looksLikeOnDiskBaselineName(name) {
+    return /-(?:[^-]+-)?(?:darwin|linux|win32)\.png$/i.test(name);
+}

package/build/utils/removedUiElements.d.ts

@@ -0,0 +1,34 @@
+import type { CandidateUiPage } from "./uiPageEnumerator.js";
+import type { FrontendFileIntegration } from "../types/FrontendIntegration.js";
+export interface RemovedUiElement {
+    /** Lower-cased identifying attribute: `data-testid`, `data-cy`, `data-qa`, `data-section`, … */
+    attribute: string;
+    /** Its literal value. `attribute` + `value` is unique across the result. */
+    value: string;
+    /** Repo-relative frontend file the diff removed it from. */
+    file: string;
+    /** Candidate UI pages attributed to that file (directly, or via its importers). */
+    pageUrls: string[];
+}
+/**
+ * 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 declare const MAX_REMOVED_UI_ELEMENTS = 5;
+export interface CollectRemovedUiElementsInput {
+    changedFrontendFiles: string[];
+    /** Files with `+++ /dev/null` in the diff — their page is gone, no guard. */
+    deletedFiles: string[];
+    /** Per-file diff slices for the WHOLE diff keyed by repo-relative path (see sliceDiffByFile). */
+    diffByFile: Map<string, string>;
+    frontendFileIntegration?: FrontendFileIntegration[];
+    candidateUiPages: CandidateUiPage[];
+    /** Absolute paths of discovered existing tests (skyramp + relevant external). */
+    existingTestFiles: string[];
+    /** True when test discovery threw — the existing-test check cannot run, so report nothing. */
+    discoveryFailed?: boolean;
+    /** Injectable for tests; defaults to a tolerant fs read that logs failures. */
+    readFile?: (absPath: string) => string | undefined;
+}
+export declare function collectRemovedUiElements(input: CollectRemovedUiElementsInput): RemovedUiElement[];