@weavetab/plugin-realtime 0.0.0-stage → 0.2.0

package/dist/canvas.js

@@ -0,0 +1,159 @@
+import { run } from "./page.js";
+// recorder hooks CanvasRenderingContext2D.prototype and window.requestAnimationFrame.
+// draws are only kept while a rAF callback is running, that is what defines a frame.
+const SPY = `(() => {
+  if (window.__wt_cv) return 1;
+  const cv = window.__wt_cv = { frames: [], n: 0, cur: null, orig: {}, canvases: [], bg: 0, raf: window.requestAnimationFrame };
+  const P = CanvasRenderingContext2D.prototype;
+
+  const rec = (ctx, kind, key, x, y, w, h) => {
+    const m = ctx.getTransform();
+    const x1 = m.a * x + m.c * y + m.e, y1 = m.b * x + m.d * y + m.f;
+    const x2 = m.a * (x + w) + m.c * (y + h) + m.e, y2 = m.b * (x + w) + m.d * (y + h) + m.f;
+    let ci = cv.canvases.indexOf(ctx.canvas);
+    if (ci < 0) ci = cv.canvases.push(ctx.canvas) - 1;
+    const ww = Math.abs(x2 - x1), hh = Math.abs(y2 - y1);
+    cv.cur.push({ sig: kind + '|' + Math.round(ww) + 'x' + Math.round(hh) + '|' + key,
+      x: Math.min(x1, x2), y: Math.min(y1, y2), w: ww, h: hh, c: ci });
+  };
+  const styleKey = (s) => typeof s === 'string' ? s : 'grad';
+  const imgKey = (im) => {
+    const s = im.currentSrc || im.src;
+    return s ? s.split('?')[0].split('/').pop() : (im.id || im.tagName || 'bmp');
+  };
+  const wrap = (name, fn) => {
+    const o = P[name];
+    cv.orig[name] = o;
+    P[name] = function () {
+      const r = o.apply(this, arguments);
+      // the spy must never break the game's own draw call
+      try { if (cv.cur && this.canvas.isConnected && cv.cur.length < 2000) fn(this, arguments); } catch (e) {}
+      return r;
+    };
+  };
+
+  wrap('fillRect', (c, a) => rec(c, 'rect', styleKey(c.fillStyle), a[0], a[1], a[2], a[3]));
+  wrap('strokeRect', (c, a) => rec(c, 'frame', styleKey(c.strokeStyle), a[0], a[1], a[2], a[3]));
+  wrap('drawImage', (c, a) => {
+    const im = a[0], n = a.length;
+    if (n >= 9) rec(c, 'img', imgKey(im) + '@' + a[1] + ',' + a[2], a[5], a[6], a[7], a[8]);
+    else if (n >= 5) rec(c, 'img', imgKey(im), a[1], a[2], a[3], a[4]);
+    else rec(c, 'img', imgKey(im), a[1], a[2], im.naturalWidth || im.videoWidth || im.width || 0, im.naturalHeight || im.videoHeight || im.height || 0);
+  });
+  const text = (c, a) => {
+    const m = c.measureText(a[0]);
+    rec(c, 'text', String(a[0]).slice(0, 24), a[1], a[2] - m.actualBoundingBoxAscent, m.width, m.actualBoundingBoxAscent + m.actualBoundingBoxDescent);
+  };
+  wrap('fillText', text);
+  wrap('strokeText', text);
+  wrap('beginPath', (c) => { c.__wtp = []; });
+  wrap('arc', (c, a) => {
+    if (Math.abs(a[4] - a[3]) >= 6.2) (c.__wtp || (c.__wtp = [])).push([a[0], a[1], a[2]]);
+  });
+  const commit = (style) => (c) => {
+    for (const p of (c.__wtp || [])) rec(c, 'arc', styleKey(c[style]), p[0] - p[2], p[1] - p[2], p[2] * 2, p[2] * 2);
+    c.__wtp = [];
+  };
+  wrap('fill', commit('fillStyle'));
+  wrap('stroke', commit('strokeStyle'));
+
+  window.requestAnimationFrame = function (cb) {
+    return cv.raf.call(window, function (ts) {
+      cv.cur = [];
+      try { return cb(ts); } finally {
+        cv.frames.push({ t: ts, d: cv.cur });
+        if (cv.frames.length > 16) cv.frames.shift();
+        cv.cur = null;
+        cv.n++;
+      }
+    });
+  };
+
+  cv.track = (sig, depth) => {
+    const fr = cv.frames;
+    if (!fr.length) return [];
+    const last = fr[fr.length - 1].d.filter((d) => d.sig === sig);
+    if (last.length > 200) return last.map((d) => Object.assign({ vx: 0, vy: 0 }, d));
+    const prevs = fr.slice(Math.max(0, fr.length - 1 - depth), -1).reverse().map((f) => f.d.filter((d) => d.sig === sig));
+    return last.map((d) => {
+      let cur = d, steps = 0;
+      for (const p of prevs) {
+        let best = null, bd = 1e9;
+        for (const q of p) {
+          const dd = (q.x - cur.x) * (q.x - cur.x) + (q.y - cur.y) * (q.y - cur.y);
+          if (dd < bd) { bd = dd; best = q; }
+        }
+        if (!best || bd > 40000) break;
+        cur = best; steps++;
+      }
+      return Object.assign({}, d, { vx: steps ? (d.x - cur.x) / steps : 0, vy: steps ? (d.y - cur.y) / steps : 0 });
+    });
+  };
+  return 0;
+})()`;
+const WAIT = (frames) => `new Promise((res) => {
+  const cv = window.__wt_cv, start = cv.n, t0 = performance.now();
+  const tick = () => (cv.n - start >= ${frames} || performance.now() - t0 > 3000) ? res(cv.n - start) : setTimeout(tick, 8);
+  tick();
+})`;
+const REPORT = `(() => {
+  const cv = window.__wt_cv;
+  const fr = cv.frames, last = fr[fr.length - 1];
+  const r1 = (v) => Math.round(v * 10) / 10;
+  const dt = fr.length > 1 ? fr[fr.length - 1].t - fr[0].t : 0;
+  const cans = [];
+  const info = (i) => {
+    let o = cans.find((c) => c.i === i);
+    if (!o) {
+      const el = cv.canvases[i], r = el.getBoundingClientRect();
+      o = { i, id: el.id || null, w: el.width, h: el.height, left: r.left, top: r.top, sx: r.width / el.width, sy: r.height / el.height };
+      cans.push(o);
+    }
+    return o;
+  };
+  const sigs = {};
+  for (const d of last.d) (sigs[d.sig] || (sigs[d.sig] = [])).push(d);
+  const ents = [], groups = [];
+  let bg = 0;
+  for (const sig of Object.keys(sigs).slice(0, 200)) {
+    const inst = sigs[sig];
+    const kind = sig.split('|')[0];
+    const tr = cv.track(sig, 5);
+    if (inst.length > 6) {
+      groups.push({ sig, count: inst.length, moving: tr.filter((t) => t.vx || t.vy).length });
+      continue;
+    }
+    for (const t of tr) {
+      const cn = info(t.c);
+      if ((kind === 'rect') && t.w >= cn.w * 0.9 && t.h >= cn.h * 0.9) { bg++; continue; }
+      ents.push({ sig, canvas: t.c, x: r1(t.x), y: r1(t.y), w: r1(t.w), h: r1(t.h), vx: r1(t.vx), vy: r1(t.vy) });
+    }
+  }
+  ents.sort((a, b) => (Math.abs(b.vx) + Math.abs(b.vy)) - (Math.abs(a.vx) + Math.abs(a.vy)));
+  return { frames: fr.length, fps: dt ? Math.round((fr.length - 1) * 1000 / dt) : null, canvases: cans,
+    entities: ents.slice(0, 40), groups: groups.slice(0, 20), background_fills: bg, truncated: ents.length > 40 };
+})()`;
+const OFF = `(() => {
+  const cv = window.__wt_cv;
+  if (!cv) return 0;
+  const P = CanvasRenderingContext2D.prototype;
+  for (const k of Object.keys(cv.orig)) P[k] = cv.orig[k];
+  window.requestAnimationFrame = cv.raf;
+  delete window.__wt_cv;
+  return 1;
+})()`;
+export async function canvasTool(sess, a) {
+    if (a.action === "detach")
+        return { detached: Boolean(await run(sess, OFF)) };
+    const fresh = (await run(sess, SPY)) === 0;
+    if (a.action === "attach")
+        return { attached: true, already: !fresh };
+    const want = Math.min(Math.max(a.frames ?? 6, 2), 15);
+    const got = await run(sess, WAIT(want), true);
+    if (!got)
+        throw new Error("no frames seen: tab hidden, or the game does not use requestAnimationFrame");
+    return run(sess, REPORT);
+}
+export function canvasSnap(sess) {
+    return run(sess, `window.__wt_cv && window.__wt_cv.frames.length ? ${REPORT} : null`);
+}

package/dist/causal.d.ts

@@ -0,0 +1 @@
+export declare function tagMap(sess: any, res: any, winMs: number): Promise<any>;

package/dist/causal.js

@@ -0,0 +1,72 @@
+import { run } from "./page.js";
+const LINE = /^(\s*)\[w:(\d+)\]/;
+function probeIds(ids, winMs) {
+    return `((ids, win) => {
+    const rt = window.__wt_rt;
+    if (!rt) return [];
+    const now = performance.now();
+    const clk = rt.click && now - rt.click.t < 15000 ? rt.click : null;
+    const out = [];
+    for (const id of ids) {
+      const el = document.querySelector('[data-wt-id="' + id + '"]');
+      if (!el) continue;
+      let b;
+      for (let n = el; n && b === undefined; n = n.parentElement) b = rt.born.get(n);
+      if (b === undefined || now - b > win) continue;
+      let dist = null;
+      if (clk) {
+        const r = el.getBoundingClientRect();
+        dist = Math.round(Math.hypot(r.left + r.width / 2 - clk.x, r.top + r.height / 2 - clk.y));
+      }
+      out.push([id, Math.round(now - b), dist]);
+    }
+    return out;
+  })(${JSON.stringify(ids)}, ${winMs})`;
+}
+async function tagText(sess, text, winMs) {
+    const lines = text.split("\n");
+    const ids = new Set();
+    for (const ln of lines) {
+        const m = LINE.exec(ln);
+        if (m)
+            ids.add(m[2]);
+    }
+    if (!ids.size)
+        return text;
+    const hits = await run(sess, probeIds([...ids], winMs));
+    if (!hits.length)
+        return text;
+    const byId = new Map(hits.map((h) => [h[0], h]));
+    return lines
+        .map((ln) => {
+        const m = LINE.exec(ln);
+        const h = m && byId.get(m[2]);
+        if (!h)
+            return ln;
+        return `${ln} {new ${h[1]}ms${h[2] == null ? "" : `, ${h[2]}px from click`}}`;
+    })
+        .join("\n");
+}
+// returns undefined when nothing changed so the pipeline keeps the original result
+export async function tagMap(sess, res, winMs) {
+    if (typeof res === "string") {
+        const t = await tagText(sess, res, winMs);
+        return t === res ? undefined : t;
+    }
+    if (!Array.isArray(res?.content))
+        return;
+    let touched = false;
+    const content = [];
+    for (const blk of res.content) {
+        if (blk?.type === "text" && typeof blk.text === "string") {
+            const t = await tagText(sess, blk.text, winMs);
+            if (t !== blk.text)
+                touched = true;
+            content.push({ ...blk, text: t });
+        }
+        else {
+            content.push(blk);
+        }
+    }
+    return touched ? { ...res, content } : undefined;
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+declare const plugin: import("@weavetab/sdk").WeavetabPluginDefinition;
+export default plugin;
+export { plugin };

package/dist/index.js

@@ -0,0 +1,135 @@
+import { definePlugin, defineTool, definePrompt, defineResource, z } from "@weavetab/sdk";
+import { arm, sessOf } from "./page.js";
+import { tagMap } from "./causal.js";
+import { canvasTool } from "./canvas.js";
+import { reflexTool, statusTool } from "./reflex.js";
+import { autopilotTool } from "./autopilot.js";
+import { readFeed } from "./surface.js";
+let winMs = 4000;
+const asText = (v) => ({ content: [{ type: "text", text: JSON.stringify(v, null, 2) }] });
+const plugin = definePlugin({
+    name: "@weavetab/plugin-realtime",
+    version: "0.2.0",
+    description: "Causal tags for browser_map, in-page reflex rules, canvas entity sampling, bounded click loop.",
+    defaultConfig: { causalWindowMs: 4000 },
+    permissions: {
+        cdp: { evaluate: true, input: true, reason: "Page probe, canvas spy, 60Hz reflex loop, and trusted CDP mouse clicks." },
+        tools: { add: true, reason: "Registers realtime_canvas, realtime_reflex, realtime_autopilot and realtime_status." },
+        prompts: { add: true, reason: "Registers /realtime_watch to guide setting up 60Hz DOM or canvas reflexes." },
+        resources: { add: true, reason: "Registers @realtime_feed (realtime://feed) for live reflex, DOM, and canvas telemetry." },
+        hooks: { onBeforeAction: true, onAfterAction: true, reason: "Arms page probe and appends {new ...} causal tags to browser_map." },
+        network: { hosts: ["127.0.0.1", "localhost"], reason: "Optional local model_url in realtime_autopilot." },
+    },
+    async onBeforeAction(_tool, _args, sess) {
+        if (sess?.Runtime)
+            await arm(sess).catch(() => { }); // page may be mid-navigation, next call retries
+    },
+    async onAfterAction(tool, res, sess) {
+        if (tool !== "browser_map" || !sess?.Runtime)
+            return;
+        return tagMap(sess, res, winMs).catch(() => undefined);
+    },
+    async onLoad(ctx) {
+        winMs = Number(ctx.config?.causalWindowMs) || 4000;
+        const reg = ctx.mcp.registerTool;
+        reg(defineTool({
+            name: "realtime_canvas",
+            description: "Sample what a 2D <canvas> game draws. 'sample' watches a few frames and returns entities (signature, bbox, px/frame velocity) in canvas pixels, plus canvas position/scale to convert to viewport coords. Only sees Canvas2D draw calls made inside requestAnimationFrame; WebGL is invisible to it. 'attach' starts recording early, 'detach' restores the page.",
+            requiresSession: true,
+            schema: {
+                action: z.enum(["sample", "attach", "detach"]).default("sample"),
+                frames: z.number().int().min(2).max(15).optional().describe("frames to watch, default 6"),
+            },
+            handler: async (a, ctx) => asText(await canvasTool(sessOf(ctx), a)),
+        }));
+        reg(defineTool({
+            name: "realtime_reflex",
+            description: "Register a rule that runs inside the page every animation frame, no LLM round-trip. Trigger is either a DOM selector (optionally text / only_new) or a canvas expression over named entity signatures from realtime_canvas: names {player:'rect|20x20|#f00'}, js \"gap(E.player[0], E.cactus[0]) < 50\" (E.name = array of {x,y,w,h,vx,vy}; dist() and gap() return Infinity when an entity is missing). Action: click, click_xy, key, or js. Events are synthetic, sites that check isTrusted ignore them. Needs a visible tab.",
+            requiresSession: true,
+            schema: {
+                action: z.enum(["add", "remove", "list", "clear"]).default("add"),
+                id: z.string().optional(),
+                when: z
+                    .object({
+                    selector: z.string().optional(),
+                    text: z.string().optional().describe("case-insensitive substring of label/text"),
+                    only_new: z.boolean().optional().describe("only elements added after this rule was created"),
+                    enabled: z.boolean().optional().describe("skip disabled elements, default true"),
+                    canvas: z.object({ names: z.record(z.string()), js: z.string() }).optional(),
+                })
+                    .optional(),
+                do: z
+                    .object({
+                    type: z.enum(["click", "click_xy", "key", "js"]),
+                    x: z.number().optional(),
+                    y: z.number().optional(),
+                    key: z.string().optional(),
+                    hold_ms: z.number().optional().describe("key hold time, default 40"),
+                    code: z.string().optional(),
+                })
+                    .optional(),
+                cooldown_ms: z.number().optional().describe("default 100"),
+                max_hits: z.number().optional().describe("default 50"),
+                ttl_ms: z.number().optional().describe("default 30000, max 600000"),
+                stop_selector: z.string().optional(),
+            },
+            handler: async (a, ctx) => asText(await reflexTool(sessOf(ctx), a)),
+        }));
+        reg(defineTool({
+            name: "realtime_autopilot",
+            description: "Bounded click loop for short UI sub-goals ('accept cookies', 'click next until Order summary shows'). Ranks visible, unoccluded clickable elements by word overlap with the goal, boosts ones that just appeared and ones inside an open dialog, and never re-clicks a button whose last click changed nothing. Trusted CDP mouse clicks. Skips delete/pay/sign-out style labels unless the goal says so. Not a planner: stops with no_match when no label overlaps the goal. Optional model_url = OpenAI-compatible chat endpoint to pick instead; falls back to the ranker on any failure.",
+            requiresSession: true,
+            schema: {
+                goal: z.string().min(3),
+                max_steps: z.number().int().min(1).max(25).optional().describe("default 8"),
+                stop_when_selector: z.string().optional(),
+                stop_when_text: z.string().optional(),
+                stop_when_url: z.string().optional().describe("regex tested against location.href"),
+                avoid_labels: z.string().optional().describe("regex of extra labels never to click"),
+                model_url: z.string().url().optional(),
+                model: z.string().optional(),
+                model_timeout_ms: z.number().optional().describe("default 1500"),
+            },
+            handler: async (a, ctx) => asText(await autopilotTool(sessOf(ctx), a)),
+        }));
+        reg(defineTool({
+            name: "realtime_status",
+            description: "Probe/canvas/reflex state for the current page. wait_ms (max 30000) blocks until every active reflex has finished, so the agent can sleep through a game or a drop-watch.",
+            requiresSession: true,
+            schema: { wait_ms: z.number().optional() },
+            handler: async (a, ctx) => asText(await statusTool(sessOf(ctx), a.wait_ms)),
+        }));
+        ctx.mcp.registerPrompt?.(definePrompt({
+            name: "realtime_watch",
+            title: "Watch & React (60Hz Reflex)",
+            description: "Set up an in-page 60Hz reflex rule or canvas game loop and wait until it finishes.",
+            arguments: {
+                goal: z.string().describe("What to watch for and trigger (e.g. 'click Claim as soon as it appears' or 'jump over green obstacles in the canvas game')"),
+                mode: z.string().optional().describe("'dom', 'canvas', or 'auto' (default 'auto')"),
+            },
+            handler: async ({ goal, mode }, sctx) => {
+                const feed = await readFeed(sessOf(sctx), winMs).catch(() => ({ active_tab: false }));
+                const m = (mode || "auto").toLowerCase();
+                return [
+                    `Goal: ${goal}`,
+                    `Mode: ${m}`,
+                    `Live state: ${JSON.stringify(feed)}`,
+                    m === "canvas"
+                        ? "1. Call realtime_canvas with action='sample' to inspect moving entity signatures and velocities.\n2. Arm realtime_reflex with when.canvas ({ names, js }) using gap(E.a[0], E.b[0]) or dist(E.a[0], E.b[0]).\n3. Call realtime_status with wait_ms to block until the reflex completes."
+                        : "1. If targeting a 2D <canvas>, run realtime_canvas (action='sample') first to grab entity signatures; if targeting DOM changes, pick a selector/text filter (set only_new=true to ignore elements already on screen).\n2. Arm the rule with realtime_reflex (action='add').\n3. Call realtime_status with wait_ms (up to 30000) to sleep until the reflex hits max_hits or stop_selector.",
+                ].join("\n\n");
+            },
+        }));
+        ctx.mcp.registerResource?.(defineResource({
+            name: "realtime_feed",
+            title: "Realtime Page Feed",
+            uri: "realtime://feed",
+            mimeType: "application/json",
+            description: "Live snapshot of active 60Hz reflex rules, recently mutated DOM elements with click distance, and tracked Canvas2D entities.",
+            read: async (_uri, _vars, sctx) => JSON.stringify(await readFeed(sessOf(sctx), winMs), null, 2),
+        }));
+        ctx.logger?.info("realtime up");
+    },
+});
+export default plugin;
+export { plugin };

package/dist/page.d.ts

@@ -0,0 +1,3 @@
+export declare function sessOf(ctx: any): any;
+export declare function run(sess: any, expression: string, awaitPromise?: boolean): Promise<any>;
+export declare function arm(sess: any): Promise<any>;

package/dist/page.js

@@ -0,0 +1,33 @@
+// page-side probe shared by every tool in here. one per document, survives until navigation.
+const PROBE = `(() => {
+  if (window.__wt_rt) return 1;
+  const rt = window.__wt_rt = { born: new WeakMap(), click: null, lastMut: 0 };
+  new MutationObserver(recs => {
+    const now = performance.now();
+    for (const r of recs) {
+      if (r.type === 'childList') {
+        for (const n of r.addedNodes) if (n.nodeType === 1 && !rt.born.has(n)) rt.born.set(n, now);
+      }
+    }
+    rt.lastMut = now;
+  }).observe(document.documentElement, {
+    childList: true, subtree: true, characterData: true, attributes: true,
+    attributeFilter: ['class', 'hidden', 'aria-expanded', 'aria-hidden', 'open', 'disabled']
+  });
+  addEventListener('pointerdown', e => { rt.click = { x: e.clientX, y: e.clientY, t: performance.now() }; }, true);
+  return 0;
+})()`;
+export function sessOf(ctx) {
+    return ctx?.tab?.session || ctx?.session || ctx;
+}
+export async function run(sess, expression, awaitPromise = false) {
+    const out = await sess.Runtime.evaluate({ expression, returnByValue: true, awaitPromise });
+    if (out.exceptionDetails) {
+        const ex = out.exceptionDetails;
+        throw new Error(ex.exception?.description?.split("\n")[0] || ex.text || "page eval failed");
+    }
+    return out.result?.value;
+}
+export function arm(sess) {
+    return run(sess, PROBE);
+}

package/dist/reflex.d.ts

@@ -0,0 +1,29 @@
+type Rule = {
+    action: "add" | "remove" | "list" | "clear";
+    id?: string;
+    when?: {
+        selector?: string;
+        text?: string;
+        only_new?: boolean;
+        enabled?: boolean;
+        canvas?: {
+            names: Record<string, string>;
+            js: string;
+        };
+    };
+    do?: {
+        type: "click" | "click_xy" | "key" | "js";
+        x?: number;
+        y?: number;
+        key?: string;
+        hold_ms?: number;
+        code?: string;
+    };
+    cooldown_ms?: number;
+    max_hits?: number;
+    ttl_ms?: number;
+    stop_selector?: string;
+};
+export declare function reflexTool(sess: any, a: Rule): Promise<any>;
+export declare function statusTool(sess: any, waitMs?: number): Promise<any>;
+export {};

package/dist/reflex.js

@@ -0,0 +1,163 @@
+import { run, arm } from "./page.js";
+import { canvasTool } from "./canvas.js";
+// one rAF loop per page, only alive while a rule is active.
+// it grabs the un-spied rAF so reflex ticks never show up as canvas frames.
+const RUNTIME = `(() => {
+  if (window.__wt_rf) return 1;
+  const nativeRaf = (window.__wt_cv && window.__wt_cv.raf) || window.requestAnimationFrame;
+  const rf = window.__wt_rf = { rules: {}, on: false };
+
+  const CODES = { ' ': ['Space', 32], Enter: ['Enter', 13], Escape: ['Escape', 27], Tab: ['Tab', 9],
+    ArrowLeft: ['ArrowLeft', 37], ArrowUp: ['ArrowUp', 38], ArrowRight: ['ArrowRight', 39], ArrowDown: ['ArrowDown', 40] };
+  const press = (k, hold) => {
+    if (k === 'Space') k = ' ';
+    const c = CODES[k] || (/^[a-z]$/i.test(k) ? ['Key' + k.toUpperCase(), k.toUpperCase().charCodeAt(0)]
+      : /^[0-9]$/.test(k) ? ['Digit' + k, k.charCodeAt(0)] : [k, 0]);
+    const o = { key: k, code: c[0], keyCode: c[1], which: c[1], bubbles: true, cancelable: true };
+    const tgt = document.activeElement || document.body;
+    tgt.dispatchEvent(new KeyboardEvent('keydown', o));
+    setTimeout(() => tgt.dispatchEvent(new KeyboardEvent('keyup', o)), hold);
+  };
+  const click = (el, x, y) => {
+    if (x == null) { const b = el.getBoundingClientRect(); x = b.left + b.width / 2; y = b.top + b.height / 2; }
+    const o = { bubbles: true, cancelable: true, composed: true, clientX: x, clientY: y, view: window, button: 0 };
+    for (const t of ['pointerdown', 'mousedown', 'pointerup', 'mouseup', 'click'])
+      el.dispatchEvent(t.startsWith('pointer') ? new PointerEvent(t, o) : new MouseEvent(t, o));
+  };
+  const shown = (el) => {
+    const r = el.getBoundingClientRect();
+    if (!r.width || !r.height) return false;
+    const s = getComputedStyle(el);
+    return s.visibility !== 'hidden' && s.display !== 'none';
+  };
+  const isNew = (el, since) => {
+    const rt = window.__wt_rt;
+    if (!rt) return false;
+    for (let n = el; n; n = n.parentElement) { const b = rt.born.get(n); if (b !== undefined) return b >= since; }
+    return false;
+  };
+  const find = (r) => {
+    for (const el of document.querySelectorAll(r.sel)) {
+      if (r.enabled && (el.disabled || el.getAttribute('aria-disabled') === 'true')) continue;
+      if (r.text && !((el.getAttribute('aria-label') || '') + ' ' + (el.value || '') + ' ' + el.textContent).toLowerCase().includes(r.text)) continue;
+      if (r.onlyNew && !isNew(el, r.t0)) continue;
+      if (shown(el)) return el;
+    }
+    return null;
+  };
+  const dist = (a, b) => (a && b) ? Math.hypot(a.x + a.w / 2 - b.x - b.w / 2, a.y + a.h / 2 - b.y - b.h / 2) : Infinity;
+  const gap = (a, b) => (a && b) ? b.x - (a.x + a.w) : Infinity;
+  const E = new Proxy({}, { get: (_, k) => {
+    const cv = window.__wt_cv, sig = rf.names && rf.names[k];
+    return cv && sig ? cv.track(sig, 2) : [];
+  } });
+
+  const tick = () => {
+    const now = performance.now();
+    let live = 0;
+    for (const id in rf.rules) {
+      const r = rf.rules[id];
+      if (r.done) continue;
+      try {
+        if (now - r.t0 > r.ttl) { r.done = 'ttl'; continue; }
+        if (r.stop && document.querySelector(r.stop)) { r.done = 'stop_selector'; continue; }
+        live++;
+        if (now - r.last < r.cooldown) continue;
+        rf.names = r.names;
+        let el = null;
+        if (r.sel) { el = find(r); if (!el) continue; }
+        else if (!r.whenFn(E, dist, gap)) continue;
+        const a = r.act;
+        if (a.type === 'click') click(el);
+        else if (a.type === 'click_xy') click(document.elementFromPoint(a.x, a.y) || document.body, a.x, a.y);
+        else if (a.type === 'key') press(a.key, a.hold);
+        else r.jsFn();
+        r.hits++; r.last = now;
+        if (r.hits >= r.max) { r.done = 'max_hits'; live--; }
+      } catch (e) { r.done = 'error'; r.err = String((e && e.message) || e); }
+    }
+    if (live) nativeRaf.call(window, tick); else rf.on = false;
+  };
+  rf.add = (rule, whenFn, jsFn) => {
+    rf.rules[rule.id] = Object.assign({}, rule, { t0: performance.now(), last: -1e9, hits: 0, done: null, err: null, whenFn, jsFn });
+    if (!rf.on) { rf.on = true; nativeRaf.call(window, tick); }
+  };
+  rf.snap = () => {
+    const now = performance.now();
+    return Object.keys(rf.rules).map((id) => {
+      const r = rf.rules[id];
+      return { id, kind: r.sel ? 'dom' : 'canvas', hits: r.hits, done: r.done, error: r.err,
+        last_hit_ms_ago: r.hits ? Math.round(now - r.last) : null, age_ms: Math.round(now - r.t0) };
+    });
+  };
+  return 0;
+})()`;
+let seq = 0;
+export async function reflexTool(sess, a) {
+    await arm(sess);
+    await run(sess, RUNTIME);
+    if (a.action === "list")
+        return run(sess, "__wt_rf.snap()");
+    if (a.action === "clear") {
+        await run(sess, "(() => { for (const k in __wt_rf.rules) delete __wt_rf.rules[k]; })()");
+        return { cleared: true };
+    }
+    if (a.action === "remove") {
+        if (!a.id)
+            throw new Error("id required");
+        const had = await run(sess, `(() => { const had = ${JSON.stringify(a.id)} in __wt_rf.rules; delete __wt_rf.rules[${JSON.stringify(a.id)}]; return had; })()`);
+        return { removed: had };
+    }
+    if (!a.when || !a.do)
+        throw new Error("add needs both when and do");
+    const w = a.when, d = a.do;
+    const cv = w.canvas;
+    if (!!w.selector === !!cv)
+        throw new Error("when needs exactly one of selector or canvas");
+    if (d.type === "click" && !w.selector)
+        throw new Error("do.click only works with a selector trigger, use click_xy");
+    if (d.type === "click_xy" && (d.x == null || d.y == null))
+        throw new Error("click_xy needs x and y");
+    if (d.type === "key" && !d.key)
+        throw new Error("key needs a key");
+    if (d.type === "js" && !d.code)
+        throw new Error("js needs code");
+    const id = a.id || `r${++seq}`;
+    const rule = {
+        id,
+        sel: w.selector || null,
+        text: w.text ? w.text.toLowerCase() : null,
+        onlyNew: Boolean(w.only_new),
+        enabled: w.enabled !== false,
+        names: cv?.names ?? null,
+        act: { type: d.type, x: d.x, y: d.y, key: d.key, hold: d.hold_ms ?? 40 },
+        cooldown: a.cooldown_ms ?? 100,
+        max: a.max_hits ?? 50,
+        ttl: Math.min(a.ttl_ms ?? 30000, 600000),
+        stop: a.stop_selector || null,
+    };
+    if (cv)
+        await canvasTool(sess, { action: "attach" });
+    // fns go in as source so page CSP (no unsafe-eval) can't block them
+    const whenFn = cv ? `(E, dist, gap) => (\n${cv.js}\n)` : "null";
+    const jsFn = d.type === "js" ? `() => {\n${d.code}\n}` : "null";
+    await run(sess, `__wt_rf.add(${JSON.stringify(rule)}, ${whenFn}, ${jsFn})`);
+    return { id, armed: true };
+}
+export function statusTool(sess, waitMs = 0) {
+    const ms = Math.min(Math.max(waitMs, 0), 30000);
+    return run(sess, `new Promise((res) => {
+      const t0 = performance.now();
+      const snap = () => ({
+        probe: Boolean(window.__wt_rt),
+        canvas: window.__wt_cv ? { attached: true, frames_seen: window.__wt_cv.n } : { attached: false },
+        reflexes: window.__wt_rf ? window.__wt_rf.snap() : []
+      });
+      const tick = () => {
+        const s = snap();
+        if (!${ms} || !s.reflexes.some((r) => !r.done) || performance.now() - t0 > ${ms}) res(s);
+        else setTimeout(tick, 50);
+      };
+      tick();
+    })`, true);
+}

package/dist/surface.d.ts

@@ -0,0 +1,19 @@
+export declare function readFeed(sess: any, winMs: number): Promise<{
+    active_tab: boolean;
+    url?: undefined;
+    probe?: undefined;
+    last_click?: undefined;
+    last_mut_ms_ago?: undefined;
+    recent_elements?: undefined;
+    reflexes?: undefined;
+    canvas?: undefined;
+} | {
+    url: any;
+    probe: any;
+    last_click: any;
+    last_mut_ms_ago: any;
+    recent_elements: any;
+    reflexes: any;
+    canvas: any;
+    active_tab?: undefined;
+}>;