@jobshimo/browser-link 0.36.0 → 0.38.0

package/dist/extension/inpage/observer.js

@@ -22,7 +22,7 @@
  * `cdp/builders-parity.test.ts` checks the built output.
  */
 /** Bump whenever the in-page protocol (global shape, messages, methods) changes. */
-export const OBSERVER_VERSION = 2;
+export const OBSERVER_VERSION = 3;
 /** Name of the `Runtime.addBinding` function the observer pushes messages through. */
 export const OBSERVER_BINDING = '__blPageObserverPush';
 /** Well-known global that holds the installed observer instance. */
@@ -43,10 +43,30 @@ function clampInt(value, fallback, min, max) {
  * `{ ok: true, installed, version, doc_id, coverage }`.
  *
  * The instance also owns element identity (spec v4 §5.6): `refFor(el)` issues
- * `e<N>` (monotonic per document instance, from `e1`) the first time an
- * element is seen and reuses it while the node lives; `resolveRef(ref)`
- * returns the element while it is connected, else `null`. Refs are only valid
- * for the `doc_id` that issued them. Neither method throws. `nextSnapshotId()`
+ * `<doc_tag>:e<N>` (`doc_tag` = the first 6 characters of `doc_id`, N
+ * monotonic per document instance, from 1) the first time an element is seen
+ * and reuses it while the node lives; `resolveRef(ref)` returns the element
+ * while it is connected, else `null`. Refs are only valid for the document
+ * instance that issued them: a ref whose tag is not this instance's tag, or a
+ * bare `e<N>` with no tag, is `null` everywhere (resolve, re-resolve, key)
+ * without consulting the registries. Neither method throws.
+ *
+ * Secondary identity (spec v4 §5.6, decided by lab 10): `semanticKeyFor(el)`
+ * returns `{ role, name, path }` — role from the `role` attribute or a small
+ * implicit table, accessible-ish name (aria-label, aria-labelledby, associated
+ * label, text ≤ 80 chars, placeholder, title, button-like input value) and up
+ * to 8 `{ tag, index }` ancestor steps (1-based same-tag sibling index, a
+ * shadow boundary as `{ tag: '#shadow', index: 0 }`). `refFor` stores the key
+ * when it issues a ref. `resolveRefDetailed(ref)` returns `{ el, reresolved }`:
+ * the live node with `reresolved: false`, else the element with the same role,
+ * name and tag-only path when exactly one exists, rebinding the ref to it
+ * (`reresolved: true`); zero or several candidates give `null` (sibling
+ * indices are kept in the key as data but never pick among candidates). Candidates come from the document, every open shadow root reachable
+ * from it, and every root the `attachShadow` patch observed (closed ones
+ * included); closed roots attached before install are not reachable.
+ * `resolveRef(ref)` is `resolveRefDetailed(ref)?.el ?? null`. `keyForRef(ref)`
+ * returns a copy of the stored key or `null`. None of these throws.
+ * `nextSnapshotId()`
  * issues `<doc_id>:s<N>` (N monotonic per document instance, from 1) for each
  * `snapshot` result and returns `null` once the instance is torn down; the
  * `doc_id` prefix lets a stale id from another document be rejected.
@@ -97,7 +117,14 @@ export function buildObserverInstallJs(opts = {}) {
   const observed = new WeakSet();
   let refs = new WeakMap();
   const refNodes = new Map();
+  // Semantic key captured when each ref is issued; kept while the ref lives so
+  // a replaced node can be found again (spec v4 §5.6 secondary identity).
+  const refKeys = new Map();
   let refSeq = 0;
+  // Every ref carries the issuing document's tag, so a ref from another
+  // document instance (or a bare e<N>) never reaches the registries.
+  const refPrefix = g.doc_id.slice(0, 6) + ':e';
+  const ownsRef = (ref) => typeof ref === 'string' && ref.startsWith(refPrefix);
   let snapshotSeq = 0;
   // Last SNAPSHOT_KEEP snapshot records (opaque to the observer; the snapshot
   // builder owns their shape), keyed by snapshot_id in insertion order.
@@ -225,7 +252,7 @@ export function buildObserverInstallJs(opts = {}) {
     try {
       const mo = new MutationObserver(onRecords(kind));
       mo.observe(root, { subtree: true, childList: true, attributes: true, characterData: true });
-      observers.push({ mo: mo, kind: kind });
+      observers.push({ mo: mo, kind: kind, root: root });
       g.roots++;
     } catch (e) {}
   }
@@ -293,13 +320,179 @@ export function buildObserverInstallJs(opts = {}) {
 
   g.flush = flush;
 
+  const KEY_PATH_STEPS = 8;
+  const KEY_TEXT_CAP = 80;
+  // Elements an HTML <label> can be associated with.
+  const LABELABLE = ['button', 'input', 'meter', 'output', 'progress', 'select', 'textarea'];
+  const BUTTON_INPUT_TYPES = ['button', 'submit', 'reset'];
+
+  function tagOf(el) {
+    return el.localName || String(el.nodeName).toLowerCase();
+  }
+
+  function collapse(text) {
+    return String(text || '').replace(/\\s+/g, ' ').trim();
+  }
+
+  function inputType(el) {
+    return (el.getAttribute('type') || 'text').toLowerCase();
+  }
+
+  function roleOf(el) {
+    const explicit = (el.getAttribute('role') || '').trim();
+    if (explicit) return explicit;
+    const tag = tagOf(el);
+    if (tag === 'a' && el.hasAttribute('href')) return 'link';
+    if (tag === 'button' || tag === 'summary') return 'button';
+    if (tag === 'input') {
+      const type = inputType(el);
+      if (type === 'checkbox' || type === 'radio') return type;
+      if (BUTTON_INPUT_TYPES.indexOf(type) >= 0) return 'button';
+      return 'textbox';
+    }
+    if (tag === 'textarea') return 'textbox';
+    if (tag === 'select') return 'combobox';
+    if (el.hasAttribute('contenteditable') && el.getAttribute('contenteditable') !== 'false') return 'textbox';
+    return tag;
+  }
+
+  function labelTextOf(el, root) {
+    if (LABELABLE.indexOf(tagOf(el)) < 0) return '';
+    const id = el.getAttribute('id');
+    if (id && root && typeof root.querySelectorAll === 'function') {
+      for (const label of root.querySelectorAll('label')) {
+        if (label.getAttribute('for') !== id) continue;
+        const text = collapse(label.textContent);
+        if (text) return text;
+      }
+    }
+    const wrapping = typeof el.closest === 'function' ? el.closest('label') : null;
+    return wrapping ? collapse(wrapping.textContent) : '';
+  }
+
+  function nameOf(el) {
+    const ariaLabel = collapse(el.getAttribute('aria-label'));
+    if (ariaLabel) return ariaLabel;
+    const root = typeof el.getRootNode === 'function' ? el.getRootNode() : document;
+    const labelledBy = collapse(el.getAttribute('aria-labelledby'));
+    if (labelledBy && root && typeof root.getElementById === 'function') {
+      const parts = [];
+      for (const id of labelledBy.split(' ')) {
+        const target = root.getElementById(id);
+        const text = target ? collapse(target.textContent) : '';
+        if (text) parts.push(text);
+      }
+      if (parts.length > 0) return parts.join(' ');
+    }
+    const label = labelTextOf(el, root);
+    if (label) return label;
+    const text = collapse(el.textContent).slice(0, KEY_TEXT_CAP);
+    if (text) return text;
+    const placeholder = collapse(el.getAttribute('placeholder'));
+    if (placeholder) return placeholder;
+    const title = collapse(el.getAttribute('title'));
+    if (title) return title;
+    if (tagOf(el) === 'input' && BUTTON_INPUT_TYPES.indexOf(inputType(el)) >= 0) return collapse(el.value);
+    return '';
+  }
+
+  function sameTagIndex(el) {
+    const tag = el.localName;
+    let index = 1;
+    for (let s = el.previousElementSibling; s; s = s.previousElementSibling) {
+      if (s.localName === tag) index++;
+    }
+    return index;
+  }
+
+  // Unlike pathOf (descriptors, pinned settle output), this path carries the
+  // same-tag sibling index: role + name alone collides (spec v4 §4.6).
+  function keyPathOf(el) {
+    const steps = [];
+    let n = el;
+    while (n && steps.length < KEY_PATH_STEPS) {
+      if (n.nodeType === 1) {
+        if (n === document.documentElement) break;
+        steps.unshift({ tag: tagOf(n), index: sameTagIndex(n) });
+        n = n.parentNode;
+      } else if (n.nodeType === 11 && n.host) {
+        steps.unshift({ tag: '#shadow', index: 0 });
+        n = n.host;
+      } else {
+        break;
+      }
+    }
+    return steps;
+  }
+
+  function semanticKeyFor(el) {
+    try {
+      if (!el || el.nodeType !== 1) return null;
+      return { role: roleOf(el), name: nameOf(el), path: keyPathOf(el) };
+    } catch (e) {
+      return null;
+    }
+  }
+
+  // The document, every open shadow root reachable from it, and every root the
+  // attachShadow patch observed (closed ones included) whose host is connected.
+  function searchRoots() {
+    const roots = [document];
+    const seen = new Set(roots);
+    const add = (root) => {
+      if (!root || seen.has(root)) return;
+      if (root.nodeType === 11 && !(root.host && root.host.isConnected)) return;
+      seen.add(root);
+      roots.push(root);
+    };
+    for (const o of observers) add(o.root);
+    for (let i = 0; i < roots.length; i++) {
+      let all;
+      try { all = roots[i].querySelectorAll('*'); } catch (e) { continue; }
+      for (const el of all) {
+        if (el.shadowRoot) add(el.shadowRoot);
+      }
+    }
+    return roots;
+  }
+
+  // Same role and name and an identical tag-only path, and exactly one such
+  // element: identical rows are refused, never guessed, so a ref never jumps
+  // across rows. Sibling indices stay in the key but select nothing.
+  function findByKey(key) {
+    const last = key.path[key.path.length - 1];
+    if (!last) return null;
+    let found = null;
+    for (const root of searchRoots()) {
+      let all;
+      try { all = root.querySelectorAll('*'); } catch (e) { continue; }
+      for (const el of all) {
+        if (tagOf(el) !== last.tag || roleOf(el) !== key.role || nameOf(el) !== key.name) continue;
+        const path = keyPathOf(el);
+        if (path.length !== key.path.length) continue;
+        let same = true;
+        for (let i = 0; i < path.length && same; i++) {
+          if (path[i].tag !== key.path[i].tag) same = false;
+        }
+        if (!same) continue;
+        if (found) return null;
+        found = el;
+      }
+    }
+    return found;
+  }
+
+  g.semanticKeyFor = semanticKeyFor;
+
   g.refFor = function (el) {
     try {
       if (g.dead || !el || el.nodeType !== 1) return null;
       let ref = refs.get(el);
       if (!ref) {
-        ref = 'e' + ++refSeq;
+        ref = refPrefix + ++refSeq;
         refs.set(el, ref);
+        const key = semanticKeyFor(el);
+        if (key) refKeys.set(ref, key);
       }
       // Same node, same ref: re-register one pruned while it was detached.
       if (!refNodes.has(ref)) refNodes.set(ref, holdWeakly(el));
@@ -309,20 +502,40 @@ export function buildObserverInstallJs(opts = {}) {
     }
   };
 
-  g.resolveRef = function (ref) {
+  g.resolveRefDetailed = function (ref) {
     try {
-      if (typeof ref !== 'string') return null;
+      if (g.dead || !ownsRef(ref)) return null;
       const held = refNodes.get(ref);
-      if (!held) return null;
-      const el = held.deref();
-      if (el && el.isConnected) return el;
+      const old = held ? held.deref() : null;
+      if (old && old.isConnected) return { el: old, reresolved: false };
       refNodes.delete(ref);
-      return null;
+      const key = refKeys.get(ref);
+      if (!key) return null;
+      const el = findByKey(key);
+      if (!el) return null;
+      if (old && refs.get(old) === ref) refs.delete(old);
+      // A node that already has its own ref keeps it for refFor; this ref
+      // still resolves to it through refNodes.
+      if (!refs.has(el)) refs.set(el, ref);
+      refNodes.set(ref, holdWeakly(el));
+      return { el: el, reresolved: true };
     } catch (e) {
       return null;
     }
   };
 
+  g.resolveRef = function (ref) {
+    const result = g.resolveRefDetailed(ref);
+    return result ? result.el : null;
+  };
+
+  g.keyForRef = function (ref) {
+    if (g.dead || !ownsRef(ref)) return null;
+    const key = refKeys.get(ref);
+    if (!key) return null;
+    return { role: key.role, name: key.name, path: key.path.map((s) => ({ tag: s.tag, index: s.index })) };
+  };
+
   g.nextSnapshotId = function () {
     if (g.dead) return null;
     return g.doc_id + ':s' + ++snapshotSeq;
@@ -422,6 +635,7 @@ export function buildObserverInstallJs(opts = {}) {
     g.baselines.clear();
     refs = new WeakMap();
     refNodes.clear();
+    refKeys.clear();
     snapshotSeq = 0;
     snapshots.clear();
     if (window[opts.key] === g) {
@@ -490,12 +704,24 @@ function jsStringLiteral(value) {
 /**
  * Build the ref-resolve expression, for tests and debugging. Evaluates to
  * `{ ok: true, found: true, tag }` when `ref` names an element of the current
- * document that is still connected, `{ ok: true, found: false }` when it is
- * unknown or stale, or `{ ok: false, reason: 'observer-unavailable' }`.
+ * document that is still connected — plus `reresolved: true` when the node was
+ * gone and the ref was just rebound by its semantic key —
+ * `{ ok: true, found: false }` when it is unknown or stale, or
+ * `{ ok: false, reason: 'observer-unavailable' }`.
  */
 export function buildObserverRefResolveJs(ref) {
     const refJson = jsStringLiteral(typeof ref === 'string' ? ref : '');
-    return callInstance(`((el) => el ? { ok: true, found: true, tag: el.localName || String(el.nodeName).toLowerCase() } : { ok: true, found: false })(g.resolveRef(${refJson}))`);
+    return callInstance(`((r) => { if (!r) return { ok: true, found: false }; const tag = r.el.localName || String(r.el.nodeName).toLowerCase(); return r.reresolved ? { ok: true, found: true, tag: tag, reresolved: true } : { ok: true, found: true, tag: tag }; })(g.resolveRefDetailed(${refJson}))`);
+}
+/**
+ * Build the semantic-key read expression. Evaluates to `{ ok: true, key }`
+ * with the `{ role, name, path }` stored when `ref` was issued, `{ ok: true,
+ * key: null }` for a ref this document instance does not know, or
+ * `{ ok: false, reason: 'observer-unavailable' }`.
+ */
+export function buildObserverSemanticKeyJs(ref) {
+    const refJson = jsStringLiteral(typeof ref === 'string' ? ref : '');
+    return callInstance(`({ ok: true, key: g.keyForRef(${refJson}) })`);
 }
 /**
  * Build the teardown expression: disconnects every observer, restores the

package/dist/extension/inpage/observer.js.map

@@ -1 +1 @@
-{"version":3,"file":"observer.js","sourceRoot":"","sources":["../../src/inpage/observer.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"observer.js","sourceRoot":"","sources":["../../src/inpage/observer.ts"],"names":[],"mappings":"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"}

package/dist/extension/manifest.json

@@ -1,7 +1,7 @@
 {
   "manifest_version": 3,
   "name": "browser-link",
-  "version": "0.36.0",
+  "version": "0.38.0",
   "description": "Bridge between Chrome and an MCP client (Claude Code, OpenCode, GitHub Copilot CLI, …). Per-tab manual activation.",
   "permissions": [
     "debugger",

package/dist/manual/core.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The hand-written core of the agent manual: the part every agent must see
+ * before its first browser call. It is rendered first in the MCP
+ * `initialize.instructions` (hosts truncate that text; Claude Code cut it at
+ * ~4,090 characters) and first in the installed instructions block, so it is
+ * pinned at 3,800 characters by `manual.test.ts`.
+ *
+ * Rule for editing: every line must change what the agent does next. Depth
+ * lives in the per-tool `doc` blocks and in `topics.ts`, reachable through
+ * `browser.manual`.
+ *
+ * The bilingual phrases in the trigger list are DATA (what users actually
+ * type), not instructions; tests pin them verbatim.
+ */
+export interface CoreOptions {
+    /** One line placed before everything else, e.g. an outdated-block notice. */
+    notice?: string;
+}
+/** The core as one string; the optional notice is its first line. */
+export declare function renderCore(opts?: CoreOptions): string;

package/dist/manual/core.js

@@ -0,0 +1,71 @@
+/**
+ * The hand-written core of the agent manual: the part every agent must see
+ * before its first browser call. It is rendered first in the MCP
+ * `initialize.instructions` (hosts truncate that text; Claude Code cut it at
+ * ~4,090 characters) and first in the installed instructions block, so it is
+ * pinned at 3,800 characters by `manual.test.ts`.
+ *
+ * Rule for editing: every line must change what the agent does next. Depth
+ * lives in the per-tool `doc` blocks and in `topics.ts`, reachable through
+ * `browser.manual`.
+ *
+ * The bilingual phrases in the trigger list are DATA (what users actually
+ * type), not instructions; tests pin them verbatim.
+ */
+import { TOPIC_NAMES } from './topics.js';
+const CORE_LINES = [
+    '## browser-link — reflex protocol (ALWAYS ACTIVE)',
+    '',
+    '`browser.*` tools see only the Chrome tabs the user connected through the companion extension. Never reason about page state you have not seen.',
+    '',
+    '### TRIGGER LIST — call before responding when ANY apply',
+    '',
+    'User mentions any of these (English or Spanish):',
+    '- "the button doesn\'t work" / "no anda el botón" / "no funciona X"',
+    '- "broken layout" / "está roto" / "se ve mal" / "looks wrong"',
+    '- "check if X works" / "fíjate si anda X" / "¿anda X?" / "does X work?"',
+    '- "the page" / "la página" / "la web" / "the site"',
+    '- "open this in the browser" / "abrí esto en el navegador" / "navegá a"',
+    '- a UI element, web app name, URL, browser tab, layout, dialog, form',
+    '→ call `browser.list_tabs` FIRST. A tab with a `map` field: read its `inline` map when present, otherwise call `browser.map.recall` BEFORE `browser.snapshot`.',
+    '',
+    '- Before suggesting a UI code change or a click, `browser.snapshot` and verify the element exists.',
+    '- "Tab not connected" → `browser.events` for the renamed tab_id, then retry.',
+    '- SELF-CHECK after each user message: is this about something visible in a browser? Did I run `browser.list_tabs`?',
+    '',
+    '### Success is not proof',
+    '',
+    'An `ok` result can still mean the action missed. Check these fields:',
+    '- `hit_element` on `click` (and flow click steps) appears when a `pointer-events: none` target passes the click on, or on `force: true`; it names the real receiver: if it is not your target or inside it, the click missed → do not proceed; `find` the element that receives clicks by its text.',
+    '- `retargeted` error on `click`: the click would land on an ancestor of your target (clipped or covered by its own container) → scroll or expand the container, or `find` the element that receives clicks; `force: true` clicks there anyway.',
+    '- `settle.settled: false` or `mutation_count: 0`: quiet is not effect → `expect` or `wait_for` the effect you need.',
+    '- `since_status` on `snapshot`: you received a full snapshot → keep its new `snapshot_id`.',
+    '- `reresolved: true`: the node was replaced and re-found → fine.',
+    '- `ref-stale` → take a fresh `snapshot`/`find`; never retry the same ref.',
+    '- `wait_for` returning `matched: false` is not an error → decide.',
+    '',
+    '### Habits',
+    '',
+    '- One full `snapshot` per view, then `snapshot({ since: snapshot_id })` for every later look.',
+    '- Act on the `ref` from the last `snapshot`/`find`, not a selector copied earlier; never inject attributes with `evaluate` to build selectors.',
+    '- Locate with `find` by text (`role` optional). `evaluate` only reads, never clicks or types: synthetic events are `isTrusted: false`, apps ignore them, and nothing records what happened.',
+    '- Downloads only through `browser.download` (`url` or `selector`), never a click on a download control.',
+    '- Pass `expect` to `click`/`type`/`press` when the effect matters.',
+    '',
+    '### Shared tabs and cdp-direct',
+    '',
+    '- Several agents can share the bridge: `browser.claim_tab` before a multi-step flow, `browser.release_tab` after.',
+    '- On a claim conflict do not spin-retry: use another tab or ask the user.',
+    '- `cdp:` tabs (`transport: "cdp"`) lack drag, console, network, network_body, canvas_screenshot, dialog_respond, set_permission, wait_for_tab and download by selector.',
+    '- "cdp-direct is disabled" / "requires an active grant" → relay `browser-link config set cdp-direct.enabled true` or `browser-link cdp allow` to the user; there is no workaround.',
+    '',
+    '### Depth on demand',
+    '',
+    `\`browser.manual()\` lists tools and topics; \`browser.manual({ tool: "browser.click" })\` gives one tool's full doc; \`browser.manual({ topic })\` gives one topic: ${TOPIC_NAMES.join(', ')}.`,
+];
+/** The core as one string; the optional notice is its first line. */
+export function renderCore(opts = {}) {
+    const lines = opts.notice ? [opts.notice, '', ...CORE_LINES] : CORE_LINES;
+    return lines.join('\n');
+}
+//# sourceMappingURL=core.js.map

package/dist/manual/core.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"core.js","sourceRoot":"","sources":["../../src/manual/core.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE1C,MAAM,UAAU,GAAsB;IACpC,mDAAmD;IACnD,EAAE;IACF,iJAAiJ;IACjJ,EAAE;IACF,0DAA0D;IAC1D,EAAE;IACF,kDAAkD;IAClD,qEAAqE;IACrE,+DAA+D;IAC/D,yEAAyE;IACzE,oDAAoD;IACpD,yEAAyE;IACzE,sEAAsE;IACtE,gKAAgK;IAChK,EAAE;IACF,oGAAoG;IACpG,8EAA8E;IAC9E,oHAAoH;IACpH,EAAE;IACF,0BAA0B;IAC1B,EAAE;IACF,sEAAsE;IACtE,qSAAqS;IACrS,gPAAgP;IAChP,qHAAqH;IACrH,4FAA4F;IAC5F,kEAAkE;IAClE,2EAA2E;IAC3E,mEAAmE;IACnE,EAAE;IACF,YAAY;IACZ,EAAE;IACF,+FAA+F;IAC/F,gJAAgJ;IAChJ,6LAA6L;IAC7L,yGAAyG;IACzG,oEAAoE;IACpE,EAAE;IACF,gCAAgC;IAChC,EAAE;IACF,mHAAmH;IACnH,2EAA2E;IAC3E,yKAAyK;IACzK,oLAAoL;IACpL,EAAE;IACF,qBAAqB;IACrB,EAAE;IACF,wKAAwK,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG;CAClM,CAAC;AAOF,qEAAqE;AACrE,MAAM,UAAU,UAAU,CAAC,OAAoB,EAAE;IAC/C,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,EAAE,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC;IAC1E,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC"}

package/dist/manual/render.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Renderers for the agent manual. One source, three outputs:
+ *
+ *  - `renderServerInstructions` — the MCP `initialize.instructions` text:
+ *    the core first (hosts truncate this text, so what comes first is what
+ *    arrives), then one section per tool rendered from its `doc` block.
+ *  - `renderInstallBody` — the body of the block `browser-link instructions
+ *    install` writes into each client's instructions file: the core, then
+ *    the topics an agent needs every session.
+ *  - `renderTopic` (in `topics.ts`) — one topic on demand.
+ */
+import type { ToolDefinition } from '../tools/types.js';
+import { type CoreOptions } from './core.js';
+/** Render a single tool's documentation as a markdown section. Skips
+ * tools without a `doc` block. */
+export declare function renderTool(def: ToolDefinition): string | null;
+/** The MCP `initialize.instructions` text: core, then `## Tools` and one
+ * section per documented tool, browser tools first, then map tools. */
+export declare function renderServerInstructions(opts?: CoreOptions): string;
+/** The installed block body as single lines: the core, then the install
+ * topics, each separated by one blank line. */
+export declare function renderInstallBody(): string[];

package/dist/manual/render.js

@@ -0,0 +1,56 @@
+/**
+ * Renderers for the agent manual. One source, three outputs:
+ *
+ *  - `renderServerInstructions` — the MCP `initialize.instructions` text:
+ *    the core first (hosts truncate this text, so what comes first is what
+ *    arrives), then one section per tool rendered from its `doc` block.
+ *  - `renderInstallBody` — the body of the block `browser-link instructions
+ *    install` writes into each client's instructions file: the core, then
+ *    the topics an agent needs every session.
+ *  - `renderTopic` (in `topics.ts`) — one topic on demand.
+ */
+import { BROWSER_TOOL_DEFINITIONS } from '../tools/browser-definitions.js';
+import { MAP_TOOL_DEFINITIONS } from '../map/tools.js';
+import { renderCore } from './core.js';
+import { renderTopic } from './topics.js';
+/** Topics embedded in the installed block, in order. The block is read in
+ * full every session, so these are the ones worth that cost. */
+const INSTALL_TOPICS = ['token-efficiency', 'downloads', 'flows', 'map'];
+/** Render a single tool's documentation as a markdown section. Skips
+ * tools without a `doc` block. */
+export function renderTool(def) {
+    if (!def.doc)
+        return null;
+    const { purpose, when_to_use, gotchas, example } = def.doc;
+    const lines = [`### ${def.name}`, '', purpose, '', '**When to use:**'];
+    for (const w of when_to_use)
+        lines.push(`- ${w}`);
+    if (gotchas && gotchas.length > 0) {
+        lines.push('', '**Gotchas:**');
+        for (const g of gotchas)
+            lines.push(`- ${g}`);
+    }
+    if (example !== undefined && example !== '') {
+        lines.push('', '**Example:**', '```', example, '```');
+    }
+    return lines.join('\n');
+}
+/** The MCP `initialize.instructions` text: core, then `## Tools` and one
+ * section per documented tool, browser tools first, then map tools. */
+export function renderServerInstructions(opts = {}) {
+    const all = [...BROWSER_TOOL_DEFINITIONS, ...MAP_TOOL_DEFINITIONS];
+    const sections = [renderCore(opts), '', '## Tools'];
+    for (const def of all) {
+        const rendered = renderTool(def);
+        if (rendered)
+            sections.push('', rendered);
+    }
+    return sections.join('\n');
+}
+/** The installed block body as single lines: the core, then the install
+ * topics, each separated by one blank line. */
+export function renderInstallBody() {
+    const text = [renderCore({}), ...INSTALL_TOPICS.map(renderTopic)].join('\n\n');
+    return text.split('\n');
+}
+//# sourceMappingURL=render.js.map

package/dist/manual/render.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"render.js","sourceRoot":"","sources":["../../src/manual/render.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,wBAAwB,EAAE,MAAM,iCAAiC,CAAC;AAC3E,OAAO,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAEvD,OAAO,EAAE,UAAU,EAAoB,MAAM,WAAW,CAAC;AACzD,OAAO,EAAE,WAAW,EAAkB,MAAM,aAAa,CAAC;AAE1D;gEACgE;AAChE,MAAM,cAAc,GAAyB,CAAC,kBAAkB,EAAE,WAAW,EAAE,OAAO,EAAE,KAAK,CAAC,CAAC;AAE/F;kCACkC;AAClC,MAAM,UAAU,UAAU,CAAC,GAAmB;IAC5C,IAAI,CAAC,GAAG,CAAC,GAAG;QAAE,OAAO,IAAI,CAAC;IAC1B,MAAM,EAAE,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,GAAG,CAAC,GAAG,CAAC;IAC3D,MAAM,KAAK,GAAa,CAAC,OAAO,GAAG,CAAC,IAAI,EAAE,EAAE,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE,kBAAkB,CAAC,CAAC;IACjF,KAAK,MAAM,CAAC,IAAI,WAAW;QAAE,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IAClD,IAAI,OAAO,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAClC,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,cAAc,CAAC,CAAC;QAC/B,KAAK,MAAM,CAAC,IAAI,OAAO;YAAE,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IAChD,CAAC;IACD,IAAI,OAAO,KAAK,SAAS,IAAI,OAAO,KAAK,EAAE,EAAE,CAAC;QAC5C,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,cAAc,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,CAAC,CAAC;IACxD,CAAC;IACD,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED;uEACuE;AACvE,MAAM,UAAU,wBAAwB,CAAC,OAAoB,EAAE;IAC7D,MAAM,GAAG,GAAqB,CAAC,GAAG,wBAAwB,EAAE,GAAG,oBAAoB,CAAC,CAAC;IACrF,MAAM,QAAQ,GAAa,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,UAAU,CAAC,CAAC;IAC9D,KAAK,MAAM,GAAG,IAAI,GAAG,EAAE,CAAC;QACtB,MAAM,QAAQ,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC;QACjC,IAAI,QAAQ;YAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,EAAE,QAAQ,CAAC,CAAC;IAC5C,CAAC;IACD,OAAO,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC7B,CAAC;AAED;+CAC+C;AAC/C,MAAM,UAAU,iBAAiB;IAC/B,MAAM,IAAI,GAAG,CAAC,UAAU,CAAC,EAAE,CAAC,EAAE,GAAG,cAAc,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAC/E,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC"}

package/dist/manual/status.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Read-only status of the installed instructions block, per client, shared
+ * by the primary's start-time notice (`server.ts`) and the `browser.manual`
+ * index. Detection only reads the clients' instructions files through each
+ * installer's `detect()` (home-guarded as the installers already are); this
+ * module never writes anything.
+ */
+import { type ClientId, type InstructionsInstaller, type InstructionsState } from '../agent-instructions/index.js';
+export interface ClientInstructionsStatus {
+    id: ClientId;
+    displayName: string;
+    state: InstructionsState;
+}
+/** Detect every client's block. A client whose detection throws (permissions,
+ * EBADF) is skipped, never fatal. */
+export declare function detectInstructionsStatus(installers?: readonly InstructionsInstaller[]): ClientInstructionsStatus[];
+/** One status line for the `browser.manual` index. */
+export declare function formatClientStatus(s: ClientInstructionsStatus, version?: string): string;
+/** The one-line notice placed before the core when a client's block exists
+ * and is older than the server (`installed-outdated`); `undefined` otherwise.
+ * A client without a block (`not-installed`, `no-file`) is a choice and a
+ * `corrupt` file is the CLI's business: neither ever produces a notice. */
+export declare function instructionsNotice(statuses: readonly ClientInstructionsStatus[], version?: string): string | undefined;

package/dist/manual/status.js

@@ -0,0 +1,52 @@
+/**
+ * Read-only status of the installed instructions block, per client, shared
+ * by the primary's start-time notice (`server.ts`) and the `browser.manual`
+ * index. Detection only reads the clients' instructions files through each
+ * installer's `detect()` (home-guarded as the installers already are); this
+ * module never writes anything.
+ */
+import { VERSION } from '../version.js';
+import { INSTRUCTIONS_INSTALLERS, } from '../agent-instructions/index.js';
+/** Detect every client's block. A client whose detection throws (permissions,
+ * EBADF) is skipped, never fatal. */
+export function detectInstructionsStatus(installers = INSTRUCTIONS_INSTALLERS) {
+    const out = [];
+    for (const installer of installers) {
+        try {
+            const { state } = installer.detect();
+            out.push({ id: installer.id, displayName: installer.displayName, state });
+        }
+        catch {
+            /* best effort: an unreadable client is left out */
+        }
+    }
+    return out;
+}
+const v = (version) => (version === null ? 'unversioned' : `v${version}`);
+/** One status line for the `browser.manual` index. */
+export function formatClientStatus(s, version = VERSION) {
+    const { state } = s;
+    switch (state.kind) {
+        case 'installed':
+            return `${s.displayName}: installed ${v(state.version)}`;
+        case 'installed-outdated':
+            return `${s.displayName}: installed-outdated ${v(state.version)} → v${version}: run browser-link instructions install`;
+        case 'corrupt':
+            return `${s.displayName}: corrupt (${state.reason})`;
+        default:
+            return `${s.displayName}: ${state.kind}`;
+    }
+}
+/** The one-line notice placed before the core when a client's block exists
+ * and is older than the server (`installed-outdated`); `undefined` otherwise.
+ * A client without a block (`not-installed`, `no-file`) is a choice and a
+ * `corrupt` file is the CLI's business: neither ever produces a notice. */
+export function instructionsNotice(statuses, version = VERSION) {
+    for (const s of statuses) {
+        if (s.state.kind === 'installed-outdated') {
+            return `Your browser-link instructions block is installed-outdated (installed ${v(s.state.version)}, server v${version}): run \`browser-link instructions install\` and restart the client.`;
+        }
+    }
+    return undefined;
+}
+//# sourceMappingURL=status.js.map

package/dist/manual/status.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"status.js","sourceRoot":"","sources":["../../src/manual/status.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AACxC,OAAO,EACL,uBAAuB,GAIxB,MAAM,gCAAgC,CAAC;AAQxC;qCACqC;AACrC,MAAM,UAAU,wBAAwB,CACtC,aAA+C,uBAAuB;IAEtE,MAAM,GAAG,GAA+B,EAAE,CAAC;IAC3C,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;QACnC,IAAI,CAAC;YACH,MAAM,EAAE,KAAK,EAAE,GAAG,SAAS,CAAC,MAAM,EAAE,CAAC;YACrC,GAAG,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,SAAS,CAAC,EAAE,EAAE,WAAW,EAAE,SAAS,CAAC,WAAW,EAAE,KAAK,EAAE,CAAC,CAAC;QAC5E,CAAC;QAAC,MAAM,CAAC;YACP,mDAAmD;QACrD,CAAC;IACH,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,MAAM,CAAC,GAAG,CAAC,OAAsB,EAAU,EAAE,CAAC,CAAC,OAAO,KAAK,IAAI,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,IAAI,OAAO,EAAE,CAAC,CAAC;AAEjG,sDAAsD;AACtD,MAAM,UAAU,kBAAkB,CAAC,CAA2B,EAAE,OAAO,GAAG,OAAO;IAC/E,MAAM,EAAE,KAAK,EAAE,GAAG,CAAC,CAAC;IACpB,QAAQ,KAAK,CAAC,IAAI,EAAE,CAAC;QACnB,KAAK,WAAW;YACd,OAAO,GAAG,CAAC,CAAC,WAAW,eAAe,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC;QAC3D,KAAK,oBAAoB;YACvB,OAAO,GAAG,CAAC,CAAC,WAAW,wBAAwB,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,OAAO,yCAAyC,CAAC;QACzH,KAAK,SAAS;YACZ,OAAO,GAAG,CAAC,CAAC,WAAW,cAAc,KAAK,CAAC,MAAM,GAAG,CAAC;QACvD;YACE,OAAO,GAAG,CAAC,CAAC,WAAW,KAAK,KAAK,CAAC,IAAI,EAAE,CAAC;IAC7C,CAAC;AACH,CAAC;AAED;;;2EAG2E;AAC3E,MAAM,UAAU,kBAAkB,CAChC,QAA6C,EAC7C,OAAO,GAAG,OAAO;IAEjB,KAAK,MAAM,CAAC,IAAI,QAAQ,EAAE,CAAC;QACzB,IAAI,CAAC,CAAC,KAAK,CAAC,IAAI,KAAK,oBAAoB,EAAE,CAAC;YAC1C,OAAO,yEAAyE,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,aAAa,OAAO,sEAAsE,CAAC;QAC/L,CAAC;IACH,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/dist/manual/tool.d.ts

@@ -0,0 +1,20 @@
+/**
+ * `browser.manual` — the agent manual on demand. Server-only: it reads the
+ * tool definitions, the topics and the instructions-block status, never a
+ * tab or the bridge.
+ *
+ *  - no arguments → the index: version, block status per client, one line
+ *    per tool, the topic list;
+ *  - `{ tool }` → that tool's `doc` plus one line per `inputSchema` property;
+ *  - `{ topic }` → one hand-written topic.
+ */
+import { type ClientInstructionsStatus } from './status.js';
+export interface ManualOptions {
+    /** Current block status per client (read-only detection). */
+    statuses: () => readonly ClientInstructionsStatus[];
+}
+/** Text up to and including the first sentence end followed by a capital
+ * letter or the end of the text, so "e.g. `x`" does not cut it short. */
+export declare function firstSentence(text: string): string;
+/** Render `browser.manual`'s answer for `args`; throws on invalid input. */
+export declare function renderManual(args: unknown, opts: ManualOptions): string;