agello 0.4.2 → 0.4.4

package/web/agent-bridge.js

@@ -42,7 +42,9 @@
 //   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.
+//   closing it with X (or Esc) before asking sends action=hand-lower so it can go on.
+//   The input stays open while the agent answers, for follow-up questions; X
+//   (or Esc) sends action=hand-done so the agent resumes the presentation.
 //   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
@@ -54,6 +56,8 @@
 //   el.clearHistory()                  clear saved chat for the current pane
 //   el.stopPresent()                   end presentation mode, tell the agent -> Promise<{ok, error?, notified?}>
 
+import { PresentationMedia, DEFAULT_VOICE } from "./presentation-media.js";
+
 const SCRIPT_ORIGIN = new URL(import.meta.url).origin;
 
 let mdPromise;
@@ -79,9 +83,31 @@ const SCREEN_REASONS = {
   tab_unknown: "에이전트의 herdr 탭을 확인할 수 없음",
   no_active_tab: "브라우저에 활성 탭 없음",
 };
+const MEDIA_ERRORS = {
+  tts_key_required: "Typecast API 키를 적용한 뒤 TTS를 켜 주세요.",
+  tts_invalid_key: "Typecast API 키가 올바르지 않아요. 키를 확인한 뒤 다시 재생해 주세요.",
+  tts_local_key_unavailable: "로컬 키를 찾지 못했어요. ../yt-outlier/.env의 TYPECAST_API_KEY를 확인하거나 키를 직접 입력해 주세요.",
+  tts_driver_disconnected: "음성을 재생하던 화면의 연결이 끊겼어요. 이 화면에서 TTS를 켠 뒤 다시 재생해 주세요.",
+  tts_prepare_timeout: "음성 생성 시간이 초과됐어요. 연결을 확인하고 다시 재생해 주세요.",
+  tts_start_timeout: "음성이 시작되지 않았어요. TTS 켜기로 음성 재생을 허용한 뒤 다시 재생해 주세요.",
+  tts_end_timeout: "음성 완료를 확인하지 못했어요. 연결을 확인하고 다시 재생해 주세요.",
+  tts_playback_error: "음성을 재생하지 못했어요. TTS 켜기로 음성 재생을 허용한 뒤 다시 재생해 주세요.",
+  tts_provider_error: "Typecast 요청이 실패했어요. 키·목소리·사용 한도를 확인하고 다시 재생해 주세요.",
+  tts_network_error: "Typecast에 연결하지 못했어요. 인터넷 연결을 확인하고 다시 재생해 주세요.",
+  tts_text_limit: "대본 한 줄이 너무 길어요. 2,000자 이하로 나눠 주세요.",
+  tts_invalid_audio: "올바른 음성을 받지 못했어요. 목소리 설정을 확인하고 다시 재생해 주세요.",
+  tts_audio_not_found: "준비된 음성이 만료됐어요. 대본을 다시 재생해 주세요.",
+  tts_failed: "TTS 처리에 실패했어요. 설정을 확인하고 다시 재생하거나 TTS를 꺼 주세요.",
+  tts_cancelled: "음성 생성이 취소됐어요. 계속하려면 대본을 다시 재생해 주세요.",
+  tts_config_superseded: "TTS 설정이 변경됐어요. 현재 설정을 확인하고 다시 적용해 주세요.",
+  tts_stopped: "음성 재생이 종료됐어요. 계속하려면 TTS를 켠 뒤 대본을 재생해 주세요.",
+  invalid_voice: "목소리 ID가 올바르지 않아요. Typecast 목소리 ID를 확인해 주세요.",
+  invalid_viewer: "발표 화면 연결을 확인하지 못했어요. 페이지를 새로 고친 뒤 다시 시도해 주세요.",
+  invalid_tts_config: "TTS 설정이 올바르지 않아요. 키와 목소리 ID를 확인해 주세요.",
+};
 const ACTIONS = {
   message: "메시지", approve: "승인", reject: "거절",
-  "present-stop": "발표 종료", "hand-raise": "손들기", "hand-lower": "손 내림", annotate: "주석",
+  "present-stop": "발표 종료", "hand-raise": "손들기", "hand-lower": "손 내림", "hand-done": "질문 완료", annotate: "주석",
 };
 
 const CSS = `
@@ -173,6 +199,21 @@ h1 { font-size: 14px; margin: 0; font-weight: 600; }
 .screen-bar { display: flex; align-items: center; gap: 8px; padding: 8px 12px; font-size: 12px; color: var(--_muted);
               border-bottom: 1px solid var(--_line); min-width: 0; }
 .screen-bar .url { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; flex: 1; }
+.screen { position: relative; }
+.media-controls { padding: 7px 12px; border-bottom: 1px solid var(--_line); font-size: 12px; background: var(--_panel); z-index: 6; }
+.media-toolbar { display: flex; align-items: center; gap: 6px; flex-wrap: wrap; }
+.media-toolbar button { padding: 3px 9px; border-radius: 7px; font-size: 12px; }
+.media-record[aria-pressed="true"] { color: #c92a2a; border-color: #c92a2a; }
+.media-download { color: var(--_accent); }
+.media-panel { max-width: 420px; display: grid; gap: 8px; padding: 12px 0 4px; }
+.media-panel[hidden], .media-download[hidden] { display: none; }
+.media-panel label { display: grid; gap: 3px; }
+.media-panel input { min-width: 0; width: 100%; padding: 6px 8px; font: inherit; color: var(--_text); background: var(--_bg); border: 1px solid var(--_line); border-radius: 6px; }
+.media-panel .media-actions { display: flex; gap: 6px; flex-wrap: wrap; }
+.media-status { margin: 4px 0 0; color: var(--_muted); overflow-wrap: anywhere; }
+.media-status.error { color: #c92a2a; }
+.media-note { color: var(--_muted); }
+.body.present .media-controls { position: absolute; top: 12px; right: 12px; left: 12px; width: fit-content; max-width: calc(100% - 24px); border: 1px solid var(--_line); border-radius: 10px; box-shadow: 0 4px 16px rgb(0 0 0 / .2); }
 .live[hidden] { display: none; }
 .live { flex: none; font-size: 11px; padding: 1px 8px; border-radius: 999px; border: 1px solid var(--_line); }
 .live.on { background: var(--_accent); border-color: var(--_accent); color: #fff; }
@@ -237,6 +278,8 @@ h1 { font-size: 14px; margin: 0; font-weight: 600; }
 /* 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; }
+.sound-btn { flex: none; font-size: 12px; padding: 2px 10px; border-radius: 999px; }
+.sound-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; }
@@ -276,6 +319,9 @@ h1 { font-size: 14px; margin: 0; font-weight: 600; }
   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); }
+/* system event (hand raised / lowered / done): small, light, not part of the conversation */
+.caption.event { padding: 6px 14px; border-radius: 999px; font-size: 13px; color: #1d1d1f;
+  background: rgba(255, 255, 255, .9); box-shadow: 0 4px 16px rgba(0,0,0,.25); }
 .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; }
@@ -317,6 +363,13 @@ h1 { font-size: 14px; margin: 0; font-weight: 600; }
 .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; }
+.ask .ask-row .primary { margin-left: 0; }
+.ask .ask-head { display: flex; align-items: center; gap: 8px; margin-bottom: 8px; font-size: 13px; color: rgba(255,255,255,.75); }
+.ask .ask-title { flex: 1; }
+.ask .ask-done { width: 28px; height: 28px; padding: 0; border-radius: 50%; display: grid; place-items: center;
+  background: transparent; color: #fff; border-color: rgba(255,255,255,.22); }
+.ask .ask-done:hover { background: rgba(255,255,255,.14); }
+.ask .ask-done svg { width: 16px; height: 16px; }
 @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) {
@@ -439,15 +492,31 @@ const TEMPLATE = `
 </section>
 <aside class="screen" part="screen">
   <div class="screen-bar"><span class="live" hidden>에이전트 조작 중</span><span class="url"></span>
+    <button class="sound-btn" type="button" aria-pressed="false" title="켜면 브라우저 탭 소리가 이 화면에서만 나와요 (에이전트 쪽 브라우저는 음소거)">소리</button>
     <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="media-controls" aria-label="발표 설정 및 녹화">
+    <div class="media-toolbar"><button type="button" class="media-settings" aria-expanded="false">발표 설정</button>
+      <button type="button" class="media-play">대본 재생</button><button type="button" class="media-record" aria-pressed="false">녹화 시작</button>
+      <span class="media-elapsed"></span><a class="media-download" hidden>영상 저장</a></div>
+    <div class="media-panel" hidden role="group" aria-label="TTS 설정">
+      <label>Typecast API 키<input class="media-key" type="password" autocomplete="off" placeholder="키는 서버 메모리에만 보관해요"></label>
+      <label>목소리 ID<input class="media-voice" type="text" spellcheck="false" value="${DEFAULT_VOICE}"></label>
+      <div class="media-actions"><button type="button" class="media-save">키·목소리 적용</button><button type="button" class="media-local">로컬 키 불러오기</button><button type="button" class="media-clear">키 삭제</button></div>
+      <button type="button" class="media-tts" aria-pressed="false">TTS 켜기</button>
+      <span class="media-note">TTS와 녹화는 각각 선택해요. 발표 화면 이미지와 대본을 녹화하며, TTS 음성은 TTS를 켠 제어 화면의 녹화에만 담겨요. 최대 15분·256MB.</span>
+    </div><p class="media-status" role="status" aria-live="polite"></p>
+  </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>
+      <form class="ask" part="ask" hidden>
+        <div class="ask-head"><span class="ask-title"></span><button type="button" class="ask-done">
+          <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></div>
+        <textarea aria-label="에이전트에게 질문"></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>
@@ -464,6 +533,7 @@ class AgentBridge extends HTMLElement {
   #root = this.attachShadow({ mode: "open" });
   #es = null;
   #screenEs = null;
+  #sound = null; // page audio: { ctx, es, next: Map<stream id, end time> }
   #ws = null; // /input: control input and annotate inspect queries
   #control = false;
   #annot = false;
@@ -489,8 +559,13 @@ class AgentBridge extends HTMLElement {
   #historyKey = null;
   #history = [];
   #present = { on: false };
+  #viewerId = crypto.randomUUID();
+  #media;
+  #mediaBusy = false;
+  #mediaConnection = 0;
   static HISTORY_LIMIT = 500;
   static CAPTION_MS = 10000; // presentation bubble lifetime
+  static EVENT_MS = 5000; // system event bubble lifetime
   static CAPTION_MAX = 3; // bubbles on screen at once (oldest leaves early)
 
   constructor() {
@@ -505,7 +580,8 @@ class AgentBridge extends HTMLElement {
       controlBtn: q(".control-btn"), kbd: q(".kbd"),
       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"),
-      annotBtn: q(".annot-btn"), hlHover: q(".hl.hover"), hlSel: q(".hl.sel"), hlLabel: q(".hl-label"),
+      askTitle: q(".ask-title"), askDone: q(".ask-done"),
+      annotBtn: q(".annot-btn"), soundBtn: q(".sound-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)));
@@ -519,11 +595,13 @@ class AgentBridge extends HTMLElement {
     loadMarkdown().then((md) => (this.#md = md));
     this.#bindControl();
     this.#bindAnnotate();
+    this.$.soundBtn.addEventListener("click", () => this.#setSound(!this.#sound));
     this.#bindHand();
     q(".term-btn").addEventListener("click", () => this.#showTerminal(!this.hasAttribute("terminal-open")));
     q(".terminal-retry").addEventListener("click", () => this.#showTerminal(true));
     this.#bindPanes();
     this.#bindImages();
+    this.#bindMedia();
   }
 
   get server() {
@@ -536,17 +614,21 @@ class AgentBridge extends HTMLElement {
     this.#syncScreen();
   }
   disconnectedCallback() {
+    this.#mediaConnection++;
+    this.#media.reset(this.server, true);
+    this.$.captions.replaceChildren();
     this.#showTerminal(false);
     this.#es?.close();
     this.#es = null;
     this.#screenEs?.close();
     this.#screenEs = null;
+    this.#setSound(false);
     this.#setControl(false);
     this.#setAnnotate(false);
   }
   attributeChangedCallback(name) {
     if (name === "heading") this.$.heading.textContent = this.getAttribute("heading") || "agello";
-    if (name === "server" && this.isConnected) { this.#showTerminal(false); this.#openPanes(false); this.#connect(); this.#screenEs?.close(); this.#screenEs = null; this.#syncScreen(); }
+    if (name === "server" && this.isConnected) { this.#showTerminal(false); this.#openPanes(false); this.#connect(); this.#screenEs?.close(); this.#screenEs = null; this.#setSound(false); this.#syncScreen(); }
     if (name === "screen" && this.isConnected) this.#syncScreen();
   }
 
@@ -858,7 +940,13 @@ class AgentBridge extends HTMLElement {
 
   #connect() {
     this.#es?.close();
-    const es = (this.#es = new EventSource(`${this.server}/events`));
+    this.#media.reset(this.server);
+    this.$.captions.replaceChildren();
+    const version = ++this.#mediaConnection;
+    const es = (this.#es = new EventSource(`${this.server}/events?viewer=${encodeURIComponent(this.#viewerId)}`));
+    this.#media.request("/tts").then((config) => {
+      if (version === this.#mediaConnection) this.#media.setConfig(config);
+    }).catch((error) => { if (version === this.#mediaConnection) this.#media.report(error); });
     const on = (name, fn) => es.addEventListener(name, (e) => fn(JSON.parse(e.data)));
     on("hello", (d) => {
       if (!d.transcript) this.$.hint.textContent = "대화 기록 파일 없음: 메시지 표시 불가";
@@ -868,14 +956,25 @@ class AgentBridge extends HTMLElement {
     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);
+      // Joining during speech replays its caption snapshot, which may already
+      // be in this pane's saved history. Keep the live caption without a duplicate row.
+      const replayedNarration = typeof m.narration === "string" && this.#history.some((saved) => saved.narration === m.narration);
+      if (!replayedNarration) {
+        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 === "assistant") this.#caption(m.text, "agent", m.hold * 1000 || undefined, typeof m.narration === "string" ? m.narration : null);
       if (this.#present.on && m.role === "browser" && m.action === "message") this.#caption(m.text, "user");
+      // a reply to the viewer's question (status polling may miss a short working phase)
+      // (the agent took the question once it is echoed in the transcript; earlier work was the hand-raise turn)
+      if (this.#qa === "asked" && m.role === "browser" && m.action === "message") this.#qaTaken = true;
+      if (this.#qa === "asked" && this.#qaTaken && m.role === "assistant" && !m.script) { this.#qaWorked = true; this.#checkAnswered(); }
       this.#emit("agent-message", m);
     });
     on("present", (p) => this.#setPresent(p));
+    on("tts", (config) => this.#media.setConfig(config));
+    on("speech", (event) => { void this.#media.handleSpeech(event); });
     on("tool_start", (t) => {
       this.#tools.set(t.id, t);
       this.#renderActivity();
@@ -892,12 +991,17 @@ class AgentBridge extends HTMLElement {
       this.#setToolState(t.id, t.isError ? "error" : "done");
       this.#emit("agent-tool", { phase: "end", ...t });
     });
-    es.onerror = () => { this.#renderStatus(null); this.#setPresent({ on: false }); };
+    es.onerror = () => {
+      this.#mediaConnection++;
+      this.#media.reset(this.server);
+      this.#renderStatus(null); this.#setPresent({ on: false });
+      this.#media.report("서버 연결이 끊겨 음성과 녹화를 종료했어요. 다시 연결한 뒤 TTS를 켜 주세요.");
+    };
   }
 
   #syncScreen() {
     const want = this.hasAttribute("screen") || this.#present.on;
-    if (!want) { this.#screenEs?.close(); this.#screenEs = null; this.#setControl(false); this.#setAnnotate(false); return; }
+    if (!want) { this.#screenEs?.close(); this.#screenEs = null; this.#setSound(false); 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)));
@@ -911,17 +1015,154 @@ class AgentBridge extends HTMLElement {
     es.onerror = () => this.#renderScreenMeta({ connected: false });
   }
 
+  // ---------- page audio ----------
+  // On: the relayed tab's audio plays here and is muted in the agent's
+  // browser (while any viewer has it on). The click creates the AudioContext,
+  // which is what the browser's autoplay policy needs.
+  #setSound(on) {
+    if (!on) {
+      if (!this.#sound) return;
+      this.#sound.es.close();
+      this.#sound.ctx.close().catch(() => {});
+      this.#sound = null;
+    } else {
+      if (this.#sound) return;
+      const ctx = new AudioContext();
+      ctx.resume().catch(() => {});
+      const es = new EventSource(`${this.server}/screen/audio`);
+      const s = (this.#sound = { ctx, es, next: new Map() });
+      es.addEventListener("pcm", (e) => this.#playPcm(s, JSON.parse(e.data)));
+    }
+    this.$.soundBtn.setAttribute("aria-pressed", String(!!this.#sound));
+  }
+
+  // One chunk: 16-bit little-endian stereo. Chunks of a stream are queued
+  // back to back; a gap or a backlog over 1s restarts with a 150ms buffer.
+  #playPcm(s, { c, r, d }) {
+    if (this.#sound !== s) return;
+    const bin = atob(d);
+    const pcm = new Int16Array(bin.length >> 1);
+    for (let i = 0; i < pcm.length; i++) pcm[i] = (bin.charCodeAt(2 * i) | (bin.charCodeAt(2 * i + 1) << 8)) << 16 >> 16;
+    const n = pcm.length >> 1;
+    if (!n) return;
+    const buf = s.ctx.createBuffer(2, n, r);
+    const L = buf.getChannelData(0), R = buf.getChannelData(1);
+    for (let i = 0; i < n; i++) { L[i] = pcm[2 * i] / 32768; R[i] = pcm[2 * i + 1] / 32768; }
+    const src = s.ctx.createBufferSource();
+    src.buffer = buf;
+    src.connect(s.ctx.destination);
+    const now = s.ctx.currentTime;
+    let at = s.next.get(c) ?? 0;
+    if (at < now + 0.02 || at > now + 1) at = now + 0.15;
+    src.start(at);
+    s.next.set(c, at + buf.duration);
+  }
+
   // ---------- presentation mode ----------
 
+  #bindMedia() {
+    const q = (selector) => this.#root.querySelector(selector);
+    this.#media = new PresentationMedia({
+      viewerId: this.#viewerId, image: this.$.img,
+      captions: () => [...this.$.captions.children].filter((el) => !el.classList.contains("out")).map((el) => ({ text: el.textContent, kind: el.__captionKind || "agent" })),
+      onChange: () => this.#renderMedia(),
+      onSpeech: ({ id, phase }) => {
+        if (["ended", "cancel", "error"].includes(phase)) {
+          for (const el of this.$.captions.children) if (el.dataset.narration === id) el.__leave?.();
+        }
+      },
+    });
+    this.$.img.addEventListener("load", () => this.#media.flushRecordingFrame());
+    q(".media-settings").addEventListener("click", () => {
+      const panel = q(".media-panel");
+      panel.hidden = !panel.hidden;
+      q(".media-settings").setAttribute("aria-expanded", String(!panel.hidden));
+      if (!panel.hidden) q(".media-key").focus();
+    });
+    const run = async (fn) => {
+      if (this.#mediaBusy) return;
+      this.#mediaBusy = true;
+      this.#renderMedia();
+      try { await fn(); } catch (error) { this.#media.report(error); }
+      finally { this.#mediaBusy = false; this.#renderMedia(); }
+    };
+    q(".media-save").addEventListener("click", () => {
+      const input = q(".media-key");
+      const apiKey = input.value.trim();
+      input.value = "";
+      void run(() => this.#media.configure({ ...(apiKey ? { apiKey } : {}), voiceId: q(".media-voice").value.trim() }));
+    });
+    q(".media-local").addEventListener("click", () => { q(".media-key").value = ""; void run(() => this.#media.configure({ useLocalKey: true, voiceId: q(".media-voice").value.trim() })); });
+    q(".media-clear").addEventListener("click", () => { q(".media-key").value = ""; void run(() => this.#media.configure({ clearKey: true })); });
+    q(".media-tts").addEventListener("click", () => {
+      const enabled = !(this.#media.config.enabled && this.#media.config.driverId === this.#viewerId);
+      // Invoke resume while this click still holds browser user activation.
+      void run(async () => {
+        if (enabled) await this.#media.unlock();
+        await this.#media.configure({ enabled, voiceId: q(".media-voice").value.trim() });
+      });
+    });
+    q(".media-play").addEventListener("click", () => {
+      const cmd = this.#present.player?.state === "playing" ? "pause" : "resume";
+      if (cmd === "pause") this.#media.pauseSpeech();
+      else this.#media.resumeSpeech();
+      void run(async () => {
+        if (cmd === "resume" && this.#present.player?.state === "done") await this.#media.request("/player", { cmd: "goto", at: "1" });
+        const data = await this.#media.request("/player", { cmd });
+        this.#present.player = data.player;
+      });
+    });
+    q(".media-record").addEventListener("click", () => {
+      try {
+        if (this.#media.recording) this.#media.stopRecording();
+        else this.#media.startRecording();
+      } catch (error) { this.#media.report(error); }
+    });
+    this.#renderMedia();
+  }
+
+  #renderMedia() {
+    if (!this.#media) return;
+    const q = (selector) => this.#root.querySelector(selector);
+    const media = this.#media, config = media.config;
+    const recording = media.recording;
+    const own = config.enabled && config.driverId === this.#viewerId;
+    const tts = q(".media-tts");
+    tts.textContent = own ? "TTS 끄기" : config.enabled ? "이 화면에서 TTS 켜기" : "TTS 켜기";
+    tts.setAttribute("aria-pressed", String(own));
+    for (const selector of [".media-tts", ".media-save", ".media-local", ".media-clear", ".media-voice"]) q(selector).disabled = this.#mediaBusy || !!recording;
+    const play = q(".media-play");
+    play.textContent = this.#present.player?.state === "playing" ? "일시정지" : this.#present.player?.state === "done" ? "다시 재생" : "대본 재생";
+    play.disabled = this.#mediaBusy || !this.#present.player?.steps;
+    const record = q(".media-record");
+    record.textContent = recording?.stopping ? "영상 저장 중…" : recording ? "녹화 종료" : "녹화 시작";
+    record.setAttribute("aria-pressed", String(!!recording));
+    record.disabled = !!recording?.stopping;
+    const seconds = recording ? Math.floor((performance.now() - recording.started) / 1000) : 0;
+    q(".media-elapsed").textContent = recording ? `${String(Math.floor(seconds / 60)).padStart(2, "0")}:${String(seconds % 60).padStart(2, "0")}` : "";
+    const link = q(".media-download");
+    link.hidden = !media.download;
+    if (media.download) { link.href = media.download.url; link.download = media.download.name; }
+    else { link.removeAttribute("href"); link.removeAttribute("download"); }
+    const status = q(".media-status");
+    status.classList.toggle("error", !!media.error);
+    const errorText = Object.hasOwn(MEDIA_ERRORS, media.error) ? MEDIA_ERRORS[media.error] : media.error;
+    status.textContent = errorText || (own ? "TTS ON · 이 화면에서 음성 재생" : config.enabled ? "TTS ON · 다른 화면에서 음성 재생" : config.configured ? "TTS OFF · API 키 준비됨" : "TTS OFF · API 키 미설정");
+  }
+
   #setPresent(p) {
     const on = !!p?.on;
     const was = this.#present.on;
     this.#present = p ?? { on: false };
+    this.#media.observePlayer(p?.player?.state);
+    if (!on) this.#media.cancelSpeech();
+    if (!on) this.#media.stopRecording();
+    this.#renderMedia();
     this.#emit("agent-present", this.#present);
     this.#renderBusy();
     if (on === was) return;
     if (on) { this.#showTerminal(false); this.#setControl(false); this.#setAnnotate(false); }
-    else { this.$.captions.replaceChildren(); this.#openAsk(false); this.#handUp = false; }
+    else { this.$.captions.replaceChildren(); this.#openAsk(false); this.#qa = null; }
     this.#syncScreen();
     // FLIP: grow from (or shrink back to) the side panel
     const { screen, body } = this.$;
@@ -940,20 +1181,31 @@ class AgentBridge extends HTMLElement {
     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);
+    this.#checkAnswered();
   }
 
-  // Raise hand: open a small input over the presentation and send it as a message.
+  // Raise hand: a question session over the presentation.
+  // The input stays open for the whole session; X / Esc / the hand button close it.
+  //   raised: nothing asked yet. close -> hand-lower (agent resumes)
+  //   asked:  question sent, agent answering (follow-ups can be typed already)
+  //   follow: answered, waiting for a follow-up. close -> hand-done (agent resumes)
+  // The session ends when the script plays again or the presentation stops.
+  #qa = null; // null | "raised" | "asked" | "follow"
+  #qaTaken = false; // the last question reached the agent (echoed in the transcript)
+  #qaWorked = false; // agent seen working on it
+
   #bindHand() {
     const { hand, ask, askBox, askHint } = this.$;
     hand.addEventListener("click", () => {
-      if (ask.hidden) this.#raiseHand();
-      else this.#lowerHand();
+      if (!this.#qa) this.#raiseHand();
+      else this.#closeHand();
     });
+    this.$.askDone.addEventListener("click", () => { this.#closeHand(); hand.focus(); });
     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}`; }
+      if (!res.ok) { this.#openAsk(this.#qa ?? "raised"); askHint.textContent = `발표 종료 실패: ${res.error}`; }
     });
     ask.addEventListener("submit", async (e) => {
       e.preventDefault();
@@ -963,60 +1215,110 @@ class AgentBridge extends HTMLElement {
       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);
+      this.#qa = "asked";
+      this.#qaTaken = this.#qaWorked = false;
+      this.#openAsk("asked");
       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(); }
+      if (e.key === "Escape") { e.preventDefault(); this.#closeHand(); 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;
+  // Raise: open the input and tell the agent to pause. Failures only show a hint; asking still works.
   async #raiseHand() {
-    this.#openAsk(true);
-    if (this.#handUp) return;
-    this.#handUp = true;
+    this.#media.pauseSpeech();
+    this.#event("손들기 확인 · 발표 일시정지");
+    this.#qa = "raised";
+    this.#openAsk("raised");
     const res = await this.send("사용자가 손을 듦: 질문 입력 중", "hand-raise");
     if (!res.ok && !this.$.ask.hidden) this.$.askHint.textContent = `손들기 알림 실패: ${res.error}`;
   }
+  // X / Esc / hand button: before asking = cancel (hand-lower), after = resolved (hand-done).
+  #closeHand() {
+    if (this.#qa === "raised") this.#lowerHand(); else this.#doneHand();
+  }
+  // Cancel before asking: tell the agent to go on.
   async #lowerHand() {
     this.#openAsk(false);
-    if (!this.#handUp) return;
-    this.#handUp = false;
-    await this.send("사용자가 질문 없이 손을 내림", "hand-lower");
+    if (this.#qa !== "raised") return;
+    this.#qa = null;
+    this.#event("손들기 취소 · 곧 발표 재개");
+    await this.send("사용자가 질문 없이 손을 내림: 발표 계속", "hand-lower");
+  }
+  // X after an answer: the question is resolved, tell the agent to go on.
+  async #doneHand() {
+    this.#openAsk(false);
+    if (!this.#qa || this.#qa === "raised") return;
+    this.#qa = null;
+    this.#event("질문 완료 · 곧 발표 재개");
+    await this.send("사용자가 질문 완료 (추가 질문 없음): 발표 계속", "hand-done");
   }
 
-  #openAsk(open) {
-    const { hand, ask, askBox, askHint } = this.$;
-    ask.hidden = !open;
-    hand.setAttribute("aria-expanded", String(open));
+  // Answer finished (agent was working, now is not): reopen the input for a follow-up.
+  // If the script plays again (agent resumed on its own), the session is over.
+  #checkAnswered() {
+    if (!this.#qa) return;
+    if (this.#present.player?.state === "playing") {
+      if (this.#qa !== "raised") { this.#qa = null; this.#openAsk(false); }
+      return;
+    }
+    if (this.#qa !== "asked") return;
+    const s = this.#status;
+    if (s?.alive && s.status === "working") { if (this.#qaTaken) this.#qaWorked = true; return; }
+    if (this.#qaWorked && s?.alive) { this.#qa = "follow"; this.#openAsk("follow"); }
+  }
+
+  // The input stays open for the whole session. mode: false (close) | "raised" | "asked" | "follow"
+  static ASK_TEXT = {
+    raised: ["질문 입력", "에이전트에게 질문 (Enter 전송, Esc·X 취소)", "손들기 취소: 발표 계속"],
+    asked: ["답변 준비 중…", "추가 질문 (Enter 전송, Esc·X 질문 완료)", "질문 완료: 발표 계속"],
+    follow: ["추가 질문이 있으면 입력", "추가 질문 (Enter 전송, Esc·X 질문 완료)", "질문 완료: 발표 계속"],
+  };
+  #openAsk(mode) {
+    const { hand, ask, askBox, askHint, askTitle, askDone } = this.$;
+    const wasOpen = !ask.hidden;
+    ask.hidden = !mode;
+    hand.setAttribute("aria-expanded", String(!!mode));
     askHint.textContent = "";
-    if (open) askBox.focus();
+    if (!mode) return;
+    const [title, placeholder, done] = AgentBridge.ASK_TEXT[mode];
+    askTitle.textContent = title;
+    askBox.placeholder = placeholder;
+    askDone.setAttribute("aria-label", done);
+    askDone.title = done;
+    if (!wasOpen || mode !== "asked") askBox.focus();
+  }
+
+  // Instant local feedback for a hand interaction (no agent round trip).
+  #event(text) {
+    this.#caption(text, "event", AgentBridge.EVENT_MS);
   }
 
   // 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) {
+  #caption(text, kind = "agent", ms = AgentBridge.CAPTION_MS, narration = null) {
     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"); }
+    if (narration) el.dataset.narration = narration;
+    el.__captionKind = kind;
+    if (kind === "user" || kind === "event") { 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);
+    this.#media.flushRecordingFrame();
     const leave = () => {
       if (el.classList.contains("out")) return;
       el.classList.add("out");
+      this.#media.flushRecordingFrame();
       setTimeout(() => el.remove(), 500);
     };
-    setTimeout(leave, ms);
+    if (!narration) 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;