@jobshimo/browser-link 0.42.0 → 0.43.0

package/dist/manual/topics.js

@@ -37,7 +37,7 @@ export const TOPICS = {
     },
     map: {
         title: 'The persistent map — identifying the app, mechanisms and pitfalls',
-        body: lines('The map is a private, per-machine SQLite cache of UI structure in the data dir ($XDG_DATA_HOME/browser-link on Linux, ~/Library/Application Support/browser-link on macOS, %APPDATA%/browser-link on Windows; override with $BROWSER_LINK_DATA_DIR). It is never written to a repo.', '- `origin` = scheme://host:port of the tab. `app_key` tells apart apps that share an origin; omit it on the first save (derived from the page title) and fix a poor guess with `browser.map.rename_app`.', '- After a non-trivial flow worked end-to-end, `browser.map.save` the selectors you just executed, optionally with `flows` recipes that use placeholders (`<QUERY>`, `<NAME>`) for every free-text value.', '- Save how the app behaves underneath too: `mechanisms: [{ key, description }]` ("a GET of an item URL marks it complete server-side") and `pitfalls: [{ key, description, symptom? }]` ("click on the next link returns ok but does not navigate"). A pitfall costs far more to rediscover than a selector; `recall` returns pitfalls first.', '- A `find` single match carries `semantic_key`. When the selector you save is structural (`:nth-of-type`), save that `semantic_key` in the payload next to it, and use `browser.find({ key })` when recall returns `prefer: "semantic_key"`. Never save a key for an `ambiguous` entry.', '- Never save a `ref` (refs die with the document) or an `ambiguous` selector, and never domain data: no IDs, names, dates or real values.'),
+        body: lines('The map is a private per-machine SQLite cache of UI structure in the data dir ($BROWSER_LINK_DATA_DIR overrides it), never in a repo.', '- `origin` = scheme://host:port of the tab. `app_key` tells apart apps that share an origin; omit it on the first save (from the page title) and fix a poor guess with `browser.map.rename_app`.', '- After a non-trivial flow worked end-to-end, `browser.map.save` the selectors you just executed, optionally with `flows` recipes that use placeholders (`<QUERY>`, `<NAME>`) for every free-text value.', '- Save how the app behaves underneath too: `mechanisms: [{ key, description }]` ("a GET of an item URL marks it complete server-side") and `pitfalls: [{ key, description, symptom? }]` ("click on the next link returns ok but does not navigate"). A pitfall costs far more to rediscover than a selector; `recall` returns pitfalls first.', '- A `find` single match carries `semantic_key`. When the selector you save is structural (`:nth-of-type`), save that `semantic_key` in the payload next to it, and use `browser.find({ key })` when recall returns `prefer: "semantic_key"`. Never save a key for an `ambiguous` entry.', '- Never save a `ref` or an `ambiguous` selector, and never domain data: no IDs, names, dates or real values.', '- It learns alone: `recall`/`list_tabs` show `learned` counts per selector or `find` key, failed first: avoid those. Never values. Off: `browser-link config set map-learning off`.'),
     },
     'token-efficiency': {
         title: 'Token-efficient patterns and reading data',
@@ -45,7 +45,7 @@ export const TOPICS = {
     },
     'multi-agent': {
         title: 'Sharing tabs with other agents (multi-agent mode)',
-        body: lines('Several MCP clients can share one bridge; a cooperative claim layer keeps two agents off the same tab.', '- Action tools (`browser.click`, `browser.type`, `browser.navigate`, `browser.evaluate`) auto-claim a free tab on first use. If another agent holds it they fail naming the owner: ask the user whose tab it is, or use a different one.', '- Read tools (`browser.snapshot`, `browser.state`, `browser.console`, `browser.network`, `browser.network_body`, `browser.events`, `browser.ping`) ignore claims.', '- Give `browser.claim_tab` a stable `label` ("claude-code", "opencode"); claims also end on disconnect and after the inactivity TTL. The label is display only: ownership rests on the IPC session id, not on what an agent calls itself.', '- One server process is the primary. A newer browser-link that starts displaces an older primary (it reads `GET /version` on the bridge port, then stops the old process), and the extension reconnects by itself.', '- A `list_tabs` hint "server running X, installed Y" means the package was updated under a live server: ask the user to run `browser-link stop` and restart the agent, or to click "Repair connection" in the extension popup. Do not kill processes yourself.'),
+        body: lines('Several MCP clients can share one bridge; a cooperative claim layer keeps two agents off the same tab.', '- Action tools (`browser.click`, `browser.type`, `browser.navigate`, `browser.evaluate`) auto-claim a free tab on first use. If another agent holds it they fail naming the owner: ask the user whose tab it is, or use a different one.', '- Read tools (`browser.snapshot`, `browser.state`, `browser.console`, `browser.network`, `browser.network_body`, `browser.events`, `browser.ping`) ignore claims.', '- Give `browser.claim_tab` a stable `label` ("claude-code", "opencode"); claims also end on disconnect and after the inactivity TTL. The label is display only: ownership rests on the IPC session id, not on what an agent calls itself.', '- One server process is the primary. A newer browser-link that starts displaces an older primary (it reads `GET /version` on the bridge port, then stops the old process), and the extension reconnects by itself.', '- `browser.activity({ summary: true })` is the friction report: errors and flagged calls (`not-found`, `unsettled`, flow or download `timeout`...) by flag, by tool, top failing selectors and one line per agent session; narrow it with `since`, `since_id` or `agent_id`.', '- A `list_tabs` hint "server running X, installed Y" means the package was updated under a live server: ask the user to run `browser-link stop` and restart the agent, or to click "Repair connection" in the extension popup. Do not kill processes yourself.'),
     },
     'cdp-direct': {
         title: 'cdp-direct tabs (optional, off by default, human-gated)',

package/dist/manual/topics.js.map

@@ -1 +1 @@
-{"version":3,"file":"topics.js","sourceRoot":"","sources":["../../src/manual/topics.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,MAAM,CAAC,MAAM,WAAW,GAAG;IACzB,WAAW;IACX,QAAQ;IACR,YAAY;IACZ,OAAO;IACP,KAAK;IACL,kBAAkB;IAClB,aAAa;IACb,YAAY;CACJ,CAAC;AASX,MAAM,KAAK,GAAG,CAAC,GAAG,CAAW,EAAU,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAEvD,MAAM,CAAC,MAAM,MAAM,GAA6B;IAC9C,SAAS,EAAE;QACT,KAAK,EAAE,2CAA2C;QAClD,IAAI,EAAE,KAAK,CACT,kOAAkO,EAClO,+OAA+O,EAC/O,0EAA0E,EAC1E,uHAAuH,CACxH;KACF;IACD,MAAM,EAAE;QACN,KAAK,EAAE,0DAA0D;QACjE,IAAI,EAAE,KAAK,CACT,+OAA+O,EAC/O,oPAAoP,EACpP,oSAAoS,CACrS;KACF;IACD,UAAU,EAAE;QACV,KAAK,EAAE,mCAAmC;QAC1C,IAAI,EAAE,KAAK,CACT,wKAAwK,EACxK,oLAAoL,EACpL,oFAAoF,CACrF;KACF;IACD,KAAK,EAAE;QACL,KAAK,EAAE,wDAAwD;QAC/D,IAAI,EAAE,KAAK,CACT,gaAAga,EACha,EAAE,EACF,iJAAiJ,EACjJ,6HAA6H,EAC7H,iOAAiO,EACjO,gWAAgW,EAChW,qIAAqI,EACrI,sXAAsX,EACtX,kMAAkM,EAClM,EAAE,EACF,6aAA6a,EAC7a,EAAE,EACF,2XAA2X,EAC3X,kNAAkN,EAClN,qGAAqG,EACrG,uGAAuG,EACvG,mLAAmL,CACpL;KACF;IACD,GAAG,EAAE;QACH,KAAK,EAAE,mEAAmE;QAC1E,IAAI,EAAE,KAAK,CACT,qRAAqR,EACrR,0MAA0M,EAC1M,0MAA0M,EAC1M,+UAA+U,EAC/U,yRAAyR,EACzR,2IAA2I,CAC5I;KACF;IACD,kBAAkB,EAAE;QAClB,KAAK,EAAE,2CAA2C;QAClD,IAAI,EAAE,KAAK,CACT,kGAAkG,EAClG,qRAAqR,EACrR,iJAAiJ,EACjJ,gNAAgN,EAChN,wFAAwF,EACxF,2HAA2H,EAC3H,iGAAiG,EACjG,sPAAsP,EACtP,uaAAua,EACva,sQAAsQ,EACtQ,+HAA+H,EAC/H,2QAA2Q,EAC3Q,oNAAoN,CACrN;KACF;IACD,aAAa,EAAE;QACb,KAAK,EAAE,mDAAmD;QAC1D,IAAI,EAAE,KAAK,CACT,wGAAwG,EACxG,0OAA0O,EAC1O,mKAAmK,EACnK,2OAA2O,EAC3O,oNAAoN,EACpN,gQAAgQ,CACjQ;KACF;IACD,YAAY,EAAE;QACZ,KAAK,EAAE,yDAAyD;QAChE,IAAI,EAAE,KAAK,CACT,yOAAyO,EACzO,gIAAgI,EAChI,qHAAqH,EACrH,0GAA0G,CAC3G;KACF;CACF,CAAC;AAEF,wEAAwE;AACxE,MAAM,UAAU,WAAW,CAAC,IAAe;IACzC,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC;IAC3B,OAAO,OAAO,KAAK,CAAC,KAAK,OAAO,KAAK,CAAC,IAAI,EAAE,CAAC;AAC/C,CAAC"}
+{"version":3,"file":"topics.js","sourceRoot":"","sources":["../../src/manual/topics.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,MAAM,CAAC,MAAM,WAAW,GAAG;IACzB,WAAW;IACX,QAAQ;IACR,YAAY;IACZ,OAAO;IACP,KAAK;IACL,kBAAkB;IAClB,aAAa;IACb,YAAY;CACJ,CAAC;AASX,MAAM,KAAK,GAAG,CAAC,GAAG,CAAW,EAAU,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAEvD,MAAM,CAAC,MAAM,MAAM,GAA6B;IAC9C,SAAS,EAAE;QACT,KAAK,EAAE,2CAA2C;QAClD,IAAI,EAAE,KAAK,CACT,kOAAkO,EAClO,+OAA+O,EAC/O,0EAA0E,EAC1E,uHAAuH,CACxH;KACF;IACD,MAAM,EAAE;QACN,KAAK,EAAE,0DAA0D;QACjE,IAAI,EAAE,KAAK,CACT,+OAA+O,EAC/O,oPAAoP,EACpP,oSAAoS,CACrS;KACF;IACD,UAAU,EAAE;QACV,KAAK,EAAE,mCAAmC;QAC1C,IAAI,EAAE,KAAK,CACT,wKAAwK,EACxK,oLAAoL,EACpL,oFAAoF,CACrF;KACF;IACD,KAAK,EAAE;QACL,KAAK,EAAE,wDAAwD;QAC/D,IAAI,EAAE,KAAK,CACT,gaAAga,EACha,EAAE,EACF,iJAAiJ,EACjJ,6HAA6H,EAC7H,iOAAiO,EACjO,gWAAgW,EAChW,qIAAqI,EACrI,sXAAsX,EACtX,kMAAkM,EAClM,EAAE,EACF,6aAA6a,EAC7a,EAAE,EACF,2XAA2X,EAC3X,kNAAkN,EAClN,qGAAqG,EACrG,uGAAuG,EACvG,mLAAmL,CACpL;KACF;IACD,GAAG,EAAE;QACH,KAAK,EAAE,mEAAmE;QAC1E,IAAI,EAAE,KAAK,CACT,uIAAuI,EACvI,kMAAkM,EAClM,0MAA0M,EAC1M,+UAA+U,EAC/U,yRAAyR,EACzR,8GAA8G,EAC9G,qLAAqL,CACtL;KACF;IACD,kBAAkB,EAAE;QAClB,KAAK,EAAE,2CAA2C;QAClD,IAAI,EAAE,KAAK,CACT,kGAAkG,EAClG,qRAAqR,EACrR,iJAAiJ,EACjJ,gNAAgN,EAChN,wFAAwF,EACxF,2HAA2H,EAC3H,iGAAiG,EACjG,sPAAsP,EACtP,uaAAua,EACva,sQAAsQ,EACtQ,+HAA+H,EAC/H,2QAA2Q,EAC3Q,oNAAoN,CACrN;KACF;IACD,aAAa,EAAE;QACb,KAAK,EAAE,mDAAmD;QAC1D,IAAI,EAAE,KAAK,CACT,wGAAwG,EACxG,0OAA0O,EAC1O,mKAAmK,EACnK,2OAA2O,EAC3O,oNAAoN,EACpN,8QAA8Q,EAC9Q,gQAAgQ,CACjQ;KACF;IACD,YAAY,EAAE;QACZ,KAAK,EAAE,yDAAyD;QAChE,IAAI,EAAE,KAAK,CACT,yOAAyO,EACzO,gIAAgI,EAChI,qHAAqH,EACrH,0GAA0G,CAC3G;KACF;CACF,CAAC;AAEF,wEAAwE;AACxE,MAAM,UAAU,WAAW,CAAC,IAAe;IACzC,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC;IAC3B,OAAO,OAAO,KAAK,CAAC,KAAK,OAAO,KAAK,CAAC,IAAI,EAAE,CAAC;AAC/C,CAAC"}

package/dist/map/db.js

@@ -121,6 +121,32 @@ function runMigrations(db) {
     );
 
     CREATE INDEX IF NOT EXISTS idx_insights_app ON insights(app_id);
+  `);
+    // v0.43.0: what the map learned from use, with no bookkeeping by the agent
+    // (see map/learning.ts). One row per durable target (a CSS selector or a
+    // `browser.find` semantic key, never typed text or values) per action per
+    // route, with ok/fail counters. Additive CREATE-IF-NOT-EXISTS like every
+    // table above: an older DB picks it up on next open, no row is rewritten.
+    // `last_reason` holds a fixed enum (`LEARNED_REASONS` in learning.ts),
+    // enforced in code rather than by a CHECK, so widening the enum later
+    // never means rebuilding this table (see the `insights` comment).
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS selector_outcomes (
+      id INTEGER PRIMARY KEY,
+      app_id INTEGER NOT NULL REFERENCES apps(id) ON DELETE CASCADE,
+      url_pattern TEXT NOT NULL,
+      target TEXT NOT NULL,
+      target_kind TEXT NOT NULL CHECK (target_kind IN ('selector', 'key')),
+      action TEXT NOT NULL,
+      ok_n INTEGER NOT NULL DEFAULT 0,
+      fail_n INTEGER NOT NULL DEFAULT 0,
+      last_reason TEXT,
+      last_ok_at TEXT,
+      last_fail_at TEXT,
+      UNIQUE(app_id, url_pattern, target, target_kind, action)
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_selector_outcomes_app ON selector_outcomes(app_id);
   `);
     // v0.20.0: normalize apps.origin rows written before the write path
     // canonicalized origins (see origin.ts). Before this release, save

package/dist/map/db.js.map

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

package/dist/map/learning.d.ts

@@ -0,0 +1,81 @@
+import type Database from 'better-sqlite3';
+/**
+ * The map learns from use.
+ *
+ * Every click/type/press/find/wait_for an agent dispatches already tells us
+ * whether a target worked: a thrown `retargeted`, a `find` that resolved with
+ * `matched: false`, a click whose `expect` was met. Until now that evidence
+ * died with the tool result. This module turns it into ok/fail counters per
+ * durable target in the map DB (`selector_outcomes`, see db.ts), so the
+ * `list_tabs` hint and `browser.map.recall` can say "this selector failed
+ * here before" without the agent doing any bookkeeping.
+ *
+ * Privacy rule: the stored target is the CSS selector string or the
+ * `browser.find` semantic key, and nothing else. Typed text, evaluate
+ * expressions, key names and any other value an action carried are never
+ * read here.
+ *
+ * Two layers:
+ *   - `classifyOutcome` is pure: (tool, args, result, error) → verdict.
+ *   - `recordOutcome` persists one verdict; `learnFromDispatch` is the glue
+ *     the dispatcher's `recordOutcome` dep calls, gated by the config switch.
+ */
+/** The fixed failure vocabulary. `last_reason` never holds anything else. */
+export declare const LEARNED_REASONS: readonly ["retargeted", "ref-stale", "expect-failed", "not-found", "multiple-matches", "unmatched", "timeout", "unsettled", "hit-mismatch"];
+export type LearnedReason = (typeof LEARNED_REASONS)[number];
+export type LearnedOutcome = {
+    ok: true;
+} | {
+    ok: false;
+    reason: LearnedReason;
+};
+export type TargetKind = 'selector' | 'key';
+/** Rows kept per app. Past it, the least used row is evicted. */
+export declare const MAX_LEARNED_PER_APP = 200;
+/**
+ * Classify one dispatched call.
+ *
+ * Returns `{ ok: true }`, `{ ok: false, reason }`, or null when there is
+ * nothing to learn: a tool outside click/type/press/find/wait_for, a call
+ * without a durable target, or a result that proves neither success nor
+ * failure (a quiet click with no `expect`: quiet is not effect).
+ */
+export declare function classifyOutcome(tool: string, args: unknown, result: unknown, error: unknown): LearnedOutcome | null;
+export interface RecordOutcomeInput {
+    origin: string;
+    pathname: string;
+    target: string;
+    target_kind: TargetKind;
+    action: string;
+    outcome: LearnedOutcome;
+}
+/**
+ * Persist one verdict: upsert the counters of the (app, route, target,
+ * kind, action) row, then enforce the per-app cap.
+ *
+ * The app is resolved by `resolveLearnerApp`: the most recently seen app
+ * of the origin (the one `list_tabs` and `recall` show), left untouched,
+ * or a new app keyed by the origin host when the origin has none. The tab
+ * title is never an input: a title such as "Inbox (3) - My App" would mint
+ * a fresh app that then hides the saved map.
+ */
+export declare function recordOutcome(db: Database.Database, input: RecordOutcomeInput): void;
+/** What the dispatcher hands the learner after a call settles. */
+export interface DispatchOutcomeContext {
+    tool: string;
+    args: unknown;
+    result: unknown;
+    error: unknown;
+    /** The tab's URL after the call, from the live tab table. */
+    url: string | null;
+    /** The tab's title. Part of the dispatcher contract but deliberately
+     * ignored by the learner: it never resolves apps from or stores titles. */
+    title: string | null;
+}
+/**
+ * The dispatcher's `recordOutcome` dep in production (wired in server.ts).
+ * Classifies first, so calls with nothing to learn cost no config read and
+ * no DB access; then honours the `mapLearningEnabled` switch, read on every
+ * call so `browser-link config set map-learning off` applies at once.
+ */
+export declare function learnFromDispatch(ctx: DispatchOutcomeContext): void;

package/dist/map/learning.js

@@ -0,0 +1,244 @@
+import { loadConfig } from '../config.js';
+import { getDb } from './db.js';
+import { resolveLearnerApp } from './queries.js';
+/**
+ * The map learns from use.
+ *
+ * Every click/type/press/find/wait_for an agent dispatches already tells us
+ * whether a target worked: a thrown `retargeted`, a `find` that resolved with
+ * `matched: false`, a click whose `expect` was met. Until now that evidence
+ * died with the tool result. This module turns it into ok/fail counters per
+ * durable target in the map DB (`selector_outcomes`, see db.ts), so the
+ * `list_tabs` hint and `browser.map.recall` can say "this selector failed
+ * here before" without the agent doing any bookkeeping.
+ *
+ * Privacy rule: the stored target is the CSS selector string or the
+ * `browser.find` semantic key, and nothing else. Typed text, evaluate
+ * expressions, key names and any other value an action carried are never
+ * read here.
+ *
+ * Two layers:
+ *   - `classifyOutcome` is pure: (tool, args, result, error) → verdict.
+ *   - `recordOutcome` persists one verdict; `learnFromDispatch` is the glue
+ *     the dispatcher's `recordOutcome` dep calls, gated by the config switch.
+ */
+/** The fixed failure vocabulary. `last_reason` never holds anything else. */
+export const LEARNED_REASONS = [
+    'retargeted',
+    'ref-stale',
+    'expect-failed',
+    'not-found',
+    'multiple-matches',
+    'unmatched',
+    'timeout',
+    'unsettled',
+    'hit-mismatch',
+];
+/** Rows kept per app. Past it, the least used row is evicted. */
+export const MAX_LEARNED_PER_APP = 200;
+/** Tools whose outcome says something about a target, and the short action
+ * name stored for them. */
+const LEARNABLE_ACTIONS = {
+    'browser.click': 'click',
+    'browser.type': 'type',
+    'browser.press': 'press',
+    'browser.find': 'find',
+    'browser.wait_for': 'wait_for',
+};
+function asRecord(value) {
+    return typeof value === 'object' && value !== null ? value : null;
+}
+/**
+ * The durable target of a call, or null. A selector string counts for every
+ * learnable tool. A semantic key counts only for `browser.find` — on
+ * `browser.press`, `key` is the keyboard key, not an element. A `ref` (or
+ * `find` by text) names no durable target: refs die with the document and
+ * text is a value, so such calls learn nothing.
+ */
+function durableTarget(tool, args) {
+    const a = asRecord(args);
+    if (!a)
+        return null;
+    if (typeof a.selector === 'string' && a.selector.length > 0) {
+        return { target: a.selector, target_kind: 'selector' };
+    }
+    if (tool === 'browser.find') {
+        const key = asRecord(a.key);
+        if (key) {
+            // Fixed field order so the same key always yields the same row.
+            return {
+                target: JSON.stringify({ role: key.role, name: key.name, path: key.path }),
+                target_kind: 'key',
+            };
+        }
+    }
+    return null;
+}
+/** Results normally arrive raw; an MCP `{ content: [{ type: 'text', text }] }`
+ * envelope is read through its first text block. Unparseable text is no
+ * result at all. */
+function unwrapEnvelope(result) {
+    const content = asRecord(result)?.content;
+    if (!Array.isArray(content))
+        return result;
+    const first = asRecord(content[0]);
+    if (first?.type !== 'text' || typeof first.text !== 'string')
+        return null;
+    try {
+        return JSON.parse(first.text);
+    }
+    catch {
+        return null;
+    }
+}
+function errorText(error) {
+    if (error instanceof Error)
+        return error.message;
+    return typeof error === 'string' ? error : String(error);
+}
+/** Thrown failures with a known meaning. Anything else (argument
+ * validation, claim conflicts, a disconnected tab) says nothing about the
+ * target and is not learned. */
+function classifyError(error) {
+    const message = errorText(error);
+    if (/\bretargeted\b|^Click would land on /.test(message)) {
+        return { ok: false, reason: 'retargeted' };
+    }
+    if (/\bref-stale\b/.test(message))
+        return { ok: false, reason: 'ref-stale' };
+    if (/expectation not met/.test(message))
+        return { ok: false, reason: 'expect-failed' };
+    if (/^Tool '.*' timed out after/.test(message))
+        return { ok: false, reason: 'timeout' };
+    if (/^Element not found:/.test(message))
+        return { ok: false, reason: 'not-found' };
+    return null;
+}
+/**
+ * Classify one dispatched call.
+ *
+ * Returns `{ ok: true }`, `{ ok: false, reason }`, or null when there is
+ * nothing to learn: a tool outside click/type/press/find/wait_for, a call
+ * without a durable target, or a result that proves neither success nor
+ * failure (a quiet click with no `expect`: quiet is not effect).
+ */
+export function classifyOutcome(tool, args, result, error) {
+    if (LEARNABLE_ACTIONS[tool] === undefined)
+        return null;
+    const target = durableTarget(tool, args);
+    if (!target)
+        return null;
+    if (error !== undefined)
+        return classifyError(error);
+    const r = asRecord(unwrapEnvelope(result)) ?? {};
+    if (tool === 'browser.find' || tool === 'browser.wait_for') {
+        if (r.matched === true)
+            return { ok: true };
+        if (r.matched !== false)
+            return null;
+        if (tool === 'browser.find' && r.reason === 'not-found') {
+            return { ok: false, reason: 'not-found' };
+        }
+        if (tool === 'browser.find' && r.reason === 'multiple-matches') {
+            return { ok: false, reason: 'multiple-matches' };
+        }
+        return { ok: false, reason: 'unmatched' };
+    }
+    // click / type / press resolved.
+    if (typeof r.hit_element === 'string' &&
+        target.target_kind === 'selector' &&
+        r.hit_element !== target.target) {
+        return { ok: false, reason: 'hit-mismatch' };
+    }
+    // An `expect` that did not hold would have thrown, so a resolved call
+    // carrying one is proof of effect.
+    if (asRecord(args)?.expect !== undefined)
+        return { ok: true };
+    const settle = asRecord(r.settle);
+    if (settle?.settled === false)
+        return { ok: false, reason: 'unsettled' };
+    if (typeof settle?.mutation_count === 'number' && settle.mutation_count > 0) {
+        return { ok: true };
+    }
+    return null;
+}
+/**
+ * Persist one verdict: upsert the counters of the (app, route, target,
+ * kind, action) row, then enforce the per-app cap.
+ *
+ * The app is resolved by `resolveLearnerApp`: the most recently seen app
+ * of the origin (the one `list_tabs` and `recall` show), left untouched,
+ * or a new app keyed by the origin host when the origin has none. The tab
+ * title is never an input: a title such as "Inbox (3) - My App" would mint
+ * a fresh app that then hides the saved map.
+ */
+export function recordOutcome(db, input) {
+    if (!input.outcome.ok && !LEARNED_REASONS.includes(input.outcome.reason))
+        return;
+    const app = resolveLearnerApp(db, input.origin);
+    const ts = new Date().toISOString();
+    const ok = input.outcome.ok;
+    const reason = input.outcome.ok ? null : input.outcome.reason;
+    db.transaction(() => {
+        db.prepare(`INSERT INTO selector_outcomes
+         (app_id, url_pattern, target, target_kind, action, ok_n, fail_n, last_reason, last_ok_at, last_fail_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+       ON CONFLICT(app_id, url_pattern, target, target_kind, action) DO UPDATE SET
+         ok_n = ok_n + excluded.ok_n,
+         fail_n = fail_n + excluded.fail_n,
+         last_reason = COALESCE(excluded.last_reason, last_reason),
+         last_ok_at = COALESCE(excluded.last_ok_at, last_ok_at),
+         last_fail_at = COALESCE(excluded.last_fail_at, last_fail_at)`).run(app.id, input.pathname, input.target, input.target_kind, input.action, ok ? 1 : 0, ok ? 0 : 1, reason, ok ? ts : null, ok ? null : ts);
+        const { n } = db
+            .prepare('SELECT COUNT(*) AS n FROM selector_outcomes WHERE app_id = ?')
+            .get(app.id);
+        if (n <= MAX_LEARNED_PER_APP)
+            return;
+        // Evict the least used rows, oldest first on a tie, never the row just
+        // written: evicting the newcomer would freeze a full app forever.
+        db.prepare(`DELETE FROM selector_outcomes WHERE id IN (
+         SELECT id FROM selector_outcomes
+         WHERE app_id = ?
+           AND NOT (url_pattern = ? AND target = ? AND target_kind = ? AND action = ?)
+         ORDER BY ok_n + fail_n ASC,
+                  MAX(COALESCE(last_ok_at, ''), COALESCE(last_fail_at, '')) ASC,
+                  id ASC
+         LIMIT ?
+       )`).run(app.id, input.pathname, input.target, input.target_kind, input.action, n - MAX_LEARNED_PER_APP);
+    })();
+}
+/**
+ * The dispatcher's `recordOutcome` dep in production (wired in server.ts).
+ * Classifies first, so calls with nothing to learn cost no config read and
+ * no DB access; then honours the `mapLearningEnabled` switch, read on every
+ * call so `browser-link config set map-learning off` applies at once.
+ */
+export function learnFromDispatch(ctx) {
+    const outcome = classifyOutcome(ctx.tool, ctx.args, ctx.result, ctx.error);
+    if (!outcome)
+        return;
+    const target = durableTarget(ctx.tool, ctx.args);
+    const action = LEARNABLE_ACTIONS[ctx.tool];
+    if (!target || !action || !ctx.url)
+        return;
+    let url;
+    try {
+        url = new URL(ctx.url);
+    }
+    catch {
+        return;
+    }
+    if (url.origin === 'null')
+        return;
+    if (loadConfig().mapLearningEnabled === false)
+        return;
+    recordOutcome(getDb(), {
+        origin: url.origin,
+        pathname: url.pathname,
+        target: target.target,
+        target_kind: target.target_kind,
+        action,
+        outcome,
+    });
+}
+//# sourceMappingURL=learning.js.map

package/dist/map/learning.js.map

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

package/dist/map/queries.d.ts

@@ -1,3 +1,4 @@
+import type Database from 'better-sqlite3';
 export type EntryKind = 'selector' | 'flow' | 'gotcha';
 export interface AppRow {
     id: number;
@@ -30,6 +31,19 @@ export interface UpsertAppInput {
     notes?: string | null;
 }
 export declare function upsertApp(input: UpsertAppInput): AppRow;
+/**
+ * The app the map learner counts into for an origin, read-only on purpose.
+ *
+ * Picks the most recently seen app of the canonical origin with the same
+ * winner rule `getMapHints` applies (last_seen_at DESC, id DESC), so learned
+ * rows land in the app `list_tabs` and `recall` already show. It never
+ * touches that app's `last_seen_at` or `title`: a passive learner bumping
+ * freshness would reorder which app an origin resolves to. Only when the
+ * origin has no app at all does it create one, keyed and titled by the
+ * origin host, never by a tab title (titles change with page state, e.g.
+ * "Inbox (3) - My App", and would mint a new app per title).
+ */
+export declare function resolveLearnerApp(db: Database.Database, origin: string): AppRow;
 export interface SaveEntryInput {
     origin: string;
     app_key?: string | null;
@@ -84,8 +98,32 @@ export interface RecallResult {
     pitfalls: InsightRow[];
     mechanisms: InsightRow[];
     entries: EntryRow[];
+    /** What the map learned from use (see learning.ts): failures first, then
+     * most used, at most `RECALL_MAX_LEARNED`. Present only when the app has
+     * learned rows, so a recall of an app with none reads exactly as before. */
+    learned?: LearnedRecallItem[];
     flows: FlowRow[];
 }
+/** One learned target as `list_tabs`' inline map carries it. Targets only:
+ * a CSS selector, or a `browser.find` semantic key as JSON. */
+export interface LearnedSummary {
+    target: string;
+    target_kind: 'selector' | 'key';
+    action: string;
+    ok_n: number;
+    fail_n: number;
+    last_reason: string | null;
+}
+/** Recall's richer form: the route it was learned on and when. */
+export interface LearnedRecallItem extends LearnedSummary {
+    url_pattern: string;
+    last_ok_at: string | null;
+    last_fail_at: string | null;
+}
+/** Learned rows of one app in hint order, capped at `limit`. Takes the DB
+ * explicitly so the learner's tests can read through the handle they write
+ * through. */
+export declare function listLearned(db: Database.Database, app_id: number, limit: number): LearnedRecallItem[];
 export declare function recall(input: RecallInput): RecallResult;
 export interface RecordUseInput {
     entry_id: number;
@@ -193,6 +231,10 @@ export interface MapHintInline {
         description: string | null;
         steps: unknown;
     }[];
+    /** Up to 3 learned targets, failures first. Present only when the app has
+     * learned rows and at least one fits the byte cap; never counted toward
+     * `INLINE_MAX_ITEMS`. */
+    learned?: LearnedSummary[];
 }
 export interface MapHint {
     app_key: string;
@@ -203,6 +245,9 @@ export interface MapHint {
     /** Present only when the map is small (see `INLINE_MAX_ITEMS` /
      * `INLINE_MAX_BYTES`); otherwise the counts above are all there is. */
     inline?: MapHintInline;
+    /** Learned targets of this app that have failed at least once, present
+     * only when there are some and no inline map carrying them fits. */
+    learned_failures?: number;
 }
 /**
  * Lean existence-and-count lookup for a tab's origin — powers the optional