agello 0.1.4 → 0.2.1

package/README.md

@@ -67,11 +67,45 @@ The approve / reject buttons send `action=approve` / `action=reject`.
 | `agello stop [--port N \| --pane ID \| --all]` | Stop a server (default: this pane's) |
 | `agello status [--json]` | List running servers, agent state and screen browser |
 | `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`.
 
 State and logs: `~/.local/state/agello/<port>.json`, `<port>.log`.
 
+### Presentation mode
+
+`agello present x,y,w,h` (CSS px of the browser's visible viewport; omit for the whole screen):
+
+- only that rectangle is sent to the page (`Page.captureScreenshot` with a clip, at device resolution)
+- the screen panel expands to fill the window
+- agent replies appear over it as bubbles that fade after 10s
+- `agello present stop` returns to the normal layout; the replies are in the chat as usual
+- the viewer can ask a question with the raise-hand button (its bubble fades after 10s too) or end the presentation with the end button; the agent then receives `[browser] action=present-stop`
+- raising the hand tells the agent at once (`action=hand-raise`) so it can pause; closing the input without asking sends `action=hand-lower`
+
+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

@@ -22,6 +22,18 @@ Usage:
   ${NAME} stop [--port N|--pane ID|--all]  Stop a server (default: this pane's)
   ${NAME} status [--json]      List running servers
   ${NAME} open [--port N|--pane ID]        Open the page (default: this pane's server)
+  ${NAME} present [x,y,w,h] [--port N|--pane ID]  Presentation mode: the page shows only the screen,
+                         full size, cropped to the rect (CSS px of the visible viewport; omit for the
+                         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:
@@ -279,6 +291,98 @@ 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,
+    options: { port: { type: "string" }, pane: { type: "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 };
+  else if (!arg) body = {};
+  else {
+    const v = arg.split(/[\s,]+/).filter(Boolean).map(Number);
+    if (v.length !== 4 || !v.every(Number.isFinite)) fail(`rect must be x,y,w,h (got "${arg}")`);
+    body = { rect: { x: v[0], y: v[1], w: v[2], h: v[3] } };
+  }
+  let res: any;
+  try {
+    const r = await fetch(`${inst.url}/present`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(4000),
+    });
+    res = await r.json();
+  } catch {
+    fail(`server unreachable: ${inst.url}`);
+  }
+  if (!res?.ok) fail(res?.error ?? "failed");
+  const p = res.present;
+  if (!p.on) console.log("presentation: off");
+  else console.log(`presentation: on ${p.rect ? `rect=${p.rect.x},${p.rect.y},${p.rect.w},${p.rect.h}` : "(whole screen)"}`);
+}
+
 // ---------- main ----------
 
 const [cmd, ...rest] = Bun.argv.slice(2);
@@ -295,6 +399,12 @@ switch (cmd) {
   case "open":
     await cmdOpen(rest);
     break;
+  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.1.4",
+  "version": "0.2.1",
   "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

@@ -14,6 +14,9 @@ type Browser = {
   tabs: { id: number; url: string; title: string; active: boolean; targetId: string; agentControlled: boolean }[];
 };
 
+// Presentation crop: a rectangle of the visible viewport, in CSS pixels.
+export type Rect = { x: number; y: number; w: number; h: number };
+
 export type ScreenMeta = {
   connected: boolean;
   reason?: "browser_not_found" | "no_browser_in_tab" | "tab_unknown" | "no_active_tab";
@@ -28,11 +31,15 @@ export function createScreencast(opts: { browserKey?: string; herdrTab?: () => P
   const enc = new TextEncoder();
 
   let meta: ScreenMeta = { connected: false };
-  let lastFrame: { data: string; w: number; h: number } | null = null;
+  type Frame = { data: string; w: number; h: number; clip?: Rect };
+  let lastFrame: Frame | null = null; // full screencast frame
+  let lastCrop: Frame | null = null; // cropped frame while a clip is set
+  let clip: Rect | null = null;
   let ws: WebSocket | null = null;
   let wsTarget = "";
   let msgId = 0;
   let timer: Timer | null = null;
+  const pending = new Map<number, (result: any) => void>();
 
   const emit = (c: ReadableStreamDefaultController, event: string, data: unknown) => {
     try {
@@ -74,6 +81,63 @@ export function createScreencast(opts: { browserKey?: string; herdrTab?: () => P
     ws?.close();
     ws = null;
     wsTarget = "";
+    pending.forEach((r) => r(null));
+    pending.clear();
+  }
+
+  // CDP call that resolves with the result (null on error or closed socket).
+  function request(method: string, params: object = {}): Promise<any> {
+    const sock = ws;
+    if (!sock || sock.readyState !== WebSocket.OPEN) return Promise.resolve(null);
+    return new Promise((resolve) => {
+      const id = ++msgId;
+      const t = setTimeout(() => pending.delete(id) && resolve(null), 5000);
+      pending.set(id, (r) => (clearTimeout(t), resolve(r)));
+      sock.send(JSON.stringify({ id, method, params }));
+    });
+  }
+
+  // While a clip is set, only the clipped region is sent to viewers: every
+  // screencast frame (= the page changed) triggers one Page.captureScreenshot
+  // of the rectangle at full device resolution. At most one capture runs at a
+  // time; changes during a capture are coalesced into one more capture.
+  let capturing = false;
+  let dirty = false;
+  async function capture() {
+    if (!clip) return;
+    if (capturing) {
+      dirty = true;
+      return;
+    }
+    capturing = true;
+    try {
+      do {
+        dirty = false;
+        const c = clip;
+        if (!c) break;
+        // clip coordinates are document-relative; the rect is viewport-relative
+        const vv = (await request("Page.getLayoutMetrics"))?.cssVisualViewport;
+        if (!vv) break;
+        const shot = await request("Page.captureScreenshot", {
+          format: "jpeg",
+          quality: 85,
+          clip: { x: c.x + vv.pageX, y: c.y + vv.pageY, width: c.w, height: c.h, scale: 1 },
+        });
+        if (!shot?.data || clip !== c) continue;
+        lastCrop = { data: shot.data, w: c.w, h: c.h, clip: c };
+        broadcast("frame", lastCrop);
+        await Bun.sleep(100); // cap at ~10 captures/s
+      } while (dirty && clip);
+    } finally {
+      capturing = false;
+    }
+  }
+
+  function setClip(next: Rect | null) {
+    clip = next;
+    lastCrop = null;
+    if (clip) capture();
+    else if (lastFrame) broadcast("frame", lastFrame);
   }
 
   function connect(port: number, targetId: string) {
@@ -88,14 +152,22 @@ export function createScreencast(opts: { browserKey?: string; herdrTab?: () => P
     sock.onopen = () => {
       call("Page.enable");
       call("Page.startScreencast", { format: "jpeg", quality: 70, maxWidth: 1600, maxHeight: 1600 });
+      if (clip) capture();
     };
     sock.onmessage = (ev) => {
       const msg = JSON.parse(String(ev.data));
+      if (msg.id && pending.has(msg.id)) {
+        const resolve = pending.get(msg.id)!;
+        pending.delete(msg.id);
+        resolve(msg.result ?? null);
+        return;
+      }
       if (msg.method !== "Page.screencastFrame") return;
       const { data, metadata, sessionId } = msg.params;
       call("Page.screencastFrameAck", { sessionId });
       lastFrame = { data, w: metadata.deviceWidth, h: metadata.deviceHeight };
-      broadcast("frame", lastFrame);
+      if (clip) capture();
+      else broadcast("frame", lastFrame);
     };
     sock.onclose = () => {
       if (ws === sock) {
@@ -122,6 +194,7 @@ export function createScreencast(opts: { browserKey?: string; herdrTab?: () => P
     if (!b || !tab) {
       disconnect();
       lastFrame = null;
+      lastCrop = null;
       setMeta({ connected: false, reason: reason ?? "no_active_tab" });
       return;
     }
@@ -146,6 +219,7 @@ export function createScreencast(opts: { browserKey?: string; herdrTab?: () => P
     timer = null;
     disconnect();
     lastFrame = null;
+    lastCrop = null;
     meta = { connected: false };
   }
 
@@ -158,7 +232,8 @@ export function createScreencast(opts: { browserKey?: string; herdrTab?: () => P
         ctrl = c;
         viewers.add(c);
         emit(c, "meta", meta);
-        if (lastFrame) emit(c, "frame", lastFrame);
+        const f = clip ? lastCrop : lastFrame;
+        if (f) emit(c, "frame", f);
         ping = setInterval(() => emit(c, "ping", {}), 15000);
         start();
       },
@@ -181,7 +256,8 @@ export function createScreencast(opts: { browserKey?: string; herdrTab?: () => P
     } catch {
       return;
     }
-    if (!INPUT_METHODS.has(m?.method) || !ws || ws.readyState !== WebSocket.OPEN) return;
+    // input coordinates assume the full frame: ignore input while cropped
+    if (clip || !INPUT_METHODS.has(m?.method) || !ws || ws.readyState !== WebSocket.OPEN) return;
     ws.send(JSON.stringify({ id: ++msgId, method: m.method, params: m.params ?? {} }));
   }
 
@@ -192,5 +268,12 @@ export function createScreencast(opts: { browserKey?: string; herdrTab?: () => P
     return browser ? { connected: false, browser: browser.key } : { connected: false, reason };
   }
 
-  return { handle, input, describe };
+  // 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;
+  }
+
+  return { handle, input, describe, setClip, evaluate };
 }

package/src/server.ts

@@ -7,11 +7,19 @@
 // POST /send             {action, text} -> herdr agent prompt
 // GET  /screen           SSE: terminal-browser screen frames (CDP screencast)
 // WS   /input            user control: CDP Input.* commands forwarded to the page
+// 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 { homedir } from "node:os";
 import { join } from "node:path";
 import { runJson } from "./run.ts";
-import { createScreencast } from "./screencast.ts";
+import { createPlayer, parsePos, parseScript, type PlayerInfo } from "./player.ts";
+import { createScreencast, type Rect } from "./screencast.ts";
 
 export type ServerOptions = {
   port: number;
@@ -77,6 +85,17 @@ async function herdr(timeout: number, ...cmd: string[]): Promise<any> {
   return (await runJson(["herdr", ...cmd], timeout)) ?? { error: { code: "herdr_failed" } };
 }
 
+// Presentation rect from the API: finite, non-negative origin, positive size (CSS px).
+export function parseRect(r: any): Rect | null {
+  if (!r || typeof r !== "object") return null;
+  const v = [r.x, r.y, r.w, r.h].map(Number);
+  if (!v.every(Number.isFinite) || v[0] < 0 || v[1] < 0 || v[2] < 1 || v[3] < 1) return null;
+  const [x, y, w, h] = v.map(Math.round);
+  return { x, y, w, h };
+}
+
+export type Present = { on: boolean; rect?: Rect; since?: string; player?: PlayerInfo };
+
 type Status =
   | { alive: false; reason: string; pane: string }
   | { alive: true; status: string; pane: string; label?: string; session: string; title?: string };
@@ -291,6 +310,98 @@ export async function startServer(opts: ServerOptions) {
     herdrTab: async () => (await agentInfo())?.tab_id,
   });
 
+  // ----- presentation mode -----
+  // on: viewers show only the screen, full size, with agent replies as
+  // 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);
+    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> {
+    const data = (await req.json().catch(() => ({}))) as { rect?: unknown; stop?: boolean; from?: string };
+    if (data.stop) {
+      const was = present.on;
+      setPresent({ on: false });
+      // Ended from the page: the agent may still be presenting, so tell it.
+      // (The CLI stop comes from the agent itself and needs no notice.)
+      let notified: string | undefined;
+      if (was && data.from === "viewer") {
+        const at = where();
+        const r = await promptAgent("present-stop", `사용자가 페이지에서 발표를 종료함${at ? ` (대본 정지: ${at})` : ""}`);
+        notified = r.ok ? "ok" : r.error;
+      }
+      return Response.json({ ok: true, present: presentView(), notified });
+    }
+    let rect: Rect | undefined;
+    if (data.rect != null) {
+      rect = parseRect(data.rect) ?? undefined;
+      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: presentView() });
+  }
+
   // ----- HTTP -----
 
   // Same-origin and localhost pages are allowed by default; add more with
@@ -329,6 +440,7 @@ export async function startServer(opts: ServerOptions) {
           tools: [...pendingTools.keys()],
         });
         if (lastStatus) send(c, "status", lastStatus);
+        send(c, "present", presentView());
         for (const t of pendingTools.values()) send(c, "tool_start", t);
         ping = setInterval(() => send(c, "ping", {}), 15000);
       },
@@ -342,22 +454,40 @@ export async function startServer(opts: ServerOptions) {
     });
   }
 
-  async function sendPrompt(req: Request): Promise<Response> {
-    const data = (await req.json().catch(() => ({}))) as { action?: string; text?: string };
+  // Type a [browser] prompt into the agent session.
+  async function promptAgent(action: string, text: string): Promise<{ ok: boolean; error?: string; status?: number }> {
     const st = await checkStatus();
-    if (!st.alive) return Response.json({ ok: false, error: st.reason }, { status: 409 });
-    if (st.status === "blocked") return Response.json({ ok: false, error: "agent_blocked" }, { status: 409 });
+    if (!st.alive) return { ok: false, error: st.reason, status: 409 };
+    if (st.status === "blocked") return { ok: false, error: "agent_blocked", status: 409 };
+    const res = await herdr(10000, "agent", "prompt", PANE, formatPrompt(action, text.trim()));
+    if (res?.error) return { ok: false, error: res.error.code, status: 502 };
+    return { ok: true };
+  }
 
+  async function sendPrompt(req: Request): Promise<Response> {
+    const data = (await req.json().catch(() => ({}))) as { action?: string; text?: string };
     const action = /^[\w-]{1,32}$/.test(data.action ?? "") ? data.action! : "message";
-    const res = await herdr(10000, "agent", "prompt", PANE, formatPrompt(action, (data.text ?? "").trim()));
-    if (res?.error) return Response.json({ ok: false, error: res.error.code }, { status: 502 });
-    return Response.json({ ok: true });
+    let text = data.text ?? "";
+    // 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 r = await promptAgent(action, text);
+    return r.ok ? Response.json({ ok: true }) : Response.json({ ok: false, error: r.error }, { status: r.status });
   }
 
   async function route(req: Request, url: URL): Promise<Response> {
     switch (url.pathname) {
       case "/status":
-        return Response.json({ ...(await checkStatus()), browser: opts.browser, screen: await screen.describe() });
+        return Response.json({
+          ...(await checkStatus()),
+          browser: opts.browser,
+          screen: await screen.describe(),
+          present: presentView(),
+        });
       case "/events":
         return events();
       case "/screen":
@@ -368,6 +498,14 @@ export async function startServer(opts: ServerOptions) {
         });
       case "/send":
         if (req.method === "POST") return sendPrompt(req);
+        break;
+      case "/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" } });
   }

package/web/agent-bridge.js

@@ -23,10 +23,27 @@
 //   agent-tool     detail: { phase: 'start'|'end', id, name?, summary?, isError? }
 //                  (tool calls are also kept in the conversation as one-line rows, like the terminal)
 //   agent-screen   detail: { connected, browser?, url?, title?, agentControlled? }
+//   agent-present  detail: { on, rect?: {x,y,w,h}, since? }
+//
+// Presentation mode (started by the agent: `agello present [x,y,w,h]`)
+//   The screen panel expands to fill the window and shows only the given
+//   rectangle of the browser. Agent replies appear over it as bubbles that fade
+//   after 10s; they are also added to the chat, so it is all there when the
+//   presentation ends. User control is off while presenting.
+//   A raise-hand button next to the bubbles opens a small input so the viewer
+//   can ask the agent something mid-presentation (sent as action=message).
+//   Opening it tells the agent right away (action=hand-raise) so it can pause;
+//   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') -> Promise<{ok, error?}>
 //   el.clearHistory()                  clear saved chat for the current pane
+//   el.stopPresent()                   end presentation mode, tell the agent -> Promise<{ok, error?, notified?}>
 
 const SCRIPT_ORIGIN = new URL(import.meta.url).origin;
 
@@ -53,7 +70,10 @@ const SCREEN_REASONS = {
   tab_unknown: "에이전트의 herdr 탭을 확인할 수 없음",
   no_active_tab: "브라우저에 활성 탭 없음",
 };
-const ACTIONS = { message: "메시지", approve: "승인", reject: "거절" };
+const ACTIONS = {
+  message: "메시지", approve: "승인", reject: "거절",
+  "present-stop": "발표 종료", "hand-raise": "손들기", "hand-lower": "손 내림",
+};
 
 const CSS = `
 :host {
@@ -154,6 +174,68 @@ h1 { font-size: 14px; margin: 0; font-weight: 600; }
 .control-btn:focus-visible { outline: 2px solid var(--_accent); outline-offset: 2px; border-radius: 6px; }
 @media (prefers-reduced-motion: reduce) { .control-btn .track, .control-btn .knob { transition: none; } }
 .placeholder { font-size: 13px; color: var(--_muted); text-align: center; }
+
+/* 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; }
+.body.present .screen { display: flex; position: fixed; inset: 0; z-index: 2147483000; border: 0;
+                        width: auto; height: auto; background: #0b0b0c; }
+.body.present .screen-bar, .body.present .ring, .body.present .glow, .body.present .agent-badge { display: none; }
+.body.present .viewport { padding: 0; background: #0b0b0c; }
+.body.present .viewport img { width: 100%; height: 100%; max-width: none; max-height: none; border-radius: 0;
+                              box-shadow: none; }
+.captions { display: none; }
+.body.present .captions { position: absolute; left: 0; right: 0; bottom: 0; z-index: 4; display: flex;
+  flex-direction: column; align-items: center; gap: 10px; padding: 0 88px 28px; pointer-events: none; }
+.caption { max-width: min(900px, 86%); padding: 12px 18px; border-radius: 16px; overflow-wrap: anywhere;
+  font-size: 18px; line-height: 1.5; color: #fff; background: rgba(20, 20, 22, .72);
+  -webkit-backdrop-filter: blur(16px) saturate(1.3); backdrop-filter: blur(16px) saturate(1.3);
+  box-shadow: 0 8px 30px rgba(0, 0, 0, .35); animation: capIn .3s ease; }
+.caption.plain { white-space: pre-wrap; }
+.caption.user { background: color-mix(in srgb, var(--_accent) 88%, transparent); }
+.caption.out { opacity: 0; translate: 0 6px; transition: opacity .5s ease, translate .5s ease; }
+.caption > :first-child { margin-top: 0; } .caption > :last-child { margin-bottom: 0; }
+.caption p, .caption ul, .caption ol { margin: .35em 0; }
+.caption code { font-family: ui-monospace, Menlo, monospace; font-size: .85em; background: rgba(255,255,255,.14);
+                padding: 1px 5px; border-radius: 4px; }
+.caption pre { background: rgba(255,255,255,.1); padding: 8px 10px; border-radius: 8px; overflow-x: auto; }
+.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;
+  flex-direction: column; align-items: flex-end; gap: 10px; }
+.hand, .end { width: 48px; height: 48px; padding: 0; border-radius: 50%; display: grid; place-items: center;
+  color: #fff; border: 1px solid rgba(255,255,255,.18); 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);
+  transition: background .2s ease, transform .2s ease; }
+.hand:hover, .end:hover { background: rgba(40, 40, 44, .85); transform: translateY(-2px); }
+.hand[aria-expanded="true"] { background: var(--_accent); border-color: var(--_accent); }
+.hand.sent { background: var(--_ok); border-color: var(--_ok); }
+.end:hover { background: var(--_dead); border-color: var(--_dead); }
+.end:disabled { opacity: .5; cursor: progress; }
+.hand:focus-visible, .end:focus-visible { outline: 2px solid #fff; outline-offset: 3px; }
+.hand svg, .end svg { width: 22px; height: 22px; }
+.ask { width: min(420px, calc(100vw - 44px)); padding: 12px; border-radius: 16px; color: #fff;
+  background: rgba(20, 20, 22, .82); -webkit-backdrop-filter: blur(16px); backdrop-filter: blur(16px);
+  box-shadow: 0 8px 30px rgba(0,0,0,.4); animation: capIn .2s ease; }
+.ask[hidden] { display: none; }
+.ask textarea { min-height: 64px; background: rgba(255,255,255,.08); color: #fff;
+  border-color: rgba(255,255,255,.16); font-size: 15px; }
+.ask textarea::placeholder { color: rgba(255,255,255,.5); }
+.ask .ask-row { display: flex; align-items: center; gap: 8px; margin-top: 8px; }
+.ask .ask-hint { font-size: 12px; color: rgba(255,255,255,.6); flex: 1; }
+@media (prefers-reduced-motion: reduce) { .hand, .ask { transition: none; animation: none; } }
+@media (prefers-reduced-motion: reduce) { .caption { animation: none; } .caption.out { transition: none; } }
 @container (max-width: 820px) {
   .body { flex-direction: column; }
   :host([screen]) .screen { order: -1; flex: none; height: 45%; border-left: 0; border-bottom: 1px solid var(--_line); }
@@ -256,7 +338,18 @@ const TEMPLATE = `
   <div class="screen-bar"><span class="live" hidden>에이전트 조작 중</span><span class="url"></span>
     <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>
+  <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="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>
+      <button class="end" part="end" type="button" aria-label="발표 종료" title="발표 종료">
+        <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M18 6 6 18"/><path d="m6 6 12 12"/></svg>
+      </button>
+      <button class="hand" part="hand" type="button" aria-expanded="false" aria-label="손들기: 에이전트에게 질문" title="손들기: 에이전트에게 질문">
+        <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M18 11V6a2 2 0 0 0-2-2a2 2 0 0 0-2 2"/><path d="M14 10V4a2 2 0 0 0-2-2a2 2 0 0 0-2 2v2"/><path d="M10 10.5V6a2 2 0 0 0-2-2a2 2 0 0 0-2 2v8"/><path d="M18 8a2 2 0 1 1 4 0v6a8 8 0 0 1-8 8h-2c-2.8 0-4.5-.86-5.99-2.34l-3.6-3.6a2 2 0 0 1 2.83-2.82L7 15"/></svg>
+      </button>
+    </div></div>
 </aside></div>`;
 
 class AgentBridge extends HTMLElement {
@@ -273,7 +366,10 @@ class AgentBridge extends HTMLElement {
   #md = null;
   #historyKey = null;
   #history = [];
+  #present = { on: false };
   static HISTORY_LIMIT = 500;
+  static CAPTION_MS = 10000; // presentation bubble lifetime
+  static CAPTION_MAX = 3; // bubbles on screen at once (oldest leaves early)
 
   constructor() {
     super();
@@ -285,6 +381,8 @@ class AgentBridge extends HTMLElement {
       buttons: this.#root.querySelectorAll("button[data-action]"),
       live: q(".live"), url: q(".screen-bar .url"), viewport: q(".viewport"), img: q(".viewport img"),
       controlBtn: q(".control-btn"), kbd: q(".kbd"), clearBtn: q(".clear-btn"),
+      body: q(".body"), screen: q(".screen"), captions: q(".captions"),
+      busy: q(".busy"), hand: q(".hand"), end: q(".end"), ask: q(".ask"), askBox: q(".ask textarea"), askHint: q(".ask-hint"),
     };
     this.$.buttons.forEach((b) => b.addEventListener("click", () => this.#submit(b.dataset.action)));
     this.#bindGrip();
@@ -296,6 +394,7 @@ class AgentBridge extends HTMLElement {
     });
     loadMarkdown().then((md) => (this.#md = md));
     this.#bindControl();
+    this.#bindHand();
     this.$.clearBtn.addEventListener("click", () => this.clearHistory());
   }
 
@@ -334,6 +433,19 @@ class AgentBridge extends HTMLElement {
     }
   }
 
+  async stopPresent() {
+    try {
+      const res = await fetch(`${this.server}/present`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ stop: true, from: "viewer" }),
+      });
+      return await res.json();
+    } catch {
+      return { ok: false, error: "server_unreachable" };
+    }
+  }
+
   #emit(type, detail) {
     this.dispatchEvent(new CustomEvent(type, { detail, bubbles: true, composed: true }));
   }
@@ -349,7 +461,15 @@ class AgentBridge extends HTMLElement {
     on("delivered", ({ id }) => { this.#deliver(id); this.#emit("agent-queue", { phase: "delivered", id }); });
     on("unqueued", ({ id }) => { this.#unqueue(id); this.#emit("agent-queue", { phase: "unqueued", id }); });
     on("status", (s) => this.#renderStatus(s));
-    on("message", (m) => { this.#addMessage(m); this.#saveMessage(m); this.#emit("agent-message", m); });
+    on("message", (m) => {
+      this.#addMessage(m);
+      this.#saveMessage(m);
+      // 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);
+    });
+    on("present", (p) => this.#setPresent(p));
     on("tool_start", (t) => {
       this.#tools.set(t.id, t);
       this.#renderActivity();
@@ -366,11 +486,11 @@ class AgentBridge extends HTMLElement {
       this.#setToolState(t.id, t.isError ? "error" : "done");
       this.#emit("agent-tool", { phase: "end", ...t });
     });
-    es.onerror = () => this.#renderStatus(null);
+    es.onerror = () => { this.#renderStatus(null); this.#setPresent({ on: false }); };
   }
 
   #syncScreen() {
-    const want = this.hasAttribute("screen");
+    const want = this.hasAttribute("screen") || this.#present.on;
     if (!want) { this.#screenEs?.close(); this.#screenEs = null; this.#setControl(false); return; }
     if (this.#screenEs) return;
     const es = (this.#screenEs = new EventSource(`${this.server}/screen`));
@@ -384,6 +504,117 @@ class AgentBridge extends HTMLElement {
     es.onerror = () => this.#renderScreenMeta({ connected: false });
   }
 
+  // ---------- presentation mode ----------
+
+  #setPresent(p) {
+    const on = !!p?.on;
+    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.#setControl(false);
+    else { this.$.captions.replaceChildren(); this.#openAsk(false); this.#handUp = false; }
+    this.#syncScreen();
+    // FLIP: grow from (or shrink back to) the side panel
+    const { screen, body } = this.$;
+    const before = screen.getBoundingClientRect();
+    body.classList.toggle("present", on);
+    this.toggleAttribute("presenting", on);
+    const after = screen.getBoundingClientRect();
+    if (matchMedia("(prefers-reduced-motion: reduce)").matches || !before.width || !after.width) return;
+    const t = `translate(${before.left - after.left}px, ${before.top - after.top}px) ` +
+      `scale(${before.width / after.width}, ${before.height / after.height})`;
+    screen.animate([{ transformOrigin: "0 0", transform: t }, { transformOrigin: "0 0", transform: "none" }],
+      { 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.$;
+    hand.addEventListener("click", () => {
+      if (ask.hidden) this.#raiseHand();
+      else this.#lowerHand();
+    });
+    this.$.end.addEventListener("click", async () => {
+      this.$.end.disabled = true;
+      const res = await this.stopPresent();
+      this.$.end.disabled = false;
+      if (!res.ok) { this.#openAsk(true); askHint.textContent = `발표 종료 실패: ${res.error}`; }
+    });
+    ask.addEventListener("submit", async (e) => {
+      e.preventDefault();
+      const text = askBox.value.trim();
+      if (!text) return;
+      askHint.textContent = "보내는 중…";
+      const res = await this.send(text, "message");
+      if (!res.ok) { askHint.textContent = `전송 실패: ${res.error}`; return; }
+      askBox.value = "";
+      this.#handUp = false; // the question itself ends the raised hand
+      this.#openAsk(false);
+      hand.classList.add("sent");
+      setTimeout(() => hand.classList.remove("sent"), 1500);
+    });
+    askBox.addEventListener("keydown", (e) => {
+      if (e.key === "Enter" && !e.shiftKey && !e.isComposing) { e.preventDefault(); ask.requestSubmit(); }
+      if (e.key === "Escape") { e.preventDefault(); this.#lowerHand(); hand.focus(); }
+    });
+  }
+
+  // Raise: open the input and tell the agent to pause. Lower (closed without
+  // asking): tell it to go on. Failures only show a hint; asking still works.
+  #handUp = false;
+  async #raiseHand() {
+    this.#openAsk(true);
+    if (this.#handUp) return;
+    this.#handUp = true;
+    const res = await this.send("사용자가 손을 듦: 질문 입력 중", "hand-raise");
+    if (!res.ok && !this.$.ask.hidden) this.$.askHint.textContent = `손들기 알림 실패: ${res.error}`;
+  }
+  async #lowerHand() {
+    this.#openAsk(false);
+    if (!this.#handUp) return;
+    this.#handUp = false;
+    await this.send("사용자가 질문 없이 손을 내림", "hand-lower");
+  }
+
+  #openAsk(open) {
+    const { hand, ask, askBox, askHint } = this.$;
+    ask.hidden = !open;
+    hand.setAttribute("aria-expanded", String(open));
+    askHint.textContent = "";
+    if (open) askBox.focus();
+  }
+
+  // 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", ms = AgentBridge.CAPTION_MS) {
+    if (!text?.trim()) return;
+    const el = document.createElement("div");
+    el.className = `caption ${kind}`;
+    el.part = "caption";
+    if (kind === "user") { el.textContent = text; el.classList.add("plain"); }
+    else if (this.#md) el.innerHTML = this.#md(text);
+    else { el.textContent = text; el.classList.add("plain"); }
+    const box = this.$.captions;
+    box.append(el);
+    const leave = () => {
+      if (el.classList.contains("out")) return;
+      el.classList.add("out");
+      setTimeout(() => el.remove(), 500);
+    };
+    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;
+  }
+
   // ---------- composer resize grip (top edge) ----------
 
   #bindGrip() {
@@ -456,7 +687,7 @@ class AgentBridge extends HTMLElement {
     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", () => this.#setControl(!this.#controlWs));
+    controlBtn.addEventListener("click", () => { if (!this.#present.on) this.#setControl(!this.#controlWs); });
 
     img.addEventListener("mousedown", (e) => {
       if (!on()) return;
@@ -673,7 +904,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") {
@@ -735,6 +966,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);
   }