@f5xc-salesdemos/xcsh 19.34.1 → 19.35.2

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@f5xc-salesdemos/xcsh",
-	"version": "19.34.1",
+	"version": "19.35.2",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
 	"homepage": "https://github.com/f5xc-salesdemos/xcsh",
 	"author": "Can Boluk",
@@ -31,11 +31,11 @@
 		"xcsh": "src/cli.ts"
 	},
 	"scripts": {
-		"build": "bun run generate-build-info && bun run generate-api-spec-index && bun run generate-branding-index && bun run generate-terraform-index && test -f src/internal-urls/api-spec-index.generated.ts && bun --cwd=../stats scripts/generate-client-bundle.ts --generate && bun --cwd=../natives run embed:native && bun build --compile --define PI_COMPILED=true --external mupdf --root ../.. ./src/cli.ts --outfile dist/xcsh && bun --cwd=../natives run embed:native --reset && bun --cwd=../stats scripts/generate-client-bundle.ts --reset",
+		"build": "bun run generate-build-info && bun run generate-api-spec-index && bun run generate-branding-index && bun run generate-terraform-index && bun run generate-console-catalog && test -f src/internal-urls/api-spec-index.generated.ts && bun --cwd=../stats scripts/generate-client-bundle.ts --generate && bun --cwd=../natives run embed:native && bun build --compile --define PI_COMPILED=true --external mupdf --root ../.. ./src/cli.ts --outfile dist/xcsh && bun --cwd=../natives run embed:native --reset && bun --cwd=../stats scripts/generate-client-bundle.ts --reset",
 		"check": "biome check . && bun run format-prompts -- --check && bun run check:types",
 		"check:types": "bun run generate-build-info && bun run generate-api-spec-index && bun run generate-branding-index && bun run generate-terraform-index && tsgo -p tsconfig.json --noEmit",
 		"lint": "biome lint .",
-		"test": "bun run generate-build-info && bun run generate-api-spec-index && bun test --max-concurrency 4",
+		"test": "bun run generate-build-info && bun run generate-api-spec-index && bun run generate-console-catalog && bun test --max-concurrency 4",
 		"fix": "biome check --write --unsafe . && bun run format-prompts && bun run generate-docs-index && bun run generate-api-spec-index && bun run generate-build-info",
 		"fmt": "biome format --write . && bun run format-prompts",
 		"format-prompts": "bun scripts/format-prompts.ts",
@@ -44,19 +44,20 @@
 		"generate-branding-index": "bun scripts/generate-branding-index.ts",
 		"generate-build-info": "bun scripts/generate-build-info.ts",
 		"generate-terraform-index": "bun scripts/generate-terraform-index.ts",
-		"prepack": "bun scripts/generate-docs-index.ts && bun scripts/generate-api-spec-index.ts && bun scripts/generate-build-info.ts && bun scripts/generate-terraform-index.ts",
+		"generate-console-catalog": "bun scripts/generate-console-catalog.ts",
+		"prepack": "bun scripts/generate-docs-index.ts && bun scripts/generate-api-spec-index.ts && bun scripts/generate-build-info.ts && bun scripts/generate-terraform-index.ts && bun scripts/generate-console-catalog.ts",
 		"generate-template": "bun scripts/generate-template.ts"
 	},
 	"dependencies": {
 		"@agentclientprotocol/sdk": "0.16.1",
 		"@mozilla/readability": "^0.6",
-		"@f5xc-salesdemos/xcsh-stats": "19.34.1",
-		"@f5xc-salesdemos/pi-agent-core": "19.34.1",
-		"@f5xc-salesdemos/pi-ai": "19.34.1",
-		"@f5xc-salesdemos/pi-natives": "19.34.1",
-		"@f5xc-salesdemos/pi-resource-management": "19.34.1",
-		"@f5xc-salesdemos/pi-tui": "19.34.1",
-		"@f5xc-salesdemos/pi-utils": "19.34.1",
+		"@f5xc-salesdemos/xcsh-stats": "19.35.2",
+		"@f5xc-salesdemos/pi-agent-core": "19.35.2",
+		"@f5xc-salesdemos/pi-ai": "19.35.2",
+		"@f5xc-salesdemos/pi-natives": "19.35.2",
+		"@f5xc-salesdemos/pi-resource-management": "19.35.2",
+		"@f5xc-salesdemos/pi-tui": "19.35.2",
+		"@f5xc-salesdemos/pi-utils": "19.35.2",
 		"@sinclair/typebox": "^0.34",
 		"@xterm/headless": "^6.0",
 		"ajv": "^8.20",

package/scripts/capture-ax-fixture.ts

@@ -0,0 +1,84 @@
+#!/usr/bin/env bun
+// One-shot capture: login + open the HTTP-LB create form + snapshot the accessibility tree.
+// Creds via env (KC_USER/KC_PASS); never hard-coded. Output is the resolver's test oracle.
+import puppeteer from "puppeteer";
+
+const CHROME = process.env.CHROME_PATH;
+const BASE = process.env.F5XC_CONSOLE_URL ?? "https://nferreira.staging.volterra.us";
+const NS = process.env.F5XC_NS ?? "demo";
+const OUT = "test/browser/fixtures/xc-http-lb-create.ax.json";
+
+const browser = await puppeteer.launch({
+	headless: true,
+	executablePath: CHROME,
+	userDataDir: "/tmp/xc-ax-capture",
+});
+try {
+	const page = (await browser.pages())[0] ?? (await browser.newPage());
+	await page.goto(BASE, { waitUntil: "networkidle2", timeout: 45000 }).catch(() => {});
+	if (/login-staging\.volterra\.us/.test(page.url())) {
+		await page.waitForSelector("#username", { timeout: 20000 });
+		await page.type("#username", process.env.KC_USER ?? "");
+		await page.type("#password", process.env.KC_PASS ?? "");
+		await Promise.all([
+			page.waitForNavigation({ waitUntil: "networkidle2", timeout: 45000 }).catch(() => {}),
+			page.click("#kc-login").catch(() => page.keyboard.press("Enter")),
+		]);
+		await new Promise(r => setTimeout(r, 4000));
+	}
+	const route = `/web/workspaces/web-app-and-api-protection/namespaces/${NS}/manage/load_balancers/http_loadbalancers`;
+	await page.goto(`${BASE}${route}`, { waitUntil: "networkidle2", timeout: 45000 });
+	await new Promise(r => setTimeout(r, 4000));
+	// open the create form: click the "Add HTTP Load Balancer" tab via its resolved handle
+	{
+		const h = (await page.$("aria/Add HTTP Load Balancer")) ?? (await page.$("text/Add HTTP Load Balancer"));
+		if (!h) {
+			console.log("could not resolve the Add tab handle");
+		} else {
+			await h.click().catch(async () => {
+				await h.evaluate(el => (el as { click(): void }).click()).catch(() => {});
+			});
+			await h.dispose();
+		}
+	}
+	// wait until the create form's Name textbox is present in the AX tree (form actually open)
+	let opened = false;
+	for (let i = 0; i < 40; i++) {
+		await new Promise(r => setTimeout(r, 1000));
+		const s = await page.accessibility.snapshot({ interestingOnly: false });
+		const hasName = (function find(n: { role?: string; name?: string; children?: unknown[] }): boolean {
+			if (n.role === "textbox" && (n.name ?? "").trim() === "Name") return true;
+			return (n.children ?? []).some(c => find(c as never));
+		})((s ?? {}) as never);
+		if (hasName) {
+			opened = true;
+			break;
+		}
+	}
+	console.log("create form opened (Name textbox present):", opened, "url=", page.url().slice(0, 110));
+	const snap = await page.accessibility.snapshot({ interestingOnly: false });
+	if (!snap) throw new Error("accessibility snapshot was null");
+	await Bun.write(OUT, JSON.stringify(snap, null, 2));
+	// also capture the create-form DOM root (for DOM-structural context-scoping tests)
+	const HTML_OUT = "test/browser/fixtures/xc-http-lb-create.html";
+	const formHtml = await page.evaluate(() => {
+		const d = (
+			globalThis as unknown as {
+				document: { querySelector(s: string): { outerHTML: string } | null; body: { outerHTML: string } };
+			}
+		).document;
+		const root = d.querySelector('[role="main"], main, .ant-drawer-body, .ant-modal-body') ?? d.body;
+		return root.outerHTML;
+	});
+	await Bun.write(HTML_OUT, formHtml);
+	console.log(`wrote ${HTML_OUT} (${formHtml.length} bytes)`);
+	const json = JSON.stringify(snap);
+	const roleCount = (role: string) => (json.match(new RegExp(`"role":"${role}"`, "g")) ?? []).length;
+	console.log(`wrote ${OUT} (${json.length} bytes)`);
+	console.log(`url=${page.url().slice(0, 90)}`);
+	console.log(
+		`roles: tab=${roleCount("tab")} textbox=${roleCount("textbox")} button=${roleCount("button")} listbox=${roleCount("listbox")}`,
+	);
+} finally {
+	await browser.close().catch(() => {});
+}

package/scripts/generate-console-catalog.ts

@@ -0,0 +1,88 @@
+#!/usr/bin/env bun
+// scripts/generate-console-catalog.ts
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+const repoRoot = path.resolve(import.meta.dir, "..");
+const outputPath = path.join(repoRoot, "src/internal-urls/console-catalog.generated.ts");
+
+function resolveCatalogRoot(): string | null {
+	const fromEnv = process.env.CONSOLE_CATALOG_DIR;
+	if (fromEnv && fs.existsSync(path.join(fromEnv, "catalog"))) return fromEnv;
+	// Local sibling checkout: <workspace>/console
+	const sibling = path.resolve(repoRoot, "../../../console");
+	if (fs.existsSync(path.join(sibling, "catalog"))) return sibling;
+	// TODO(P2): add release-artifact download mirroring generate-api-spec-index.ts.
+	return null;
+}
+
+function readYamlDir(dir: string, keyFn: (rel: string) => string): Record<string, string> {
+	const out: Record<string, string> = {};
+	if (!fs.existsSync(dir)) return out;
+	const walk = (d: string) => {
+		for (const entry of fs.readdirSync(d, { withFileTypes: true })) {
+			const full = path.join(d, entry.name);
+			if (entry.isDirectory()) walk(full);
+			else if (entry.name.endsWith(".yaml")) {
+				const rel = path.relative(dir, full).replace(/\.yaml$/, "");
+				out[keyFn(rel)] = fs.readFileSync(full, "utf-8");
+			}
+		}
+	};
+	walk(dir);
+	// Sort keys for deterministic output regardless of readdir order.
+	return Object.fromEntries(
+		Object.keys(out)
+			.sort()
+			.map(k => [k, out[k]]),
+	);
+}
+
+function build(): {
+	version: string;
+	workflows: Record<string, string>;
+	resources: Record<string, string>;
+	routes: Record<string, string>;
+	navigation: string | null;
+} {
+	const root = resolveCatalogRoot();
+	if (!root) {
+		console.warn("console catalogue source not found; emitting empty catalogue");
+		return { version: "unavailable", workflows: {}, resources: {}, routes: {}, navigation: null };
+	}
+	const catalog = path.join(root, "catalog");
+	// workflows keyed "<resource>/<operation>" (directory/file)
+	const workflows = readYamlDir(path.join(catalog, "workflows"), rel => rel.split(path.sep).join("/"));
+	// resources/routes keyed by basename id
+	const resources = readYamlDir(path.join(catalog, "resources"), rel => path.basename(rel));
+	const routes = readYamlDir(path.join(catalog, "routes"), rel => path.basename(rel));
+	const navPath = path.join(catalog, "navigation/console-tree.yaml");
+	const navigation = fs.existsSync(navPath) ? fs.readFileSync(navPath, "utf-8") : null;
+	const version = process.env.CONSOLE_CATALOG_VERSION ?? "local";
+	return { version, workflows, resources, routes, navigation };
+}
+
+const data = build();
+
+// Fix A: when the source was not found AND the output file already exists,
+// keep the committed catalogue rather than overwriting it with empty data.
+if (data.version === "unavailable" && fs.existsSync(outputPath)) {
+	console.log("console catalogue source not found; keeping existing generated module");
+	process.exit(0);
+}
+
+const output = [
+	"// Auto-generated by scripts/generate-console-catalog.ts - DO NOT EDIT",
+	"",
+	`import type { ConsoleCatalogData } from "./console-catalog-types";`,
+	"",
+	`export const CONSOLE_CATALOG_VERSION = ${JSON.stringify(data.version)};`,
+	"",
+	`export const CONSOLE_CATALOG_DATA: ConsoleCatalogData = ${JSON.stringify(data, null, 2)};`,
+	"",
+].join("\n");
+
+await Bun.write(outputPath, output);
+console.log(
+	`Wrote ${outputPath} (workflows=${Object.keys(data.workflows).length}, resources=${Object.keys(data.resources).length})`,
+);

package/scripts/generate-terraform-index.ts

@@ -38,6 +38,30 @@ async function loadTerraformIndex(): Promise<unknown> {
 	return response.json();
 }
 
+// Backfill provider fields that older terraform-llms-index.json revisions lack, so the
+// generated index always satisfies TerraformProvider regardless of which provider-repo
+// revision it was fetched from (the source repo is the authority once it ships them).
+const DEFAULT_CONFIG_BLOCK = 'provider "f5xc" {}';
+const DEFAULT_AUTH_METHODS = [
+	'REQUIRED: every .tf must contain a `provider "f5xc" {}` block. Without it Terraform errors: "Provider requires explicit configuration. Add a provider block".',
+	"Configure exactly ONE auth method, via environment variables (preferred) or explicit arguments in the provider block:",
+	"api_token (env F5XC_API_TOKEN) — API token authentication.",
+	"api_p12_file + p12_password (env F5XC_P12_FILE + F5XC_P12_PASSWORD) — PKCS#12 certificate authentication.",
+	"api_cert + api_key (env F5XC_CERT + F5XC_KEY) — PEM certificate authentication.",
+	"api_url (env F5XC_API_URL) — tenant base URL without /api suffix, e.g. https://your-tenant.console.ves.volterra.io.",
+];
+
+function normalizeProvider(data: unknown): unknown {
+	if (data && typeof data === "object" && "provider" in data) {
+		const provider = (data as { provider: Record<string, unknown> }).provider;
+		if (provider && typeof provider === "object") {
+			if (typeof provider.config_block !== "string") provider.config_block = DEFAULT_CONFIG_BLOCK;
+			if (!Array.isArray(provider.auth_methods)) provider.auth_methods = DEFAULT_AUTH_METHODS;
+		}
+	}
+	return data;
+}
+
 function generateTypeScript(data: unknown): string {
 	const lines = [
 		"// AUTO-GENERATED — do not edit. Run `bun generate-terraform-index` to regenerate.",
@@ -50,7 +74,7 @@ function generateTypeScript(data: unknown): string {
 	return lines.join("\n");
 }
 
-const data = await loadTerraformIndex();
+const data = normalizeProvider(await loadTerraformIndex());
 const output = generateTypeScript(data);
 await fs.writeFile(OUTPUT_FILE, output, "utf-8");
 await Bun.$`bunx biome format --write ${OUTPUT_FILE}`.quiet();

package/src/browser/actions.ts

@@ -0,0 +1,126 @@
+import type { Page } from "puppeteer";
+import { commitInputValue } from "./input-commit";
+import { resolve } from "./resolver";
+
+/** Delay after a fill to let blur-triggered framework revalidation complete. */
+const SETTLE_AFTER_FILL_MS = 600;
+
+/** Resolve after `ms` milliseconds (a small, explicit settle for SPA timing). */
+function settle(ms: number): Promise<void> {
+	return new Promise(resolveSettle => setTimeout(resolveSettle, ms));
+}
+
+/** XC-SPA-aware: wait until the console's loading/spinner indicators clear. */
+export async function waitForXcSettled(page: Page, timeoutMs = 15000): Promise<void> {
+	const start = Date.now();
+	while (Date.now() - start < timeoutMs) {
+		const busy = await page
+			.evaluate((): boolean => {
+				const sel = '[aria-busy="true"], .ant-spin-spinning, [role="progressbar"], .loading-indicator';
+				const doc = (globalThis as unknown as { document: { querySelector(s: string): unknown } }).document;
+				return doc.querySelector(sel) != null;
+			})
+			.catch(() => false);
+		if (!busy) return;
+		await Bun.sleep(150);
+	}
+}
+
+async function withRetry<T>(fn: () => Promise<T>, timeoutMs = 15000): Promise<T> {
+	const start = Date.now();
+	let last: unknown;
+	while (Date.now() - start < timeoutMs) {
+		try {
+			return await fn();
+		} catch (e) {
+			last = e;
+			await Bun.sleep(150);
+		}
+	}
+	throw last instanceof Error ? last : new Error(String(last));
+}
+
+export async function click(page: Page, selector: string, context?: string): Promise<void> {
+	await waitForXcSettled(page);
+	await withRetry(async () => {
+		const h = await resolve(page, selector, context);
+		try {
+			await h.scrollIntoView().catch(() => {});
+			try {
+				await h.click();
+			} catch {
+				// sticky/offscreen elements: synthetic DOM click fallback
+				await h.evaluate(el => (el as unknown as { click(): void }).click());
+			}
+		} finally {
+			await h.dispose().catch(() => {});
+		}
+	});
+}
+
+export async function fill(page: Page, selector: string, value: string, context?: string): Promise<void> {
+	await waitForXcSettled(page);
+	await withRetry(async () => {
+		const h = await resolve(page, selector, context);
+		try {
+			await h.focus().catch(() => {});
+			// Set the value through the native value setter + framework events
+			// (input/change/blur/focusout). This replaces any existing value and is
+			// the robust path for framework-bound controls — including the console's
+			// vsui-input over ngx-datatable, whose patched value descriptor swallows
+			// plain keystrokes so they never reach the Angular model. (Use the `type`
+			// action for fields that must observe individual keystrokes.)
+			await h.evaluate(commitInputValue, value);
+		} finally {
+			await h.dispose().catch(() => {});
+		}
+	});
+	// Let the framework's blur-triggered revalidation run before the next action
+	// (Angular `updateOn: 'blur'` controls update validity asynchronously, so an
+	// immediate Save would otherwise still see the field as invalid).
+	await settle(SETTLE_AFTER_FILL_MS);
+}
+
+export async function selectOption(page: Page, selector: string, value: string, context?: string): Promise<void> {
+	await click(page, selector, context); // open the listbox/combobox
+	await click(page, `option:text('${value}')`); // pick the option by role+name
+}
+
+export async function scrollIntoView(page: Page, selector: string, context?: string): Promise<void> {
+	await waitForXcSettled(page);
+	const h = await resolve(page, selector, context);
+	try {
+		await h.scrollIntoView();
+	} finally {
+		await h.dispose().catch(() => {});
+	}
+}
+
+export async function pressKey(page: Page, key: string): Promise<void> {
+	await page.keyboard.press(key as Parameters<Page["keyboard"]["press"]>[0]);
+}
+
+export async function assertText(page: Page, selector: string, expected: string, context?: string): Promise<void> {
+	await waitForXcSettled(page);
+	const h = await resolve(page, selector, context);
+	try {
+		const txt = (await h.evaluate(el => (el as unknown as { innerText: string }).innerText)) as string;
+		if (!txt.includes(expected)) throw new Error(`assert failed: "${expected}" not in "${txt.slice(0, 200)}"`);
+	} finally {
+		await h.dispose().catch(() => {});
+	}
+}
+
+export async function waitFor(page: Page, selector: string, context?: string, timeoutMs = 30000): Promise<void> {
+	await withRetry(async () => {
+		const h = await resolve(page, selector, context);
+		await h.dispose().catch(() => {});
+	}, timeoutMs);
+}
+
+export async function screenshot(page: Page, file: string): Promise<void> {
+	if (!file.endsWith(".png") || file.includes("..") || file.includes("\0")) {
+		throw new Error(`Invalid screenshot path: ${file}`);
+	}
+	await page.screenshot({ path: file as `${string}.png`, type: "png" });
+}

package/src/browser/ax.ts

@@ -0,0 +1,134 @@
+import type { Locator } from "./selector";
+
+export interface AxNode {
+	role: string;
+	name?: string;
+	children?: AxNode[];
+	[k: string]: unknown;
+}
+
+export class NotFoundError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = "NotFoundError";
+	}
+}
+
+export class AmbiguousError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = "AmbiguousError";
+	}
+}
+
+function norm(s: string): string {
+	return s.trim().replace(/\s+/g, " ");
+}
+
+function collect(node: AxNode, results: AxNode[]): void {
+	results.push(node);
+	for (const child of node.children ?? []) {
+		collect(child, results);
+	}
+}
+
+export function matchNode(tree: AxNode, loc: Locator): AxNode {
+	if (loc.kind === "css") {
+		throw new Error("css locators cannot be resolved against an AX tree — resolve live via CDP");
+	}
+
+	const all: AxNode[] = [];
+	collect(tree, all);
+
+	let matches: AxNode[];
+
+	if (loc.kind === "roleName") {
+		const wantRole = loc.role;
+		const wantName = norm(loc.name);
+		matches = all.filter(n => {
+			if (n.role !== wantRole) return false;
+			const nodeName = norm(n.name ?? "");
+			// roleName from role:text('X') pattern — text match (includes)
+			// roleName from role[name='X'] pattern — exact match
+			// We always use exact match for roleName kind (the parser normalises both patterns to roleName)
+			return nodeName === wantName;
+		});
+	} else if (loc.kind === "role") {
+		matches = all.filter(n => n.role === loc.role);
+	} else {
+		// kind === "text"
+		const want = norm(loc.text);
+		matches = all.filter(n => {
+			const nodeName = norm(n.name ?? "");
+			return nodeName === want || nodeName.includes(want);
+		});
+	}
+
+	if (matches.length === 0) {
+		// Collect candidates for helpful error message
+		let hint = "";
+		if (loc.kind === "roleName" || loc.kind === "role") {
+			const sameRole = all.filter(n => n.role === loc.role && n.name).map(n => JSON.stringify(n.name));
+			if (sameRole.length > 0) {
+				hint = ` (same-role candidates: ${sameRole.slice(0, 5).join(", ")})`;
+			}
+		} else if (loc.kind === "text") {
+			// For text kind, list nearby text candidates (non-empty normalized names)
+			const textCandidates: string[] = [];
+			const seen = new Set<string>();
+			for (const node of all) {
+				if (node.name) {
+					const normalized = norm(node.name);
+					if (normalized.length > 0 && !seen.has(normalized)) {
+						seen.add(normalized);
+						textCandidates.push(JSON.stringify(normalized));
+						if (textCandidates.length >= 5) break;
+					}
+				}
+			}
+			if (textCandidates.length > 0) {
+				hint = ` (nearby text candidates: ${textCandidates.join(", ")})`;
+			}
+		}
+		throw new NotFoundError(`No AX node found for ${JSON.stringify(loc)}${hint}`);
+	}
+
+	// For text locators, return the first match (presence semantics).
+	// For roleName and role, enforce strict 1:1 matching.
+	if (loc.kind === "text") {
+		return matches[0]!;
+	}
+
+	if (matches.length > 1) {
+		const names = matches.map(n => JSON.stringify(n.name ?? n.role));
+		throw new AmbiguousError(
+			`${matches.length} AX nodes match ${JSON.stringify(loc)}: ${names.slice(0, 5).join(", ")}`,
+		);
+	}
+
+	return matches[0]!;
+}
+
+export function matchNodes(tree: AxNode, loc: Locator): AxNode[] {
+	if (loc.kind === "css") {
+		throw new Error("css locators cannot be resolved against an AX tree — resolve live via CDP");
+	}
+
+	const all: AxNode[] = [];
+	collect(tree, all);
+
+	if (loc.kind === "roleName") {
+		const wantRole = loc.role;
+		const wantName = norm(loc.name);
+		return all.filter(n => n.role === wantRole && norm(n.name ?? "") === wantName);
+	} else if (loc.kind === "role") {
+		return all.filter(n => n.role === loc.role);
+	} else {
+		// kind === "text"
+		const want = norm(loc.text);
+		return all.filter(n => {
+			const nodeName = norm(n.name ?? "");
+			return nodeName === want || nodeName.includes(want);
+		});
+	}
+}

package/src/browser/cdp-core.ts

@@ -0,0 +1,48 @@
+import type { Browser, CDPSession, Page } from "puppeteer";
+import { assertLoopbackBrowserUrl, pickCoDrivePage, resolveBrowserConnectUrl } from "../tools/browser";
+
+type Settings = { get(key: string): unknown };
+
+export class BrowserSession {
+	#browser: Browser | null = null;
+	#page: Page | null = null;
+	#cdp: CDPSession | null = null;
+	#attached = false;
+	constructor(private readonly settings: Settings) {}
+
+	async ensurePage(): Promise<Page> {
+		if (this.#page && !this.#page.isClosed()) return this.#page;
+		const puppeteer = (await import("puppeteer")).default;
+		const connectUrl = resolveBrowserConnectUrl(this.settings);
+		if (connectUrl) {
+			assertLoopbackBrowserUrl(connectUrl);
+			this.#browser = await puppeteer.connect({ browserURL: connectUrl });
+			this.#attached = true;
+			const pages = await this.#browser.pages();
+			this.#page = pages.length ? pages[pickCoDrivePage(pages)]! : await this.#browser.newPage();
+		} else {
+			this.#browser = await puppeteer.launch({ headless: !!this.settings.get("browser.headless") });
+			this.#attached = false;
+			this.#page = await this.#browser.newPage();
+		}
+		this.#cdp = null;
+		return this.#page;
+	}
+
+	async cdp(): Promise<CDPSession> {
+		const page = await this.ensurePage();
+		if (!this.#cdp) this.#cdp = await page.createCDPSession();
+		return this.#cdp;
+	}
+
+	async close(): Promise<void> {
+		if (this.#browser) {
+			if (this.#attached) await this.#browser.disconnect();
+			else await this.#browser.close();
+		}
+		this.#browser = null;
+		this.#page = null;
+		this.#cdp = null;
+		this.#attached = false;
+	}
+}

package/src/browser/dom-context.ts

@@ -0,0 +1,89 @@
+/**
+ * DOM context scoping for XC component classes.
+ * Pure module — no Puppeteer imports. Works under linkedom in tests and
+ * the live document in page.evaluate in the resolver (Task 5).
+ *
+ * We define minimal structural interfaces instead of relying on the DOM lib
+ * (the project tsconfig does not include DOM types globally).
+ */
+
+/** Minimal structural interface matching both linkedom and browser Element. */
+export interface DomElement {
+	tagName: string;
+	textContent: string | null;
+	className: string | { toString(): string };
+	parentElement: DomElement | null;
+	querySelector(sel: string): DomElement | null;
+	querySelectorAll(sel: string): ArrayLike<DomElement>;
+}
+
+/** Minimal structural interface matching both linkedom and browser Document. */
+export interface DomDocument {
+	body: DomElement | null;
+	documentElement: DomElement;
+	querySelectorAll(sel: string): ArrayLike<DomElement>;
+}
+
+/** Strip a leading asterisk, trim, and collapse internal whitespace. */
+export function normLabel(s: string): string {
+	return s.trim().replace(/^\*/, "").trim().replace(/\s+/g, " ");
+}
+
+/** Suffixes we strip before matching a label phrase. */
+export const STRIP_SUFFIX = / (?:section|table|table row|selector)$/i;
+
+/** CSS selectors that identify XC field/section labels. */
+export const LABEL_SELECTORS = [
+	"label.ves-label_level_3_label",
+	"label[class*='ves-label_level_3_label']",
+	".datatable-header-cell-label",
+	".tile-header__name",
+	"label.form-control-label",
+];
+
+/** CSS that identifies "interactive" controls — presence means the ancestor is the section container. */
+export const CONTROL_SELECTOR = "button, [role='listbox'], .listbox, input";
+
+/**
+ * Find the nearest ancestor element that:
+ *   1. Is an ancestor of the matched label element, AND
+ *   2. Contains at least one interactive control (button / listbox / input).
+ *
+ * Walk up from the label, stopping at `document.body` (or `documentElement`).
+ */
+export function findControlBearingAncestor(label: DomElement, doc: DomDocument): DomElement | null {
+	const body = doc.body ?? doc.documentElement;
+	let current: DomElement | null = label.parentElement;
+	while (current && current !== body) {
+		if (current.querySelector(CONTROL_SELECTOR)) {
+			return current;
+		}
+		current = current.parentElement;
+	}
+	return null;
+}
+
+/**
+ * Given a phrase like "Domains table" or "Origin Pools section",
+ * strip the trailing qualifier, find the matching label element in the DOM,
+ * then return the nearest ancestor that contains an interactive control.
+ *
+ * Returns `null` if no label or no control-bearing ancestor is found.
+ */
+export function findSectionContainer(doc: DomDocument, phrase: string): DomElement | null {
+	const bare = phrase.replace(STRIP_SUFFIX, "").trim();
+	const want = normLabel(bare);
+
+	// Try each label selector in priority order
+	for (const sel of LABEL_SELECTORS) {
+		const candidates = Array.from(doc.querySelectorAll(sel));
+		for (const el of candidates) {
+			if (normLabel(el.textContent ?? "") === want) {
+				const container = findControlBearingAncestor(el, doc);
+				if (container) return container;
+			}
+		}
+	}
+
+	return null;
+}