pi-browser-harness 0.10.2 → 0.12.0

package/src/prompt.ts

@@ -1,127 +1,27 @@
-/**
- * System prompt guidance for browser usage.
- *
- * Injects a compact browser control reference into the pi system prompt.
- * This prompt carries only cross-cutting knowledge — the mental model, tool
- * routing, workflows, and gotchas. Per-tool specifics (schemas, detailed usage)
- * are injected separately via promptGuidelines on each tool registration, so this
- * file intentionally does NOT restate full tool descriptions.
- */
-
-export function getBrowserSystemPrompt(): string {
+export function getBrowserSystemPrompt(connected = true): string {
+  const connectionNotice = connected
+    ? ""
+    : "Browser is not connected. Run browser_setup or /browser-setup to connect.\n\n";
   return `
 ## Browser Control
 
-You drive a **real Chrome** (the user's running instance, not headless) through
-\`browser_*\` tools. These coexist with every standard pi tool — read, bash, edit,
-write — so mix them freely: \`browser_*\` for the page, everything else alongside.
-
-### The core handle: refs
-
-Interaction is ref-first. Call \`browser_snapshot\` to get an accessibility tree
-where every interactive element has a stable ref (\`[eN]\`) and \`@(x,y)\`. **Target
-elements by ref, not by coordinates or guessed selectors** — refs are keyed to
-element identity, so they survive the re-renders that React/Vue forms trigger on
-every edit and save. Coordinates go stale; guessed selectors miss.
-
-- Prefer \`browser_fill\` for text — it fires input/change so controlled components
-  update, and returns the value for verification. Use \`browser_click\` + \`browser_type\`
-  only for keystroke-sensitive widgets (autocomplete, masked inputs).
-- Mutating calls append a compact **"Page changes"** diff — read it to confirm the
-  change landed (form closed, new \`*[eN]\` appeared).
-- \`"ref is stale"\` means the page changed: re-run \`browser_snapshot\` for fresh refs.
-
-### Choosing a tool
-
-| To… | Reach for |
-|-----|-----------|
-| See the page structure (for interaction) | \`browser_snapshot\` (refs) |
-| See the page visually | \`browser_screenshot\` |
-| Search the web | \`browser_web_search\` → ranked {title, url, snippet} |
-| Read an article's clean text | \`browser_read_page\` (reader mode; url or owned tab) |
-| Extract specific DOM values | \`browser_execute_js\` |
-| Hit a JSON/API endpoint | \`browser_http_get\` (raw GET, outside the browser) |
-| Click / fill / type / select / focus / press a key | \`browser_click\` · \`browser_fill\` · \`browser_type\` · \`browser_select_option\` · \`browser_focus\` · \`browser_press_key\` |
-| Upload a file · drag · resize viewport | \`browser_upload_file\` · \`browser_drag_and_drop\` · \`browser_viewport_resize\` |
-| Go to a URL / open many / manage tabs | \`browser_navigate\` · \`browser_new_tab\` · \`browser_open_urls\` · \`browser_list_tabs\` · \`browser_switch_tab\` · \`browser_go_back\`/\`go_forward\`/\`reload\` |
-| Wait for content / load / a fixed delay | \`browser_wait_for\` (selector/text) · \`browser_wait_for_load\` (readyState) · \`browser_wait\` |
-| Inspect page / handle a dialog | \`browser_page_info\` · \`browser_current_tab\` · \`browser_handle_dialog\` |
-| Diagnose a broken action | \`browser_console\` (JS errors) · \`browser_get_network_log\` |
-| Save output / config downloads | \`browser_print_to_pdf\` · \`browser_download\` |
-| Anything the tools can't express | \`browser_run_script\` (see Extending) |
-
-Each tool carries its own detailed guidelines — this table is only for routing.
-
-### Workflows
-
-**Research (search → read):**
-\`\`\`
-browser_web_search("query")        // ranked links, no page content
-→ browser_read_page(url)           // clean article text for the top hits
-// fall back to browser_open_urls + browser_execute_js only when reader mode misses
-\`\`\`
-
-**Form filling (ref-first — the reliable path on SPA forms):**
-\`\`\`
-browser_wait_for({ selector: "#email" })   // ensure the field is rendered
-browser_snapshot()                          // interactive elements get [eN] refs
-→ browser_fill({ ref: "e7", value: "a@b.com" })
-→ browser_select_option({ ref: "e9", label: "India" })
-→ browser_click({ ref: "e12" })             // re-resolves position even after reflow
-// read each "Page changes" diff to confirm the step landed
-\`\`\`
-
-**Navigate + verify:**
-\`\`\`
-browser_new_tab("https://example.com") → browser_wait_for_load() → browser_screenshot()
-\`\`\`
-
-**Scroll:** \`browser_scroll({ deltaY: 500 })\` — W3C wheel convention: positive = down,
-negative = up (default 300, down).
-
-### Parallelism
-
-Observation tools (\`browser_screenshot\`, \`browser_page_info\`, \`browser_execute_js\`,
-\`browser_list_tabs\`, \`browser_http_get\`, \`browser_web_search\`, \`browser_read_page\`, …)
-run in parallel with each other and with mutations. The harness serializes mutations
-(click, type, scroll, navigate, switch_tab) so they never race. Emit independent calls
-in one turn:
-\`\`\`
-browser_screenshot() + browser_page_info() + browser_execute_js("document.title")
-\`\`\`
-
-**Multi-agent:** tab switching by one agent changes the active tab for all agents,
-but per-tab data (console, network, dialogs) stays isolated. Call \`browser_current_tab\`
-before a mutation to confirm you're on the expected tab. Handle any dialog reported by
-\`browser_page_info\` promptly — dialogs block interaction and aren't queued across agents.
-
-**Session boundary & tab hygiene:** you operate only inside this session's own Chrome
-window. \`browser_switch_tab\`/\`browser_close_tab\` refuse tabs this session didn't open,
-and \`browser_list_tabs\` defaults to owned tabs — never reach into the user's other tabs
-or windows. Close tabs when you're done with them: call \`browser_close_tab\` on any tab
-you opened (via \`browser_new_tab\`/\`browser_open_urls\`) once you've extracted what you
-need. Don't leave a pile of stale tabs behind — keep only what a later step still needs.
-(Leftover tabs are closed automatically when the session ends, but close them yourself
-as you go.)
-
-### Extending: temporary scripts
-
-When built-in tools can't express a multi-step workflow, write a script to a temp file
-and run it with \`browser_run_script\`. It executes in the harness process with direct
-daemon + Node access.
-\`\`\`
-write(<tempfile>.js, \`
-  const results = [];
-  for (const url of params.urls) {
-    await daemon.cdp("Page.navigate", { url });
-    await new Promise(r => setTimeout(r, 2000));
-    results.push({ url, title: await daemon.evaluateJS("document.title") });
-  }
-  return { content: [{ type: "text", text: JSON.stringify(results, null, 2) }] };
-\`)
-browser_run_script(<tempfile>.js, { urls: [...] })
-\`\`\`
-Script bindings: params, daemon, require, signal, onUpdate, ctx, console, fetch, JSON,
-Buffer, setTimeout, clearTimeout. Use a real temp path from the OS — don't hardcode \`/tmp\`.
+${connectionNotice}You control the user's running Chrome through \`browser_*\` tools alongside the
+standard pi tools. Per-tool usage lives in tool descriptions, parameter schemas,
+and tool-specific guidelines.
+
+- Operate only inside this session's owned Chrome window. Never reach into the
+  user's other tabs or windows. Close owned tabs once no later step needs them.
+- Mutating tools (click, type, fill, press_key, scroll, navigate, history, tab
+  switch/new/close, upload, download, headers, viewport, drag, web_search) are
+  serialized. Observations (snapshot, screenshot, page_info, current_tab, list_tabs,
+  console, network_requests, http_get, read_page, execute_js, wait, wait_for) may run
+  concurrently with them. \`browser_run_script\` bypasses that lane: keep mutating
+  scripts sequential with other browser calls. Parallelize only independent calls.
+- Agents sharing a session share its active tab. Check \`browser_current_tab\`
+  before a mutation to confirm the expected tab when another agent may switch it.
+- Read any appended "Page changes" diff to confirm an interaction. Tools without a
+  diff, including \`browser_run_script\`, need explicit state verification.
+- If a tool reports "ref is stale", call \`browser_snapshot\` for fresh refs before
+  retrying; do not reuse the stale handle.
 `;
 }

package/src/registry.ts

@@ -3,7 +3,8 @@ import type { BrowserClient } from "./client";
 import { type AnyBrowserToolDefinition, registerBrowserTool } from "./util/tool";
 import { clickTool } from "./domains/click";
 import { typeTool, pressKeyTool, dispatchKeyTool } from "./domains/keyboard";
-import { fillTool, selectOptionTool, focusTool } from "./domains/form";
+import { fillTool, selectOptionTool, focusTool, setCheckedTool } from "./domains/form";
+import { fillFormTool } from "./domains/form-batch";
 import { pageInfoTool, waitTool, waitForLoadTool, waitForTool } from "./domains/page";
 import { scrollTool } from "./domains/scroll";
 import { handleDialogTool } from "./domains/dialog";
@@ -15,6 +16,7 @@ import { uploadFileTool, downloadTool, printToPdfTool } from "./domains/files";
 import { viewportResizeTool } from "./domains/viewport";
 import { dragAndDropTool } from "./domains/drag";
 import { httpGetTool, networkRequestsTool } from "./domains/network";
+import { clearHeadersTool, setHeadersTool } from "./domains/headers";
 import { consoleTool } from "./domains/console";
 import { snapshotTool } from "./domains/snapshot";
 import { executeJsTool, runScriptTool } from "./domains/js";
@@ -22,53 +24,51 @@ import { setupTool } from "./domains/setup";
 import { webSearchTool } from "./domains/search/web-search";
 import { readPageTool } from "./domains/readpage/read-page";
 
-// Mutation tools that modify page / browser state are marked `serialized: true`
-// so they run through a shared async mutex.  Observation / read-only tools are
-// left unmarked and can execute in parallel.
-const TOOLS: ReadonlyArray<AnyBrowserToolDefinition> = [
-  // setup comes first — the agent calls this to self-recover from not-initialized
+export const ALL_TOOLS: ReadonlyArray<AnyBrowserToolDefinition> = [
   setupTool,
-  { ...clickTool, serialized: true },
-  { ...typeTool, serialized: true },
-  { ...fillTool, serialized: true },
-  { ...selectOptionTool, serialized: true },
-  { ...focusTool, serialized: true },
-  { ...pressKeyTool, serialized: true },
-  { ...dispatchKeyTool, serialized: true },
-  { ...scrollTool, serialized: true },
+  clickTool,
+  typeTool,
+  fillTool,
+  fillFormTool,
+  selectOptionTool,
+  setCheckedTool,
+  focusTool,
+  pressKeyTool,
+  dispatchKeyTool,
+  scrollTool,
   pageInfoTool,
   waitTool,
   waitForTool,
-  { ...waitForLoadTool, serialized: true },
-  { ...handleDialogTool, serialized: true },
+  waitForLoadTool,
+  handleDialogTool,
   screenshotTool,
-  { ...navigateTool, serialized: true },
-  { ...openUrlsTool, serialized: true },
-  { ...goBackTool, serialized: true },
-  { ...goForwardTool, serialized: true },
-  { ...reloadTool, serialized: true },
+  navigateTool,
+  openUrlsTool,
+  goBackTool,
+  goForwardTool,
+  reloadTool,
   listTabsTool,
   currentTabTool,
-  { ...switchTabTool, serialized: true },
-  { ...newTabTool, serialized: true },
-  { ...closeTabTool, serialized: true },
-  { ...uploadFileTool, serialized: true },
-  { ...downloadTool, serialized: true },
-  { ...printToPdfTool, serialized: true },
-  { ...viewportResizeTool, serialized: true },
-  { ...dragAndDropTool, serialized: true },
+  switchTabTool,
+  newTabTool,
+  closeTabTool,
+  uploadFileTool,
+  downloadTool,
+  printToPdfTool,
+  viewportResizeTool,
+  dragAndDropTool,
   httpGetTool,
   networkRequestsTool,
+  setHeadersTool,
+  clearHeadersTool,
   consoleTool,
   snapshotTool,
   executeJsTool,
   runScriptTool,
-  // Opens and owns an isolated tab to scrape a SERP — same class as openUrlsTool.
-  { ...webSearchTool, serialized: true },
-  // Pure isolated read (own sessionId, own tab) — safe concurrent, like executeJsTool.
+  webSearchTool,
   readPageTool,
 ];
 
 export const registerAllTools = (pi: ExtensionAPI, client: BrowserClient): void => {
-  for (const t of TOOLS) registerBrowserTool(pi, client, t);
+  for (const t of ALL_TOOLS) registerBrowserTool(pi, client, t);
 };

package/src/schemas/parse.ts

@@ -0,0 +1,23 @@
+import type { Static, TSchema } from "typebox";
+import type { Validator } from "typebox/compile";
+import { type Result, err, ok } from "../util/result";
+
+export const parseJson = <S extends TSchema>(
+  raw: string,
+  validator: Validator<{}, S>,
+): Result<Static<S>, string> => {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (e) {
+    return err(`JSON parse failed: ${e instanceof Error ? e.message : String(e)}`);
+  }
+  if (!validator.Check(parsed)) {
+    const messages = validator
+      .Errors(parsed)
+      .map((x) => x.message)
+      .join("; ");
+    return err(messages.length > 0 ? messages : "JSON did not match the expected shape");
+  }
+  return ok(parsed);
+};

package/src/setup.ts

@@ -1,9 +1,3 @@
-/**
- * Setup — verifies Chrome is running with remote debugging and connects
- * the pi agent to it. Exposed as both a slash command (/browser-setup) for
- * users and a tool (browser_setup) for the agent to self-recover.
- */
-
 import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
 import type { BrowserClient } from "./client";
 import { ensureDaemon } from "./daemon/spawn";
@@ -11,8 +5,6 @@ import { DAEMON_SOCKET_PATH } from "./daemon/protocol";
 import { isBrowserRunning } from "./profile/browser-process";
 import { promptForProfileIfUnset } from "./profile/command";
 
-// ── Public: register the /browser-setup slash command ──────────────────────
-
 export function registerSetupCommand(pi: ExtensionAPI, client: BrowserClient): void {
   pi.registerCommand("browser-setup", {
     description: "Connect pi to your Chrome browser",
@@ -27,32 +19,21 @@ export function registerSetupCommand(pi: ExtensionAPI, client: BrowserClient): v
   });
 }
 
-// ── Shared setup result ────────────────────────────────────────────────────
-
 export type SetupResult = { success: true; data: string } | { success: false; error: string };
 
-// ── Shared setup logic (used by both the command and the tool) ─────────────
-
 export async function performSetup(client: BrowserClient, ctx?: ExtensionContext): Promise<SetupResult> {
-  // Step 1: Check Chrome is running
   const chromeRunning = await isBrowserRunning();
   if (!chromeRunning) {
     return { success: false, error: "No browser instance running. Please open your browser and then run /browser-setup." };
   }
 
-  // Step 2: Start the browser daemon (spawns if not running, silently reuses if alive)
   const daemonReady = await ensureDaemon();
   if (!daemonReady) {
     return { success: false, error: `Could not start the browser daemon. Check ${DAEMON_SOCKET_PATH}.` };
   }
 
-  // Step 3: Ask which profile to work in, the first time only. Enumeration
-  // reads DevToolsActivePort + Local State from disk, so it works before the
-  // connection exists. Declining leaves the pre-profile behavior untouched —
-  // this must never block setup.
   const profileNote = await promptForProfileIfUnset(client, ctx);
 
-  // Step 4: Connect to Chrome DevTools
   const startResult = await client.start();
   if (!startResult.success) {
     const msg = startResult.error.message;
@@ -80,7 +61,6 @@ export async function performSetup(client: BrowserClient, ctx?: ExtensionContext
     return { success: false, error: `Connection failed: ${msg}` };
   }
 
-  // Step 5: Verify with test navigation
   const tabResult = await client.newTab("https://github.com");
   if (!tabResult.success) {
     return { success: false, error: `Browser connected but test navigation failed: ${tabResult.error.message}` };
@@ -97,8 +77,3 @@ export async function performSetup(client: BrowserClient, ctx?: ExtensionContext
   return { success: true, data: lines.join("\n") };
 }
 
-// ── Chrome process detection ───────────────────────────────────────────────
-//
-// Detection moved to src/profile/browser-process.ts, which answers the same
-// "is a browser running?" question per platform and additionally reports the
-// executable path and any explicit --user-data-dir that profile selection needs.

package/src/state.ts

@@ -1,15 +1,8 @@
-/**
- * Session persistence for pi-browser-harness.
- *
- * Persists the daemon namespace and (when applicable) the remote browser ID
- * across session reloads and branch navigation.
- */
-
 import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
+import { asArrayOf, asNumber, asString, isRecord } from "./util/guards";
 
 export type BrowserState = {
   readonly namespace: string;
-  readonly remoteBrowserId?: string;
   readonly ownedTargetIds?: ReadonlyArray<string>;
   readonly harnessWindowTargetId?: string;
   readonly harnessWindowId?: number;
@@ -20,24 +13,61 @@ export const defaultState = (namespace = "default"): BrowserState => ({
   ownedTargetIds: [],
 });
 
-export const persistState = (pi: ExtensionAPI, state: BrowserState): void => {
-  pi.appendEntry<BrowserState>("browser-harness-state", state);
+// Pi session JSONL is append-only and every custom entry shows up in the branch navigator, so a
+// snapshot is only worth appending when it differs from the one the branch already holds (#26).
+// Tab order is not a difference: ownership is a set.
+const stateKey = (state: BrowserState): string =>
+  JSON.stringify({
+    namespace: state.namespace,
+    ownedTargetIds: [...(state.ownedTargetIds ?? [])].sort(),
+    harnessWindowTargetId: state.harnessWindowTargetId ?? null,
+    harnessWindowId: state.harnessWindowId ?? null,
+  });
+
+export type StatePersister = {
+  // Appends the snapshot unless it equals the last one persisted or restored. Returns whether it wrote.
+  readonly persist: (state: BrowserState) => boolean;
+  // Records a snapshot that already lives in the session (restored from the branch) without writing it.
+  readonly markPersisted: (state: BrowserState) => void;
+};
+
+export const createStatePersister = (pi: ExtensionAPI): StatePersister => {
+  let last: string | undefined;
+  return {
+    persist: (state) => {
+      const key = stateKey(state);
+      if (key === last) return false;
+      pi.appendEntry<BrowserState>("browser-harness-state", state);
+      last = key;
+      return true;
+    },
+    markPersisted: (state) => {
+      last = stateKey(state);
+    },
+  };
+};
+
+const asPersistedState = (v: unknown): Partial<BrowserState> | undefined => {
+  if (!isRecord(v)) return undefined;
+  const namespace = asString(v["namespace"]);
+  const ownedTargetIds = asArrayOf(v["ownedTargetIds"], asString);
+  const harnessWindowTargetId = asString(v["harnessWindowTargetId"]);
+  const harnessWindowId = asNumber(v["harnessWindowId"]);
+  return {
+    ...(namespace !== undefined ? { namespace } : {}),
+    ...(ownedTargetIds !== undefined ? { ownedTargetIds } : {}),
+    ...(harnessWindowTargetId !== undefined ? { harnessWindowTargetId } : {}),
+    ...(harnessWindowId !== undefined ? { harnessWindowId } : {}),
+  };
 };
 
-/**
- * Find the last browser-harness-state entry in the current branch
- * and return the restored state, merged with defaults.
- *
- * If `currentNamespace` is supplied (e.g. from the --browser-namespace flag),
- * it overrides whatever is in the persisted entry.
- */
 export const restoreState = (ctx: ExtensionContext, currentNamespace?: string): BrowserState => {
   const branchEntries = ctx.sessionManager.getBranch();
   const fallback = defaultState(currentNamespace);
   for (let i = branchEntries.length - 1; i >= 0; i--) {
     const entry = branchEntries[i];
     if (entry?.type === "custom" && entry.customType === "browser-harness-state") {
-      const data = entry.data as Partial<BrowserState> | undefined;
+      const data = asPersistedState(entry.data);
       if (data) {
         return {
           ...fallback,

package/src/util/debug.ts

@@ -0,0 +1,8 @@
+let flagEnabled = false;
+
+export const setDebugClicks = (on: boolean): void => {
+  flagEnabled = on;
+};
+
+export const debugClicksEnabled = (env: NodeJS.ProcessEnv = process.env): boolean =>
+  flagEnabled || Boolean(env["BH_DEBUG_CLICKS"]);

package/src/util/guards.ts

@@ -0,0 +1,30 @@
+export const isRecord = (v: unknown): v is Readonly<Record<string, unknown>> =>
+  typeof v === "object" && v !== null && !Array.isArray(v);
+
+export const asRecord = (v: unknown): Readonly<Record<string, unknown>> | undefined =>
+  isRecord(v) ? v : undefined;
+
+export const asString = (v: unknown): string | undefined => (typeof v === "string" ? v : undefined);
+
+export const asNumber = (v: unknown): number | undefined => (typeof v === "number" ? v : undefined);
+
+export const asBoolean = (v: unknown): boolean | undefined => (typeof v === "boolean" ? v : undefined);
+
+export const asArrayOf = <T>(
+  v: unknown,
+  item: (x: unknown) => T | undefined,
+): ReadonlyArray<T> | undefined => {
+  if (!Array.isArray(v)) return undefined;
+  const out: T[] = [];
+  for (const x of v) {
+    const parsed = item(x);
+    if (parsed === undefined) return undefined;
+    out.push(parsed);
+  }
+  return out;
+};
+
+export const errnoCode = (e: unknown): string | undefined => {
+  if (!(e instanceof Error) || !("code" in e)) return undefined;
+  return asString(e.code);
+};

package/src/util/js-template.ts

@@ -1,19 +1,4 @@
-/**
- * Build a JavaScript source string with safely-interpolated values.
- * Every interpolated value is JSON.stringify'd, so strings, numbers,
- * objects, and special characters all become valid JS literals.
- *
- * This is the ONLY supported way to interpolate untrusted values into
- * evaluation source — never use raw template literals for JS that
- * crosses the CDP boundary. The static parts of the template (the
- * `strings` array) must remain hard-coded; only the `${...}` slots
- * are sanitized.
- *
- * Values must be JSON-serializable: BigInt and Symbol throw at runtime;
- * functions and undefined serialize to `undefined`/omitted, which yields
- * a ReferenceError when evaluated. Pass strings, numbers, booleans,
- * plain objects, or arrays.
- */
+// The ONLY supported way to interpolate untrusted values into evaluation source — never use raw template literals for JS crossing the CDP boundary.
 export const safeJs = (
   strings: TemplateStringsArray,
   ...values: ReadonlyArray<unknown>

package/src/util/mutex.ts

@@ -1,8 +1,3 @@
-/**
- * Lightweight async mutex (~10 lines). Acquire returns a release function.
- * When the mutex is free, acquire() resolves immediately. When held,
- * callers are queued and execute serially in FIFO order.
- */
 export type Mutex = {
   acquire(): Promise<() => void>;
 };

package/src/util/paths.ts

@@ -1,6 +1,16 @@
 import { randomUUID } from "node:crypto";
 import { tmpdir } from "node:os";
-import { join } from "node:path";
+import { isAbsolute, join, relative, resolve } from "node:path";
+
+// `relative` rather than a string prefix: it is separator-agnostic and carries each platform's
+// own case rules, so a Windows path is not rejected for its backslashes or its drive-letter case.
+export const isPathWithin = (root: string, target: string): boolean => {
+  const absRoot = resolve(root);
+  const absTarget = resolve(target);
+  if (absTarget === absRoot) return true;
+  const rel = relative(absRoot, absTarget);
+  return rel !== "" && !rel.startsWith("..") && !isAbsolute(rel);
+};
 
 const NAMESPACE_RE = /^[a-zA-Z0-9_-]+$/;
 

package/src/util/result.ts

@@ -7,9 +7,3 @@ export const err = <E>(error: E): Result<never, E> => ({ success: false, error }
 
 export const map = <T, U, E>(r: Result<T, E>, f: (t: T) => U): Result<U, E> =>
   r.success ? ok(f(r.data)) : r;
-
-export const andThen = <T, U, E>(r: Result<T, E>, f: (t: T) => Result<U, E>): Result<U, E> =>
-  r.success ? f(r.data) : r;
-
-export const mapErr = <T, E, F>(r: Result<T, E>, f: (e: E) => F): Result<T, F> =>
-  r.success ? r : err(f(r.error));

package/src/util/sharp-shim.ts

@@ -1,10 +1,4 @@
-// Typed minimal shim for the optional `sharp` dependency. Sharp is a heavy
-// native module not installed in every workspace; we import dynamically and
-// distinguish "missing" (no install) from "error" (installed but threw).
-//
-// We declare only the surface we use. The dynamic import returns `unknown`
-// at the boundary; the cast inside loadSharp() is the documented escape
-// hatch — every other consumer sees the typed SharpFactory.
+// `sharp` is an optional dependency not installed in every workspace, so the import must stay dynamic and unresolvable to tsc.
 
 export type SharpInstance = {
   metadata(): Promise<{ width?: number; height?: number }>;
@@ -20,26 +14,25 @@ export type SharpLoad =
   | { readonly kind: "missing" }
   | { readonly kind: "error"; readonly message: string };
 
+const SHARP_SPECIFIER: string = "sharp";
+
+const MISSING_MODULE_MARKERS: ReadonlyArray<string> = [
+  "Cannot find module",
+  "MODULE_NOT_FOUND",
+  "ERR_MODULE_NOT_FOUND",
+];
+
 export const loadSharp = async (): Promise<SharpLoad> => {
   let mod: unknown;
   try {
-    // sharp is an optional dependency; it may not be installed.
-    // @ts-ignore — optional peer dependency not required at compile time
-    mod = await import("sharp");
+    mod = await import(SHARP_SPECIFIER);
   } catch (e) {
     const msg = e instanceof Error ? e.message : String(e);
-    if (
-      msg.includes("Cannot find module") ||
-      msg.includes("MODULE_NOT_FOUND") ||
-      msg.includes("ERR_MODULE_NOT_FOUND")
-    ) {
-      return { kind: "missing" };
-    }
+    if (MISSING_MODULE_MARKERS.some((marker) => msg.includes(marker))) return { kind: "missing" };
     return { kind: "error", message: msg };
   }
   if (mod === null || mod === undefined) return { kind: "missing" };
-  // The CommonJS sharp module's default export IS the factory. ESM-wrapped
-  // sharp puts it on .default. Probe both.
+  // The CommonJS sharp module's default export IS the factory; ESM-wrapped sharp puts it on .default.
   const m = mod as { default?: unknown };
   const candidate: unknown = typeof m.default === "function" ? m.default : mod;
   if (typeof candidate !== "function") {