agello 0.4.1 → 0.4.2

package/README.md

@@ -7,6 +7,7 @@
 - Conversation saved per pane in the browser, kept across reloads
 - Interactive terminal view of the existing herdr pane: live cursor, keyboard input, and automatic resize
 - Optional live view of a `terminal-browser` screen, with an on/off switch to control it yourself
+- Annotate: point at an element on that screen and send a request about it, with its CSS selector
 - Embeddable `<agent-bridge>` web component
 
 Chat currently supports **Claude Code** sessions. The terminal view connects directly to the pane, including ordinary shells and other terminal applications.
@@ -60,6 +61,18 @@ Messages sent from the page arrive in the agent as:
 
 The approve / reject buttons send `action=approve` / `action=reject`.
 
+### Annotate
+
+The `주석` button on the screen panel turns on annotate mode: hovering tints the element under the pointer (with its tag and size), clicking outlines it and opens an input next to it. The wheel still scrolls the page, and the outline follows the element as the page changes. The request arrives as:
+
+```
+[browser] action=annotate make this red / and bolder
+대상: #app > main > button:nth-of-type(2)
+요소: button.primary "Save" · 위치 120,340 크기 96x32 · http://localhost:3000/
+```
+
+Selector: nearest unique `id` / `data-testid` ancestor, then `tag:nth-of-type` steps (light DOM only). Coordinates are CSS px of the viewport. Off while presenting and while "내 조작" is on.
+
 ### Commands
 
 | Command | Description |
@@ -70,6 +83,8 @@ The approve / reject buttons send `action=approve` / `action=reject`.
 | `agello open [--port N \| --pane ID]` | Open the page (default: this pane's server) |
 | `agello present [x,y,w,h] [--port N \| --pane ID]` | Presentation mode (see below) |
 | `agello present stop` | End presentation mode |
+| `agello script load <file> \| show` | Load / show a presentation script |
+| `agello present resume \| pause \| goto <n[.m]>` | Play the script from where it stopped / stop it / move to a step |
 
 `start` options: `--pane <id>`, `--port <n>` (default: first free from 8765), `--session <id>`, `--browser <terminal-browser key>`, `--allow-origin <origin>` (repeatable), `--open`, `--foreground`.
 
@@ -102,6 +117,23 @@ The xterm.js renderer and its styles are served locally; no terminal CDN is requ
 
 Run `present` again to move the crop. User control is off while presenting.
 
+#### Scripts
+
+Write the talk ahead so each line appears the moment its screen does:
+
+```json
+{ "rect": "28,157,688,477",
+  "steps": [
+    { "go": "#1", "say": ["First line", "Second line"] },
+    { "go": "#2", "say": ["..."], "hold": 6 } ] }
+```
+
+- step: `go` brings the screen there (`#n` sets `location.hash`, anything else is JS run in the page; agello knows nothing about the deck), `say` lines are one bubble each, `hold` seconds a line stays on screen (default from length, 10 to 20s; never below 10s). Pacing: screen change, 1s, line, fade out, 0.3s, next line; after a step's last line 0.7s before the next screen
+- `present resume` plays from where it stopped (starts presentation mode with the script's `rect`); it first re-runs the current step's `go`, so the agent may move the screen freely while answering
+- raising a hand pauses at once; the agent gets `action=hand-raise` with the position (`마지막 표시 2.1 · 다음 2.2`)
+- `script load` again after editing keeps the position; `present goto 2.2` then `present resume` replays from a fixed line
+- at the end the agent gets `action=present-done`; while the script is paused and the agent is working, the page shows a small loader
+
 ## Embed
 
 ```html

package/bin/agello.ts

@@ -27,6 +27,13 @@ Usage:
                          whole screen), with agent replies as bubbles that fade after 10s.
                          Run again to move the crop.
   ${NAME} present stop [--port N|--pane ID]       End presentation mode (bubbles stay in the chat)
+  ${NAME} script load <file.json>   Load a presentation script (keeps the current position):
+                         {"rect": "x,y,w,h", "steps": [{"go": "#1", "say": ["line", ...], "hold": 6}]}
+                         go: "#n" sets location.hash, otherwise JS run in the page; one line = one bubble
+  ${NAME} script show               Script with positions (step.line) and player state
+  ${NAME} present resume            Play the script from where it stopped (starts presentation mode)
+  ${NAME} present pause             Stop the script (raising a hand on the page also pauses)
+  ${NAME} present goto <n[.m]>      Move to step n (line m) and show its screen
   ${NAME} help | --version
 
 start options:
@@ -284,6 +291,56 @@ async function cmdOpen(argv: string[]) {
   console.log(inst.url);
 }
 
+async function api(url: string, path: string, body?: object): Promise<any> {
+  try {
+    const r = await fetch(`${url}${path}`, {
+      method: body ? "POST" : "GET",
+      headers: { "Content-Type": "application/json" },
+      body: body ? JSON.stringify(body) : undefined,
+      signal: AbortSignal.timeout(8000),
+    });
+    return await r.json();
+  } catch {
+    return fail(`server unreachable: ${url}`);
+  }
+}
+
+const playerLine = (p: any) =>
+  `script: ${p.state}${p.last ? ` last=${p.last}` : ""}${p.next ? ` next=${p.next}` : ""} steps=${p.steps}`;
+
+async function cmdScript(argv: string[]) {
+  const { values: o, positionals } = parseArgs({
+    args: argv,
+    options: { port: { type: "string" }, pane: { type: "string" } },
+    allowPositionals: true,
+  });
+  const [sub, file] = positionals;
+  const inst = await resolveTarget(o);
+  if (sub === "load") {
+    if (!file) fail("usage: script load <file.json>");
+    let script: unknown;
+    try {
+      script = await Bun.file(file!).json();
+    } catch (e) {
+      fail(`cannot read ${file}: ${(e as Error).message}`);
+    }
+    const res = await api(inst.url, "/script", { script });
+    if (!res.ok) fail(res.error);
+    console.log(playerLine(res.player));
+  } else if (sub === "show" || !sub) {
+    const res = await api(inst.url, "/script");
+    console.log(playerLine(res.player));
+    for (const [i, st] of (res.script?.steps ?? []).entries()) {
+      console.log(`${i + 1}${st.go ? `  go=${st.go}` : ""}${st.hold ? `  hold=${st.hold}s` : ""}`);
+      st.say.forEach((l: string, j: number) => {
+        const at = `${i + 1}.${j + 1}`;
+        const mark = at === res.player.next ? ">" : at === res.player.last ? "*" : " ";
+        console.log(` ${mark} ${at}  ${l}`);
+      });
+    }
+  } else fail(`unknown script command: ${sub}`);
+}
+
 async function cmdPresent(argv: string[]) {
   const { values: o, positionals } = parseArgs({
     args: argv,
@@ -291,6 +348,14 @@ async function cmdPresent(argv: string[]) {
     allowPositionals: true,
   });
   const inst = await resolveTarget(o);
+  const [sub, at] = positionals;
+  if (sub === "resume" || sub === "pause" || sub === "goto") {
+    if (sub === "goto" && !at) fail("usage: present goto <n[.m]>");
+    const res = await api(inst.url, "/player", { cmd: sub, at });
+    if (!res.ok) fail(`${res.error}${res.player ? ` (${playerLine(res.player)})` : ""}`);
+    console.log(playerLine(res.player));
+    return;
+  }
   const arg = positionals.join(",");
   let body: object;
   if (arg === "stop") body = { stop: true };
@@ -337,6 +402,9 @@ switch (cmd) {
   case "present":
     await cmdPresent(rest);
     break;
+  case "script":
+    await cmdScript(rest);
+    break;
   case "--version":
   case "-v":
     console.log(pkg.version);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agello",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "description": "Talk to a coding agent in a herdr pane from the browser: chat, live status, and a shared browser screen.",
   "keywords": [
     "herdr",

package/src/player.ts

@@ -0,0 +1,234 @@
+// Presentation script player.
+//
+// A script is a list of steps. Each step has an optional `go` (how to bring the
+// screen to that step: "#3" sets location.hash, anything else is evaluated as
+// JS in the page; written by the agent, agello knows nothing about the deck)
+// and lines (`say`), each shown as one bubble.
+//
+// The player owns order and timing: entering a step runs its `go`, then every
+// line is sent and held for its reading time (see PACE). pause() stops at once and keeps
+// the position, resume() re-runs the current step's `go` (the agent may have
+// moved the screen meanwhile) and continues from the next unshown line.
+// goto() moves the position and shows that step without playing.
+//
+// Positions are "step.line", 1-based, in everything that leaves this module.
+
+import type { Rect } from "./screencast.ts";
+
+export type Step = { go?: string; say: string[]; hold?: number };
+export type Script = { rect?: Rect; steps: Step[] };
+export type PlayerInfo = {
+  state: "empty" | "ready" | "playing" | "paused" | "done";
+  next?: string; // next line to show ("3.2")
+  last?: string; // last line shown
+  steps: number;
+};
+
+// Pacing: the audience looks at a new screen first, then reads and thinks.
+//   go -> 1s -> line (shown >= 10s) -> fades out -> 0.3s -> next line
+//                                     last line -> fades out -> 0.7s -> next step's go
+const MIN_HOLD = 10;
+const MAX_HOLD = 20;
+export const PACE = { afterGo: 1000, fade: 500, betweenLines: 300, afterStep: 700 };
+
+// How long one line stays on screen (s): at least 10s, longer text a bit more
+// (about 8 chars/s past the first ~50 chars), at most 20s. `hold` can only
+// lengthen it.
+export function lineHold(text: string, hold?: number): number {
+  const auto = Math.min(MAX_HOLD, Math.max(MIN_HOLD, 4 + [...text].length / 8));
+  return hold != null && Number.isFinite(hold) && hold > 0 ? Math.max(MIN_HOLD, hold) : auto;
+}
+
+export function parseRectString(v: unknown): Rect | undefined {
+  if (v && typeof v === "object") {
+    const r = v as any;
+    return { x: r.x, y: r.y, w: r.w, h: r.h };
+  }
+  if (typeof v !== "string") return undefined;
+  const n = v.split(/[\s,]+/).filter(Boolean).map(Number);
+  return n.length === 4 ? { x: n[0], y: n[1], w: n[2], h: n[3] } : undefined;
+}
+
+// Validate a script from JSON. Returns the script or an error message.
+export function parseScript(raw: any): Script | string {
+  if (!raw || typeof raw !== "object") return "script must be an object";
+  if (!Array.isArray(raw.steps) || !raw.steps.length) return "steps must be a non-empty array";
+  const steps: Step[] = [];
+  for (const [i, s] of raw.steps.entries()) {
+    const at = `steps[${i}]`;
+    if (!s || typeof s !== "object") return `${at} must be an object`;
+    if (s.go != null && typeof s.go !== "string") return `${at}.go must be a string`;
+    const say = s.say == null ? [] : Array.isArray(s.say) ? s.say : [s.say];
+    if (!say.every((l: unknown) => typeof l === "string" && l.trim())) return `${at}.say must be non-empty strings`;
+    if (s.hold != null && !(Number.isFinite(s.hold) && s.hold > 0)) return `${at}.hold must be a positive number`;
+    steps.push({ go: s.go || undefined, say: say.map((l: string) => l.trim()), hold: s.hold });
+  }
+  const rect = raw.rect == null ? undefined : parseRectString(raw.rect);
+  if (raw.rect != null && !rect) return "rect must be \"x,y,w,h\" or {x,y,w,h}";
+  return { rect, steps };
+}
+
+// "3" or "3.2" (1-based) -> 0-based position
+export function parsePos(v: string): { step: number; line: number } | null {
+  const m = String(v).trim().match(/^(\d+)(?:\.(\d+))?$/);
+  if (!m) return null;
+  const step = Number(m[1]) - 1;
+  const line = m[2] ? Number(m[2]) - 1 : 0;
+  return step >= 0 && line >= 0 ? { step, line } : null;
+}
+
+export function createPlayer(deps: {
+  go: (expr: string) => Promise<void>;
+  say: (text: string, at: string, hold: number) => void;
+  done: () => void;
+  changed: () => void;
+}) {
+  let script: Script | null = null;
+  let state: PlayerInfo["state"] = "empty";
+  let cur = { step: 0, line: 0 }; // next line to show
+  let last: { step: number; line: number } | null = null;
+  let entered = false; // `go` of cur.step already run in this play run
+  let run = 0; // bumps on every pause/goto/load, stale timers check it
+  let timer: Timer | null = null;
+
+  const fmt = (p: { step: number; line: number }) => `${p.step + 1}.${p.line + 1}`;
+  const set = (s: PlayerInfo["state"]) => {
+    state = s;
+    deps.changed();
+  };
+  const cancel = () => {
+    run++;
+    if (timer) clearTimeout(timer);
+    timer = null;
+  };
+  const wait = (ms: number, id: number, fn: () => void) => {
+    timer = setTimeout(() => id === run && fn(), ms);
+  };
+
+  function info(): PlayerInfo {
+    const steps = script?.steps.length ?? 0;
+    // next line as it will be played (a finished step points at the next step)
+    let p = cur;
+    while (script && p.step < steps && p.line >= Math.max(1, script.steps[p.step].say.length))
+      p = { step: p.step + 1, line: 0 };
+    return {
+      state,
+      steps,
+      next: script && p.step < steps ? fmt(p) : undefined,
+      last: last ? fmt(last) : undefined,
+    };
+  }
+
+  // Skip past finished steps (cur.line beyond the step's lines).
+  function normalize() {
+    if (!script) return;
+    while (cur.step < script.steps.length && cur.line >= Math.max(1, script.steps[cur.step].say.length)) {
+      cur = { step: cur.step + 1, line: 0 };
+      entered = false;
+    }
+  }
+
+  async function tick(id: number) {
+    if (id !== run || state !== "playing" || !script) return;
+    normalize();
+    if (cur.step >= script.steps.length) {
+      set("done");
+      deps.done();
+      return;
+    }
+    const step = script.steps[cur.step];
+    if (!entered) {
+      entered = true;
+      if (step.go) {
+        await deps.go(step.go);
+        if (id !== run) return;
+        wait(PACE.afterGo, id, () => tick(id));
+        return;
+      }
+    }
+    if (!step.say.length) {
+      // silent step: just show the screen for `hold` seconds
+      cur = { step: cur.step, line: 1 };
+      deps.changed();
+      wait(lineHold("", step.hold) * 1000 + PACE.afterStep, id, () => tick(id));
+      return;
+    }
+    const text = step.say[cur.line];
+    const hold = lineHold(text, step.hold);
+    const lastLine = cur.line === step.say.length - 1;
+    last = { ...cur };
+    deps.say(text, fmt(cur), hold);
+    cur = { step: cur.step, line: cur.line + 1 };
+    deps.changed();
+    const gap = lastLine ? PACE.afterStep : PACE.betweenLines;
+    wait(hold * 1000 + PACE.fade + gap, id, () => tick(id));
+  }
+
+  return {
+    info,
+    script: () => script,
+
+    // Replace the script, keeping the position (clamped) and the state.
+    load(next: Script) {
+      const playing = state === "playing";
+      cancel();
+      script = next;
+      if (cur.step > next.steps.length) cur = { step: next.steps.length, line: 0 };
+      normalize();
+      if (state === "empty") state = "ready";
+      if (state === "done" && cur.step < next.steps.length) state = "paused";
+      if (playing) {
+        entered = true; // screen is already on this step
+        tick(run);
+      }
+      deps.changed();
+    },
+
+    resume(): string | null {
+      if (!script) return "no_script";
+      if (state === "playing") return null;
+      if (state === "done") return "done";
+      cancel();
+      entered = false; // bring the screen back to the current step first
+      set("playing");
+      tick(run);
+      return null;
+    },
+
+    pause() {
+      if (state !== "playing") return;
+      cancel();
+      set("paused");
+    },
+
+    // Move to a step (and line) and show its screen. Does not play; if it was
+    // playing, it keeps playing from there.
+    async goto(pos: { step: number; line: number }): Promise<string | null> {
+      if (!script) return "no_script";
+      const step = script.steps[pos.step];
+      if (!step) return "no_such_step";
+      if (pos.line > 0 && pos.line >= step.say.length) return "no_such_line";
+      const playing = state === "playing";
+      cancel();
+      cur = { ...pos };
+      entered = false;
+      if (playing) {
+        tick(run);
+        return null;
+      }
+      if (state !== "ready") state = "paused";
+      if (step.go) await deps.go(step.go);
+      entered = true;
+      deps.changed();
+      return null;
+    },
+
+    // Presentation ended: stop where it is.
+    stop() {
+      if (state === "playing") {
+        cancel();
+        set("paused");
+      }
+    },
+  };
+}

package/src/screencast.ts

@@ -268,5 +268,75 @@ export function createScreencast(opts: { browserKey?: string; herdrTab?: () => P
     return browser ? { connected: false, browser: browser.key } : { connected: false, reason };
   }
 
-  return { handle, input, describe, setClip };
+  // Run JS in the relayed tab (presentation script `go`). Needs the relay to be
+  // connected, i.e. at least one viewer. Returns false if it could not run.
+  async function evaluate(expression: string): Promise<boolean> {
+    const r = await request("Runtime.evaluate", { expression, awaitPromise: true });
+    return !!r && !r.exceptionDetails;
+  }
+
+  // Annotation: which element is at a point (hover / click) or where a
+  // selected element is now (by selector). Coordinates are CSS px of the
+  // visible viewport, same as the full screencast frame. Not while cropped.
+  async function inspect(q: InspectQuery): Promise<Inspected | null> {
+    if (clip) return null;
+    const r = await request("Runtime.evaluate", {
+      expression: `(${INSPECT_JS})(${JSON.stringify(q)})`,
+      returnByValue: true,
+    });
+    return r && !r.exceptionDetails ? (r.result?.value ?? null) : null;
+  }
+
+  return { handle, input, describe, setClip, evaluate, inspect };
 }
+
+export type InspectQuery = { x?: number; y?: number; selector?: string; full?: boolean };
+export type Inspected = {
+  selector: string;
+  label: string; // tag#id.class, for the hover tooltip
+  rect: { x: number; y: number; w: number; h: number };
+  text?: string; // full only
+  url?: string; // full only
+};
+
+// Runs in the page. Selector: nearest unique id / data-testid ancestor, then
+// tag:nth-of-type steps down to the element (light DOM only).
+const INSPECT_JS = String((q: InspectQuery) => {
+  let el: Element | null = null;
+  if (q.selector) {
+    try {
+      el = document.querySelector(q.selector);
+    } catch {}
+  } else el = document.elementFromPoint(q.x ?? 0, q.y ?? 0);
+  if (!el || el === document.documentElement) return null;
+  const esc = CSS.escape;
+  const unique = (s: string) => document.querySelectorAll(s).length === 1;
+  const step = (e: Element): [string, boolean] => {
+    if (e.id && unique(`#${esc(e.id)}`)) return [`#${esc(e.id)}`, true];
+    for (const a of ["data-testid", "data-test", "data-cy"]) {
+      const v = e.getAttribute(a);
+      if (v && unique(`[${a}="${esc(v)}"]`)) return [`[${a}="${esc(v)}"]`, true];
+    }
+    const same = e.parentElement ? [...e.parentElement.children].filter((c) => c.localName === e.localName) : [];
+    return [same.length > 1 ? `${e.localName}:nth-of-type(${same.indexOf(e) + 1})` : e.localName, false];
+  };
+  const parts: string[] = [];
+  for (let e: Element | null = el; e && e !== document.documentElement; e = e.parentElement) {
+    const [s, anchor] = step(e);
+    parts.unshift(s);
+    if (anchor || e === document.body) break;
+  }
+  const cls = [...el.classList].slice(0, 2).map((c) => `.${c}`).join("");
+  const r = el.getBoundingClientRect();
+  const out: any = {
+    selector: parts.join(" > "),
+    label: `${el.localName}${el.id ? `#${el.id}` : ""}${cls}`,
+    rect: { x: r.x, y: r.y, w: r.width, h: r.height },
+  };
+  if (q.full) {
+    const t = (el as HTMLInputElement).value || el.getAttribute("aria-label") || el.getAttribute("alt") || el.textContent || "";
+    out.text = t.replace(/\s+/g, " ").trim().slice(0, 80);
+    out.url = location.href;
+  }
+  return out;
+});

package/src/server.ts

@@ -6,17 +6,22 @@
 // GET  /events           SSE: status, chat messages, tool start/end (from transcript JSONL)
 // POST /send             {action, text, images?: [{type, data(base64)}]} -> herdr agent prompt
 //                        (images are saved to $TMPDIR/agello-uploads and sent as [image: <path>])
+//                        (action "annotate": + target {selector, label, rect, text?, url?} from inspect)
 // GET  /screen           SSE: terminal-browser screen frames (CDP screencast)
 // POST /upload           {images: [{type, data(base64)}]} -> {paths}: terminal image paste
 // WS   /terminal         interactive herdr terminal frames, keyboard input, resize
 // GET  /panes            herdr workspace -> tab -> pane tree
 // POST /panes/connect    {pane} -> url of that pane's server (started if needed)
 // POST /panes/create     {kind: workspace|tab|pane, cwd?, label?, workspace?, pane?, direction?}
-// WS   /input            user control: CDP Input.* commands forwarded to the page
+// WS   /input            user control: CDP Input.* commands forwarded to the page;
+//                        {id, inspect: {x, y} | {selector}, full?} -> {id, result}: element at a point (annotation)
 // GET  /present          presentation state
 // POST /present          {rect?: {x,y,w,h}} start (or move the crop), {stop: true} end
 //                        ({stop: true, from: "viewer"}: ended from the page, the agent is told
 //                         with "[browser] action=present-stop")
+// GET  /script           presentation script + player position
+// POST /script           {script: {rect?, steps: [{go?, say: string[], hold?}]}} load (keeps position)
+// POST /player           {cmd: "resume" | "pause" | "goto", at?: "3" | "3.2"}
 
 import { createTerminal, type SocketData } from "./terminal.ts";
 import { panesRoute } from "./panes.ts";
@@ -24,7 +29,8 @@ import { mkdir } from "node:fs/promises";
 import { homedir, tmpdir } from "node:os";
 import { join } from "node:path";
 import { runJson } from "./run.ts";
-import { createScreencast, type Rect } from "./screencast.ts";
+import { createPlayer, parsePos, parseScript, type PlayerInfo } from "./player.ts";
+import { createScreencast, type Inspected, type Rect } from "./screencast.ts";
 
 export type ServerOptions = {
   port: number;
@@ -123,7 +129,22 @@ export function parseRect(r: any): Rect | null {
   return { x, y, w, h };
 }
 
-export type Present = { on: boolean; rect?: Rect; since?: string };
+// Annotation prompt: the viewer's request plus the element it points at, in
+// 3 lines (request / selector / element summary).
+export function formatAnnotation(text: string, t: any): string | null {
+  if (!t || typeof t.selector !== "string" || !t.selector || t.selector.length > 1000) return null;
+  const clean = (v: unknown, n: number) => String(v ?? "").replace(/\s+/g, " ").trim().slice(0, n);
+  const request = text.split(/\r?\n/).map((l) => l.trim()).filter(Boolean).join(" / ");
+  const r = t.rect ?? {};
+  const [x, y, w, h] = [r.x, r.y, r.w, r.h].map((v) => Math.round(Number(v) || 0));
+  const label = clean(t.label, 120);
+  const snippet = clean(t.text, 80);
+  const url = clean(t.url, 300);
+  const info = [`요소: ${label}${snippet ? ` "${snippet}"` : ""}`, `위치 ${x},${y} 크기 ${w}x${h}`, url].filter(Boolean);
+  return [request, `대상: ${clean(t.selector, 1000)}`, info.join(" · ")].join("\n");
+}
+
+export type Present = { on: boolean; rect?: Rect; since?: string; player?: PlayerInfo };
 
 type Status =
   | { alive: false; reason: string; pane: string }
@@ -351,10 +372,67 @@ export async function startServer(opts: ServerOptions) {
   // short-lived bubbles. rect: crop of the visible viewport (unset = whole screen).
 
   let present: Present = { on: false };
+  const presentView = (): Present => ({ ...present, player: player.info() });
   function setPresent(next: Present) {
     present = next;
     screen.setClip(next.on ? (next.rect ?? null) : null);
-    broadcast("present", present);
+    if (!next.on) player.stop();
+    broadcast("present", presentView());
+  }
+
+  // Script player: agello owns order and timing, the agent owns the deck
+  // (each step's `go`) and decides when to resume after a question.
+  const player = createPlayer({
+    async go(expr) {
+      const js = expr.startsWith("#") ? `location.hash = ${JSON.stringify(expr)}` : expr;
+      if (!(await screen.evaluate(js))) console.error(`present: go failed: ${expr}`);
+    },
+    say(text, at, hold) {
+      broadcast("message", { role: "assistant", text, ts: new Date().toISOString(), script: at, hold });
+    },
+    done() {
+      const n = player.info().steps;
+      promptAgent("present-done", `대본 끝까지 재생함 (${n}장)`);
+    },
+    changed() {
+      broadcast("present", presentView());
+    },
+  });
+
+  // "마지막 표시 3.2 · 다음 3.3" for agent notices
+  const where = () => {
+    const i = player.info();
+    if (i.state === "empty") return "";
+    return [i.last && `마지막 표시 ${i.last}`, i.next && `다음 ${i.next}`].filter(Boolean).join(" · ");
+  };
+
+  async function scriptRequest(req: Request): Promise<Response> {
+    if (req.method !== "POST") return Response.json({ script: player.script(), player: player.info() });
+    const data = (await req.json().catch(() => ({}))) as { script?: unknown };
+    const script = parseScript(data.script);
+    if (typeof script === "string") return Response.json({ ok: false, error: script }, { status: 400 });
+    if (script.rect && !parseRect(script.rect))
+      return Response.json({ ok: false, error: "invalid_rect" }, { status: 400 });
+    player.load(script);
+    return Response.json({ ok: true, player: player.info() });
+  }
+
+  async function playerRequest(req: Request): Promise<Response> {
+    const data = (await req.json().catch(() => ({}))) as { cmd?: string; at?: string };
+    let error: string | null = null;
+    if (data.cmd === "resume") {
+      if (!present.on) {
+        const rect = player.script()?.rect;
+        setPresent({ on: true, rect: rect ? parseRect(rect)! : undefined, since: new Date().toISOString() });
+      }
+      error = player.resume();
+    } else if (data.cmd === "pause") player.pause();
+    else if (data.cmd === "goto") {
+      const pos = parsePos(data.at ?? "");
+      error = pos ? await player.goto(pos) : "invalid_position";
+    } else error = "unknown_cmd";
+    if (error) return Response.json({ ok: false, error, player: player.info() }, { status: 400 });
+    return Response.json({ ok: true, player: player.info() });
   }
 
   async function presentRequest(req: Request): Promise<Response> {
@@ -366,10 +444,11 @@ export async function startServer(opts: ServerOptions) {
       // (The CLI stop comes from the agent itself and needs no notice.)
       let notified: string | undefined;
       if (was && data.from === "viewer") {
-        const r = await promptAgent("present-stop", "사용자가 페이지에서 발표를 종료함");
+        const at = where();
+        const r = await promptAgent("present-stop", `사용자가 페이지에서 발표를 종료함${at ? ` (대본 정지: ${at})` : ""}`);
         notified = r.ok ? "ok" : r.error;
       }
-      return Response.json({ ok: true, present, notified });
+      return Response.json({ ok: true, present: presentView(), notified });
     }
     let rect: Rect | undefined;
     if (data.rect != null) {
@@ -377,7 +456,7 @@ export async function startServer(opts: ServerOptions) {
       if (!rect) return Response.json({ ok: false, error: "invalid_rect" }, { status: 400 });
     }
     setPresent({ on: true, rect, since: present.on ? present.since : new Date().toISOString() });
-    return Response.json({ ok: true, present });
+    return Response.json({ ok: true, present: presentView() });
   }
 
   // ----- HTTP -----
@@ -418,7 +497,7 @@ export async function startServer(opts: ServerOptions) {
           tools: [...pendingTools.keys()],
         });
         if (lastStatus) send(c, "status", lastStatus);
-        send(c, "present", present);
+        send(c, "present", presentView());
         for (const t of pendingTools.values()) send(c, "tool_start", t);
         ping = setInterval(() => send(c, "ping", {}), 15000);
       },
@@ -443,11 +522,24 @@ export async function startServer(opts: ServerOptions) {
   }
 
   async function sendPrompt(req: Request): Promise<Response> {
-    const data = (await req.json().catch(() => ({}))) as { action?: string; text?: string; images?: unknown };
+    const data = (await req.json().catch(() => ({}))) as { action?: string; text?: string; images?: unknown; target?: Inspected };
     const action = /^[\w-]{1,32}$/.test(data.action ?? "") ? data.action! : "message";
+    let text = data.text ?? "";
+    if (action === "annotate") {
+      const t = formatAnnotation(text, data.target);
+      if (!t || !text.trim()) return Response.json({ ok: false, error: "invalid_target" }, { status: 400 });
+      text = t;
+    }
+    // Raised hand: stop the script at once (no agent round trip) and tell the
+    // agent where it stopped.
+    if (action === "hand-raise") {
+      player.pause();
+      const at = where();
+      if (at) text += ` (대본 정지: ${at})`;
+    }
     const images = await saveImages(data.images);
     if (!images) return Response.json({ ok: false, error: "invalid_images" }, { status: 400 });
-    const text = [data.text ?? "", ...images.map((p) => `[image: ${p}]`)].join("\n");
+    text = [text, ...images.map((p) => `[image: ${p}]`)].join("\n");
     const r = await promptAgent(action, text);
     return r.ok ? Response.json({ ok: true }) : Response.json({ ok: false, error: r.error }, { status: r.status });
   }
@@ -463,7 +555,7 @@ export async function startServer(opts: ServerOptions) {
           ...(await checkStatus()),
           browser: opts.browser,
           screen: await screen.describe(),
-          present,
+          present: presentView(),
         });
       case "/events":
         return events();
@@ -488,7 +580,12 @@ export async function startServer(opts: ServerOptions) {
         }
         break;
       case "/present":
-        return req.method === "POST" ? presentRequest(req) : Response.json(present);
+        return req.method === "POST" ? presentRequest(req) : Response.json(presentView());
+      case "/script":
+        return scriptRequest(req);
+      case "/player":
+        if (req.method === "POST") return playerRequest(req);
+        break;
     }
     return new Response(HTML, { headers: { "Content-Type": "text/html; charset=utf-8", "Cache-Control": "no-store" } });
   }
@@ -500,9 +597,25 @@ export async function startServer(opts: ServerOptions) {
     websocket: {
       maxPayloadLength: 128 * 1024,
       open(ws) { if (ws.data.kind === "terminal") terminal.open(ws); },
-      message(ws, msg) {
-        if (ws.data.kind === "terminal") terminal.message(ws, String(msg));
-        else screen.input(String(msg));
+      async message(ws, msg) {
+        const raw = String(msg);
+        if (ws.data.kind === "terminal") return terminal.message(ws, raw);
+        let m: any;
+        try {
+          m = JSON.parse(raw);
+        } catch {
+          return;
+        }
+        if (m?.inspect) {
+          const q = m.inspect;
+          const query =
+            typeof q.selector === "string"
+              ? { selector: q.selector.slice(0, 1000), full: !!q.full }
+              : { x: Number(q.x) || 0, y: Number(q.y) || 0, full: !!q.full };
+          ws.send(JSON.stringify({ id: m.id, result: await screen.inspect(query) }));
+          return;
+        }
+        screen.input(raw);
       },
       close(ws) { if (ws.data.kind === "terminal") terminal.close(ws); },
     },

package/web/agent-bridge.js

@@ -12,6 +12,9 @@
 //   no-history   do not persist chat in localStorage (default: persisted per server + pane)
 //   screen       show live terminal-browser screen panel (side by side, stacked when narrow)
 //                with a toggle that lets the viewer control the browser (mouse, wheel, keyboard)
+//                and an annotate toggle: hovering tints the element under the pointer, clicking
+//                outlines it and opens an input; the request goes to the agent with the element's
+//                CSS selector (action=annotate). The wheel still scrolls the page.
 //
 // Theming (CSS custom properties on the element or an ancestor)
 //   --ab-bg --ab-panel --ab-text --ab-muted --ab-line --ab-accent --ab-user --ab-font
@@ -42,9 +45,12 @@
 //   closing it without asking sends action=hand-lower so it can go on.
 //   The viewer's questions show as bubbles too, with the same 10s lifetime.
 //   An end button above it stops the presentation for every viewer.
+//   Script lines (`agello script` + `present resume`) arrive as agent messages
+//   with `script: "step.line"`. While the script is not playing and the agent
+//   is working (e.g. answering a question), a small loader is shown.
 //
 // Methods
-//   el.send(text, action = 'message', images = [{type, data (base64)}]) -> Promise<{ok, error?}>
+//   el.send(text, action = 'message', extra) -> Promise<{ok, error?}>  (extra: {images: [{type, data (base64)}]}, {target} for annotate)
 //   el.clearHistory()                  clear saved chat for the current pane
 //   el.stopPresent()                   end presentation mode, tell the agent -> Promise<{ok, error?, notified?}>
 
@@ -75,7 +81,7 @@ const SCREEN_REASONS = {
 };
 const ACTIONS = {
   message: "메시지", approve: "승인", reject: "거절",
-  "present-stop": "발표 종료", "hand-raise": "손들기", "hand-lower": "손 내림",
+  "present-stop": "발표 종료", "hand-raise": "손들기", "hand-lower": "손 내림", annotate: "주석",
 };
 
 const CSS = `
@@ -228,6 +234,30 @@ h1 { font-size: 14px; margin: 0; font-weight: 600; }
 @media (prefers-reduced-motion: reduce) { .control-btn .track, .control-btn .knob { transition: none; } }
 .placeholder { font-size: 13px; color: var(--_muted); text-align: center; }
 
+/* annotate: hover tint, selected outline, request input next to the element */
+.annot-btn { flex: none; font-size: 12px; padding: 2px 10px; border-radius: 999px; }
+.annot-btn[aria-pressed="true"] { background: var(--_accent); border-color: var(--_accent); color: #fff; }
+.viewport.annot img { cursor: crosshair; }
+.hl { position: absolute; z-index: 3; pointer-events: none; display: none; border-radius: 2px; }
+.hl.on { display: block; }
+.hl.hover { background: color-mix(in srgb, var(--_accent) 22%, transparent);
+            box-shadow: inset 0 0 0 1px color-mix(in srgb, var(--_accent) 55%, transparent); }
+.hl.sel { box-shadow: 0 0 0 2px var(--_accent), 0 0 0 5px color-mix(in srgb, var(--_accent) 25%, transparent); }
+.hl-label { position: absolute; z-index: 4; pointer-events: none; display: none; max-width: 60%;
+  padding: 2px 7px; border-radius: 5px; font: 11px/1.5 ui-monospace, Menlo, monospace; color: #fff;
+  background: rgba(20, 20, 22, .85); white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
+.hl-label.on { display: block; }
+.note { position: absolute; z-index: 5; width: min(340px, calc(100% - 16px)); padding: 10px; border-radius: 12px;
+  background: var(--_panel); border: 1px solid var(--_line); box-shadow: 0 8px 28px rgba(0,0,0,.22);
+  animation: capIn .18s ease; }
+.note[hidden] { display: none; }
+.note .note-target { font: 11px/1.4 ui-monospace, Menlo, monospace; color: var(--_muted); margin-bottom: 6px;
+  overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.note textarea { min-height: 52px; font-size: 14px; }
+.note .note-row { display: flex; align-items: center; gap: 8px; margin-top: 6px; }
+.note .note-hint { flex: 1; font-size: 12px; color: var(--_muted); }
+@media (prefers-reduced-motion: reduce) { .note { animation: none; } }
+
 /* presentation mode: the screen panel covers the window, chat stays hidden underneath.
    container-type would make the host the containing block of the fixed layer, so drop it. */
 :host([presenting]) { container-type: normal; }
@@ -255,6 +285,14 @@ h1 { font-size: 14px; margin: 0; font-weight: 600; }
 .caption a { color: inherit; }
 @keyframes capIn { from { opacity: 0; translate: 0 10px; } }
 
+/* agent busy while presenting (answering, fixing the script): minimal loader */
+.busy { display: none; }
+.body.present .busy.on { position: absolute; left: 22px; bottom: 28px; z-index: 5; display: flex; align-items: center;
+  gap: 9px; padding: 9px 14px; border-radius: 999px; font-size: 13px; color: #fff; background: rgba(20, 20, 22, .72);
+  -webkit-backdrop-filter: blur(16px); backdrop-filter: blur(16px); box-shadow: 0 8px 30px rgba(0,0,0,.35);
+  animation: capIn .25s ease; }
+.busy .spinner { border-color: rgba(255,255,255,.25); border-top-color: #fff; }
+
 /* raise hand: ask the agent mid-presentation */
 .hand-wrap { display: none; }
 .body.present .hand-wrap { position: absolute; right: 22px; bottom: 28px; z-index: 5; display: flex;
@@ -401,9 +439,13 @@ const TEMPLATE = `
 </section>
 <aside class="screen" part="screen">
   <div class="screen-bar"><span class="live" hidden>에이전트 조작 중</span><span class="url"></span>
+    <button class="annot-btn" type="button" aria-pressed="false" title="화면의 요소를 골라 에이전트에게 요청 (선택자와 함께 전달)">주석</button>
     <button class="control-btn" role="switch" aria-checked="false" title="켜면 마우스와 키보드 입력이 브라우저로 전달돼요 (끄기: Shift+Esc)">
       <span>내 조작</span><span class="track"><span class="knob"></span></span><span class="state-label">OFF</span></button></div>
-  <div class="viewport"><div class="ring"></div><div class="glow"></div><div class="agent-badge">에이전트 조작 중</div><img alt="에이전트 브라우저 화면" draggable="false"><textarea class="kbd" aria-label="브라우저 키보드 입력"></textarea><div class="placeholder">열린 terminal-browser 없음</div><div class="captions" part="captions" aria-live="polite"></div>
+  <div class="viewport"><div class="ring"></div><div class="glow"></div><div class="agent-badge">에이전트 조작 중</div><img alt="에이전트 브라우저 화면" draggable="false"><textarea class="kbd" aria-label="브라우저 키보드 입력"></textarea><div class="placeholder">열린 terminal-browser 없음</div><div class="hl hover"></div><div class="hl sel"></div><div class="hl-label"></div>
+    <form class="note" part="note" hidden><div class="note-target"></div><textarea aria-label="선택한 요소에 대한 요청" placeholder="이 요소에 대한 요청 (Enter 전송, Esc 취소)"></textarea>
+      <div class="note-row"><span class="note-hint"></span><button type="submit" class="primary">보내기</button></div></form><div class="captions" part="captions" aria-live="polite"></div>
+    <div class="busy" part="busy" role="status"><span class="spinner"></span><span>답변 준비 중</span></div>
     <div class="hand-wrap">
       <form class="ask" part="ask" hidden><textarea aria-label="에이전트에게 질문" placeholder="에이전트에게 질문 (Enter 전송, Esc 닫기)"></textarea>
         <div class="ask-row"><span class="ask-hint"></span><button type="submit" class="primary">보내기</button></div></form>
@@ -422,7 +464,14 @@ class AgentBridge extends HTMLElement {
   #root = this.attachShadow({ mode: "open" });
   #es = null;
   #screenEs = null;
-  #controlWs = null;
+  #ws = null; // /input: control input and annotate inspect queries
+  #control = false;
+  #annot = false;
+  #hover = null; // inspected element under the pointer (annotate)
+  #hoverPt = null;
+  #sel = null; // selected element (annotate)
+  #inspectId = 0;
+  #inspectWait = new Map();
   #terminalCleanup = null;
   #terminalVersion = 0;
   #terminalStyles = null;
@@ -455,7 +504,9 @@ class AgentBridge extends HTMLElement {
       live: q(".live"), url: q(".screen-bar .url"), viewport: q(".viewport"), img: q(".viewport img"),
       controlBtn: q(".control-btn"), kbd: q(".kbd"),
       body: q(".body"), screen: q(".screen"), captions: q(".captions"),
-      hand: q(".hand"), end: q(".end"), ask: q(".ask"), askBox: q(".ask textarea"), askHint: q(".ask-hint"),
+      busy: q(".busy"), hand: q(".hand"), end: q(".end"), ask: q(".ask"), askBox: q(".ask textarea"), askHint: q(".ask-hint"),
+      annotBtn: q(".annot-btn"), hlHover: q(".hl.hover"), hlSel: q(".hl.sel"), hlLabel: q(".hl-label"),
+      note: q(".note"), noteBox: q(".note textarea"), noteHint: q(".note-hint"), noteTarget: q(".note-target"),
     };
     this.$.buttons.forEach((b) => b.addEventListener("click", () => this.#submit(b.dataset.action)));
     this.#bindGrip();
@@ -467,6 +518,7 @@ class AgentBridge extends HTMLElement {
     });
     loadMarkdown().then((md) => (this.#md = md));
     this.#bindControl();
+    this.#bindAnnotate();
     this.#bindHand();
     q(".term-btn").addEventListener("click", () => this.#showTerminal(!this.hasAttribute("terminal-open")));
     q(".terminal-retry").addEventListener("click", () => this.#showTerminal(true));
@@ -490,6 +542,7 @@ class AgentBridge extends HTMLElement {
     this.#screenEs?.close();
     this.#screenEs = null;
     this.#setControl(false);
+    this.#setAnnotate(false);
   }
   attributeChangedCallback(name) {
     if (name === "heading") this.$.heading.textContent = this.getAttribute("heading") || "agello";
@@ -506,6 +559,7 @@ class AgentBridge extends HTMLElement {
     q(".term-btn").setAttribute("aria-pressed", String(on));
     if (!on) return;
     this.#setControl(false);
+    this.#setAnnotate(false);
     q(".terminal-status").textContent = "터미널 로딩 중…";
     try {
       if (!this.#terminalStyles) {
@@ -772,12 +826,12 @@ class AgentBridge extends HTMLElement {
     }));
   }
 
-  async send(text, action = "message", images = []) {
+  async send(text, action = "message", extra = {}) {
     try {
       const res = await fetch(`${this.server}/send`, {
         method: "POST",
         headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({ action, text, images: images.length ? images : undefined }),
+        body: JSON.stringify({ ...extra, action, text }),
       });
       return await res.json();
     } catch {
@@ -816,7 +870,8 @@ class AgentBridge extends HTMLElement {
     on("message", (m) => {
       this.#addMessage(m);
       this.#saveMessage(m);
-      if (this.#present.on && m.role === "assistant") this.#caption(m.text);
+      // script lines carry their own on-screen time (>= 10s), others use CAPTION_MS
+      if (this.#present.on && m.role === "assistant") this.#caption(m.text, "agent", m.hold * 1000 || undefined);
       if (this.#present.on && m.role === "browser" && m.action === "message") this.#caption(m.text, "user");
       this.#emit("agent-message", m);
     });
@@ -842,7 +897,7 @@ class AgentBridge extends HTMLElement {
 
   #syncScreen() {
     const want = this.hasAttribute("screen") || this.#present.on;
-    if (!want) { this.#screenEs?.close(); this.#screenEs = null; this.#setControl(false); return; }
+    if (!want) { this.#screenEs?.close(); this.#screenEs = null; this.#setControl(false); this.#setAnnotate(false); return; }
     if (this.#screenEs) return;
     const es = (this.#screenEs = new EventSource(`${this.server}/screen`));
     es.addEventListener("meta", (e) => this.#renderScreenMeta(JSON.parse(e.data)));
@@ -851,6 +906,7 @@ class AgentBridge extends HTMLElement {
       this.#frame = { w: f.w, h: f.h };
       this.$.img.src = `data:image/jpeg;base64,${f.data}`;
       this.$.viewport.classList.add("has");
+      if (this.#annot) this.#annotFrame();
     });
     es.onerror = () => this.#renderScreenMeta({ connected: false });
   }
@@ -862,8 +918,9 @@ class AgentBridge extends HTMLElement {
     const was = this.#present.on;
     this.#present = p ?? { on: false };
     this.#emit("agent-present", this.#present);
+    this.#renderBusy();
     if (on === was) return;
-    if (on) { this.#showTerminal(false); this.#setControl(false); }
+    if (on) { this.#showTerminal(false); this.#setControl(false); this.#setAnnotate(false); }
     else { this.$.captions.replaceChildren(); this.#openAsk(false); this.#handUp = false; }
     this.#syncScreen();
     // FLIP: grow from (or shrink back to) the side panel
@@ -879,6 +936,12 @@ class AgentBridge extends HTMLElement {
       { duration: on ? 420 : 360, easing: "cubic-bezier(.2, .7, .2, 1)" });
   }
 
+  #renderBusy() {
+    const s = this.#status;
+    const busy = this.#present.on && s?.alive && s.status === "working" && this.#present.player?.state !== "playing";
+    this.$.busy.classList.toggle("on", !!busy);
+  }
+
   // Raise hand: open a small input over the presentation and send it as a message.
   #bindHand() {
     const { hand, ask, askBox, askHint } = this.$;
@@ -938,7 +1001,7 @@ class AgentBridge extends HTMLElement {
 
   // Agent reply as a short-lived bubble over the presented screen.
   // kind "user": the viewer's own question (plain text, accent colour).
-  #caption(text, kind = "agent") {
+  #caption(text, kind = "agent", ms = AgentBridge.CAPTION_MS) {
     if (!text?.trim()) return;
     const el = document.createElement("div");
     el.className = `caption ${kind}`;
@@ -953,7 +1016,7 @@ class AgentBridge extends HTMLElement {
       el.classList.add("out");
       setTimeout(() => el.remove(), 500);
     };
-    setTimeout(leave, AgentBridge.CAPTION_MS);
+    setTimeout(leave, ms);
     const live = [...box.children].filter((c) => !c.classList.contains("out"));
     live.slice(0, Math.max(0, live.length - AgentBridge.CAPTION_MAX)).forEach((c) => c.__leave?.());
     el.__leave = leave;
@@ -996,24 +1059,43 @@ class AgentBridge extends HTMLElement {
 
   // ---------- user control ----------
 
-  #setControl(on) {
-    if (on && !this.#controlWs) {
+  // One socket for both modes; open while control or annotate is on.
+  #syncWs() {
+    const want = this.#control || this.#annot;
+    if (want && !this.#ws) {
       const ws = new WebSocket(`${this.server.replace(/^http/, "ws")}/input`);
-      ws.onclose = () => { if (this.#controlWs === ws) this.#setControl(false); };
-      this.#controlWs = ws;
-    } else if (!on && this.#controlWs) {
-      const ws = this.#controlWs;
-      this.#controlWs = null;
+      ws.onmessage = (e) => {
+        let m;
+        try { m = JSON.parse(e.data); } catch { return; }
+        this.#inspectWait.get(m.id)?.(m.result ?? null);
+      };
+      ws.onclose = () => {
+        if (this.#ws !== ws) return;
+        this.#ws = null;
+        this.#setControl(false);
+        this.#setAnnotate(false);
+      };
+      this.#ws = ws;
+    } else if (!want && this.#ws) {
+      const ws = this.#ws;
+      this.#ws = null;
       ws.close();
     }
-    this.$.controlBtn.setAttribute("aria-checked", String(!!this.#controlWs));
-    this.$.controlBtn.querySelector(".state-label").textContent = this.#controlWs ? "ON" : "OFF";
-    this.$.viewport.classList.toggle("control", !!this.#controlWs);
-    if (this.#controlWs) this.$.kbd.focus();
+    if (!this.#ws) { this.#inspectWait.forEach((r) => r(null)); this.#inspectWait.clear(); }
+  }
+
+  #setControl(on) {
+    this.#control = !!on && !this.#present.on;
+    if (this.#control) this.#setAnnotate(false);
+    this.#syncWs();
+    this.$.controlBtn.setAttribute("aria-checked", String(this.#control));
+    this.$.controlBtn.querySelector(".state-label").textContent = this.#control ? "ON" : "OFF";
+    this.$.viewport.classList.toggle("control", this.#control);
+    if (this.#control) this.$.kbd.focus();
   }
 
   #cdp(method, params) {
-    const ws = this.#controlWs;
+    const ws = this.#ws;
     if (ws?.readyState === WebSocket.OPEN) ws.send(JSON.stringify({ method, params }));
   }
 
@@ -1027,11 +1109,11 @@ class AgentBridge extends HTMLElement {
 
   #bindControl() {
     const { img, kbd, controlBtn } = this.$;
-    const on = () => !!this.#controlWs && this.#frame.w > 0;
+    const on = () => this.#control && this.#frame.w > 0;
     const mods = (e) => (e.altKey ? 1 : 0) | (e.ctrlKey ? 2 : 0) | (e.metaKey ? 4 : 0) | (e.shiftKey ? 8 : 0);
     const BUTTONS = ["left", "middle", "right"];
 
-    controlBtn.addEventListener("click", () => { if (!this.#present.on) this.#setControl(!this.#controlWs); });
+    controlBtn.addEventListener("click", () => this.#setControl(!this.#control));
 
     img.addEventListener("mousedown", (e) => {
       if (!on()) return;
@@ -1059,7 +1141,7 @@ class AgentBridge extends HTMLElement {
       });
     });
     img.addEventListener("wheel", (e) => {
-      if (!on()) return;
+      if (!on() && !(this.#annot && this.#frame.w > 0)) return; // annotate: scroll to reach the element
       e.preventDefault();
       this.#cdp("Input.dispatchMouseEvent", { type: "mouseWheel", ...this.#point(e), deltaX: e.deltaX, deltaY: e.deltaY,
         modifiers: mods(e) });
@@ -1097,6 +1179,163 @@ class AgentBridge extends HTMLElement {
     });
   }
 
+  // ---------- annotate ----------
+
+  #setAnnotate(on) {
+    on = !!on && !this.#present.on;
+    if (on === this.#annot) return;
+    this.#annot = on;
+    if (on) this.#setControl(false);
+    else { this.#hover = null; this.#hoverPt = null; this.#select(null); }
+    this.#syncWs();
+    this.$.annotBtn.setAttribute("aria-pressed", String(on));
+    this.$.viewport.classList.toggle("annot", on);
+    this.#drawHl();
+  }
+
+  // Element at a frame point ({x, y}) or by selector; null if unavailable.
+  #inspect(q, full = false) {
+    const ws = this.#ws;
+    if (ws?.readyState !== WebSocket.OPEN) return Promise.resolve(null);
+    const id = ++this.#inspectId;
+    return new Promise((resolve) => {
+      const done = (r) => { clearTimeout(t); this.#inspectWait.delete(id); resolve(r); };
+      const t = setTimeout(() => done(null), 3000);
+      this.#inspectWait.set(id, done);
+      ws.send(JSON.stringify({ id, inspect: { ...q, full } }));
+    });
+  }
+
+  // Latest pointer position wins; at most one hover query in flight.
+  #probing = false;
+  #probeAgain = false;
+  async #probeHover() {
+    if (this.#probing) { this.#probeAgain = true; return; }
+    this.#probing = true;
+    try {
+      do {
+        this.#probeAgain = false;
+        const p = this.#hoverPt;
+        if (!p || !this.#annot) break;
+        const r = await this.#inspect(p);
+        if (this.#hoverPt && this.#annot) { this.#hover = r; this.#drawHl(); }
+      } while (this.#probeAgain);
+    } finally {
+      this.#probing = false;
+    }
+  }
+
+  // The page changed (scroll, layout, HMR): follow the selected element and
+  // re-check what is under the pointer.
+  #tracking = false;
+  async #annotFrame() {
+    if (this.#hoverPt) this.#probeHover();
+    const sel = this.#sel;
+    if (!sel || this.#tracking) { this.#drawHl(); return; }
+    this.#tracking = true;
+    try {
+      const r = await this.#inspect({ selector: sel.selector });
+      if (r && this.#sel === sel) sel.rect = r.rect; // gone from the page: keep the last box
+    } finally {
+      this.#tracking = false;
+    }
+    this.#drawHl();
+  }
+
+  #select(t) {
+    const { note, noteBox, noteHint, noteTarget } = this.$;
+    this.#sel = t;
+    note.hidden = !t;
+    noteHint.textContent = "";
+    if (t) {
+      noteTarget.textContent = t.selector;
+      noteTarget.title = t.selector;
+      noteBox.focus();
+    }
+    this.#drawHl();
+  }
+
+  // Frame (CSS px of the page viewport) -> position over the displayed image.
+  #drawHl() {
+    const { viewport, img, hlHover, hlSel, hlLabel, note } = this.$;
+    const show = this.#annot && viewport.classList.contains("has") && this.#frame.w > 0;
+    const vr = viewport.getBoundingClientRect();
+    const ir = img.getBoundingClientRect();
+    const sx = ir.width / this.#frame.w, sy = ir.height / this.#frame.h;
+    const box = (r) => {
+      if (!show || !r) return null;
+      const x0 = Math.max(r.x, 0), y0 = Math.max(r.y, 0);
+      const x1 = Math.min(r.x + r.w, this.#frame.w), y1 = Math.min(r.y + r.h, this.#frame.h);
+      if (x1 <= x0 || y1 <= y0) return null;
+      return { left: ir.left - vr.left + x0 * sx, top: ir.top - vr.top + y0 * sy, width: (x1 - x0) * sx, height: (y1 - y0) * sy };
+    };
+    const place = (el, b) => {
+      el.classList.toggle("on", !!b);
+      if (b) Object.assign(el.style, { left: `${b.left}px`, top: `${b.top}px`, width: `${b.width}px`, height: `${b.height}px` });
+      return b;
+    };
+    const hb = place(hlHover, box(this.#hover?.rect));
+    const sb = place(hlSel, box(this.#sel?.rect));
+
+    hlLabel.classList.toggle("on", !!hb);
+    if (hb) {
+      const r = this.#hover.rect;
+      hlLabel.textContent = `${this.#hover.label}  ${Math.round(r.w)}×${Math.round(r.h)}`;
+      // above the box, else below it, else inside its top edge
+      const top = hb.top >= 22 ? hb.top - 22 : hb.top + hb.height + 26 <= vr.height ? hb.top + hb.height + 4 : hb.top + 4;
+      Object.assign(hlLabel.style, { left: `${hb.left + (top === hb.top + 4 ? 4 : 0)}px`, top: `${top}px` });
+    }
+
+    // input below the selected element, above it if there is no room
+    if (!note.hidden) {
+      const W = note.offsetWidth, H = note.offsetHeight, pad = 8;
+      const b = sb ?? { left: pad, top: pad, width: 0, height: 0 };
+      let top = b.top + b.height + pad;
+      if (top + H > vr.height - pad) top = b.top - H - pad;
+      top = Math.max(pad, Math.min(top, vr.height - H - pad));
+      const left = Math.max(pad, Math.min(b.left, vr.width - W - pad));
+      Object.assign(note.style, { left: `${left}px`, top: `${top}px` });
+    }
+  }
+
+  #bindAnnotate() {
+    const { img, annotBtn, note, noteBox, noteHint } = this.$;
+    annotBtn.addEventListener("click", () => this.#setAnnotate(!this.#annot));
+    img.addEventListener("mousemove", (e) => {
+      if (!this.#annot || !this.#frame.w) return;
+      this.#hoverPt = this.#point(e);
+      this.#probeHover();
+    });
+    img.addEventListener("mouseleave", () => {
+      if (!this.#annot) return;
+      this.#hoverPt = null;
+      this.#hover = null;
+      this.#drawHl();
+    });
+    img.addEventListener("click", async (e) => {
+      if (!this.#annot || !this.#frame.w) return;
+      e.preventDefault();
+      const t = await this.#inspect(this.#point(e), true);
+      if (t && this.#annot) this.#select(t);
+    });
+    new ResizeObserver(() => this.#drawHl()).observe(img);
+    note.addEventListener("submit", async (e) => {
+      e.preventDefault();
+      const text = noteBox.value.trim();
+      const target = this.#sel;
+      if (!text || !target) return;
+      noteHint.textContent = "보내는 중…";
+      const res = await this.send(text, "annotate", { target });
+      if (!res.ok) { noteHint.textContent = `전송 실패: ${res.error}`; return; }
+      noteBox.value = "";
+      if (this.#sel === target) this.#select(null);
+    });
+    noteBox.addEventListener("keydown", (e) => {
+      if (e.key === "Enter" && !e.shiftKey && !e.isComposing) { e.preventDefault(); note.requestSubmit(); }
+      if (e.key === "Escape") { e.preventDefault(); this.#select(null); }
+    });
+  }
+
   #renderScreenMeta(m) {
     const { live, url, viewport } = this.$;
     if (!m.connected) {
@@ -1112,6 +1351,7 @@ class AgentBridge extends HTMLElement {
       url.textContent = m.title ? `${m.title} · ${m.url}` : m.url || "";
       url.title = m.url || "";
     }
+    this.#drawHl();
     this.#emit("agent-screen", m);
   }
 
@@ -1248,7 +1488,7 @@ class AgentBridge extends HTMLElement {
       return;
     } else if (m.role === "assistant") {
       wrap.className = "msg assistant";
-      meta.textContent = `에이전트 · ${time}`;
+      meta.textContent = `에이전트${m.script ? ` · 대본 ${m.script}` : ""} · ${time}`;
       if (this.#md) bubble.innerHTML = this.#md(m.text);
       else { bubble.textContent = m.text; bubble.classList.add("plain"); }
     } else if (m.role === "browser") {
@@ -1310,6 +1550,7 @@ class AgentBridge extends HTMLElement {
     this.$.buttons.forEach((b) => (b.disabled = !canSend));
     if (!s || !s.alive || s.status === "idle") this.#tools.clear();
     this.#renderActivity();
+    this.#renderBusy();
     this.#emit("agent-status", s);
   }
 
@@ -1318,7 +1559,7 @@ class AgentBridge extends HTMLElement {
     const images = this.#images.map(({ type, data }) => ({ type, data }));
     if (action === "message" && !text && !images.length) return;
     this.$.buttons.forEach((b) => (b.disabled = true));
-    const res = await this.send(text, action, images);
+    const res = await this.send(text, action, { images: images.length ? images : undefined });
     if (res.ok) {
       this.$.box.value = "";
       this.$.hint.textContent = "";