agello 0.1.4 → 0.2.0

package/README.md

@@ -67,11 +67,26 @@ 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 |
 
 `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.
+
 ## Embed
 
 ```html

package/bin/agello.ts

@@ -22,6 +22,11 @@ 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} help | --version
 
 start options:
@@ -279,6 +284,40 @@ async function cmdOpen(argv: string[]) {
   console.log(inst.url);
 }
 
+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 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 +334,9 @@ switch (cmd) {
   case "open":
     await cmdOpen(rest);
     break;
+  case "present":
+    await cmdPresent(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.0",
   "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/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,5 @@ export function createScreencast(opts: { browserKey?: string; herdrTab?: () => P
     return browser ? { connected: false, browser: browser.key } : { connected: false, reason };
   }
 
-  return { handle, input, describe };
+  return { handle, input, describe, setClip };
 }

package/src/server.ts

@@ -7,11 +7,15 @@
 // 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")
 
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { runJson } from "./run.ts";
-import { createScreencast } from "./screencast.ts";
+import { createScreencast, type Rect } from "./screencast.ts";
 
 export type ServerOptions = {
   port: number;
@@ -77,6 +81,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 };
+
 type Status =
   | { alive: false; reason: string; pane: string }
   | { alive: true; status: string; pane: string; label?: string; session: string; title?: string };
@@ -291,6 +306,40 @@ 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 };
+  function setPresent(next: Present) {
+    present = next;
+    screen.setClip(next.on ? (next.rect ?? null) : null);
+    broadcast("present", present);
+  }
+
+  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 r = await promptAgent("present-stop", "사용자가 페이지에서 발표를 종료함");
+        notified = r.ok ? "ok" : r.error;
+      }
+      return Response.json({ ok: true, present, 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 });
+  }
+
   // ----- HTTP -----
 
   // Same-origin and localhost pages are allowed by default; add more with
@@ -329,6 +378,7 @@ export async function startServer(opts: ServerOptions) {
           tools: [...pendingTools.keys()],
         });
         if (lastStatus) send(c, "status", lastStatus);
+        send(c, "present", present);
         for (const t of pendingTools.values()) send(c, "tool_start", t);
         ping = setInterval(() => send(c, "ping", {}), 15000);
       },
@@ -342,22 +392,32 @@ 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 });
+    const r = await promptAgent(action, data.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,
+        });
       case "/events":
         return events();
       case "/screen":
@@ -368,6 +428,9 @@ 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(present);
     }
     return new Response(HTML, { headers: { "Content-Type": "text/html; charset=utf-8", "Cache-Control": "no-store" } });
   }

package/web/agent-bridge.js

@@ -23,10 +23,24 @@
 //   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.
 //
 // 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 +67,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 +171,60 @@ 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; } }
+
+/* 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 +327,17 @@ 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="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 +354,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 +369,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"),
+      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 +382,7 @@ class AgentBridge extends HTMLElement {
     });
     loadMarkdown().then((md) => (this.#md = md));
     this.#bindControl();
+    this.#bindHand();
     this.$.clearBtn.addEventListener("click", () => this.clearHistory());
   }
 
@@ -334,6 +421,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 +449,14 @@ 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);
+      if (this.#present.on && m.role === "assistant") this.#caption(m.text);
+      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 +473,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 +491,110 @@ 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);
+    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)" });
+  }
+
+  // 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") {
+    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, AgentBridge.CAPTION_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 +667,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;