@undo76/agent-dom 0.1.0 → 0.2.0

package/README.md

@@ -96,17 +96,32 @@ A locator throws if it finds zero or multiple elements. This keeps agent actions
 
 ## Ref lifetime
 
-Refs belong to one observation. A `MutationObserver` tracks changes to the document, including attribute and text changes. If the DOM changes, an action using an older ref throws `StaleElementReferenceError` and the agent must observe again.
+A ref identifies one element in the last observation. By default (`stale: "connected"`) it stays valid until that **own** element leaves the document, so unrelated page churn — streamed chat, spinners, clocks, framework re-renders — does not stop you acting.
 
 ```ts
-const first = page.observe();
-const button = first.findByRole("button").ref;
+const obs = page.observe({ interactiveOnly: true });
+const link = obs.findByRole("link", { name: "Home" }).ref;
+
+chat.append(document.createTextNode("thinking…")); // sibling subtree mutates
+page.click(link);                                   // works
+
+sidebar.querySelector("a")?.remove();
+page.click(link);                                 // StaleElementReferenceError
+```
+
+Opt into strict snapshot semantics with `stale: "generation"`, where any mutation under the root invalidates every older ref:
+
+```ts
+const strict = createAgentPage(window, { stale: "generation" });
+const ref = strict.observe().findByRole("button").ref;
 
 document.body.append(document.createElement("div"));
 
-page.click(button); // throws StaleElementReferenceError
+strict.click(ref); // throws StaleElementReferenceError
 ```
 
+The trade is freshness, not safety: under `"connected"` a ref can resolve to an element whose text changed since you observed it. Re-observe when the label is the contract (totals, quantities, confirm dialogs); `disabled` and removed elements are still caught.
+
 ## Browser boundaries
 
 The library traverses the current document and open shadow roots. Normal page JavaScript cannot inspect closed shadow roots or cross-origin iframe documents. A browser extension can inject one `AgentPage` into each permitted frame and merge the results in a coordinator.

package/dist/index.cjs

@@ -462,12 +462,14 @@ var AgentPage = class {
   root;
   #documentGeneration = 0;
   #snapshotGeneration = 0;
+  #stale;
   #refState;
   #observation;
   #observer;
   constructor(window, options = {}) {
     this.window = window;
     this.root = options.root ?? window.document;
+    this.#stale = options.stale ?? "connected";
     const document = ownerDocument(this.root);
     if (document.defaultView !== window) {
       throw new TypeError("The root must belong to the supplied window.");
@@ -568,7 +570,9 @@ var AgentPage = class {
   #freshObservation() {
     this.#syncMutations();
     if (!this.#observation || !this.#refState) return this.observe();
-    if (this.#refState.documentGeneration !== this.#documentGeneration) return this.observe();
+    if (this.#stale === "generation" && this.#refState.documentGeneration !== this.#documentGeneration) {
+      return this.observe();
+    }
     return this.#observation;
   }
   #resolve(ref) {
@@ -576,7 +580,7 @@ var AgentPage = class {
     const normalized = normalizeRef(ref);
     const state = this.#refState;
     if (!state) throw new ElementNotFoundError("Observe the page before using a ref.");
-    if (state.documentGeneration !== this.#documentGeneration) {
+    if (this.#stale === "generation" && state.documentGeneration !== this.#documentGeneration) {
       throw new StaleElementReferenceError(normalized, state.snapshotGeneration, this.#snapshotGeneration + 1);
     }
     const element = state.refs.get(normalized);

package/dist/index.d.cts

@@ -74,7 +74,19 @@ type AgentAction = {
 };
 interface CreateAgentPageOptions {
     root?: Document | Element | ShadowRoot;
+    /**
+     * When a ref stops being usable.
+     *
+     * - `"connected"` (default): a ref stays valid until *its own* element is removed.
+     *   Real pages never stop mutating — streaming chat, spinners, clocks, toasts,
+     *   virtualised lists, framework re-renders. A policy that reacted to all of it
+     *   would mean no action ever lands on a live page.
+     * - `"generation"`: any mutation anywhere under the root invalidates every ref from
+     *   the previous observation. Opt in for stepwise harnesses that must be current.
+     */
+    stale?: StalePolicy;
 }
+type StalePolicy = "generation" | "connected";
 
 declare class AgentPage {
     #private;
@@ -125,4 +137,4 @@ declare class ActionError extends AgentDomError {
     readonly name: string;
 }
 
-export { ActionError, type AgentAction, AgentDomError, AgentObservation, AgentPage, type BrowserWindow, type CreateAgentPageOptions, ElementNotFoundError, type ElementState, type Observation, type ObserveOptions, type ObservedElement, type RoleLocatorOptions, StaleElementReferenceError, type TextMatch, createAgentPage };
+export { ActionError, type AgentAction, AgentDomError, AgentObservation, AgentPage, type BrowserWindow, type CreateAgentPageOptions, ElementNotFoundError, type ElementState, type Observation, type ObserveOptions, type ObservedElement, type RoleLocatorOptions, StaleElementReferenceError, type StalePolicy, type TextMatch, createAgentPage };

package/dist/index.d.ts

@@ -74,7 +74,19 @@ type AgentAction = {
 };
 interface CreateAgentPageOptions {
     root?: Document | Element | ShadowRoot;
+    /**
+     * When a ref stops being usable.
+     *
+     * - `"connected"` (default): a ref stays valid until *its own* element is removed.
+     *   Real pages never stop mutating — streaming chat, spinners, clocks, toasts,
+     *   virtualised lists, framework re-renders. A policy that reacted to all of it
+     *   would mean no action ever lands on a live page.
+     * - `"generation"`: any mutation anywhere under the root invalidates every ref from
+     *   the previous observation. Opt in for stepwise harnesses that must be current.
+     */
+    stale?: StalePolicy;
 }
+type StalePolicy = "generation" | "connected";
 
 declare class AgentPage {
     #private;
@@ -125,4 +137,4 @@ declare class ActionError extends AgentDomError {
     readonly name: string;
 }
 
-export { ActionError, type AgentAction, AgentDomError, AgentObservation, AgentPage, type BrowserWindow, type CreateAgentPageOptions, ElementNotFoundError, type ElementState, type Observation, type ObserveOptions, type ObservedElement, type RoleLocatorOptions, StaleElementReferenceError, type TextMatch, createAgentPage };
+export { ActionError, type AgentAction, AgentDomError, AgentObservation, AgentPage, type BrowserWindow, type CreateAgentPageOptions, ElementNotFoundError, type ElementState, type Observation, type ObserveOptions, type ObservedElement, type RoleLocatorOptions, StaleElementReferenceError, type StalePolicy, type TextMatch, createAgentPage };

package/dist/index.js

@@ -434,12 +434,14 @@ var AgentPage = class {
   root;
   #documentGeneration = 0;
   #snapshotGeneration = 0;
+  #stale;
   #refState;
   #observation;
   #observer;
   constructor(window, options = {}) {
     this.window = window;
     this.root = options.root ?? window.document;
+    this.#stale = options.stale ?? "connected";
     const document = ownerDocument(this.root);
     if (document.defaultView !== window) {
       throw new TypeError("The root must belong to the supplied window.");
@@ -540,7 +542,9 @@ var AgentPage = class {
   #freshObservation() {
     this.#syncMutations();
     if (!this.#observation || !this.#refState) return this.observe();
-    if (this.#refState.documentGeneration !== this.#documentGeneration) return this.observe();
+    if (this.#stale === "generation" && this.#refState.documentGeneration !== this.#documentGeneration) {
+      return this.observe();
+    }
     return this.#observation;
   }
   #resolve(ref) {
@@ -548,7 +552,7 @@ var AgentPage = class {
     const normalized = normalizeRef(ref);
     const state = this.#refState;
     if (!state) throw new ElementNotFoundError("Observe the page before using a ref.");
-    if (state.documentGeneration !== this.#documentGeneration) {
+    if (this.#stale === "generation" && state.documentGeneration !== this.#documentGeneration) {
       throw new StaleElementReferenceError(normalized, state.snapshotGeneration, this.#snapshotGeneration + 1);
     }
     const element = state.refs.get(normalized);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@undo76/agent-dom",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "A browser-native semantic DOM API for AI agents.",
   "type": "module",
   "main": "./dist/index.cjs",