donobu 5.61.0 → 5.61.2

package/dist/browser-side-scripts/smart-selector-generator.js

@@ -147,6 +147,23 @@ function installSmartSelectorGenerator() {
             // 3. ≥2 long hex-ish segments joined with - or _
             str.split(/[-_]/).filter((s) => /^[a-f0-9]{6,}$/i.test(s)).length >= 2);
     };
+    /**
+     * Detects ids that are *ephemeral* — regenerated on every render — and so must
+     * never anchor a persisted selector: pinning one guarantees it goes stale at
+     * replay (the next render mints a fresh value).
+     *
+     * The canonical case is React's `useId()`, whose values are wrapped in colons
+     * (e.g. `:r18:`, `:R2iclofb:`, `:r1H2:`). React deliberately uses colons because
+     * they are invalid in a CSS id selector without escaping, signalling these ids
+     * are not meant to be used as selectors. The leading+trailing colon is the
+     * distinctive marker, and it avoids matching server-framework ids that merely
+     * use a colon as an internal separator (e.g. JSF's `form:button`). Extend this
+     * predicate as other ephemeral-id conventions surface.
+     *
+     * @param {string|null|undefined} id - The element id to test
+     * @returns {boolean} True if the id looks ephemeral (per-render)
+     */
+    const isEphemeralId = (id) => typeof id === 'string' && /^:.+:$/.test(id);
     // Semantic HTML5 elements that are likely to be unique and stable.
     const LANDMARK_TAGS = [
         'html',
@@ -400,6 +417,12 @@ function installSmartSelectorGenerator() {
             if (!id) {
                 return;
             }
+            // Ephemeral ids (e.g. React useId() values) regenerate every render, so a
+            // selector pinned to one is guaranteed stale at replay. Never anchor on
+            // them — let the stable anchors (text, aria, placeholder, …) take over.
+            if (isEphemeralId(id)) {
+                return;
+            }
             const dynamic = isHashLike(id) || id.length > 24;
             this.push(`#${escapeCss(id)}`, dynamic ? 20 : 100);
         }
@@ -649,7 +672,10 @@ function installSmartSelectorGenerator() {
             const scope = scopeNode instanceof ShadowRoot || scopeNode instanceof Document
                 ? scopeNode
                 : document;
-            if (el.id && !isHashLike(el.id) && el.id.length <= 24) {
+            if (el.id &&
+                !isHashLike(el.id) &&
+                !isEphemeralId(el.id) &&
+                el.id.length <= 24) {
                 if (countMatchesCSS(`#${escapeCss(el.id)}`, scope) === 1) {
                     return `#${escapeCss(el.id)}`;
                 }

package/dist/cli/donobu-cli.d.ts

@@ -18,12 +18,20 @@ declare function ensureReporterValueHasJson(value: string): {
  * caller to fall back to the rerun's own exit code rather than assume success.
  */
 declare function countUnexpectedTests(report: DonobuReport): number | undefined;
+/**
+ * Reconcile a run's process status with its recorded report. The child process
+ * is normally authoritative, but wrappers can surface exit 0 even when the
+ * report records unexpected failures. Escalate only zero exits so infra and
+ * crash codes keep their original signal.
+ */
+declare function reconcileExitCodeWithReport(exitCode: number, report: DonobuReport | null): number;
 /** @internal Exposed for unit tests only — not part of the public API. */
 export declare const _forTesting: {
     countUnexpectedTests: typeof countUnexpectedTests;
     ensureReporterValueHasJson: typeof ensureReporterValueHasJson;
     hasReporterArg: typeof hasReporterArg;
     injectJsonReporterIntoArgs: typeof injectJsonReporterIntoArgs;
+    reconcileExitCodeWithReport: typeof reconcileExitCodeWithReport;
 };
 export {};
 //# sourceMappingURL=donobu-cli.d.ts.map

package/dist/cli/donobu-cli.js

@@ -1512,6 +1512,23 @@ function countUnexpectedTests(report) {
     const unexpected = stats?.unexpected;
     return typeof unexpected === 'number' ? unexpected : undefined;
 }
+/**
+ * Reconcile a run's process status with its recorded report. The child process
+ * is normally authoritative, but wrappers can surface exit 0 even when the
+ * report records unexpected failures. Escalate only zero exits so infra and
+ * crash codes keep their original signal.
+ */
+function reconcileExitCodeWithReport(exitCode, report) {
+    if (exitCode !== 0 || !report) {
+        return exitCode;
+    }
+    const unexpected = countUnexpectedTests(report);
+    if (unexpected !== undefined && unexpected > 0) {
+        Logger_1.appLogger.warn(`Run exited 0 but the report records ${unexpected} failed test(s); exiting non-zero.`);
+        return 1;
+    }
+    return exitCode;
+}
 /**
  * Find a test entry in a report by title + project name. File paths are
  * deliberately not part of the lookup: treatment plans carry absolute paths
@@ -2038,6 +2055,7 @@ async function runTestCommand(cliArgs) {
                     // guarantee the reporter was deferring for.
                     await postDeferredSlackFromInitialRun(playwrightOutputDir);
                 }
+                return reconcileExitCodeWithReport(autoHealOutcome.exitCode, enrichedInitialReport ?? initialDonobuReport);
             }
             return autoHealOutcome.exitCode;
         }
@@ -2268,5 +2286,6 @@ exports._forTesting = {
     ensureReporterValueHasJson,
     hasReporterArg,
     injectJsonReporterIntoArgs,
+    reconcileExitCodeWithReport,
 };
 //# sourceMappingURL=donobu-cli.js.map

package/dist/esm/browser-side-scripts/smart-selector-generator.js

@@ -147,6 +147,23 @@ function installSmartSelectorGenerator() {
             // 3. ≥2 long hex-ish segments joined with - or _
             str.split(/[-_]/).filter((s) => /^[a-f0-9]{6,}$/i.test(s)).length >= 2);
     };
+    /**
+     * Detects ids that are *ephemeral* — regenerated on every render — and so must
+     * never anchor a persisted selector: pinning one guarantees it goes stale at
+     * replay (the next render mints a fresh value).
+     *
+     * The canonical case is React's `useId()`, whose values are wrapped in colons
+     * (e.g. `:r18:`, `:R2iclofb:`, `:r1H2:`). React deliberately uses colons because
+     * they are invalid in a CSS id selector without escaping, signalling these ids
+     * are not meant to be used as selectors. The leading+trailing colon is the
+     * distinctive marker, and it avoids matching server-framework ids that merely
+     * use a colon as an internal separator (e.g. JSF's `form:button`). Extend this
+     * predicate as other ephemeral-id conventions surface.
+     *
+     * @param {string|null|undefined} id - The element id to test
+     * @returns {boolean} True if the id looks ephemeral (per-render)
+     */
+    const isEphemeralId = (id) => typeof id === 'string' && /^:.+:$/.test(id);
     // Semantic HTML5 elements that are likely to be unique and stable.
     const LANDMARK_TAGS = [
         'html',
@@ -400,6 +417,12 @@ function installSmartSelectorGenerator() {
             if (!id) {
                 return;
             }
+            // Ephemeral ids (e.g. React useId() values) regenerate every render, so a
+            // selector pinned to one is guaranteed stale at replay. Never anchor on
+            // them — let the stable anchors (text, aria, placeholder, …) take over.
+            if (isEphemeralId(id)) {
+                return;
+            }
             const dynamic = isHashLike(id) || id.length > 24;
             this.push(`#${escapeCss(id)}`, dynamic ? 20 : 100);
         }
@@ -649,7 +672,10 @@ function installSmartSelectorGenerator() {
             const scope = scopeNode instanceof ShadowRoot || scopeNode instanceof Document
                 ? scopeNode
                 : document;
-            if (el.id && !isHashLike(el.id) && el.id.length <= 24) {
+            if (el.id &&
+                !isHashLike(el.id) &&
+                !isEphemeralId(el.id) &&
+                el.id.length <= 24) {
                 if (countMatchesCSS(`#${escapeCss(el.id)}`, scope) === 1) {
                     return `#${escapeCss(el.id)}`;
                 }

package/dist/esm/cli/donobu-cli.d.ts

@@ -18,12 +18,20 @@ declare function ensureReporterValueHasJson(value: string): {
  * caller to fall back to the rerun's own exit code rather than assume success.
  */
 declare function countUnexpectedTests(report: DonobuReport): number | undefined;
+/**
+ * Reconcile a run's process status with its recorded report. The child process
+ * is normally authoritative, but wrappers can surface exit 0 even when the
+ * report records unexpected failures. Escalate only zero exits so infra and
+ * crash codes keep their original signal.
+ */
+declare function reconcileExitCodeWithReport(exitCode: number, report: DonobuReport | null): number;
 /** @internal Exposed for unit tests only — not part of the public API. */
 export declare const _forTesting: {
     countUnexpectedTests: typeof countUnexpectedTests;
     ensureReporterValueHasJson: typeof ensureReporterValueHasJson;
     hasReporterArg: typeof hasReporterArg;
     injectJsonReporterIntoArgs: typeof injectJsonReporterIntoArgs;
+    reconcileExitCodeWithReport: typeof reconcileExitCodeWithReport;
 };
 export {};
 //# sourceMappingURL=donobu-cli.d.ts.map

package/dist/esm/cli/donobu-cli.js

@@ -1512,6 +1512,23 @@ function countUnexpectedTests(report) {
     const unexpected = stats?.unexpected;
     return typeof unexpected === 'number' ? unexpected : undefined;
 }
+/**
+ * Reconcile a run's process status with its recorded report. The child process
+ * is normally authoritative, but wrappers can surface exit 0 even when the
+ * report records unexpected failures. Escalate only zero exits so infra and
+ * crash codes keep their original signal.
+ */
+function reconcileExitCodeWithReport(exitCode, report) {
+    if (exitCode !== 0 || !report) {
+        return exitCode;
+    }
+    const unexpected = countUnexpectedTests(report);
+    if (unexpected !== undefined && unexpected > 0) {
+        Logger_1.appLogger.warn(`Run exited 0 but the report records ${unexpected} failed test(s); exiting non-zero.`);
+        return 1;
+    }
+    return exitCode;
+}
 /**
  * Find a test entry in a report by title + project name. File paths are
  * deliberately not part of the lookup: treatment plans carry absolute paths
@@ -2038,6 +2055,7 @@ async function runTestCommand(cliArgs) {
                     // guarantee the reporter was deferring for.
                     await postDeferredSlackFromInitialRun(playwrightOutputDir);
                 }
+                return reconcileExitCodeWithReport(autoHealOutcome.exitCode, enrichedInitialReport ?? initialDonobuReport);
             }
             return autoHealOutcome.exitCode;
         }
@@ -2268,5 +2286,6 @@ exports._forTesting = {
     ensureReporterValueHasJson,
     hasReporterArg,
     injectJsonReporterIntoArgs,
+    reconcileExitCodeWithReport,
 };
 //# sourceMappingURL=donobu-cli.js.map

package/dist/esm/tools/ReplayableInteraction.js

@@ -608,6 +608,14 @@ class ReplayableInteraction extends Tool_1.Tool {
             ? ElementSelector_1.ElementSelectorSchema.parse(toolCall.parameters.selector)
             : ElementSelector_1.ElementSelectorSchema.parse(toolCall.outcome.metadata);
         let selectorCandidates = [...originalSelector.element];
+        // 0) Drop ephemeral-id selectors (e.g. React useId() values like
+        //    `#\:r18\:`) outright. They regenerate every render, so replaying or
+        //    (below) promoting one only re-pins a value that is already stale. Older
+        //    recordings may still carry them; keep the list non-empty as a backstop.
+        const nonEphemeral = selectorCandidates.filter((sel) => !(0, AdvancedSelectorGenerator_1.isEphemeralIdSelector)(sel));
+        if (nonEphemeral.length > 0) {
+            selectorCandidates = nonEphemeral;
+        }
         // 1) Drop ID-based selectors if requested --------------------------------
         if (options.areElementIdsVolatile) {
             const nonId = selectorCandidates.filter((sel) => {
@@ -625,11 +633,18 @@ class ReplayableInteraction extends Tool_1.Tool {
             const firstSelectorIsAria = selectorCandidates.length > 0 &&
                 ReplayableInteraction.isAriaBasedSelector(selectorCandidates[0]);
             if (!firstSelectorIsAria) {
-                const idBasedSelectors = selectorCandidates.filter((sel) => ReplayableInteraction.isIdBasedSelector(sel));
-                const nonIdBasedSelectors = selectorCandidates.filter((sel) => !ReplayableInteraction.isIdBasedSelector(sel));
-                // Reorder: ID-based selectors first, then non-ID-based selectors
-                if (idBasedSelectors.length > 0) {
-                    selectorCandidates = [...idBasedSelectors, ...nonIdBasedSelectors];
+                // Promote only STABLE ids. A dynamic id (a per-render React useId()
+                // value, a hash/UUID, an over-long id) is one the generator already
+                // deprioritized; promoting it would re-pin a value that is guaranteed
+                // stale at replay — exactly over the robust env/text selector that
+                // actually works. Such ids stay where generation ranked them (failover).
+                const stableIdSelectors = selectorCandidates.filter((sel) => ReplayableInteraction.isIdBasedSelector(sel) &&
+                    !(0, AdvancedSelectorGenerator_1.isDynamicIdSelector)(sel));
+                const otherSelectors = selectorCandidates.filter((sel) => !ReplayableInteraction.isIdBasedSelector(sel) ||
+                    (0, AdvancedSelectorGenerator_1.isDynamicIdSelector)(sel));
+                // Reorder: stable ID-based selectors first, the rest in generated order.
+                if (stableIdSelectors.length > 0) {
+                    selectorCandidates = [...stableIdSelectors, ...otherSelectors];
                 }
             }
             // If first selector is aria-based, leave the order unchanged

package/dist/esm/utils/AdvancedSelectorGenerator.d.ts

@@ -92,6 +92,30 @@ export declare function advanceSelectorCandidates(rawCandidates: string[], envDa
 export declare function pruneCoincidentalPositional(candidates: string[]): string[];
 /** A selector that carries an env reference (so it tracks the value at replay). */
 export declare function isEnvBearingSelector(selector: string): boolean;
+/**
+ * A selector anchored on an *ephemeral* id — one regenerated on every render, so
+ * pinning it guarantees the selector goes stale at replay. The canonical case is
+ * a React `useId()` value: a colon-wrapped id (`#:r18:`, often CSS-escaped as
+ * `#\:r18\:`), possibly scoped (`#\:rd\: > li:nth-of-type(7)`). Mirrors the
+ * `isEphemeralId` guard in the browser-side generator; kept here as a Node-side
+ * funnel guard for candidates from any source. PURE.
+ */
+export declare function isEphemeralIdSelector(selector: string): boolean;
+/**
+ * Drop candidates anchored on an ephemeral id, but never empty the list: if every
+ * candidate is ephemeral, keep them (a stale selector still beats no selector).
+ * PURE.
+ */
+export declare function pruneEphemeralIdSelectors(candidates: string[]): string[];
+/**
+ * A selector anchored on a *dynamic* id — one the generator deliberately
+ * deprioritizes because it is machine-generated and unstable: an ephemeral
+ * (per-render) id like React's `useId()`, a hash/UUID-style id, or an over-long
+ * id. Such an id may legitimately survive as a low-priority failover, but must
+ * never be *promoted* to primary (doing so re-pins a value that is stale at
+ * replay). Mirrors the browser-side ranking heuristics. PURE.
+ */
+export declare function isDynamicIdSelector(selector: string): boolean;
 /**
  * Heuristic for a selector that locates an element *purely by DOM position* — an
  * `:nth-*` pseudo, an XPath numeric index `[N]`, or a bare combinator chain — with

package/dist/esm/utils/AdvancedSelectorGenerator.js

@@ -8,6 +8,9 @@ exports.buildSynthesisRequest = buildSynthesisRequest;
 exports.advanceSelectorCandidates = advanceSelectorCandidates;
 exports.pruneCoincidentalPositional = pruneCoincidentalPositional;
 exports.isEnvBearingSelector = isEnvBearingSelector;
+exports.isEphemeralIdSelector = isEphemeralIdSelector;
+exports.pruneEphemeralIdSelectors = pruneEphemeralIdSelectors;
+exports.isDynamicIdSelector = isDynamicIdSelector;
 exports.isPurelyPositionalSelector = isPurelyPositionalSelector;
 const v4_1 = require("zod/v4");
 const Logger_1 = require("./Logger");
@@ -66,7 +69,10 @@ exports.SynthesizedSelectorSchema = v4_1.z.object({
  * or the model's rewrite can't be validated.
  */
 async function generateAdvancedSelectors(target, context) {
-    const element = (await PlaywrightUtils_1.PlaywrightUtils.generateSelectors(target)).slice(0, MAX_REPLAY_SELECTOR_CANDIDATES);
+    // Prune ephemeral-id candidates (e.g. React useId() values) before capping, so
+    // the cap keeps stable failovers rather than spending slots on selectors that
+    // are guaranteed stale at replay.
+    const element = pruneEphemeralIdSelectors(await PlaywrightUtils_1.PlaywrightUtils.generateSelectors(target)).slice(0, MAX_REPLAY_SELECTOR_CANDIDATES);
     const frame = await deriveFrameSelector(target);
     const raw = { element, frame };
     if (element.length === 0) {
@@ -197,10 +203,14 @@ The target element is marked with the attribute \`${markerAttribute}\` in the HT
 below. Return a single CSS or XPath selector that UNIQUELY locates that element —
 but do NOT use \`${markerAttribute}\` (it is temporary and gone at replay).
 Instead, anchor on the env-derived text near it (e.g. a sibling/ancestor title or
-label), written as a {{$.env.NAME}} placeholder (use the \`| filter\` form when the
-on-page text is a transformed form of the value). Prefer an XPath that finds the
-container by its env-derived text and then descends to the target. If you cannot
-build a reliable, unique anchor, return null.
+label), written as a {{$.env.NAME}} placeholder. When the on-page text is a
+transformed form of the value, append EXACTLY ONE filter with the pipe form
+\`{{$.env.NAME | filter}}\`, using only these filter names (they take NO
+arguments): ${Object.keys(TemplateInterpolator_1.ENV_VALUE_FILTERS).join(', ')}. Do NOT invent other
+filter names (e.g. \`upcase\`, \`slice\`) or pass arguments — any other filter is
+rejected and the selector is discarded. Prefer an XPath that finds the container
+by its env-derived text and then descends to the target. If you cannot build a
+reliable, unique anchor, return null.
 
 Env vars in play:
 ${envMapping}`,
@@ -260,6 +270,85 @@ function pruneCoincidentalPositional(candidates) {
 function isEnvBearingSelector(selector) {
     return selector.includes('{{$.env.');
 }
+/**
+ * A selector anchored on an *ephemeral* id — one regenerated on every render, so
+ * pinning it guarantees the selector goes stale at replay. The canonical case is
+ * a React `useId()` value: a colon-wrapped id (`#:r18:`, often CSS-escaped as
+ * `#\:r18\:`), possibly scoped (`#\:rd\: > li:nth-of-type(7)`). Mirrors the
+ * `isEphemeralId` guard in the browser-side generator; kept here as a Node-side
+ * funnel guard for candidates from any source. PURE.
+ */
+function isEphemeralIdSelector(selector) {
+    // Drop CSS escaping (`#\:r18\:` -> `#:r18:`), then look for a `#`-id token
+    // whose value is colon-wrapped.
+    const unescaped = selector.replace(/\\/g, '');
+    return /#:[^\s>+~#.[\]:]+:/.test(unescaped);
+}
+/**
+ * Drop candidates anchored on an ephemeral id, but never empty the list: if every
+ * candidate is ephemeral, keep them (a stale selector still beats no selector).
+ * PURE.
+ */
+function pruneEphemeralIdSelectors(candidates) {
+    const stable = candidates.filter((candidate) => !isEphemeralIdSelector(candidate));
+    return stable.length > 0 ? stable : candidates;
+}
+/**
+ * Mirrors the browser-side `isHashLike` heuristic (smart-selector-generator):
+ * detects machine-generated id *values* (webpack hashes, UUIDs, multi-segment
+ * hex) that change between builds/renders. Kept in sync by hand — the browser
+ * script is a separate, injected runtime that cannot import this module. PURE.
+ */
+function isHashLikeIdValue(id) {
+    return (/^[a-f0-9]{6,}$/i.test(id) ||
+        /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(id) ||
+        id.split(/[-_]/).filter((segment) => /^[a-f0-9]{6,}$/i.test(segment))
+            .length >= 2);
+}
+/**
+ * Decode the CSS identifier escapes that {@link CSS.escape} emits, enough to
+ * recover the underlying id value: hex escapes (`\39 ` -> `9`) and literal
+ * backslash escapes (`\:` -> `:`). PURE.
+ */
+function cssUnescapeIdentifier(value) {
+    return value
+        .replace(/\\([0-9a-fA-F]{1,6})\s?/g, (match, hex) => {
+        const codePoint = parseInt(hex, 16);
+        return codePoint > 0 && codePoint <= 0x10ffff
+            ? String.fromCodePoint(codePoint)
+            : match;
+    })
+        .replace(/\\(.)/g, '$1');
+}
+/**
+ * The leading `#id` value of a CSS selector (unescaped), or null when the
+ * selector does not start with an id. Reads only the id token, stopping at the
+ * first structural boundary (combinator, attribute, class, or pseudo). PURE.
+ */
+function leadingCssIdValue(selector) {
+    const trimmed = selector.trim();
+    if (!trimmed.startsWith('#')) {
+        return null;
+    }
+    const unescaped = cssUnescapeIdentifier(trimmed.slice(1));
+    const match = /^[^\s>+~.[:]+/.exec(unescaped);
+    return match ? match[0] : null;
+}
+/**
+ * A selector anchored on a *dynamic* id — one the generator deliberately
+ * deprioritizes because it is machine-generated and unstable: an ephemeral
+ * (per-render) id like React's `useId()`, a hash/UUID-style id, or an over-long
+ * id. Such an id may legitimately survive as a low-priority failover, but must
+ * never be *promoted* to primary (doing so re-pins a value that is stale at
+ * replay). Mirrors the browser-side ranking heuristics. PURE.
+ */
+function isDynamicIdSelector(selector) {
+    if (isEphemeralIdSelector(selector)) {
+        return true;
+    }
+    const id = leadingCssIdValue(selector);
+    return id !== null && (isHashLikeIdValue(id) || id.length > 24);
+}
 /**
  * Heuristic for a selector that locates an element *purely by DOM position* — an
  * `:nth-*` pseudo, an XPath numeric index `[N]`, or a bare combinator chain — with

package/dist/tools/ReplayableInteraction.js

@@ -608,6 +608,14 @@ class ReplayableInteraction extends Tool_1.Tool {
             ? ElementSelector_1.ElementSelectorSchema.parse(toolCall.parameters.selector)
             : ElementSelector_1.ElementSelectorSchema.parse(toolCall.outcome.metadata);
         let selectorCandidates = [...originalSelector.element];
+        // 0) Drop ephemeral-id selectors (e.g. React useId() values like
+        //    `#\:r18\:`) outright. They regenerate every render, so replaying or
+        //    (below) promoting one only re-pins a value that is already stale. Older
+        //    recordings may still carry them; keep the list non-empty as a backstop.
+        const nonEphemeral = selectorCandidates.filter((sel) => !(0, AdvancedSelectorGenerator_1.isEphemeralIdSelector)(sel));
+        if (nonEphemeral.length > 0) {
+            selectorCandidates = nonEphemeral;
+        }
         // 1) Drop ID-based selectors if requested --------------------------------
         if (options.areElementIdsVolatile) {
             const nonId = selectorCandidates.filter((sel) => {
@@ -625,11 +633,18 @@ class ReplayableInteraction extends Tool_1.Tool {
             const firstSelectorIsAria = selectorCandidates.length > 0 &&
                 ReplayableInteraction.isAriaBasedSelector(selectorCandidates[0]);
             if (!firstSelectorIsAria) {
-                const idBasedSelectors = selectorCandidates.filter((sel) => ReplayableInteraction.isIdBasedSelector(sel));
-                const nonIdBasedSelectors = selectorCandidates.filter((sel) => !ReplayableInteraction.isIdBasedSelector(sel));
-                // Reorder: ID-based selectors first, then non-ID-based selectors
-                if (idBasedSelectors.length > 0) {
-                    selectorCandidates = [...idBasedSelectors, ...nonIdBasedSelectors];
+                // Promote only STABLE ids. A dynamic id (a per-render React useId()
+                // value, a hash/UUID, an over-long id) is one the generator already
+                // deprioritized; promoting it would re-pin a value that is guaranteed
+                // stale at replay — exactly over the robust env/text selector that
+                // actually works. Such ids stay where generation ranked them (failover).
+                const stableIdSelectors = selectorCandidates.filter((sel) => ReplayableInteraction.isIdBasedSelector(sel) &&
+                    !(0, AdvancedSelectorGenerator_1.isDynamicIdSelector)(sel));
+                const otherSelectors = selectorCandidates.filter((sel) => !ReplayableInteraction.isIdBasedSelector(sel) ||
+                    (0, AdvancedSelectorGenerator_1.isDynamicIdSelector)(sel));
+                // Reorder: stable ID-based selectors first, the rest in generated order.
+                if (stableIdSelectors.length > 0) {
+                    selectorCandidates = [...stableIdSelectors, ...otherSelectors];
                 }
             }
             // If first selector is aria-based, leave the order unchanged

package/dist/utils/AdvancedSelectorGenerator.d.ts

@@ -92,6 +92,30 @@ export declare function advanceSelectorCandidates(rawCandidates: string[], envDa
 export declare function pruneCoincidentalPositional(candidates: string[]): string[];
 /** A selector that carries an env reference (so it tracks the value at replay). */
 export declare function isEnvBearingSelector(selector: string): boolean;
+/**
+ * A selector anchored on an *ephemeral* id — one regenerated on every render, so
+ * pinning it guarantees the selector goes stale at replay. The canonical case is
+ * a React `useId()` value: a colon-wrapped id (`#:r18:`, often CSS-escaped as
+ * `#\:r18\:`), possibly scoped (`#\:rd\: > li:nth-of-type(7)`). Mirrors the
+ * `isEphemeralId` guard in the browser-side generator; kept here as a Node-side
+ * funnel guard for candidates from any source. PURE.
+ */
+export declare function isEphemeralIdSelector(selector: string): boolean;
+/**
+ * Drop candidates anchored on an ephemeral id, but never empty the list: if every
+ * candidate is ephemeral, keep them (a stale selector still beats no selector).
+ * PURE.
+ */
+export declare function pruneEphemeralIdSelectors(candidates: string[]): string[];
+/**
+ * A selector anchored on a *dynamic* id — one the generator deliberately
+ * deprioritizes because it is machine-generated and unstable: an ephemeral
+ * (per-render) id like React's `useId()`, a hash/UUID-style id, or an over-long
+ * id. Such an id may legitimately survive as a low-priority failover, but must
+ * never be *promoted* to primary (doing so re-pins a value that is stale at
+ * replay). Mirrors the browser-side ranking heuristics. PURE.
+ */
+export declare function isDynamicIdSelector(selector: string): boolean;
 /**
  * Heuristic for a selector that locates an element *purely by DOM position* — an
  * `:nth-*` pseudo, an XPath numeric index `[N]`, or a bare combinator chain — with

package/dist/utils/AdvancedSelectorGenerator.js

@@ -8,6 +8,9 @@ exports.buildSynthesisRequest = buildSynthesisRequest;
 exports.advanceSelectorCandidates = advanceSelectorCandidates;
 exports.pruneCoincidentalPositional = pruneCoincidentalPositional;
 exports.isEnvBearingSelector = isEnvBearingSelector;
+exports.isEphemeralIdSelector = isEphemeralIdSelector;
+exports.pruneEphemeralIdSelectors = pruneEphemeralIdSelectors;
+exports.isDynamicIdSelector = isDynamicIdSelector;
 exports.isPurelyPositionalSelector = isPurelyPositionalSelector;
 const v4_1 = require("zod/v4");
 const Logger_1 = require("./Logger");
@@ -66,7 +69,10 @@ exports.SynthesizedSelectorSchema = v4_1.z.object({
  * or the model's rewrite can't be validated.
  */
 async function generateAdvancedSelectors(target, context) {
-    const element = (await PlaywrightUtils_1.PlaywrightUtils.generateSelectors(target)).slice(0, MAX_REPLAY_SELECTOR_CANDIDATES);
+    // Prune ephemeral-id candidates (e.g. React useId() values) before capping, so
+    // the cap keeps stable failovers rather than spending slots on selectors that
+    // are guaranteed stale at replay.
+    const element = pruneEphemeralIdSelectors(await PlaywrightUtils_1.PlaywrightUtils.generateSelectors(target)).slice(0, MAX_REPLAY_SELECTOR_CANDIDATES);
     const frame = await deriveFrameSelector(target);
     const raw = { element, frame };
     if (element.length === 0) {
@@ -197,10 +203,14 @@ The target element is marked with the attribute \`${markerAttribute}\` in the HT
 below. Return a single CSS or XPath selector that UNIQUELY locates that element —
 but do NOT use \`${markerAttribute}\` (it is temporary and gone at replay).
 Instead, anchor on the env-derived text near it (e.g. a sibling/ancestor title or
-label), written as a {{$.env.NAME}} placeholder (use the \`| filter\` form when the
-on-page text is a transformed form of the value). Prefer an XPath that finds the
-container by its env-derived text and then descends to the target. If you cannot
-build a reliable, unique anchor, return null.
+label), written as a {{$.env.NAME}} placeholder. When the on-page text is a
+transformed form of the value, append EXACTLY ONE filter with the pipe form
+\`{{$.env.NAME | filter}}\`, using only these filter names (they take NO
+arguments): ${Object.keys(TemplateInterpolator_1.ENV_VALUE_FILTERS).join(', ')}. Do NOT invent other
+filter names (e.g. \`upcase\`, \`slice\`) or pass arguments — any other filter is
+rejected and the selector is discarded. Prefer an XPath that finds the container
+by its env-derived text and then descends to the target. If you cannot build a
+reliable, unique anchor, return null.
 
 Env vars in play:
 ${envMapping}`,
@@ -260,6 +270,85 @@ function pruneCoincidentalPositional(candidates) {
 function isEnvBearingSelector(selector) {
     return selector.includes('{{$.env.');
 }
+/**
+ * A selector anchored on an *ephemeral* id — one regenerated on every render, so
+ * pinning it guarantees the selector goes stale at replay. The canonical case is
+ * a React `useId()` value: a colon-wrapped id (`#:r18:`, often CSS-escaped as
+ * `#\:r18\:`), possibly scoped (`#\:rd\: > li:nth-of-type(7)`). Mirrors the
+ * `isEphemeralId` guard in the browser-side generator; kept here as a Node-side
+ * funnel guard for candidates from any source. PURE.
+ */
+function isEphemeralIdSelector(selector) {
+    // Drop CSS escaping (`#\:r18\:` -> `#:r18:`), then look for a `#`-id token
+    // whose value is colon-wrapped.
+    const unescaped = selector.replace(/\\/g, '');
+    return /#:[^\s>+~#.[\]:]+:/.test(unescaped);
+}
+/**
+ * Drop candidates anchored on an ephemeral id, but never empty the list: if every
+ * candidate is ephemeral, keep them (a stale selector still beats no selector).
+ * PURE.
+ */
+function pruneEphemeralIdSelectors(candidates) {
+    const stable = candidates.filter((candidate) => !isEphemeralIdSelector(candidate));
+    return stable.length > 0 ? stable : candidates;
+}
+/**
+ * Mirrors the browser-side `isHashLike` heuristic (smart-selector-generator):
+ * detects machine-generated id *values* (webpack hashes, UUIDs, multi-segment
+ * hex) that change between builds/renders. Kept in sync by hand — the browser
+ * script is a separate, injected runtime that cannot import this module. PURE.
+ */
+function isHashLikeIdValue(id) {
+    return (/^[a-f0-9]{6,}$/i.test(id) ||
+        /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(id) ||
+        id.split(/[-_]/).filter((segment) => /^[a-f0-9]{6,}$/i.test(segment))
+            .length >= 2);
+}
+/**
+ * Decode the CSS identifier escapes that {@link CSS.escape} emits, enough to
+ * recover the underlying id value: hex escapes (`\39 ` -> `9`) and literal
+ * backslash escapes (`\:` -> `:`). PURE.
+ */
+function cssUnescapeIdentifier(value) {
+    return value
+        .replace(/\\([0-9a-fA-F]{1,6})\s?/g, (match, hex) => {
+        const codePoint = parseInt(hex, 16);
+        return codePoint > 0 && codePoint <= 0x10ffff
+            ? String.fromCodePoint(codePoint)
+            : match;
+    })
+        .replace(/\\(.)/g, '$1');
+}
+/**
+ * The leading `#id` value of a CSS selector (unescaped), or null when the
+ * selector does not start with an id. Reads only the id token, stopping at the
+ * first structural boundary (combinator, attribute, class, or pseudo). PURE.
+ */
+function leadingCssIdValue(selector) {
+    const trimmed = selector.trim();
+    if (!trimmed.startsWith('#')) {
+        return null;
+    }
+    const unescaped = cssUnescapeIdentifier(trimmed.slice(1));
+    const match = /^[^\s>+~.[:]+/.exec(unescaped);
+    return match ? match[0] : null;
+}
+/**
+ * A selector anchored on a *dynamic* id — one the generator deliberately
+ * deprioritizes because it is machine-generated and unstable: an ephemeral
+ * (per-render) id like React's `useId()`, a hash/UUID-style id, or an over-long
+ * id. Such an id may legitimately survive as a low-priority failover, but must
+ * never be *promoted* to primary (doing so re-pins a value that is stale at
+ * replay). Mirrors the browser-side ranking heuristics. PURE.
+ */
+function isDynamicIdSelector(selector) {
+    if (isEphemeralIdSelector(selector)) {
+        return true;
+    }
+    const id = leadingCssIdValue(selector);
+    return id !== null && (isHashLikeIdValue(id) || id.length > 24);
+}
 /**
  * Heuristic for a selector that locates an element *purely by DOM position* — an
  * `:nth-*` pseudo, an XPath numeric index `[N]`, or a bare combinator chain — with

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "donobu",
-  "version": "5.61.0",
+  "version": "5.61.2",
   "description": "Create browser automations with an LLM agent and replay them as Playwright scripts.",
   "main": "dist/main.js",
   "module": "dist/esm/main.js",