[chore]: pull stringified JS into TS file (#1622)

# why
- stringified JS is hard to debug & not good practice
# what changed
- pulled stringified JS from `screenshotUtils.ts` into its own
`resolveMaskRect.ts` file
- added a generator to compile screenshot scripts into function strings:
`packages/core/lib/v3/dom/genScreenshotScripts.ts`
# test plan
- existing tests should cover this

<!-- This is an auto-generated description by cubic. -->
---
## Summary by cubic
Replace stringified screenshot DOM code with typed TS functions and
generate function strings at build time. This makes screenshot scripts
easier to maintain and debug.

- **Refactors**
- Extracted resolveMaskRect into
lib/v3/dom/screenshotScripts/resolveMaskRect.ts with types.
- Added genScreenshotScripts.ts to bundle TS scripts and emit
build/screenshotScripts.generated.ts.
- Updated screenshotUtils to use
screenshotScriptSources.resolveMaskRect; included generator in
build-dom-scripts.

<sup>Written for commit 8ce9a91.
Summary will update on new commits. <a
href="https://cubic.dev/pr/browserbase/stagehand/pull/1622">Review in
cubic</a></sup>

<!-- End of auto-generated description by cubic. -->

Author: seanmcguire12

packages/core/lib/v3/dom/genScreenshotScripts.ts

@@ -0,0 +1,56 @@
+import fs from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import esbuild from "esbuild";
+
+const here = __dirname;
+const srcDir = path.join(here, "./screenshotScripts");
+const outDir = path.join(here, "./build");
+const entry = path.join(srcDir, "index.ts");
+const moduleOut = path.join(outDir, "screenshotScripts.mjs");
+
+async function main(): Promise<void> {
+  fs.mkdirSync(outDir, { recursive: true });
+
+  esbuild.buildSync({
+    entryPoints: [entry],
+    bundle: true,
+    format: "esm",
+    platform: "browser",
+    target: "es2020",
+    minify: true,
+    outfile: moduleOut,
+  });
+
+  const compiledModule = (await import(
+    pathToFileURL(moduleOut).href
+  )) as Record<string, unknown>;
+
+  const entries = Object.entries(compiledModule).filter(
+    ([, value]) => typeof value === "function",
+  );
+  const sorted = entries.sort(([a], [b]) => a.localeCompare(b));
+
+  const scriptMap: Record<string, string> = Object.fromEntries(
+    sorted.map(([name, fn]) => {
+      const callable = fn as (...args: unknown[]) => unknown;
+      return [name, callable.toString()];
+    }),
+  );
+
+  const banner = `/*\n * AUTO-GENERATED FILE. DO NOT EDIT.\n * Update sources in lib/v3/dom/screenshotScripts and run genScreenshotScripts.ts.\n */`;
+
+  const content = `${banner}
+export const screenshotScriptSources = ${JSON.stringify(scriptMap, null, 2)} as const;
+export type ScreenshotScriptName = keyof typeof screenshotScriptSources;
+`;
+
+  fs.writeFileSync(
+    path.join(outDir, "screenshotScripts.generated.ts"),
+    content,
+  );
+
+  await fs.promises.unlink(moduleOut).catch(() => {});
+}
+
+void main();

packages/core/lib/v3/dom/screenshotScripts/index.ts

@@ -0,0 +1 @@
+export { resolveMaskRect } from "./resolveMaskRect";

packages/core/lib/v3/dom/screenshotScripts/resolveMaskRect.ts

@@ -0,0 +1,22 @@
+export type MaskRect = {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+};
+
+export function resolveMaskRect(this: Element | null): MaskRect | null {
+  if (!this || typeof this.getBoundingClientRect !== "function") return null;
+  const rect = this.getBoundingClientRect();
+  if (!rect) return null;
+  const style = window.getComputedStyle(this);
+  if (!style) return null;
+  if (style.visibility === "hidden" || style.display === "none") return null;
+  if (rect.width <= 0 || rect.height <= 0) return null;
+  return {
+    x: rect.left + window.scrollX,
+    y: rect.top + window.scrollY,
+    width: rect.width,
+    height: rect.height,
+  };
+}

packages/core/lib/v3/understudy/screenshotUtils.ts

@@ -8,6 +8,7 @@ import type {
   ScreenshotScaleOption,
 } from "../types/public/screenshotTypes";
 import { StagehandInvalidArgumentError } from "../types/public/sdkErrors";
+import { screenshotScriptSources } from "../dom/build/screenshotScripts.generated";
 
 export type ScreenshotCleanup = () => Promise<void> | void;
 
@@ -325,21 +326,7 @@ async function resolveMaskRectForObject(
     "Runtime.callFunctionOn",
     {
       objectId,
-      functionDeclaration: `function() {
-        if (!this || typeof this.getBoundingClientRect !== 'function') return null;
-        const rect = this.getBoundingClientRect();
-        if (!rect) return null;
-        const style = window.getComputedStyle(this);
-        if (!style) return null;
-        if (style.visibility === 'hidden' || style.display === 'none') return null;
-        if (rect.width <= 0 || rect.height <= 0) return null;
-        return {
-          x: rect.left + window.scrollX,
-          y: rect.top + window.scrollY,
-          width: rect.width,
-          height: rect.height,
-        };
-      }`,
+      functionDeclaration: screenshotScriptSources.resolveMaskRect,
       returnByValue: true,
     },
   );

packages/core/package.json

@@ -7,7 +7,7 @@
   "types": "./dist/index.d.ts",
   "scripts": {
     "gen-version": "tsx scripts/gen-version.ts",
-    "build-dom-scripts": "tsx lib/v3/dom/genDomScripts.ts && tsx lib/v3/dom/genLocatorScripts.ts && tsx lib/v3/dom/genA11yScripts.ts",
+    "build-dom-scripts": "tsx lib/v3/dom/genDomScripts.ts && tsx lib/v3/dom/genLocatorScripts.ts && tsx lib/v3/dom/genScreenshotScripts.ts && tsx lib/v3/dom/genA11yScripts.ts",
     "build-js": "tsup --entry.index lib/v3/index.ts --dts",
     "typecheck": "tsc --noEmit",
     "build": "pnpm run gen-version && pnpm run build-dom-scripts && pnpm run build-js && pnpm run typecheck",