agent-browser-loop 0.2.1 → 0.3.0

package/src/ref-store.ts

@@ -0,0 +1,216 @@
+import type { Locator, Page } from "playwright";
+
+/**
+ * Selector strategies for locating an element
+ * Multiple strategies provide resilience if one fails
+ */
+export interface ElementSelectors {
+  /** XPath from document root */
+  xpath: string;
+  /** CSS selector path */
+  cssPath: string;
+  /** Fingerprint-based selector using stable attributes */
+  fingerprint?: string;
+}
+
+/**
+ * Stored reference to an element
+ */
+export interface StoredElementRef {
+  /** The ref string (e.g., "button_0") */
+  ref: string;
+  /** Sequential index */
+  index: number;
+  /** Multiple selector strategies */
+  selectors: ElementSelectors;
+  /** Element fingerprint for validation */
+  fingerprint: {
+    tagName: string;
+    role?: string;
+    type?: string;
+    name?: string;
+    placeholder?: string;
+  };
+}
+
+/**
+ * Server-side store for element references
+ * Avoids DOM modification that causes React hydration errors
+ */
+export class ElementRefStore {
+  private refMap = new Map<string, StoredElementRef>();
+  private indexMap = new Map<number, StoredElementRef>();
+  private snapshotVersion = 0;
+
+  /**
+   * Clear all stored refs (call before new snapshot)
+   */
+  clear(): void {
+    this.refMap.clear();
+    this.indexMap.clear();
+    this.snapshotVersion++;
+  }
+
+  /**
+   * Get current snapshot version
+   */
+  getVersion(): number {
+    return this.snapshotVersion;
+  }
+
+  /**
+   * Store a ref for an element
+   */
+  set(
+    ref: string,
+    index: number,
+    selectors: ElementSelectors,
+    fingerprint: StoredElementRef["fingerprint"],
+  ): void {
+    const stored: StoredElementRef = { ref, index, selectors, fingerprint };
+    this.refMap.set(ref, stored);
+    this.indexMap.set(index, stored);
+  }
+
+  /**
+   * Get stored ref by ref string
+   */
+  getByRef(ref: string): StoredElementRef | undefined {
+    return this.refMap.get(ref);
+  }
+
+  /**
+   * Get stored ref by index
+   */
+  getByIndex(index: number): StoredElementRef | undefined {
+    return this.indexMap.get(index);
+  }
+
+  /**
+   * Resolve a Playwright locator for an element by ref or index
+   */
+  async resolveLocator(
+    page: Page,
+    options: { ref?: string; index?: number },
+  ): Promise<Locator> {
+    let stored: StoredElementRef | undefined;
+
+    if (options.ref) {
+      stored = this.refMap.get(options.ref);
+      if (!stored) {
+        throw new Error(
+          `Unknown ref: ${options.ref}. Call getState() first to snapshot elements.`,
+        );
+      }
+    } else if (options.index !== undefined) {
+      stored = this.indexMap.get(options.index);
+      if (!stored) {
+        throw new Error(
+          `Unknown index: ${options.index}. Call getState() first to snapshot elements.`,
+        );
+      }
+    } else {
+      throw new Error("Must provide either ref or index");
+    }
+
+    const pickMatching = async (locator: Locator): Promise<Locator | null> => {
+      const count = await locator.count();
+      if (count === 0) {
+        return null;
+      }
+
+      for (let i = 0; i < count; i++) {
+        const candidate = locator.nth(i);
+        const matches = await candidate.evaluate((el, fingerprint) => {
+          const element = el as HTMLElement;
+          if (
+            fingerprint.tagName &&
+            element.tagName.toLowerCase() !== fingerprint.tagName
+          ) {
+            return false;
+          }
+          if (
+            fingerprint.role &&
+            element.getAttribute("role") !== fingerprint.role
+          ) {
+            return false;
+          }
+          if (
+            fingerprint.type &&
+            element.getAttribute("type") !== fingerprint.type
+          ) {
+            return false;
+          }
+          if (
+            fingerprint.name &&
+            element.getAttribute("name") !== fingerprint.name
+          ) {
+            return false;
+          }
+          if (
+            fingerprint.placeholder &&
+            element.getAttribute("placeholder") !== fingerprint.placeholder
+          ) {
+            return false;
+          }
+          return true;
+        }, stored!.fingerprint);
+
+        if (matches) {
+          return candidate;
+        }
+      }
+
+      return null;
+    };
+
+    const selectors = stored.selectors;
+
+    const xpathLocator = page.locator(`xpath=${selectors.xpath}`);
+    const xpathMatch = await pickMatching(xpathLocator);
+    if (xpathMatch) {
+      return xpathMatch;
+    }
+
+    const cssLocator = page.locator(selectors.cssPath);
+    const cssMatch = await pickMatching(cssLocator);
+    if (cssMatch) {
+      return cssMatch;
+    }
+
+    let fingerprintLocator: Locator | null = null;
+    if (selectors.fingerprint) {
+      const tagPrefix = stored.fingerprint.tagName || "";
+      const fingerprintSelector = selectors.fingerprint.startsWith("[")
+        ? `${tagPrefix}${selectors.fingerprint}`
+        : selectors.fingerprint;
+      fingerprintLocator = page.locator(fingerprintSelector);
+      const fingerprintMatch = await pickMatching(fingerprintLocator);
+      if (fingerprintMatch) {
+        return fingerprintMatch;
+      }
+    }
+
+    // Last resort: fall back to first match from the best available selector.
+    if (await xpathLocator.count()) {
+      return xpathLocator.first();
+    }
+    if (await cssLocator.count()) {
+      return cssLocator.first();
+    }
+    if (fingerprintLocator && (await fingerprintLocator.count())) {
+      return fingerprintLocator.first();
+    }
+
+    throw new Error(
+      `Unable to resolve element for ref ${stored.ref}. Call getState() again to refresh element refs.`,
+    );
+  }
+
+  /**
+   * Get all stored refs
+   */
+  getAllRefs(): StoredElementRef[] {
+    return Array.from(this.refMap.values());
+  }
+}

package/src/server.ts

@@ -19,7 +19,16 @@ import {
 } from "./commands";
 import { createIdGenerator } from "./id";
 import { log } from "./log";
+import {
+  deleteProfile,
+  listProfiles,
+  loadProfile,
+  resolveProfilePath,
+  resolveStorageStateOption,
+  saveProfile,
+} from "./profiles";
 import { formatStateText } from "./state";
+import type { StorageState } from "./types";
 
 export interface BrowserServerConfig {
   host?: string;
@@ -232,6 +241,7 @@ function getWaitCondition(data: WaitRequest): WaitCondition {
 const createSessionBodySchema = z.object({
   headless: z.boolean().optional(),
   userDataDir: z.string().optional(),
+  profile: z.string().optional(),
 });
 
 const sessionParamsSchema = z.object({
@@ -528,16 +538,43 @@ const waitRoute = createRoute({
   },
 });
 
+const closeSessionBodySchema = z
+  .object({
+    saveProfile: z.string().optional(),
+    global: z.boolean().optional(),
+    private: z.boolean().optional(),
+  })
+  .optional();
+
 const closeRoute = createRoute({
   method: "post",
   path: "/session/{sessionId}/close",
   request: {
     params: sessionParamsSchema,
+    body: {
+      required: false,
+      content: {
+        "application/json": {
+          schema: closeSessionBodySchema,
+        },
+      },
+    },
   },
   responses: {
     204: {
       description: "Session closed",
     },
+    200: {
+      description: "Session closed with profile saved",
+      content: {
+        "application/json": {
+          schema: z.object({
+            profileSaved: z.string().optional(),
+            profilePath: z.string().optional(),
+          }),
+        },
+      },
+    },
     404: {
       description: "Session not found",
       content: {
@@ -745,6 +782,14 @@ export function startBrowserServer(config: BrowserServerConfig) {
         overrides.userDataDir = body.userDataDir;
       }
 
+      // Handle profile option
+      if (body?.profile) {
+        const storageState = resolveStorageStateOption(body.profile);
+        if (typeof storageState === "object") {
+          overrides.storageState = storageState;
+        }
+      }
+
       const id = await createNewSession(overrides);
       return c.json({ sessionId: id }, 200);
     },
@@ -886,11 +931,29 @@ export function startBrowserServer(config: BrowserServerConfig) {
   app.openapi(closeRoute, async (c) => {
     const { sessionId } = c.req.valid("param");
     const session = getSessionOrThrow(sessions, sessionId);
+    const body = c.req.valid("json");
 
     return withSession(session, async () => {
+      let profilePath: string | undefined;
+
+      // Save profile before closing if requested
+      if (body?.saveProfile) {
+        const storageState =
+          (await session.browser.saveStorageState()) as StorageState;
+        profilePath = saveProfile(body.saveProfile, storageState, {
+          global: body.global,
+          private: body.private,
+        });
+      }
+
       await session.browser.stop();
       sessions.delete(sessionId);
       idGenerator.release(sessionId);
+
+      if (profilePath) {
+        return c.json({ profileSaved: body?.saveProfile, profilePath }, 200);
+      }
+
       return c.body(null, 204);
     });
   });
@@ -905,6 +968,91 @@ export function startBrowserServer(config: BrowserServerConfig) {
     });
   });
 
+  // ========================================================================
+  // Profile Endpoints
+  // ========================================================================
+
+  // GET /profiles - list all profiles
+  app.get("/profiles", (c) => {
+    const profiles = listProfiles();
+    return c.json(profiles);
+  });
+
+  // GET /profiles/:name - get profile contents
+  app.get("/profiles/:name", (c) => {
+    const name = c.req.param("name");
+    const profile = loadProfile(name);
+    if (!profile) {
+      return c.json({ error: `Profile not found: ${name}` }, 404);
+    }
+    const resolved = resolveProfilePath(name);
+    return c.json({
+      name,
+      scope: resolved?.scope,
+      path: resolved?.path,
+      profile,
+    });
+  });
+
+  // POST /profiles/:name - save profile from session or body
+  app.post("/profiles/:name", async (c) => {
+    const name = c.req.param("name");
+    const body = await c.req.json().catch(() => ({}));
+
+    let storageState: StorageState;
+
+    // If sessionId provided, get storage state from that session
+    if (body.sessionId) {
+      const session = sessions.get(body.sessionId);
+      if (!session) {
+        return c.json({ error: `Session not found: ${body.sessionId}` }, 404);
+      }
+      storageState = (await session.browser.saveStorageState()) as StorageState;
+    } else if (body.cookies || body.origins) {
+      // Direct storage state in body
+      storageState = {
+        cookies: body.cookies || [],
+        origins: body.origins || [],
+      };
+    } else {
+      return c.json(
+        {
+          error: "Either sessionId or storage state (cookies/origins) required",
+        },
+        400,
+      );
+    }
+
+    const savedPath = saveProfile(name, storageState, {
+      global: body.global,
+      private: body.private,
+      description: body.description,
+    });
+
+    return c.json({
+      name,
+      path: savedPath,
+      cookies: storageState.cookies.length,
+      origins: storageState.origins.length,
+    });
+  });
+
+  // DELETE /profiles/:name - delete profile
+  app.delete("/profiles/:name", (c) => {
+    const name = c.req.param("name");
+    const resolved = resolveProfilePath(name);
+    if (!resolved) {
+      return c.json({ error: `Profile not found: ${name}` }, 404);
+    }
+
+    const deleted = deleteProfile(name);
+    if (!deleted) {
+      return c.json({ error: `Failed to delete profile: ${name}` }, 500);
+    }
+
+    return c.json({ deleted: name, path: resolved.path });
+  });
+
   const server = Bun.serve({
     hostname: host,
     port,