@cef-ai/widget-runtime 0.2.0

package/dist/kinds/conversation.js

@@ -0,0 +1,667 @@
+import { esc } from '../render-helpers.js';
+import { requestMicStream } from '../audio/mic.js';
+// ── main renderer ─────────────────────────────────────────────────────────────
+export function renderConversation(root, config, runtime, deps) {
+    // Stable session id — minted once per mount, never re-minted.
+    const sessionId = crypto.randomUUID();
+    // Runtime state
+    let state = { phase: 'starting' };
+    let pollTimer = null;
+    let pollStarted = 0;
+    let statusPollTimer = null;
+    let mediaRecorder = null;
+    let recordChunks = [];
+    let recordTimerId = null;
+    let recordStartedAt = 0;
+    let recordButtonLocked = false; // double-start guard
+    let startEventPublished = false; // ensure startEvent fires at most once per mount
+    let doneNotified = false; // fire deps.onDone at most once per mount
+    let pendingUserTurnIdx = null; // a submitted answer not yet seen in the DB
+    // ── safe scroll helper ────────────────────────────────────────────────────────
+    // jsdom does not implement scrollIntoView; guard to avoid TypeError in tests.
+    function scrollToBottom() {
+        const anchor = root.querySelector('#scroll_anchor');
+        if (anchor && typeof anchor.scrollIntoView === 'function') {
+            anchor.scrollIntoView({ behavior: 'smooth', block: 'end' });
+        }
+    }
+    // ── teardown ──────────────────────────────────────────────────────────────────
+    function stopPolling() {
+        if (pollTimer) {
+            clearTimeout(pollTimer);
+            pollTimer = null;
+        }
+    }
+    function stopStatusPolling() {
+        if (statusPollTimer) {
+            clearTimeout(statusPollTimer);
+            statusPollTimer = null;
+        }
+    }
+    function stopRecordTimer() {
+        if (recordTimerId) {
+            clearInterval(recordTimerId);
+            recordTimerId = null;
+        }
+    }
+    function teardown() {
+        stopPolling();
+        stopStatusPolling();
+        stopRecordTimer();
+        if (mediaRecorder && mediaRecorder.state !== 'inactive') {
+            try {
+                mediaRecorder.stop();
+            }
+            catch { /* ignore */ }
+        }
+        mediaRecorder = null;
+        recordChunks = [];
+        recordButtonLocked = false;
+    }
+    if (deps?.signal) {
+        if (deps.signal.aborted) {
+            teardown();
+            return;
+        }
+        deps.signal.addEventListener('abort', () => teardown(), { once: true });
+    }
+    // ── turn helpers ──────────────────────────────────────────────────────────────
+    function parseTurns(result) {
+        const roleIdx = result.columns.findIndex((c) => c.toLowerCase() === config.roleColumn.toLowerCase());
+        const textIdx = result.columns.findIndex((c) => c.toLowerCase() === config.textColumn.toLowerCase());
+        const idxIdx = result.columns.findIndex((c) => c.toLowerCase() === config.turnIdxColumn.toLowerCase());
+        const raw = result.rows.map((row) => ({
+            role: String(row[roleIdx] ?? ''),
+            text: String(row[textIdx] ?? ''),
+            turnIdx: Number(row[idxIdx] ?? 0),
+        }));
+        // Collapse duplicate rows for the same (role, turnIdx) — a duplicated insert
+        // or a poll race must never render the same question twice. Map.set keeps the
+        // first insertion position (rows arrive ORDER BY turn_idx) while taking the
+        // latest text for that turn.
+        const byKey = new Map();
+        for (const t of raw)
+            byKey.set(`${t.role}#${t.turnIdx}`, t);
+        return [...byKey.values()];
+    }
+    // Two turn lists render identically? Used to skip no-op poll re-renders that
+    // would otherwise rebuild the transcript (and jump the scroll) every tick.
+    function sameTurns(a, b) {
+        if (a.length !== b.length)
+            return false;
+        for (let i = 0; i < a.length; i++) {
+            if (a[i].role !== b[i].role || a[i].text !== b[i].text || a[i].turnIdx !== b[i].turnIdx)
+                return false;
+        }
+        return true;
+    }
+    // Resolve what to display + whether we're waiting on the coach, accounting for
+    // an answer the user just submitted that may not be persisted yet. Without
+    // this, a poll that runs before the user-turn write lands sees the agent's
+    // question as the last turn → flips back to the record control (the "asked
+    // again" loop) and the user's answer bubble disappears. While the submitted
+    // turn is pending we keep it visible as "(processing…)" and stay waiting.
+    function resolveWaiting(turns) {
+        const userIdxs = turns.filter((t) => t.role === 'user').map((t) => t.turnIdx);
+        const maxUserIdx = userIdxs.length ? Math.max(...userIdxs) : -1;
+        if (pendingUserTurnIdx !== null && maxUserIdx >= pendingUserTurnIdx) {
+            pendingUserTurnIdx = null; // our submitted answer is now in the transcript
+        }
+        if (pendingUserTurnIdx !== null) {
+            return {
+                turns: [...turns, { role: 'user', text: '(processing…)', turnIdx: pendingUserTurnIdx }],
+                waitingForAgent: true,
+            };
+        }
+        const last = lastTurn(turns);
+        return { turns, waitingForAgent: last ? last.role === 'user' : true };
+    }
+    function nextUserTurnIdx(turns) {
+        const userTurns = turns.filter((t) => t.role === 'user');
+        if (!userTurns.length)
+            return 0;
+        return Math.max(...userTurns.map((t) => t.turnIdx)) + 1;
+    }
+    function lastTurn(turns) {
+        return turns.length ? turns[turns.length - 1] : undefined;
+    }
+    // ── transition + render ───────────────────────────────────────────────────────
+    function transition(next) {
+        if (next.phase !== 'conversing' && next.phase !== 'uploading') {
+            stopPolling();
+        }
+        if (next.phase !== 'awaiting-confirm' && next.phase !== 'done') {
+            stopStatusPolling();
+        }
+        // Stop the record elapsed timer whenever we leave the conversing phase.
+        // Recording only happens within 'conversing'; any other phase (uploading,
+        // awaiting-confirm, done, error, not-connected) must not keep ticking it.
+        if (next.phase !== 'conversing') {
+            stopRecordTimer();
+        }
+        state = next;
+        render();
+        // Terminal: tell the host shell so it can re-check the gate and unlock
+        // panels without a page reload. Once per mount.
+        if (next.phase === 'done' && !doneNotified) {
+            doneNotified = true;
+            deps?.onDone?.();
+        }
+    }
+    function render() {
+        switch (state.phase) {
+            case 'starting': return renderStarting();
+            case 'conversing': return renderConversing(state);
+            case 'uploading': return renderUploading(state);
+            case 'awaiting-confirm': return renderAwaitingConfirm(state);
+            case 'done': return renderDone();
+            case 'error': return renderError(state);
+            case 'not-connected': return renderNotConnected();
+        }
+    }
+    // ── error handler ─────────────────────────────────────────────────────────────
+    function handleError(err) {
+        teardown();
+        if (err && err.name === 'AgentNotConnectedError') {
+            transition({ phase: 'not-connected' });
+        }
+        else {
+            transition({ phase: 'error', message: err?.message ?? String(err) });
+        }
+    }
+    // ── polling: turns (no-status path) ──────────────────────────────────────────
+    //
+    // Only poll while waitingForAgent (i.e. the last seen turn is from the user and
+    // we are waiting for the coach to reply). Once the agent has replied and the
+    // Record button is visible we STOP polling; runUpload() re-arms polling after
+    // the user submits their answer. This prevents an infinite timer loop.
+    function schedulePoll(knownTurns) {
+        // Cancel any in-flight turns poll before scheduling a new one, so a tick
+        // and a user action can never spawn concurrent/duplicate timer chains.
+        stopPolling();
+        if (Date.now() - pollStarted > config.poll.timeoutMs) {
+            transition({ phase: 'error', message: 'Session timed out. Please try again.' });
+            return;
+        }
+        pollTimer = setTimeout(async () => {
+            try {
+                if (state.phase !== 'conversing')
+                    return; // state changed under us — bail
+                const result = await runtime.query(config.turnsQuery, [sessionId]);
+                const parsed = parseTurns(result);
+                const { turns, waitingForAgent } = resolveWaiting(parsed);
+                // Skip the re-render (and scroll jump) when nothing visible changed.
+                const changed = !(sameTurns(state.turns, turns) && state.waitingForAgent === waitingForAgent);
+                if (changed)
+                    transition({ phase: 'conversing', turns, waitingForAgent });
+                // Only keep polling while still waiting for the agent to reply.
+                // When the agent has replied (waitingForAgent=false) we stop and
+                // wait for the user to click Record — runUpload re-arms the poll.
+                if (state.phase === 'conversing' && waitingForAgent) {
+                    schedulePoll(parsed);
+                }
+            }
+            catch (err) {
+                handleError(err);
+            }
+        }, config.poll.intervalMs);
+    }
+    // ── polling: session status (with-status path) ────────────────────────────────
+    //
+    // Used when config.statusQuery + confirmWhen are set.  Polls both tables in
+    // parallel.  Stops when it reaches awaiting-confirm or done.  Skips scheduling
+    // while the user is actively recording their answer (mid-recording in the
+    // conversing phase) — runUpload re-arms it once the turn is submitted and we
+    // are waiting for the agent again.  The backend can still drive the status to
+    // confirm/done after an agent reply, so we keep polling whenever the user is
+    // *not* recording.
+    function isRecording() {
+        return mediaRecorder !== null && mediaRecorder.state !== 'inactive';
+    }
+    function scheduleStatusPoll(currentTurns) {
+        // Cancel any in-flight status poll before scheduling a new one, so a tick
+        // and a user action can never spawn concurrent/duplicate timer chains.
+        stopStatusPolling();
+        if (!config.statusQuery)
+            return;
+        if (Date.now() - pollStarted > config.poll.timeoutMs) {
+            transition({ phase: 'error', message: 'Session timed out. Please try again.' });
+            return;
+        }
+        // Honour the comment: don't poll while the user is in their answer window
+        // (actively recording within the conversing phase). Re-armed by runUpload.
+        if (state.phase === 'conversing' && !state.waitingForAgent && isRecording()) {
+            return;
+        }
+        statusPollTimer = setTimeout(async () => {
+            try {
+                const currentPhase = state.phase;
+                if (currentPhase !== 'conversing' && currentPhase !== 'awaiting-confirm')
+                    return;
+                const [turnsResult, statusRes] = await Promise.all([
+                    runtime.query(config.turnsQuery, [sessionId]),
+                    runtime.query(config.statusQuery, [sessionId]),
+                ]);
+                const parsed = parseTurns(turnsResult);
+                const { turns, waitingForAgent } = resolveWaiting(parsed);
+                // Terminal: doneWhen
+                if (config.doneWhen && matchesCondition(statusRes, config.doneWhen)) {
+                    teardown();
+                    transition({ phase: 'done' });
+                    return;
+                }
+                // Transition: confirmWhen
+                if (config.confirmWhen && matchesCondition(statusRes, config.confirmWhen)) {
+                    stopPolling();
+                    if (state.phase !== 'awaiting-confirm') {
+                        transition({ phase: 'awaiting-confirm', turns });
+                    }
+                    // Keep polling so we catch doneWhen after the user confirms
+                    scheduleStatusPoll(parsed);
+                    return;
+                }
+                // Still conversing — update transcript only when something changed
+                // (avoids the every-tick re-render/scroll jump) and keep polling.
+                if (state.phase === 'conversing') {
+                    const changed = !(sameTurns(state.turns, turns) && state.waitingForAgent === waitingForAgent);
+                    if (changed)
+                        transition({ phase: 'conversing', turns, waitingForAgent });
+                    scheduleStatusPoll(parsed);
+                }
+                else if (state.phase === 'awaiting-confirm') {
+                    // awaiting-confirm: keep polling until doneWhen
+                    scheduleStatusPoll(turns);
+                }
+            }
+            catch (err) {
+                handleError(err);
+            }
+        }, config.poll.intervalMs);
+    }
+    function matchesCondition(result, cond) {
+        const colIdx = result.columns.findIndex((c) => c.toLowerCase() === cond.column.toLowerCase());
+        if (colIdx === -1 || !result.rows.length)
+            return false;
+        return String(result.rows[0][colIdx] ?? '') === cond.equals;
+    }
+    // ── boot sequence ─────────────────────────────────────────────────────────────
+    async function boot() {
+        try {
+            // Fire startEvent at most once per mount (if configured). Re-running boot()
+            // from the Try-again / Connect buttons must NOT re-fire intake.start once
+            // it has been published successfully. The flag is set only after a
+            // successful publish, so a failed first attempt can still be retried.
+            if (config.startEvent && !startEventPublished) {
+                await runtime.publish(config.startEvent.type, { schema_version: 1, session_id: sessionId }, sessionId);
+                startEventPublished = true;
+            }
+            // Start polling
+            pollStarted = Date.now();
+            const initialResult = await runtime.query(config.turnsQuery, [sessionId]);
+            const initialTurns = parseTurns(initialResult);
+            const isWaitingForAgent = lastTurn(initialTurns)?.role === 'user' || initialTurns.length === 0;
+            transition({ phase: 'conversing', turns: initialTurns, waitingForAgent: isWaitingForAgent });
+            if (config.statusQuery && config.confirmWhen) {
+                // Always poll when status-aware — we need to detect confirm/done transitions
+                scheduleStatusPoll(initialTurns);
+            }
+            else if (isWaitingForAgent) {
+                // Only poll while waiting for the agent's first reply
+                schedulePoll(initialTurns);
+            }
+            // If agent already replied (isWaitingForAgent=false), stop: wait for user to record
+        }
+        catch (err) {
+            handleError(err);
+        }
+    }
+    // ── audio recording ───────────────────────────────────────────────────────────
+    async function startRecording(turns) {
+        if (recordButtonLocked)
+            return;
+        recordButtonLocked = true;
+        recordChunks = [];
+        let stream;
+        try {
+            stream = await requestMicStream();
+        }
+        catch (err) {
+            recordButtonLocked = false;
+            transition({ phase: 'error', message: `Microphone access denied: ${err.message}` });
+            return;
+        }
+        mediaRecorder = new MediaRecorder(stream);
+        mediaRecorder.ondataavailable = (e) => { if (e.data.size > 0)
+            recordChunks.push(e.data); };
+        mediaRecorder.onstop = () => {
+            stream.getTracks().forEach((t) => t.stop());
+            stopRecordTimer();
+            const blob = new Blob(recordChunks, { type: 'audio/webm' });
+            recordChunks = [];
+            recordButtonLocked = false;
+            void runUpload(blob, turns);
+        };
+        mediaRecorder.start(500);
+        recordStartedAt = Date.now();
+        recordTimerId = setInterval(() => {
+            const elapsed = Math.floor((Date.now() - recordStartedAt) / 1000);
+            const elEl = root.querySelector('#rec_elapsed');
+            if (elEl)
+                elEl.textContent = formatElapsed(elapsed);
+        }, 1000);
+        // Re-render to show recording controls (turns stay visible)
+        renderConversing({ phase: 'conversing', turns, waitingForAgent: false }, true);
+    }
+    function stopRecording() {
+        mediaRecorder?.stop();
+        // onstop → runs runUpload
+    }
+    function formatElapsed(secs) {
+        const m = Math.floor(secs / 60);
+        const s = secs % 60;
+        return `${m}:${s.toString().padStart(2, '0')}`;
+    }
+    // ── upload + publish turn ─────────────────────────────────────────────────────
+    async function runUpload(blob, turns) {
+        const uploadFn = deps?.uploadAudio;
+        if (!uploadFn) {
+            transition({ phase: 'error', message: 'Audio upload not configured.' });
+            return;
+        }
+        const turnIdx = nextUserTurnIdx(turns);
+        transition({ phase: 'uploading', turns, progress: 'Uploading…' });
+        let urls;
+        try {
+            urls = await uploadFn(blob, {
+                segmentSeconds: config.audio.segmentSeconds,
+                onProgress: (done, total) => {
+                    if (state.phase === 'uploading') {
+                        transition({ phase: 'uploading', turns: state.turns, progress: `Uploading ${done}/${total}…` });
+                    }
+                },
+            });
+        }
+        catch (err) {
+            handleError(err);
+            return;
+        }
+        try {
+            await runtime.publish(config.turnEvent.type, {
+                schema_version: 1,
+                session_id: sessionId,
+                [config.turnEvent.turnIdxField ?? 'turn_idx']: turnIdx,
+                [config.turnEvent.audioField]: urls,
+            }, sessionId);
+        }
+        catch (err) {
+            handleError(err);
+            return;
+        }
+        // Resume polling — waiting for agent's next turn. Mark this answer pending
+        // so a poll that runs before the user-turn write lands keeps showing it as
+        // processing (and stays in the waiting state) instead of re-prompting.
+        pendingUserTurnIdx = turnIdx;
+        pollStarted = Date.now();
+        const { turns: updatedTurns, waitingForAgent } = resolveWaiting(turns);
+        transition({ phase: 'conversing', turns: updatedTurns, waitingForAgent });
+        if (config.statusQuery && config.confirmWhen) {
+            scheduleStatusPoll(turns);
+        }
+        else {
+            schedulePoll(turns);
+        }
+    }
+    // ── render: starting ──────────────────────────────────────────────────────────
+    function renderStarting() {
+        root.innerHTML = `
+      <div class="card" style="display:flex;flex-direction:column;gap:.75rem">
+        <div style="display:flex;align-items:center;gap:.5rem;color:#6366f1">
+          <span class="spin" aria-hidden="true" style="display:inline-block;font-size:1.1rem">◌</span>
+          <span>Starting session…</span>
+        </div>
+      </div>`;
+    }
+    // ── render: conversing ────────────────────────────────────────────────────────
+    function renderConversing(s, isRecording = false) {
+        const isRecordingNow = isRecording || (mediaRecorder !== null && mediaRecorder.state !== 'inactive');
+        const elapsed = isRecordingNow ? Math.floor((Date.now() - recordStartedAt) / 1000) : 0;
+        const turnsHtml = s.turns.map((t) => {
+            const isAgent = t.role === 'agent' || t.role === 'coach' || t.role === 'assistant';
+            const bubbleStyle = isAgent
+                ? 'background:#f0f0fe;border-radius:1rem 1rem 1rem .25rem;padding:.6rem .85rem;max-width:85%;align-self:flex-start;'
+                : 'background:#6366f1;color:#fff;border-radius:1rem 1rem .25rem 1rem;padding:.6rem .85rem;max-width:85%;align-self:flex-end;';
+            const roleLabel = isAgent ? 'Coach' : 'You';
+            const isPending = t.text === '(processing…)';
+            const textHtml = isPending
+                ? `<em style="opacity:.7">sending…</em>`
+                : esc(t.text);
+            return `<div style="${bubbleStyle}" role="listitem">
+        <span class="sr-only">${esc(roleLabel)}: </span>${textHtml}
+      </div>`;
+        }).join('');
+        const thinkingHtml = s.waitingForAgent && !isRecordingNow
+            ? `<div style="align-self:flex-start;display:flex;align-items:center;gap:.4rem;color:#9ca3af;font-size:.88rem;padding:.2rem .4rem">
+          <span aria-hidden="true" style="animation:pulse 1.4s ease-in-out infinite">●</span>
+          <span aria-live="polite">Coach is thinking…</span>
+        </div>`
+            : '';
+        let controlHtml = '';
+        if (isRecordingNow) {
+            controlHtml = `
+        <div style="display:flex;flex-direction:column;gap:.5rem;padding:.75rem;background:#fff7ed;border:1px solid #fed7aa;border-radius:.75rem">
+          <div style="display:flex;align-items:center;gap:.6rem">
+            <span style="color:red;font-size:1rem;animation:pulse 1s ease-in-out infinite" aria-hidden="true">●</span>
+            <span id="rec_elapsed" style="font-size:1.1rem;font-weight:600;font-variant-numeric:tabular-nums">${formatElapsed(elapsed)}</span>
+            <span style="color:#b45309;font-size:.85rem">Recording…</span>
+          </div>
+          <button id="stop_btn" type="button" class="button"
+            style="width:100%;padding:.5rem;background:#dc2626;border:none;color:#fff;border-radius:.5rem;cursor:pointer;font-size:.95rem">
+            ■ Stop &amp; Send
+          </button>
+        </div>`;
+        }
+        else if (!s.waitingForAgent) {
+            // Last turn is from agent — show the answer control(s). Depending on
+            // config.audio.mode this is a file-upload picker, a Record button, or both.
+            // The Vault iframe currently denies microphone access, so file-upload is
+            // the path that works without a mic; recording stays for hosts that grant it.
+            const mode = config.audio.mode;
+            const allowUpload = mode === 'upload' || mode === 'both';
+            const allowRecord = mode === 'record' || mode === 'both';
+            const uploadHtml = allowUpload
+                ? `<div>
+            <label class="label" for="turn_file" style="display:block;margin-bottom:.25rem;font-size:.88rem;color:#374151">${esc('Upload audio answer')}</label>
+            <input id="turn_file" type="file" accept="audio/*"
+              style="display:block;width:100%;box-sizing:border-box" />
+          </div>`
+                : '';
+            const recordHtml = allowRecord
+                ? `<button id="record_btn" type="button" class="button"
+            style="width:100%;padding:.6rem;display:flex;align-items:center;justify-content:center;gap:.5rem;background:#6366f1;color:#fff;border:none;border-radius:.5rem;cursor:pointer;font-size:.95rem"
+            aria-label="Record your answer">
+            <span aria-hidden="true">🎙</span> ${allowUpload ? esc('Or record answer') : esc('Record answer')}
+          </button>`
+                : '';
+            controlHtml = `
+        <div style="padding:.5rem 0;display:flex;flex-direction:column;gap:.6rem">
+          ${uploadHtml}
+          ${recordHtml}
+        </div>`;
+        }
+        root.innerHTML = `
+      <div class="card" style="display:flex;flex-direction:column;height:100%;min-height:300px;gap:0">
+        <div id="transcript"
+          role="list"
+          aria-label="Conversation"
+          aria-live="polite"
+          style="flex:1;overflow-y:auto;display:flex;flex-direction:column;gap:.5rem;padding:.5rem 0;margin-bottom:.5rem;max-height:420px">
+          ${turnsHtml}
+          ${thinkingHtml}
+          <div id="scroll_anchor"></div>
+        </div>
+        <div style="border-top:1px solid #f3f4f6;padding-top:.75rem">
+          ${controlHtml}
+        </div>
+      </div>`;
+        scrollToBottom();
+        // Wire stop button
+        root.querySelector('#stop_btn')?.addEventListener('click', () => {
+            stopRecording();
+        });
+        // Wire record button
+        root.querySelector('#record_btn')?.addEventListener('click', () => {
+            const btn = root.querySelector('#record_btn');
+            if (btn)
+                btn.disabled = true;
+            void startRecording(s.turns);
+        });
+        // Wire file-upload input. A pre-recorded clip goes through the SAME
+        // runUpload() helper as the record path (upload → publish turn → re-poll),
+        // so record and upload share all publish/poll logic. Disable both controls
+        // immediately so a second pick / a Record click can't race the upload.
+        root.querySelector('#turn_file')?.addEventListener('change', (e) => {
+            const file = e.target.files?.[0] ?? null;
+            if (!file)
+                return;
+            const fileInput = root.querySelector('#turn_file');
+            if (fileInput)
+                fileInput.disabled = true;
+            const recBtn = root.querySelector('#record_btn');
+            if (recBtn)
+                recBtn.disabled = true;
+            void runUpload(file, s.turns);
+        });
+    }
+    // ── render: uploading ─────────────────────────────────────────────────────────
+    function renderUploading(s) {
+        const turnsHtml = s.turns.map((t) => {
+            const isAgent = t.role === 'agent' || t.role === 'coach' || t.role === 'assistant';
+            const bubbleStyle = isAgent
+                ? 'background:#f0f0fe;border-radius:1rem 1rem 1rem .25rem;padding:.6rem .85rem;max-width:85%;align-self:flex-start;'
+                : 'background:#6366f1;color:#fff;border-radius:1rem 1rem .25rem 1rem;padding:.6rem .85rem;max-width:85%;align-self:flex-end;';
+            return `<div style="${bubbleStyle}" role="listitem">${esc(t.text)}</div>`;
+        }).join('');
+        root.innerHTML = `
+      <div class="card" style="display:flex;flex-direction:column;gap:0;height:100%;min-height:300px">
+        <div role="list" aria-label="Conversation"
+          style="flex:1;overflow-y:auto;display:flex;flex-direction:column;gap:.5rem;padding:.5rem 0;margin-bottom:.5rem;max-height:420px">
+          ${turnsHtml}
+          <div id="scroll_anchor"></div>
+        </div>
+        <div style="border-top:1px solid #f3f4f6;padding-top:.75rem">
+          <div style="display:flex;flex-direction:column;gap:.4rem;padding:.6rem;background:#f8fafc;border-radius:.5rem">
+            <p aria-live="polite" style="margin:0;font-size:.9rem;color:#374151">${esc(s.progress)}</p>
+            <div style="height:4px;background:#e5e7eb;border-radius:2px">
+              <div style="height:100%;width:60%;background:#6366f1;border-radius:2px;animation:pulse 1.2s ease-in-out infinite"></div>
+            </div>
+          </div>
+        </div>
+      </div>`;
+        scrollToBottom();
+    }
+    // ── render: awaiting-confirm ──────────────────────────────────────────────────
+    function renderAwaitingConfirm(s) {
+        const turnsHtml = s.turns.map((t) => {
+            const isAgent = t.role === 'agent' || t.role === 'coach' || t.role === 'assistant';
+            const bubbleStyle = isAgent
+                ? 'background:#f0f0fe;border-radius:1rem 1rem 1rem .25rem;padding:.6rem .85rem;max-width:85%;align-self:flex-start;'
+                : 'background:#6366f1;color:#fff;border-radius:1rem 1rem .25rem 1rem;padding:.6rem .85rem;max-width:85%;align-self:flex-end;';
+            return `<div style="${bubbleStyle}" role="listitem">${esc(t.text)}</div>`;
+        }).join('');
+        root.innerHTML = `
+      <div class="card" style="display:flex;flex-direction:column;gap:0;height:100%;min-height:300px">
+        <div role="list" aria-label="Conversation"
+          style="flex:1;overflow-y:auto;display:flex;flex-direction:column;gap:.5rem;padding:.5rem 0;margin-bottom:.5rem;max-height:420px">
+          ${turnsHtml}
+          <div id="scroll_anchor"></div>
+        </div>
+        <div style="border-top:1px solid #f3f4f6;padding-top:.75rem;display:flex;flex-direction:column;gap:.5rem">
+          <p style="margin:0;font-size:.9rem;color:#374151;text-align:center">
+            Your coach has built a draft profile based on your conversation.
+          </p>
+          <button id="confirm_btn" type="button" class="button"
+            style="width:100%;padding:.65rem;background:#059669;color:#fff;border:none;border-radius:.5rem;cursor:pointer;font-size:1rem;font-weight:600"
+            aria-label="Confirm your profile">
+            ✓ Confirm profile
+          </button>
+        </div>
+      </div>`;
+        scrollToBottom();
+        root.querySelector('#confirm_btn')?.addEventListener('click', async () => {
+            const btn = root.querySelector('#confirm_btn');
+            if (btn) {
+                btn.disabled = true;
+                btn.textContent = 'Confirming…';
+            }
+            try {
+                await runtime.publish(config.confirmEvent.type, { schema_version: 1, session_id: sessionId, edits: {} }, sessionId);
+                // Poll until doneWhen
+                if (config.doneWhen && config.statusQuery) {
+                    scheduleStatusPoll(s.turns);
+                }
+                else {
+                    transition({ phase: 'done' });
+                }
+            }
+            catch (err) {
+                handleError(err);
+            }
+        });
+    }
+    // ── render: done ──────────────────────────────────────────────────────────────
+    function renderDone() {
+        root.innerHTML = `
+      <div class="card" style="text-align:center;padding:2rem 1rem;display:flex;flex-direction:column;align-items:center;gap:1rem">
+        <div style="font-size:2.5rem" aria-hidden="true">✓</div>
+        <h2 style="margin:0;color:#059669;font-size:1.15rem">Profile confirmed!</h2>
+        <p class="muted" style="margin:0;max-width:280px">
+          Your coaching profile is ready. Check the Profile widget to review it anytime.
+        </p>
+      </div>`;
+    }
+    // ── render: error ─────────────────────────────────────────────────────────────
+    function renderError(s) {
+        root.innerHTML = `
+      <div class="card">
+        <p class="error" role="alert">${esc(s.message)}</p>
+        <button id="retry_btn" type="button" class="button" style="margin-top:.75rem">
+          Try again
+        </button>
+      </div>`;
+        root.querySelector('#retry_btn')?.addEventListener('click', () => {
+            teardown();
+            transition({ phase: 'starting' });
+            void boot();
+        });
+    }
+    // ── render: not-connected ─────────────────────────────────────────────────────
+    function renderNotConnected() {
+        root.innerHTML = `
+      <div class="card">
+        <h2 style="margin:0 0 .25rem">Connect your account</h2>
+        <p class="muted">${esc(config.connectPrompt ?? 'Connect your account to continue.')}</p>
+        <button id="connect_btn" type="button" class="button"
+          style="width:100%;padding:.6rem;font-size:1rem;margin-top:.75rem">
+          Connect
+        </button>
+      </div>`;
+        root.querySelector('#connect_btn')?.addEventListener('click', async () => {
+            const btn = root.querySelector('#connect_btn');
+            if (btn) {
+                btn.disabled = true;
+                btn.textContent = 'Connecting…';
+            }
+            try {
+                await runtime.connectAgent();
+                transition({ phase: 'starting' });
+                void boot();
+            }
+            catch (err) {
+                transition({ phase: 'error', message: err?.message ?? String(err) });
+            }
+        });
+    }
+    // ── initial boot ──────────────────────────────────────────────────────────────
+    render(); // show 'starting' immediately
+    void boot();
+}

package/dist/kinds/dashboard.d.ts

@@ -0,0 +1,2 @@
+import type { DashboardConfig, WidgetRuntimeApi } from '../types.js';
+export declare function renderDashboard(root: HTMLElement, config: DashboardConfig, runtime: WidgetRuntimeApi): Promise<void>;