@skaft/hamr 0.4.1

package/examples/extensions/hamr-browser/index.ts

@@ -0,0 +1,264 @@
+import { Type } from "typebox";
+import { getBrowserDepsDir, getBrowserDepsInstallCommand, loadInstalledPlaywright } from "./src/deps.ts";
+
+type ToolContent = { type: "text"; text: string };
+type ToolResult = { content: ToolContent[]; details?: Record<string, unknown> };
+type ToolUpdate = (result: ToolResult) => void;
+type BrowserUi = {
+	notify(message: string, level: "info" | "warning" | "error"): void;
+	confirm?(title: string, message: string): Promise<boolean>;
+};
+type ToolContext = { hasUI?: boolean; ui: BrowserUi };
+type ToolDefinition = {
+	name: string;
+	label: string;
+	description: string;
+	promptSnippet?: string;
+	promptGuidelines?: string[];
+	parameters: unknown;
+	execute(
+		toolCallId: string,
+		params: any,
+		signal: AbortSignal | undefined,
+		onUpdate: ToolUpdate | undefined,
+		ctx: ToolContext,
+	): Promise<ToolResult> | ToolResult;
+};
+type CommandContext = { hasUI?: boolean; ui: BrowserUi };
+type ExtensionAPI = {
+	registerCommand(
+		name: string,
+		options: { description?: string; handler(args: string, ctx: CommandContext): Promise<void> | void },
+	): void;
+	registerTool(definition: ToolDefinition): void;
+	on(event: "session_shutdown", handler: () => Promise<void> | void): void;
+	exec(
+		command: string,
+		args: string[],
+		options?: { signal?: AbortSignal; timeout?: number },
+	): Promise<{ code: number | null; stdout: string; stderr: string }>;
+};
+import { HamrBrowserController } from "./src/browser-controller.ts";
+
+const controller = new HamrBrowserController();
+
+function textResult(text: string, details: Record<string, unknown> = {}) {
+	return {
+		content: [{ type: "text" as const, text }],
+		details,
+	};
+}
+
+function checkAbort(signal: AbortSignal | undefined): void {
+	if (signal?.aborted) {
+		throw new Error("Cancelled");
+	}
+}
+
+function shellQuote(value: string): string {
+	return /[\s"']/.test(value) ? JSON.stringify(value) : value;
+}
+
+export default function hamrBrowserExtension(hamr: ExtensionAPI) {
+	async function ensureBrowserDependencies(
+		ctx: ToolContext | CommandContext,
+		signal?: AbortSignal,
+		onUpdate?: ToolUpdate,
+	): Promise<void> {
+		if (loadInstalledPlaywright()) return;
+
+		const depsDir = getBrowserDepsDir();
+		const installCommand = getBrowserDepsInstallCommand(depsDir);
+		const displayCommand = installCommand.map(shellQuote).join(" ");
+		const message = `Hamr Browser needs Playwright before it can open a browser. Install it into ${depsDir}?\n\nCommand: ${displayCommand}`;
+		if (!ctx.hasUI || !ctx.ui.confirm) {
+			throw new Error(`Playwright is not installed. Run: ${displayCommand}`);
+		}
+
+		const ok = await ctx.ui.confirm("Install Hamr Browser dependencies?", message);
+		if (!ok) {
+			throw new Error("Hamr Browser dependency install cancelled");
+		}
+
+		onUpdate?.(textResult(`Installing Hamr Browser dependencies with: ${displayCommand}`, { depsDir }));
+		const [command, ...args] = installCommand;
+		const result = await hamr.exec(command, args, { signal, timeout: 10 * 60 * 1000 });
+		if (result.code !== 0) {
+			const detail = (result.stderr || result.stdout || `exit code ${result.code}`).trim().split("\n").slice(-1)[0];
+			throw new Error(`Failed to install Playwright: ${detail}`);
+		}
+		if (!loadInstalledPlaywright()) {
+			throw new Error(`Playwright install finished, but module was not found in ${depsDir}`);
+		}
+	}
+
+	hamr.registerCommand("browser", {
+		description: "Launch the isolated visible Hamr Browser window",
+		handler: async (args, ctx) => {
+			const url = args.trim() || undefined;
+			const message = await controller.launch({ url, ensureDependencies: () => ensureBrowserDependencies(ctx) });
+			ctx.ui.notify(message, "info");
+		},
+	});
+
+	hamr.registerTool({
+		name: "browser_launch",
+		label: "Browser Launch",
+		description: "Launch Hamr's isolated visible browser window. Does not use the user's normal browser profile.",
+		promptSnippet: "Launch Hamr's isolated visible browser window",
+		promptGuidelines: [
+			"Use browser_launch before other browser tools when a visible Hamr-controlled browser is needed.",
+			"Hamr Browser uses an isolated profile; do not claim it has access to the user's normal browser session.",
+		],
+		parameters: Type.Object({
+			url: Type.Optional(Type.String({ description: "Optional http, https, or file URL to open after launch" })),
+		}),
+		async execute(_toolCallId, params, signal, onUpdate, ctx) {
+			checkAbort(signal);
+			const message = await controller.launch({
+				url: params.url,
+				ensureDependencies: () => ensureBrowserDependencies(ctx, signal, onUpdate),
+			});
+			if (ctx.hasUI) ctx.ui.notify(message, "info");
+			return textResult(message, { ...controller.getState() });
+		},
+	});
+
+	hamr.registerTool({
+		name: "browser_open_url",
+		label: "Browser Open URL",
+		description: "Open a URL in Hamr Browser. Launches the isolated visible browser if needed.",
+		promptSnippet: "Open a URL in Hamr Browser",
+		parameters: Type.Object({
+			url: Type.String({ description: "http, https, or file URL to open" }),
+		}),
+		async execute(_toolCallId, params, signal, onUpdate, ctx) {
+			checkAbort(signal);
+			return textResult(await controller.openUrl(params.url, () => ensureBrowserDependencies(ctx, signal, onUpdate)), {
+				url: params.url,
+			});
+		},
+	});
+
+	hamr.registerTool({
+		name: "browser_snapshot",
+		label: "Browser Snapshot",
+		description: "Return cheap text, DOM, and accessibility-ish state for the current Hamr Browser page.",
+		promptSnippet: "Snapshot current Hamr Browser page text and interactive elements",
+		parameters: Type.Object({}),
+		async execute(_toolCallId, _params, signal, onUpdate, ctx) {
+			checkAbort(signal);
+			await controller.launch({ ensureDependencies: () => ensureBrowserDependencies(ctx, signal, onUpdate) });
+			const snapshot = await controller.snapshot();
+			return textResult(snapshot, { chars: snapshot.length });
+		},
+	});
+
+	hamr.registerTool({
+		name: "browser_click",
+		label: "Browser Click",
+		description: "Click a target in Hamr Browser. Targets can be css=selector, text=label, role=button:Name, or plain visible text.",
+		promptSnippet: "Click a target in Hamr Browser",
+		parameters: Type.Object({
+			target: Type.String({ description: "css=selector, text=label, role=button:Name, CSS selector, or visible text" }),
+		}),
+		async execute(_toolCallId, params, signal, onUpdate, ctx) {
+			checkAbort(signal);
+			await controller.launch({ ensureDependencies: () => ensureBrowserDependencies(ctx, signal, onUpdate) });
+			return textResult(await controller.click(params.target), { target: params.target });
+		},
+	});
+
+	hamr.registerTool({
+		name: "browser_type",
+		label: "Browser Type",
+		description: "Fill or type text into a target in Hamr Browser. Targets can be css=selector, text=label, role=textbox:Name, or plain visible text.",
+		promptSnippet: "Type text into a target in Hamr Browser",
+		parameters: Type.Object({
+			target: Type.String({ description: "css=selector, text=label, role=textbox:Name, CSS selector, or visible text" }),
+			text: Type.String({ description: "Text to enter" }),
+		}),
+		async execute(_toolCallId, params, signal, onUpdate, ctx) {
+			checkAbort(signal);
+			await controller.launch({ ensureDependencies: () => ensureBrowserDependencies(ctx, signal, onUpdate) });
+			return textResult(await controller.type(params.target, params.text), { target: params.target });
+		},
+	});
+
+	hamr.registerTool({
+		name: "browser_press",
+		label: "Browser Press",
+		description: "Press a keyboard key in Hamr Browser, such as Enter, Escape, Tab, or Meta+L.",
+		promptSnippet: "Press a key in Hamr Browser",
+		parameters: Type.Object({
+			key: Type.String({ description: "Playwright key name or shortcut, e.g. Enter, Tab, Escape, Meta+L" }),
+		}),
+		async execute(_toolCallId, params, signal, onUpdate, ctx) {
+			checkAbort(signal);
+			await controller.launch({ ensureDependencies: () => ensureBrowserDependencies(ctx, signal, onUpdate) });
+			return textResult(await controller.press(params.key), { key: params.key });
+		},
+	});
+
+	hamr.registerTool({
+		name: "browser_scroll",
+		label: "Browser Scroll",
+		description: "Scroll Hamr Browser by direction (up/down/left/right) or a numeric pixel count.",
+		promptSnippet: "Scroll the current Hamr Browser page",
+		parameters: Type.Object({
+			direction_or_pixels: Type.String({ description: "up, down, left, right, or a pixel count like 800 or -300" }),
+		}),
+		async execute(_toolCallId, params, signal, onUpdate, ctx) {
+			checkAbort(signal);
+			await controller.launch({ ensureDependencies: () => ensureBrowserDependencies(ctx, signal, onUpdate) });
+			return textResult(await controller.scroll(params.direction_or_pixels), {
+				direction_or_pixels: params.direction_or_pixels,
+			});
+		},
+	});
+
+	hamr.registerTool({
+		name: "browser_wait",
+		label: "Browser Wait",
+		description: "Wait in Hamr Browser for the given milliseconds, capped at 60000ms.",
+		promptSnippet: "Wait for page activity in Hamr Browser",
+		parameters: Type.Object({
+			ms: Type.Number({ description: "Milliseconds to wait, capped at 60000" }),
+		}),
+		async execute(_toolCallId, params, signal, onUpdate, ctx) {
+			checkAbort(signal);
+			await controller.launch({ ensureDependencies: () => ensureBrowserDependencies(ctx, signal, onUpdate) });
+			return textResult(await controller.wait(params.ms), { ms: params.ms });
+		},
+	});
+
+	hamr.registerTool({
+		name: "browser_screenshot",
+		label: "Browser Screenshot",
+		description: "Save a full-page screenshot artifact from Hamr Browser and return the file path.",
+		promptSnippet: "Save a Hamr Browser screenshot artifact",
+		parameters: Type.Object({}),
+		async execute(_toolCallId, _params, signal, onUpdate, ctx) {
+			checkAbort(signal);
+			await controller.launch({ ensureDependencies: () => ensureBrowserDependencies(ctx, signal, onUpdate) });
+			const path = await controller.screenshot();
+			return textResult(`Saved screenshot: ${path}`, { path });
+		},
+	});
+
+	hamr.registerTool({
+		name: "browser_close",
+		label: "Browser Close",
+		description: "Close Hamr Browser and release its Playwright context.",
+		promptSnippet: "Close Hamr Browser",
+		parameters: Type.Object({}),
+		async execute(_toolCallId, _params, signal) {
+			checkAbort(signal);
+			return textResult(await controller.close());
+		},
+	});
+
+	hamr.on("session_shutdown", async () => {
+		await controller.close();
+	});
+}

package/examples/extensions/hamr-browser/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@hamr/browser-extension",
+  "private": true,
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Hamr Browser extension: an isolated visible browser controlled by Hamr tools",
+  "scripts": {
+    "build": "tsc --noEmit",
+    "test": "vitest --run"
+  },
+  "hamr": {
+    "extensions": ["./index.ts"],
+    "skills": ["./skills"]
+  },
+  "dependencies": {
+    "playwright": "^1.57.0",
+    "typebox": "1.1.38"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.9.0",
+    "vitest": "^3.2.4"
+  },
+  "keywords": ["hamr-package", "hamr", "browser", "playwright"]
+}

package/examples/extensions/hamr-browser/skills/hamr-browser.md

@@ -0,0 +1,25 @@
+---
+name: hamr-browser
+description: Use when the user wants Hamr to visibly control an isolated browser for demos, web navigation, screenshots, or page interaction.
+---
+
+# Hamr Browser
+
+Use Hamr Browser tools to control the isolated visible browser profile owned by Hamr.
+
+If browser dependencies are missing, `browser_launch` or another browser tool will ask the user before installing Playwright into Hamr's user data directory.
+
+## Rules
+
+- Start with `browser_launch` or `browser_open_url`.
+- Use `browser_snapshot` before deciding what to click or type.
+- Prefer robust targets:
+  - `css=#id` or `css=[name="q"]` when known.
+  - `role=button:Submit` for accessible controls.
+  - `text=Continue` or plain visible text for demos.
+- Use `browser_screenshot` when the user asks for a visual artifact.
+- Use `browser_close` when done.
+
+## Safety
+
+Hamr Browser uses an isolated Hamr-owned profile. Do not claim it controls or reads the user's normal browser profile.

package/examples/extensions/hamr-browser/src/browser-controller.ts

@@ -0,0 +1,206 @@
+import { mkdir } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import type { BrowserContext, Page } from "playwright";
+import { loadInstalledPlaywright } from "./deps.ts";
+import { getDefaultBrowserProfileDir, getDefaultScreenshotDir } from "./paths.ts";
+import { buildBrowserSnapshot } from "./snapshot.ts";
+import { locatorForTarget, normalizeScrollAmount } from "./targeting.ts";
+
+export interface BrowserState {
+	profileDir: string;
+	screenshotDir: string;
+	channel?: string;
+	headless: boolean;
+}
+
+export interface BrowserLaunchOptions {
+	url?: string;
+	ensureDependencies?: () => Promise<void>;
+}
+
+function conciseError(error: unknown, fallback: string): Error {
+	if (error instanceof Error && error.message.trim()) {
+		return new Error(error.message.split("\n")[0]);
+	}
+	return new Error(fallback);
+}
+
+function isTruthy(value: string | undefined): boolean {
+	return value === "1" || value?.toLowerCase() === "true" || value?.toLowerCase() === "yes";
+}
+
+function resolveState(): BrowserState {
+	const home = homedir();
+	const channel = process.env.HAMR_BROWSER_CHANNEL || (isTruthy(process.env.HAMR_BROWSER_USE_CHROME) ? "chrome" : undefined);
+	return {
+		profileDir: process.env.HAMR_BROWSER_PROFILE_DIR || getDefaultBrowserProfileDir(process.platform, home, process.env),
+		screenshotDir: process.env.HAMR_BROWSER_SCREENSHOT_DIR || getDefaultScreenshotDir(home),
+		channel,
+		headless: isTruthy(process.env.HAMR_BROWSER_HEADLESS) ? true : false,
+	};
+}
+
+export class HamrBrowserController {
+	private context: BrowserContext | undefined;
+	private page: Page | undefined;
+	private state: BrowserState = resolveState();
+
+	getState(): BrowserState {
+		this.state = resolveState();
+		return this.state;
+	}
+
+	isOpen(): boolean {
+		return !!this.context;
+	}
+
+	async launch(options: BrowserLaunchOptions = {}): Promise<string> {
+		try {
+			if (this.context && this.page) {
+				if (options.url) await this.openUrl(options.url);
+				return `Hamr Browser already open. Profile: ${this.state.profileDir}`;
+			}
+
+			this.state = resolveState();
+			await mkdir(this.state.profileDir, { recursive: true });
+			let playwright = loadInstalledPlaywright();
+			if (!playwright && options.ensureDependencies) {
+				await options.ensureDependencies();
+				playwright = loadInstalledPlaywright();
+			}
+			if (!playwright) {
+				throw new Error("Playwright is not installed for Hamr Browser");
+			}
+			this.context = await playwright.chromium.launchPersistentContext(this.state.profileDir, {
+				headless: this.state.headless,
+				channel: this.state.channel,
+				viewport: null,
+			});
+			this.page = this.context.pages()[0] ?? (await this.context.newPage());
+			if (options.url) {
+				await this.openUrl(options.url, options.ensureDependencies);
+			}
+			return `Opening isolated Hamr Browser. Your normal browser profile is untouched. Profile: ${this.state.profileDir}`;
+		} catch (error) {
+			throw conciseError(error, "Failed to launch Hamr Browser");
+		}
+	}
+
+	async openUrl(url: string, ensureDependencies?: () => Promise<void>): Promise<string> {
+		const page = await this.requirePage(ensureDependencies);
+		try {
+			const parsed = new URL(url);
+			if (parsed.protocol !== "http:" && parsed.protocol !== "https:" && parsed.protocol !== "file:") {
+				throw new Error("URL must use http, https, or file");
+			}
+			await page.goto(parsed.toString(), { waitUntil: "domcontentloaded" });
+			return `Opened ${page.url()}`;
+		} catch (error) {
+			throw conciseError(error, `Failed to open URL: ${url}`);
+		}
+	}
+
+	async snapshot(): Promise<string> {
+		const page = await this.requirePage();
+		try {
+			return await buildBrowserSnapshot(page);
+		} catch (error) {
+			throw conciseError(error, "Failed to snapshot page");
+		}
+	}
+
+	async click(target: string): Promise<string> {
+		const page = await this.requirePage();
+		try {
+			const locator = locatorForTarget(page, target);
+			await locator.click({ timeout: 5_000 });
+			return `Clicked ${target}`;
+		} catch (error) {
+			throw conciseError(error, `Could not click target: ${target}`);
+		}
+	}
+
+	async type(target: string, text: string): Promise<string> {
+		const page = await this.requirePage();
+		try {
+			const locator = locatorForTarget(page, target);
+			try {
+				await locator.fill(text, { timeout: 5_000 });
+			} catch {
+				await locator.click({ timeout: 5_000 });
+				await page.keyboard.type(text);
+			}
+			return `Typed into ${target}`;
+		} catch (error) {
+			throw conciseError(error, `Could not type into target: ${target}`);
+		}
+	}
+
+	async press(key: string): Promise<string> {
+		const page = await this.requirePage();
+		try {
+			await page.keyboard.press(key);
+			return `Pressed ${key}`;
+		} catch (error) {
+			throw conciseError(error, `Could not press key: ${key}`);
+		}
+	}
+
+	async scroll(directionOrPixels: string | number): Promise<string> {
+		const page = await this.requirePage();
+		try {
+			const { x, y } = normalizeScrollAmount(directionOrPixels);
+			await page.mouse.wheel(x, y);
+			return `Scrolled x=${x} y=${y}`;
+		} catch (error) {
+			throw conciseError(error, "Could not scroll page");
+		}
+	}
+
+	async wait(ms: number): Promise<string> {
+		const page = await this.requirePage();
+		const boundedMs = Math.max(0, Math.min(ms, 60_000));
+		await page.waitForTimeout(boundedMs);
+		return `Waited ${boundedMs}ms`;
+	}
+
+	async screenshot(): Promise<string> {
+		const page = await this.requirePage();
+		try {
+			await mkdir(this.state.screenshotDir, { recursive: true });
+			const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+			const path = join(this.state.screenshotDir, `hamr-browser-${stamp}.png`);
+			await page.screenshot({ path, fullPage: true });
+			return path;
+		} catch (error) {
+			throw conciseError(error, "Could not save screenshot");
+		}
+	}
+
+	async close(): Promise<string> {
+		if (!this.context) {
+			this.page = undefined;
+			return "Hamr Browser is already closed";
+		}
+		try {
+			await this.context.close();
+			return "Closed Hamr Browser";
+		} catch (error) {
+			throw conciseError(error, "Failed to close Hamr Browser");
+		} finally {
+			this.context = undefined;
+			this.page = undefined;
+		}
+	}
+
+	private async requirePage(ensureDependencies?: () => Promise<void>): Promise<Page> {
+		if (!this.context || !this.page) {
+			await this.launch({ ensureDependencies });
+		}
+		if (!this.page) {
+			throw new Error("Hamr Browser is not open");
+		}
+		return this.page;
+	}
+}

package/examples/extensions/hamr-browser/src/deps.ts

@@ -0,0 +1,39 @@
+import { createRequire } from "node:module";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import type { BrowserType } from "playwright";
+
+export const PLAYWRIGHT_VERSION = "^1.57.0";
+
+export interface PlaywrightModule {
+	chromium: BrowserType;
+}
+
+export function getHamrAgentDir(env: NodeJS.ProcessEnv = process.env): string {
+	return env.HAMR_CODING_AGENT_DIR || join(homedir(), ".hamr", "agent");
+}
+
+export function getBrowserDepsDir(env: NodeJS.ProcessEnv = process.env): string {
+	return env.HAMR_BROWSER_DEPS_DIR || join(getHamrAgentDir(env), "browser-deps");
+}
+
+export function getBrowserDepsInstallCommand(depsDir = getBrowserDepsDir()): string[] {
+	return ["npm", "install", "--prefix", depsDir, `playwright@${PLAYWRIGHT_VERSION}`];
+}
+
+export function loadInstalledPlaywright(depsDir = getBrowserDepsDir()): PlaywrightModule | undefined {
+	const candidateRequires = [createRequire(import.meta.url), createRequire(join(depsDir, "package.json"))];
+
+	for (const requireFrom of candidateRequires) {
+		try {
+			return requireFrom("playwright") as PlaywrightModule;
+		} catch (error) {
+			const code = typeof error === "object" && error !== null && "code" in error ? String(error.code) : undefined;
+			if (code !== "MODULE_NOT_FOUND") {
+				throw error;
+			}
+		}
+	}
+
+	return undefined;
+}

package/examples/extensions/hamr-browser/src/paths.ts

@@ -0,0 +1,25 @@
+import { join } from "node:path";
+
+export type PlatformName = NodeJS.Platform;
+
+export type BrowserPathEnv = Partial<Record<"LOCALAPPDATA" | "APPDATA", string | undefined>>;
+
+export function getDefaultBrowserProfileDir(
+	platform: PlatformName = process.platform,
+	homeDir: string,
+	env: BrowserPathEnv = process.env,
+): string {
+	if (platform === "win32") {
+		const appDataRoot = env.LOCALAPPDATA || (homeDir ? join(homeDir, "AppData", "Local") : env.APPDATA);
+		if (!appDataRoot) {
+			return join(homeDir, ".hamr", "browser-profile");
+		}
+		return join(appDataRoot, "Hamr", "browser-profile");
+	}
+
+	return join(homeDir, ".hamr", "browser-profile");
+}
+
+export function getDefaultScreenshotDir(homeDir: string): string {
+	return join(homeDir, ".hamr", "browser-artifacts", "screenshots");
+}

package/examples/extensions/hamr-browser/src/shims.d.ts

@@ -0,0 +1 @@
+declare module "highlight.js/lib/index.js";

package/examples/extensions/hamr-browser/src/snapshot.ts

@@ -0,0 +1,84 @@
+import type { Page } from "playwright";
+
+const MAX_SNAPSHOT_CHARS = 30_000;
+
+interface SnapshotElement {
+	kind: string;
+	text: string;
+	selector: string;
+}
+
+function truncate(text: string, maxChars = MAX_SNAPSHOT_CHARS): string {
+	if (text.length <= maxChars) return text;
+	return `${text.slice(0, maxChars)}\n\n[Snapshot truncated to ${maxChars} characters]`;
+}
+
+export async function buildBrowserSnapshot(page: Page): Promise<string> {
+	const data = await page.evaluate(() => {
+		function isVisible(element: Element): boolean {
+			const html = element as HTMLElement;
+			const style = window.getComputedStyle(html);
+			const rect = html.getBoundingClientRect();
+			return style.visibility !== "hidden" && style.display !== "none" && rect.width > 0 && rect.height > 0;
+		}
+
+		function cssSelector(element: Element): string {
+			const html = element as HTMLElement;
+			const tag = element.tagName.toLowerCase();
+			if (html.id) return `${tag}#${CSS.escape(html.id)}`;
+			const name = element.getAttribute("name");
+			if (name) return `${tag}[name="${CSS.escape(name)}"]`;
+			const aria = element.getAttribute("aria-label");
+			if (aria) return `${tag}[aria-label="${CSS.escape(aria)}"]`;
+			const classes = Array.from(html.classList).slice(0, 2);
+			return classes.length > 0 ? `${tag}.${classes.map((part) => CSS.escape(part)).join(".")}` : tag;
+		}
+
+		function labelFor(element: Element): string {
+			const html = element as HTMLElement;
+			const aria = element.getAttribute("aria-label") ?? element.getAttribute("alt") ?? element.getAttribute("title");
+			const value = "value" in html ? String((html as HTMLInputElement).value || "") : "";
+			return (aria || html.innerText || value || element.textContent || "").replace(/\s+/g, " ").trim().slice(0, 180);
+		}
+
+		const interactiveSelector = [
+			"a[href]",
+			"button",
+			"input",
+			"textarea",
+			"select",
+			"[role]",
+			"[contenteditable='true']",
+		].join(",");
+
+		const elements: SnapshotElement[] = Array.from(document.querySelectorAll(interactiveSelector))
+			.filter(isVisible)
+			.slice(0, 120)
+			.map((element) => ({
+				kind: element.getAttribute("role") || element.tagName.toLowerCase(),
+				text: labelFor(element),
+				selector: cssSelector(element),
+			}));
+
+		return {
+			title: document.title,
+			url: location.href,
+			text: (document.body?.innerText || "").replace(/\n{3,}/g, "\n\n").trim(),
+			elements,
+		};
+	});
+
+	const lines = [`URL: ${data.url}`, `Title: ${data.title || "(untitled)"}`];
+	if (data.elements.length > 0) {
+		lines.push("", "Interactive elements:");
+		for (const element of data.elements) {
+			const label = element.text ? ` ${JSON.stringify(element.text)}` : "";
+			lines.push(`- [${element.kind}]${label} selector=${JSON.stringify(element.selector)}`);
+		}
+	}
+	if (data.text) {
+		lines.push("", "Visible text:", data.text);
+	}
+
+	return truncate(lines.join("\n"));
+}