aboutsummaryrefslogtreecommitdiff
path: root/src/cdp/target-factory.ts
diff options
context:
space:
mode:
authoramankumarsingh77 <amankumarsingh7702@gmail.com>2026-07-28 20:25:38 +0530
committerAman Kumar <145339995+amankumarsingh77@users.noreply.github.com>2026-08-02 19:12:46 +0530
commit330767d862458386e804bde240a1f0d7835b9b8e (patch)
tree13a5f2086d265959c1bfa10bb88641a6804fd1f5 /src/cdp/target-factory.ts
parent12d7a38ba0f1b1e4e301fce81e22f4b93036d211 (diff)
refactor(cdp): strip comment noise
Removes module banners, section dividers, and comments restating the code. Keeps one-line notes for the window.open/browserContextId constraint, the seed-tab claim, the unverifiable-pin reuse rule, the SeedTargetProvider rationale, the deliberate dialog retention, the discovery-time browser quirks, and the guarded CDP decoder assertion. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Diffstat (limited to 'src/cdp/target-factory.ts')
-rw-r--r--src/cdp/target-factory.ts69
1 files changed, 3 insertions, 66 deletions
diff --git a/src/cdp/target-factory.ts b/src/cdp/target-factory.ts
index 718a8d0..62c46f1 100644
--- a/src/cdp/target-factory.ts
+++ b/src/cdp/target-factory.ts
@@ -1,31 +1,4 @@
-/**
- * The single place harness tabs and windows are created.
- *
- * Every tab the harness opens must land in the pinned profile, so all creation
- * paths (client.newTab, browser_open_urls, isolated tabs for web_search /
- * read_page) funnel through here. A missed call site would silently act in
- * another profile — with that profile's cookies and logins.
- *
- * Two mechanisms, chosen by whether a profile is pinned:
- *
- * unpinned — `Target.createTarget`, exactly as before: `newWindow: true` for
- * a fresh dedicated window, `openerId` for siblings inside it.
- *
- * pinned — the window comes from a command-line launch into the profile
- * (see profile/launch.ts), and further tabs come from
- * `window.open(..., '_blank')` evaluated in an owned page with
- * `userGesture: true`. That is the only CDP-reachable way to place
- * a tab in a non-default browser context: createTarget rejects a
- * foreign browserContextId outright, and `openerId` does NOT
- * inherit the opener's context (verified — it lands in the
- * focus-derived default context, in a different window).
- * window.open keeps both the context and the window, recursively.
- *
- * Correlation: window.open returns no target id, so each spawn carries a unique
- * `about:blank#pi-<uuid>` token and the new target is found by that token.
- * Set-difference polling would be wrong here — isolated tabs run concurrently
- * (browser_read_page is registered unserialized).
- */
+// `window.open` with userGesture is the only CDP-reachable way into a non-default browser context: createTarget rejects a foreign browserContextId and `openerId` does not inherit the opener's context.
import { randomUUID } from "node:crypto";
import type { BrowserClient } from "../client";
@@ -34,17 +7,11 @@ import { attachTo } from "./attach";
import { type CdpError, cdpError } from "./errors";
import { getWindowId } from "./window";
-/** How long to wait for a window.open-spawned target to appear. */
const SPAWN_DEADLINE_MS = 8_000;
const SPAWN_POLL_MS = 100;
export type HarnessWindow = {
- /** Target id of the window's seed tab. */
readonly targetId: string;
- /**
- * True when this call created the window. The seed tab is then a blank tab
- * the caller may use directly, instead of opening a second one.
- */
readonly freshlyCreated: boolean;
};
@@ -61,17 +28,12 @@ const listPageTargets = async (client: BrowserClient): Promise<Result<ReadonlyAr
return ok(r.data.targetInfos.filter((t) => t.type === "page"));
};
-/** A CDP session id for driving `targetId`, reusing the active one when possible. */
const sessionForTarget = async (client: BrowserClient, targetId: string): Promise<Result<string, CdpError>> => {
const current = client.current();
if (current?.targetId === targetId) return ok(current.sessionId);
return attachTo(client.session(), targetId);
};
-/**
- * Spawn a tab from `openerTargetId` via window.open, so it inherits the
- * opener's profile and window, and return its target id.
- */
const spawnTabViaOpener = async (
client: BrowserClient,
openerTargetId: string,
@@ -111,29 +73,13 @@ const spawnTabViaOpener = async (
return err(cdpError("timeout", `the tab opened in the pinned profile did not report back within ${SPAWN_DEADLINE_MS}ms`));
};
-/**
- * In-flight window creation, per client. Isolated tabs run concurrently
- * (browser_read_page is registered unserialized), so two of them starting at
- * once would otherwise each find "no harness window" and create one — two blank
- * windows before, and two launched profile windows now. Callers share the first
- * call's result instead.
- */
const inFlight = new WeakMap<BrowserClient, Promise<Result<HarnessWindow, CdpError>>>();
-/**
- * The harness window for this session, creating it when absent.
- *
- * Reuses a live owned tab when one exists — including after the user closed the
- * original seed — so reconnects don't scatter windows.
- */
export const ensureHarnessWindow = async (client: BrowserClient): Promise<Result<HarnessWindow, CdpError>> => {
const pending = inFlight.get(client);
if (pending) {
const shared = await pending;
- // `freshlyCreated` is a claim on the seed tab, and only the caller that
- // started the creation may hold it. Everyone waiting on the same window
- // must open a tab of their own beside it, or two callers would drive the
- // very same tab.
+ // `freshlyCreated` is a claim on the seed tab that only the caller which started the creation may hold, or two callers would drive the same tab.
return shared.success ? ok({ targetId: shared.data.targetId, freshlyCreated: false }) : shared;
}
const attempt = ensureHarnessWindowUncoordinated(client).finally(() => inFlight.delete(client));
@@ -150,11 +96,7 @@ const ensureHarnessWindowUncoordinated = async (
const ownership = client.ownership();
const pinnedCtx = client.profileContextId();
- // A tab may only be reused when we can prove which profile it is in. With a
- // pin set but no context resolved yet — a fresh connection, or a browser that
- // restarted — the recorded tabs cannot be verified, so we seed a new window
- // rather than risk adopting one from the wrong profile. (Sessions close their
- // owned tabs on shutdown, so this is the normal, no-cost case.)
+ // With a pin set but no context resolved yet, a recorded tab's profile cannot be verified, so seed a new window rather than risk adopting one from the wrong profile.
const canReuse = client.profilePin() === null || pinnedCtx !== undefined;
const inPinnedProfile = (targetId: string): boolean => {
if (!pinnedCtx) return true;
@@ -181,7 +123,6 @@ const ensureHarnessWindowUncoordinated = async (
return ok({ targetId: seeded.data, freshlyCreated: true });
};
-/** Unpinned path: a fresh dedicated window, exactly as the harness always did. */
const createDedicatedWindow = async (client: BrowserClient): Promise<Result<string, CdpError>> => {
const created = await client.session().callBrowser("Target.createTarget", { url: "about:blank", newWindow: true });
if (!created.success) return created;
@@ -194,10 +135,6 @@ const createDedicatedWindow = async (client: BrowserClient): Promise<Result<stri
return ok(targetId);
};
-/**
- * Open a harness-owned tab beside `openerTargetId`, in the same window and —
- * when a profile is pinned — the same profile. The tab is registered as owned.
- */
export const openHarnessTab = async (
client: BrowserClient,
openerTargetId: string,