@nijaru/pi-search 0.0.7 → 0.0.9

package/src/x-browser-page.ts

@@ -0,0 +1,191 @@
+import { SafeFetchError } from "./fetch-errors";
+import { validateRemoteUrl, type Lookup } from "./ssrf";
+import { extractXDom, type XDomDocument } from "./x-dom.mjs";
+import { parseXUrl, type XUrl } from "./x-public";
+import type { XBrowserConnection } from "./x-cdp";
+
+export interface XBrowserDocument extends XDomDocument { readonly bytesRead: number }
+const HOSTS = new Set(["x.com", "www.x.com", "twitter.com", "api.x.com", "api.twitter.com", "abs.twimg.com", "pbs.twimg.com", "video.twimg.com", "ton.twitter.com"]);
+const READ_OPERATIONS = new Set([
+	"TweetDetail", "TweetResultByRestId", "TweetResultsByRestIds", "TweetResultById",
+	"ConversationTimeline", "UserByScreenName", "UserResultByScreenName", "Viewer",
+	// The shared X application shell needs these reads before rendering conversations.
+	"DataSaverMode", "CreatorStudioTabBarItemQuery", "useFetchProductSubscriptionsQuery",
+	"getAltTextPromptPreference", "ExploreSidebar",
+]);
+const PAGE_POLICY = "frame-src 'none'; worker-src 'none'; object-src 'none'; media-src 'none'; img-src 'none'; font-src 'none'; form-action 'none'; base-uri 'none'";
+
+export function browserRequestAllowed(value: string, method: string): boolean {
+	try {
+		const url = new URL(value);
+		if (url.protocol !== "https:" || url.username || url.password || url.port || !HOSTS.has(url.hostname)) return false;
+		if (method === "GET" || method === "HEAD") {
+			if (/^\/i\/api\/graphql\//.test(url.pathname)) return READ_OPERATIONS.has(url.pathname.split("/").at(-1)!);
+			return !/^\/(?:logout|i\/flow\/logout)(?:\/|$)/.test(url.pathname);
+		}
+		return method === "POST" && ["x.com", "api.x.com", "api.twitter.com"].includes(url.hostname) && /^\/i\/api\/graphql\//.test(url.pathname) && READ_OPERATIONS.has(url.pathname.split("/").at(-1)!);
+	} catch { return false; }
+}
+
+interface TargetInfo { targetId: string; type: string; url: string; browserContextId?: string }
+interface Snapshot { url: string; document: XDomDocument | null }
+function canceled(): SafeFetchError { return new SafeFetchError({ kind: "canceled", message: "X browser read canceled" }); }
+function delay(signal: AbortSignal): Promise<void> {
+	return new Promise((resolve, reject) => {
+		const finish = (): void => { signal.removeEventListener("abort", abort); resolve(); };
+		const timer = setTimeout(finish, 150);
+		const abort = (): void => { clearTimeout(timer); signal.removeEventListener("abort", abort); reject(canceled()); };
+		signal.addEventListener("abort", abort, { once: true });
+		if (signal.aborted) abort();
+	});
+}
+
+/** A background tab in the user's existing profile, never an existing tab or shared context. */
+export async function readXBrowserPage(connection: XBrowserConnection, target: XUrl, signal: AbortSignal, maxBytes: number, lookup?: Lookup): Promise<XBrowserDocument> {
+	let targetId: string | undefined;
+	let sessionId: string | undefined;
+	let closeTask: Promise<unknown> | undefined;
+	let failure: Error | undefined;
+	let bytesRead = 0;
+	let lastActivity = Date.now();
+	let previousHtml: string | undefined;
+	let documentChangedAt = Date.now();
+	const loading = new Set<string>();
+	const completed = new Set<string>();
+	const removeHandlers: (() => void)[] = [];
+	const pendingGuards = new Set<Promise<void>>();
+	const resolvedHosts = new Map<string, Promise<unknown>>();
+	const close = (): Promise<unknown> => {
+		if (!targetId) return Promise.resolve();
+		return closeTask ??= connection.send("Target.closeTarget", { targetId }).catch(() => undefined);
+	};
+	const fail = (error: Error): void => { failure ??= error; void close(); };
+	const check = (): void => { if (failure) throw failure; if (signal.aborted) throw canceled(); };
+	const abort = (): void => { void close(); };
+	signal.addEventListener("abort", abort, { once: true });
+	try {
+		check();
+		// Inspect only target metadata to find an unambiguous X profile. Never attach to or read other tabs.
+		const { targetInfos } = await connection.send<{ targetInfos: TargetInfo[] }>("Target.getTargets");
+		const contexts = new Set(targetInfos.filter((info) => info.type === "page" && /^https:\/\/(?:www\.)?(?:x|twitter)\.com\//.test(info.url)).map((info) => info.browserContextId));
+		if (contexts.size > 1) throw new SafeFetchError({ kind: "extraction", message: "Multiple X browser profiles are open; close the other X profiles before connecting" });
+		const browserContextId = contexts.values().next().value;
+		check();
+		// Keep creation awaited even after cancellation so a late-created tab is still closed in finally.
+		const created = await connection.send<{ targetId: string }>("Target.createTarget", { url: "about:blank", background: true, ...(browserContextId ? { browserContextId } : {}) }, undefined, {
+			onLateResult: ({ targetId }) => { void connection.send("Target.closeTarget", { targetId }).catch(() => undefined); },
+		});
+		targetId = created.targetId;
+		check();
+		({ sessionId } = await connection.send<{ sessionId: string }>("Target.attachToTarget", { targetId, flatten: true }));
+		const send = <T = Record<string, never>>(method: string, params: object = {}): Promise<T> => connection.send<T>(method, params, sessionId);
+		const guard = async (event: any): Promise<void> => {
+			const request = event.request;
+			const blocked = !browserRequestAllowed(request.url, request.method) || ["Image", "Media", "Font", "WebSocket"].includes(event.resourceType);
+			if (blocked || signal.aborted || failure) { await send("Fetch.failRequest", { requestId: event.requestId, errorReason: "BlockedByClient" }); return; }
+			if (event.responseStatusCode === undefined && event.networkId) loading.add(event.networkId);
+			const hostname = new URL(request.url).hostname;
+			let resolved = resolvedHosts.get(hostname);
+			// Unlike direct HTTP, CDP cannot pin Chromium to these validated DNS answers.
+			if (!resolved) { resolved = validateRemoteUrl(request.url, { signal, lookup }); resolvedHosts.set(hostname, resolved); }
+			await resolved;
+			if (event.responseStatusCode !== undefined) {
+				const headers = event.responseHeaders as { name: string; value: string }[] ?? [];
+				const header = (name: string): string | undefined => headers.find((h) => h.name.toLowerCase() === name)?.value;
+				if (event.responseStatusCode >= 300 && event.responseStatusCode < 400 && header("location")) {
+					const redirect = new URL(header("location")!, request.url);
+					if (!browserRequestAllowed(redirect.href, "GET")) {
+						const error = new SafeFetchError({ kind: "redirect", message: "X browser redirect left the allowed HTTPS hosts" });
+						failure ??= error;
+						await send("Fetch.failRequest", { requestId: event.requestId, errorReason: "BlockedByClient" });
+						throw error;
+					}
+					await validateRemoteUrl(redirect, { signal, lookup });
+				}
+				const declared = Number(header("content-length"));
+				if (Number.isFinite(declared) && declared > maxBytes - bytesRead) throw new SafeFetchError({ kind: "responseTooLarge", message: "X browser response exceeds its byte limit" });
+				if (event.resourceType === "Document") {
+					if (/attachment/i.test(header("content-disposition") ?? "")) throw new Error("X browser refused a download");
+					await send("Fetch.continueResponse", { requestId: event.requestId, responseCode: event.responseStatusCode, responseHeaders: [...headers, { name: "Content-Security-Policy", value: PAGE_POLICY }] });
+					return;
+				}
+				await send("Fetch.continueResponse", { requestId: event.requestId });
+			} else await send("Fetch.continueRequest", { requestId: event.requestId });
+		};
+		removeHandlers.push(connection.on("Fetch.requestPaused", (event, id) => {
+			if (id !== sessionId) return;
+			const task = guard(event).catch((error: Error) => {
+				// X may cancel a request between interception and our continuation.
+				// A browser-confirmed completion makes that interception obsolete.
+				if (!event.networkId || !completed.has(event.networkId)) fail(error);
+			}).finally(() => pendingGuards.delete(task));
+			pendingGuards.add(task);
+		}));
+		for (const event of ["Network.loadingFinished", "Network.loadingFailed"]) {
+			removeHandlers.push(connection.on(event, (event, id) => {
+				if (id !== sessionId) return;
+				loading.delete(event.requestId);
+				completed.add(event.requestId);
+				lastActivity = Date.now();
+			}));
+		}
+		removeHandlers.push(connection.on("Network.dataReceived", (event, id) => {
+			if (id !== sessionId) return;
+			lastActivity = Date.now();
+			bytesRead += event.dataLength;
+			if (bytesRead > maxBytes) fail(new SafeFetchError({ kind: "responseTooLarge", message: "X browser exceeded its observed response-byte limit" }));
+		}));
+		// X defers conversation rendering in hidden tabs. Emulate focus only in our
+		// owned tab, without activating a window or changing the user's selected tab.
+		await send("Emulation.setFocusEmulationEnabled", { enabled: true });
+		await send("Network.enable");
+		await send("Network.setBypassServiceWorker", { bypass: true });
+		await send("Network.setBlockedURLs", { urls: ["ws://*", "wss://*"] });
+		await send("Page.enable");
+		await send("Page.addScriptToEvaluateOnNewDocument", { source: "Object.defineProperties(window, {open: {value: () => null, configurable: false, writable: false}, WebSocket: {value: undefined, configurable: false, writable: false}});" });
+		await send("Fetch.enable", { patterns: [{ urlPattern: "*", requestStage: "Request" }, { urlPattern: "*", requestStage: "Response" }] });
+		check();
+		const navigation = await send<{ errorText?: string }>("Page.navigate", { url: target.url });
+		if (navigation.errorText) { check(); throw new Error("X browser navigation failed"); }
+		const expression = `(() => ({url: location.href, document: (${extractXDom.toString()})(document, ${JSON.stringify(target)}, ${Math.min(maxBytes, 1_000_000)})}))()`;
+		const evaluate = async <T>(source: string): Promise<T | undefined> => {
+			const reply = await send<{ result: { value?: T }; exceptionDetails?: unknown }>("Runtime.evaluate", { expression: source, returnByValue: true, timeout: 1_000 });
+			if (reply.exceptionDetails) throw new Error("X page could not be extracted");
+			return reply.result.value;
+		};
+		for (;;) {
+			check();
+			const snapshot = await evaluate<Snapshot>(expression);
+			check();
+			if (snapshot?.document) {
+				const actual = parseXUrl(snapshot.url);
+				if (!actual || actual.postId !== target.postId || actual.articleId !== target.articleId) throw new Error("X navigated away from the requested content");
+				if (snapshot.document.html !== previousHtml) {
+					previousHtml = snapshot.document.html;
+					documentChangedAt = Date.now();
+				}
+				if (snapshot.document.collapsedPostIds?.length) {
+					// Only expand text controls inside selected author posts. Never click links or account actions.
+					await evaluate(`(() => { const ids = ${JSON.stringify(snapshot.document.collapsedPostIds)}; for (const el of document.querySelectorAll('article[data-testid="tweet"]')) { const href = el.querySelector('time')?.closest('a')?.getAttribute('href'); if (href && ids.some(id => new RegExp('/status/' + id + '(?:[/?]|$)').test(href))) el.querySelector('[data-testid="tweet-text-show-more-link"]')?.click(); } })()`);
+				} else if (!loading.size && Date.now() - Math.max(lastActivity, documentChangedAt) >= 750) {
+					// The server-rendered focal post can appear before the conversation hydrates.
+					// Wait for bounded network/DOM quiescence rather than returning that preview.
+					if (!snapshot.document.html || new TextEncoder().encode(snapshot.document.html).byteLength > maxBytes) throw new SafeFetchError({ kind: "responseTooLarge", message: "X browser extracted content exceeds its byte limit" });
+					return { ...snapshot.document, bytesRead };
+				}
+			}
+			if (snapshot && /\/i\/flow\/login|\/login(?:[/?]|$)/.test(snapshot.url)) throw new Error("X is not signed in in this browser profile");
+			await delay(signal);
+		}
+	} catch (error) {
+		if (failure) throw failure;
+		if (signal.aborted) throw canceled();
+		throw error;
+	} finally {
+		signal.removeEventListener("abort", abort);
+		// Leave interception installed until the owned tab has stopped all requests.
+		await close();
+		for (const remove of removeHandlers) remove();
+		await Promise.allSettled(pendingGuards);
+	}
+}

package/src/x-browser.ts

@@ -0,0 +1,181 @@
+import { chmod, mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { SafeFetchError } from "./fetch-errors";
+import type { Lookup } from "./ssrf";
+import type { XReadMode } from "./contracts";
+import type { XUrl } from "./x-public";
+import { browserEndpoint, XBrowserConnection } from "./x-cdp";
+import { readXBrowserPage, type XBrowserDocument } from "./x-browser-page";
+export type { XBrowserDocument } from "./x-browser-page";
+
+export type XBrowserName = "brave" | "chrome" | "chromium";
+interface Preferences { mode: Exclude<XReadMode, "browser">; browser?: XBrowserName }
+export interface XBrowserSelection {
+	readonly mode: XReadMode;
+	read(target: XUrl, signal: AbortSignal, maxBytes: number, lookup?: Lookup): Promise<XBrowserDocument | undefined>;
+}
+export interface XBrowserReader {
+	select(signal: AbortSignal): Promise<XBrowserSelection>;
+}
+export function browserDirectories(): Record<XBrowserName, string> {
+	const home = homedir();
+	if (process.platform === "darwin") {
+		const root = join(home, "Library", "Application Support");
+		return { brave: join(root, "BraveSoftware", "Brave-Browser"), chrome: join(root, "Google", "Chrome"), chromium: join(root, "Chromium") };
+	}
+	if (process.platform === "win32") {
+		const root = process.env.LOCALAPPDATA ?? join(home, "AppData", "Local");
+		return { brave: join(root, "BraveSoftware", "Brave-Browser", "User Data"), chrome: join(root, "Google", "Chrome", "User Data"), chromium: join(root, "Chromium", "User Data") };
+	}
+	const root = process.env.XDG_CONFIG_HOME ?? join(home, ".config");
+	return { brave: join(root, "BraveSoftware", "Brave-Browser"), chrome: join(root, "google-chrome"), chromium: join(root, "chromium") };
+}
+function canceled(): SafeFetchError { return new SafeFetchError({ kind: "canceled", message: "X browser operation canceled" }); }
+function abortable<T>(promise: Promise<T>, signal: AbortSignal): Promise<T> {
+	if (signal.aborted) return Promise.reject(canceled());
+	return new Promise((resolve, reject) => {
+		const abort = (): void => reject(canceled());
+		signal.addEventListener("abort", abort, { once: true });
+		promise.then(resolve, reject).finally(() => signal.removeEventListener("abort", abort));
+	});
+}
+
+/** Explicit authorization for an existing browser. Owns only its connection and temporary X tabs. */
+export class XBrowserAccess implements XBrowserReader {
+	private queue: Promise<unknown> = Promise.resolve();
+	private connection?: XBrowserConnection;
+	private connectedBrowser?: XBrowserName;
+	private active?: AbortController;
+	private stopped = false;
+	private revision = 0;
+	constructor(private readonly directory: string, private readonly browsers = browserDirectories()) {}
+
+	private async preferences(): Promise<Preferences> {
+		let value: unknown;
+		try { value = JSON.parse(await readFile(join(this.directory, "preferences.json"), "utf8")); }
+		catch (error) {
+			if ((error as NodeJS.ErrnoException).code === "ENOENT") return { mode: "auto" };
+			throw new SafeFetchError({ kind: "extraction", message: "Could not read X access preferences", cause: error });
+		}
+		const p = value as Partial<Preferences> | null;
+		if (!p || !["auto", "public", "direct"].includes(p.mode ?? "") || p.browser !== undefined && !["brave", "chrome", "chromium"].includes(p.browser)) throw new SafeFetchError({ kind: "extraction", message: "Invalid X access preferences" });
+		return { mode: p.mode!, ...(p.browser ? { browser: p.browser } : {}) };
+	}
+	private async save(preferences: Preferences, signal?: AbortSignal): Promise<void> {
+		await mkdir(this.directory, { recursive: true, mode: 0o700 });
+		await chmod(this.directory, 0o700);
+		const temporary = join(this.directory, `preferences-${randomUUID()}.tmp`);
+		try {
+			await writeFile(temporary, JSON.stringify(preferences), { mode: 0o600, flag: "wx" });
+			if (signal?.aborted) throw canceled();
+			await rename(temporary, join(this.directory, "preferences.json"));
+		} finally { await rm(temporary, { force: true }); }
+	}
+	select(signal: AbortSignal): Promise<XBrowserSelection> {
+		const revision = this.revision;
+		return this.serialized(async () => {
+			const preferences = await this.preferences();
+			return {
+				mode: preferences.mode,
+				// Bind the read to this policy, so revocation between routing and reading
+				// cannot turn an authorized request into a public fallback.
+				read: (target, signal, maxBytes, lookup) => this.read(preferences, revision, target, signal, maxBytes, lookup),
+			};
+		}, signal, revision);
+	}
+	async status(): Promise<string> {
+		const p = await this.preferences();
+		return `X access: ${p.mode}; ${p.browser ? `${p.browser} authorized${this.connection?.connected ? " and connected" : " (browser approval may be needed)"}` : "browser not authorized"}. ${p.mode === "direct" ? "Only direct X HTTP is allowed." : "Public extraction uses free FxTwitter."} No paid retrieval or separate browser profile.`;
+	}
+	private serialized<T>(task: () => Promise<T>, signal: AbortSignal, revision = this.revision): Promise<T> {
+		const check = (): void => { if (signal.aborted || this.stopped || revision !== this.revision) throw canceled(); };
+		const pending = this.queue.catch(() => undefined).then(async () => {
+			check();
+			const result = await task();
+			check();
+			return result;
+		});
+		this.queue = pending;
+		return abortable(pending, signal);
+	}
+	private async attach(browser: XBrowserName, signal: AbortSignal): Promise<XBrowserConnection> {
+		if (this.connection?.connected && this.connectedBrowser === browser) return this.connection;
+		this.connection?.close();
+		const endpoint = await browserEndpoint(this.browsers[browser]);
+		this.connection = await XBrowserConnection.open(endpoint, signal);
+		this.connectedBrowser = browser;
+		return this.connection;
+	}
+	async connect(confirm: () => Promise<boolean>, browser: XBrowserName = "brave"): Promise<boolean> {
+		const controller = new AbortController();
+		const timeout = setTimeout(() => controller.abort(), 300_000);
+		try {
+			return await this.serialized(async () => {
+				this.active = controller;
+				let authorized = false;
+				try {
+					if (!(await abortable(confirm(), controller.signal))) return false;
+					await this.attach(browser, controller.signal);
+					await this.save({ mode: "auto", browser }, controller.signal);
+					authorized = true;
+					return true;
+				} finally {
+					if (!authorized) this.detach();
+					this.active = undefined;
+				}
+			}, controller.signal);
+		} finally { clearTimeout(timeout); }
+	}
+	private async read(preferences: Preferences, revision: number, target: XUrl, signal: AbortSignal, maxBytes: number, lookup?: Lookup): Promise<XBrowserDocument | undefined> {
+		return this.serialized(async () => {
+			const controller = new AbortController();
+			this.active = controller;
+			const abort = (): void => controller.abort();
+			signal.addEventListener("abort", abort, { once: true });
+			if (signal.aborted) abort();
+			try {
+				if (controller.signal.aborted) throw canceled();
+				if (!preferences.browser) return undefined;
+				if (preferences.mode === "direct") throw canceled();
+				const connection = await this.attach(preferences.browser, controller.signal);
+				const document = await readXBrowserPage(connection, target, controller.signal, maxBytes, lookup);
+				if (controller.signal.aborted) throw canceled();
+				return document;
+			} catch (error) {
+				if (controller.signal.aborted) throw canceled();
+				if (error instanceof SafeFetchError) throw error;
+				throw new SafeFetchError({ kind: "extraction", message: "Authenticated X read failed. Check that X is signed in in your connected browser. Use public mode only if you intend to disclose this post ID to FxTwitter", cause: error });
+			} finally { signal.removeEventListener("abort", abort); this.active = undefined; }
+		}, signal, revision);
+	}
+	private change(task: () => Promise<void>): Promise<void> {
+		this.revision++;
+		this.active?.abort();
+		const pending = this.queue.catch(() => undefined).then(task);
+		this.queue = pending;
+		return pending;
+	}
+	private detach(): void {
+		this.connection?.close();
+		this.connection = undefined;
+		this.connectedBrowser = undefined;
+	}
+	async setMode(mode: Preferences["mode"]): Promise<void> {
+		await this.change(async () => {
+			if (mode !== "auto") this.detach();
+			await this.save({ ...await this.preferences(), mode });
+		});
+	}
+	async disconnect(): Promise<void> {
+		await this.change(async () => {
+			this.detach();
+			await this.save({ mode: (await this.preferences()).mode });
+		});
+	}
+	async shutdown(): Promise<void> {
+		this.stopped = true;
+		await this.change(async () => this.detach());
+	}
+}

package/src/x-cdp.ts

@@ -0,0 +1,101 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { SafeFetchError } from "./fetch-errors";
+
+/** Native discovery only. Never scans ports, launches a browser, or reads profile secrets. */
+export async function browserEndpoint(directory: string): Promise<string> {
+	let text: string;
+	try { text = await readFile(join(directory, "DevToolsActivePort"), "utf8"); }
+	catch { throw new SafeFetchError({ kind: "extraction", message: "No browser connection. Enable remote debugging in your running browser's inspect page, then run /search-x connect" }); }
+	const [port, path, ...rest] = text.trim().split(/\r?\n/);
+	if (text.length > 1024 || rest.length || !/^\d{1,5}$/.test(port ?? "") || Number(port) < 1 || Number(port) > 65535 || !/^\/devtools\/browser\/[A-Za-z0-9-]+$/.test(path ?? "")) {
+		throw new SafeFetchError({ kind: "extraction", message: "Invalid browser connection metadata" });
+	}
+	return `ws://127.0.0.1:${Number(port)}${path}`;
+}
+
+type EventHandler = (params: any, sessionId?: string) => void;
+interface CommandOptions<T> { timeoutMs?: number; onLateResult?: (value: T) => void }
+interface Pending { method: string; resolve(value: any): void; reject(error: Error): void; timer: ReturnType<typeof setTimeout>; expired?: boolean; onLateResult?: (value: any) => void }
+
+/** Target-scoped CDP: unlike general browser drivers, never auto-attaches to existing tabs. */
+export class XBrowserConnection {
+	private nextId = 0;
+	private pending = new Map<number, Pending>();
+	private handlers = new Map<string, Set<EventHandler>>();
+	private constructor(private readonly socket: WebSocket) {
+		socket.addEventListener("message", (event) => {
+			if (typeof event.data !== "string" || event.data.length > 8_000_000) { this.close(); return; }
+			let message: any;
+			try { message = JSON.parse(event.data); } catch { this.close(); return; }
+			if (!message || typeof message !== "object") { this.close(); return; }
+			const pending = this.pending.get(message.id);
+			if (pending) {
+				this.pending.delete(message.id);
+				clearTimeout(pending.timer);
+				// Protocol errors can contain session details. Never echo raw messages or endpoints.
+				if (message.error) pending.reject(new Error(`Browser command ${pending.method} failed`));
+				else if (pending.expired) pending.onLateResult?.(message.result);
+				else pending.resolve(message.result);
+			} else if (typeof message.method === "string") {
+				for (const handler of this.handlers.get(message.method) ?? []) handler(message.params, message.sessionId);
+			}
+		});
+		socket.addEventListener("close", () => this.rejectPending());
+		socket.addEventListener("error", () => this.rejectPending());
+	}
+	static async open(endpoint: string, signal: AbortSignal): Promise<XBrowserConnection> {
+		if (signal.aborted) throw new SafeFetchError({ kind: "canceled", message: "Browser connection canceled" });
+		const socket = new WebSocket(endpoint);
+		const connection = new XBrowserConnection(socket);
+		await new Promise<void>((resolve, reject) => {
+			const cleanup = (): void => {
+				socket.removeEventListener("open", opened);
+				socket.removeEventListener("error", failed);
+				socket.removeEventListener("close", failed);
+				signal.removeEventListener("abort", abort);
+			};
+			const opened = (): void => { cleanup(); resolve(); };
+			const failed = (): void => { cleanup(); connection.close(); reject(new SafeFetchError({ kind: "extraction", message: "Browser connection refused or denied. Enable remote debugging and approve the browser's connection prompt" })); };
+			const abort = (): void => { cleanup(); connection.close(); reject(new SafeFetchError({ kind: "canceled", message: "Browser connection canceled" })); };
+			socket.addEventListener("open", opened, { once: true });
+			socket.addEventListener("error", failed, { once: true });
+			socket.addEventListener("close", failed, { once: true });
+			signal.addEventListener("abort", abort, { once: true });
+			if (signal.aborted) abort();
+		});
+		return connection;
+	}
+	get connected(): boolean { return this.socket.readyState === WebSocket.OPEN; }
+	send<T = Record<string, never>>(method: string, params: object = {}, sessionId?: string, options: CommandOptions<T> = {}): Promise<T> {
+		if (!this.connected) return Promise.reject(new Error("Browser disconnected"));
+		const id = ++this.nextId;
+		return new Promise<T>((resolve, reject) => {
+			const timer = setTimeout(() => {
+				const pending = this.pending.get(id);
+				// Resource creation may complete after a timeout. Retain only its cleanup callback.
+				if (pending?.onLateResult) pending.expired = true;
+				else this.pending.delete(id);
+				reject(new Error(`Browser command ${method} timed out`));
+			}, options.timeoutMs ?? 10_000);
+			this.pending.set(id, { method, resolve, reject, timer, onLateResult: options.onLateResult });
+			try { this.socket.send(JSON.stringify({ id, method, params, ...(sessionId ? { sessionId } : {}) })); }
+			catch { this.pending.delete(id); clearTimeout(timer); reject(new Error("Browser disconnected")); }
+		});
+	}
+	on(method: string, handler: EventHandler): () => void {
+		let handlers = this.handlers.get(method);
+		if (!handlers) { handlers = new Set(); this.handlers.set(method, handlers); }
+		handlers.add(handler);
+		return () => { handlers.delete(handler); if (!handlers.size) this.handlers.delete(method); };
+	}
+	private rejectPending(): void {
+		for (const { reject, timer } of this.pending.values()) { clearTimeout(timer); reject(new Error("Browser disconnected")); }
+		this.pending.clear();
+	}
+	close(): void {
+		// Closing the transport is NOT Browser.close or Target.closeTarget on a user tab.
+		this.socket.close();
+		this.rejectPending();
+	}
+}

package/src/x-dom.d.mts

@@ -0,0 +1,7 @@
+export interface XDomDocument {
+	readonly html: string;
+	readonly title: string;
+	readonly postCount: number;
+	readonly collapsedPostIds?: readonly string[];
+}
+export function extractXDom(document: unknown, target: { readonly url: string; readonly postId?: string }, maxCharacters?: number): XDomDocument | null;

package/src/x-dom.mjs

@@ -0,0 +1,77 @@
+/** Fixed DOM reader shared by local HTML extraction and the opt-in browser. */
+export function extractXDom(document, target, maxCharacters = 1_000_000) {
+	const clean = (element) => {
+		const clone = element.cloneNode(true);
+		clone.querySelectorAll("script,style,iframe,object,embed,form,button,video,audio").forEach((el) => el.remove());
+		// X's rich-text headings contain layout divs; preserve inline markup without
+		// turning a heading into an empty Markdown heading followed by a paragraph.
+		for (const block of clone.querySelectorAll('h1 div,h1 p,h2 div,h2 p,h3 div,h3 p,h4 div,h4 p,h5 div,h5 p,h6 div,h6 p')) block.replaceWith(...block.childNodes);
+		for (const el of [clone, ...clone.querySelectorAll("*")]) {
+			for (const attr of [...el.attributes]) {
+				if (!['href', 'src', 'alt', 'title', 'class'].includes(attr.name)) el.removeAttribute(attr.name);
+			}
+			for (const attr of ['href', 'src']) {
+				const value = el.getAttribute(attr);
+				if (!value) continue;
+				try {
+					const url = new URL(value, target.url);
+					if (!['https:', 'http:'].includes(url.protocol) || url.username || url.password) el.removeAttribute(attr);
+					else el.setAttribute(attr, url.href);
+				} catch { el.removeAttribute(attr); }
+			}
+		}
+		return clone.outerHTML;
+	};
+	const bodies = document.querySelectorAll('.x-article-body, [data-testid="twitterArticleRichTextView"]');
+	if (/\/article\//.test(new URL(target.url).pathname) && bodies.length === 1 && bodies[0].textContent.trim()) {
+		const html = clean(bodies[0]);
+		if (html.length > maxCharacters) throw new Error('X article exceeds the extraction limit');
+		return { html, title: ((document.querySelector('[data-testid="twitter-article-title"]') || document.querySelector('h1'))?.textContent?.trim() || document.title || 'X Article').slice(0, 512), postCount: 1 };
+	}
+	if (!target.postId) return null;
+	const posts = [];
+	const collapsedPostIds = [];
+	let author;
+	let found = false;
+	for (const element of document.querySelectorAll('article[data-testid="tweet"]')) {
+		const stamp = element.querySelector('time');
+		const href = stamp?.closest('a')?.getAttribute('href');
+		if (!href) continue;
+		const permalink = new URL(href, target.url);
+		if (!['x.com', 'www.x.com', 'twitter.com', 'www.twitter.com'].includes(permalink.hostname) || permalink.username || permalink.password || permalink.port) continue;
+		const match = permalink.pathname.match(/^\/([A-Za-z0-9_]{1,15})\/status\/(\d{2,20})(?:\/|$)/);
+		if (!match) continue;
+		if (!found) {
+			if (match[2] !== target.postId) continue;
+			found = true;
+			author = match[1].toLowerCase();
+		} else if (match[1].toLowerCase() !== author) break;
+		const text = element.querySelector('[data-testid="tweetText"]');
+		const photos = element.querySelectorAll('[data-testid="tweetPhoto"] img');
+		const video = element.querySelector('video, [data-testid="videoPlayer"]');
+		if (!text?.textContent?.trim() && !photos.length && !video) {
+			if (!posts.length) return null;
+			break;
+		}
+		if (element.querySelector('[data-testid="tweet-text-show-more-link"]')) collapsedPostIds.push(match[2]);
+		const url = `https://x.com/${match[1]}/status/${match[2]}`;
+		const part = document.createElement('section');
+		const source = document.createElement('a');
+		source.setAttribute('href', url);
+		source.textContent = `@${match[1]} · ${stamp.getAttribute('datetime') || match[2]}`;
+		part.appendChild(source);
+		if (text) part.appendChild(text.cloneNode(true));
+		for (const photo of photos) part.appendChild(photo.cloneNode(true));
+		if (video) {
+			const notice = document.createElement('p');
+			notice.textContent = 'Video attached; media was not downloaded or transcribed.';
+			part.appendChild(notice);
+		}
+		posts.push(clean(part));
+		if (posts.length >= 100) break;
+	}
+	if (!posts.length) return null;
+	const html = posts.join('\n<hr>\n');
+	if (html.length > maxCharacters) throw new Error('X thread exceeds the extraction limit');
+	return { html, title: `@${author} on X`, postCount: posts.length, ...(collapsedPostIds.length ? { collapsedPostIds } : {}) };
+}