).
+ if (validator("")) out += ` ${attr}`;
+ continue;
+ }
+ if (validator(value)) out += ` ${attr}="${escapeHtml(value)}"`;
+ }
+ // Links open outside the canvas, matching the table and markdown renderers.
+ if (name === "a" && out.includes(' href="')) {
+ out += ' target="_blank" rel="noopener noreferrer nofollow"';
+ }
+ return `${out}>`;
+}
+
+// Strip active content from caller-supplied HTML so it can be embedded in a
+// card. Unknown or malformed tags render as visible literal text.
+export function sanitizeHtml(html) {
+ const segments = String(html ?? "").split(/(<[^>]*>)/);
+ const openStack = [];
+ let out = "";
+
+ for (const segment of segments) {
+ if (segment.length === 0) continue;
+ if (!segment.startsWith("<")) {
+ out += escapeHtml(segment);
+ continue;
+ }
+ const match = /^<\s*(\/?)\s*([a-zA-Z][a-zA-Z0-9-]*)([^>]*?)\/?\s*>$/.exec(segment);
+ const name = match?.[2]?.toLowerCase();
+ if (!match || !SAFE_HTML_TAGS.has(name)) {
+ out += escapeHtml(segment);
+ continue;
+ }
+ if (match[1] === "/") {
+ // Emit the close only if the element is actually open, closing any
+ // elements opened after it first so nesting stays valid.
+ const depth = openStack.lastIndexOf(name);
+ if (depth === -1) continue;
+ while (openStack.length > depth) {
+ out += ``;
+ }
+ continue;
+ }
+ out += rebuildTag(name, match[3] ?? "");
+ if (!SANITIZE_VOID_TAGS.has(name)) openStack.push(name);
+ }
+
+ while (openStack.length > 0) {
+ out += ``;
+ }
+ return out;
+}
+
+// ---------------------------------------------------------------------------
+// Tutor terms
+// ---------------------------------------------------------------------------
+
+const DEFAULT_MAX_PER_TERM = 1;
+const DEFAULT_MAX_TOTAL = 40;
+
+// Text inside these elements is not visible prose. A span here is either
+// shown literally or breaks the element: SVG is the native tooltip,
+// so markup inside it turns the tooltip into raw text.
+const TERM_SKIP_TAGS = new Set(["script", "style", "title", "desc", "head", "textarea", "option", "select"]);
+
+const TERM_CODE_TAGS = new Set(["pre", "code", "kbd", "samp", "var"]);
+
+// Elements with no closing tag, which therefore never open a region.
+const VOID_TAGS = new Set([
+ "area", "base", "br", "col", "embed", "hr", "img", "input",
+ "link", "meta", "param", "source", "track", "wbr",
+]);
+
+// Comments, doctypes, and a stray "<" all return null: they open nothing.
+function readTag(token) {
+ const match = /^<\s*(\/?)\s*([a-zA-Z][a-zA-Z0-9:-]*)/.exec(token);
+ if (!match) return null;
+ return {
+ name: match[2].toLowerCase(),
+ closing: match[1] === "/",
+ selfClosing: /\/\s*>$/.test(token),
+ isTerm: /class\s*=\s*["'][^"']*\bmcc-term\b/.test(token),
+ };
+}
+
+function prepareTerms(terms) {
+ const seen = new Set();
+ const prepared = [];
+ for (const entry of terms) {
+ const trimmed = (entry?.term ?? "").trim();
+ if (trimmed.length === 0) continue;
+ const key = trimmed.toLowerCase();
+ // Identical terms listed twice would otherwise burn the per-term budget
+ // twice over and produce two tips for the same word.
+ if (seen.has(key)) continue;
+ seen.add(key);
+ prepared.push({ key, tip: entry.tip ?? "", escaped: escapeHtml(trimmed) });
+ }
+ // Longest first, so "memory safety" claims the position rather than the
+ // "memory" that starts at the same index.
+ prepared.sort((a, b) => b.escaped.length - a.escaped.length || a.key.localeCompare(b.key));
+ return prepared;
+}
+
+// Wrap visible-text occurrences of tutor terms in .mcc-term spans so the
+// canvas page can show dwell tooltips. Every match is emitted straight to the
+// output and never rescanned, and a single alternation over all terms does
+// the scanning, so one term can never land inside markup produced for
+// another. Regions that are not visible prose (attributes, <title>, <script>,
+// <style>, code samples, and text already inside an .mcc-term span) are
+// skipped outright.
+export function wrapTermsInHtml(html, terms, options = {}) {
+ const maxPerTerm = options.maxPerTerm ?? DEFAULT_MAX_PER_TERM;
+ const maxTotal = options.maxTotal ?? DEFAULT_MAX_TOTAL;
+ const prepared = prepareTerms(terms ?? []);
+ if (prepared.length === 0 || maxPerTerm < 1 || maxTotal < 1) return html;
+
+ const skipTags = new Set(TERM_SKIP_TAGS);
+ if (!options.includeCode) for (const tag of TERM_CODE_TAGS) skipTags.add(tag);
+
+ const byMatch = new Map(prepared.map((term) => [term.escaped.toLowerCase(), term]));
+ const pattern = new RegExp(
+ `(?<![\\w-])(?:${prepared.map((term) => escapeRegExp(term.escaped)).join("|")})(?![\\w-])`,
+ "gi",
+ );
+
+ const used = new Map();
+ const openTags = [];
+ const segments = html.split(/(<[^>]*>)/);
+ let total = 0;
+
+ for (let i = 0; i < segments.length; i++) {
+ const segment = segments[i];
+ if (segment.length === 0) continue;
+
+ if (segment.startsWith("<")) {
+ const tag = readTag(segment);
+ if (!tag) continue;
+ if (tag.closing) {
+ for (let depth = openTags.length - 1; depth >= 0; depth--) {
+ if (openTags[depth].name === tag.name) {
+ openTags.length = depth;
+ break;
+ }
+ }
+ } else if (!tag.selfClosing && !VOID_TAGS.has(tag.name)) {
+ openTags.push({ name: tag.name, skip: skipTags.has(tag.name) || tag.isTerm });
+ }
+ continue;
+ }
+
+ if (total >= maxTotal) continue;
+ if (openTags.some((open) => open.skip)) continue;
+
+ pattern.lastIndex = 0;
+ let out = "";
+ let last = 0;
+ let match;
+ while (total < maxTotal && (match = pattern.exec(segment)) !== null) {
+ const term = byMatch.get(match[0].toLowerCase());
+ if (!term) continue;
+ const count = used.get(term.key) ?? 0;
+ if (count >= maxPerTerm) continue;
+ used.set(term.key, count + 1);
+ total += 1;
+ out +=
+ segment.slice(last, match.index) +
+ `<span class="mcc-term" data-tip="${escapeHtml(term.tip)}" tabindex="0">${match[0]}</span>`;
+ last = match.index + match[0].length;
+ }
+ if (last > 0) segments[i] = out + segment.slice(last);
+ }
+
+ return segments.join("");
+}
+
+// ---------------------------------------------------------------------------
+// Text to table
+// ---------------------------------------------------------------------------
+
+const CANDIDATE_DELIMITERS = ["\t", "|", ";", ","];
+
+// Pick the first candidate delimiter that appears on most non-empty lines.
+export function detectCellDelimiter(lines) {
+ if (lines.length === 0) return null;
+ const threshold = Math.max(1, Math.ceil(lines.length * 0.6));
+ for (const delimiter of CANDIDATE_DELIMITERS) {
+ const linesWithDelimiter = lines.filter((line) => line.includes(delimiter)).length;
+ if (linesWithDelimiter >= threshold) return delimiter;
+ }
+ return null;
+}
+
+// Pad or trim header titles to exactly `count` columns.
+export function balanceHeaders(headers, count) {
+ const out = headers.slice(0, count).map((h) => h.trim());
+ while (out.length < count) out.push(`Column ${out.length + 1}`);
+ return out;
+}
+
+export function textToTable(text, options = {}) {
+ const rowDelimiter = options.rowDelimiter ?? "\n";
+ const lines = String(text ?? "")
+ .split(rowDelimiter)
+ .map((line) => line.trim())
+ .filter((line) => line.length > 0);
+
+ if (lines.length === 0) {
+ const width = options.columns ?? options.headers?.length ?? 1;
+ return { headers: options.headers ? balanceHeaders(options.headers, width) : [], rows: [] };
+ }
+
+ const delimiter = options.cellDelimiter ?? detectCellDelimiter(lines);
+ let rows;
+ if (delimiter) {
+ rows = lines.map((line) =>
+ line
+ .split(delimiter)
+ .map((cell) => cell.trim())
+ // Drop empty edge cells produced by markdown-style "| a | b |" rows.
+ .filter((cell, index, cells) => cell.length > 0 || (index > 0 && index < cells.length - 1)),
+ );
+ } else {
+ const columns = Math.max(1, options.columns ?? options.headers?.length ?? 2);
+ rows = [];
+ for (let i = 0; i < lines.length; i += columns) {
+ rows.push(lines.slice(i, i + columns));
+ }
+ }
+
+ const width = Math.max(
+ 1,
+ options.columns ?? Math.max(options.headers?.length ?? 0, ...rows.map((row) => row.length)),
+ );
+ rows = rows.map((row) => {
+ const cells = row.slice(0, width);
+ while (cells.length < width) cells.push("");
+ return cells;
+ });
+
+ return {
+ headers: options.headers ? balanceHeaders(options.headers, width) : [],
+ rows,
+ };
+}
+
+// Ensure explicit row data is rectangular, padding short rows with blanks.
+export function normalizeRows(rows, headers = []) {
+ const width = Math.max(1, headers.length, ...rows.map((row) => row.length));
+ const balanced = rows.map((row) => {
+ const cells = row.slice(0, width).map((cell) => String(cell ?? ""));
+ while (cells.length < width) cells.push("");
+ return cells;
+ });
+ return {
+ headers: headers.length > 0 ? balanceHeaders(headers, width) : [],
+ rows: balanced,
+ };
+}
+
+// ---------------------------------------------------------------------------
+// Markdown rendering
+// ---------------------------------------------------------------------------
+// The extension stays dependency-free (no markdown package), so this is a
+// small renderer
+// covering what a model-written guide actually uses: headings, paragraphs,
+// nested lists, fenced code, pipe tables, blockquotes, rules, and the inline
+// set (code, bold, italic, links, images). Every text node passes through
+// escapeHtml, so the output cannot carry active content.
+
+function renderInline(raw) {
+ // Null bytes would collide with the placeholder markers below.
+ let text = escapeHtml(String(raw ?? "").replace(/\u0000/g, ""));
+
+ // Code spans first: their content is protected from the other inline rules.
+ const codeSpans = [];
+ text = text.replace(/`([^`]+)`/g, (_, code) => {
+ codeSpans.push(`<code>${code}</code>`);
+ return `\u0000${codeSpans.length - 1}\u0000`;
+ });
+
+ // Images before links, so  is not half-eaten by the link rule.
+ text = text.replace(/!\[([^\]]*)\]\(([^()\s]+)\)/g, (whole, alt, src) => {
+ if (/^https?:\/\//i.test(src) || /^data:image\//i.test(src)) {
+ return `<img src="${src}" alt="${alt}">`;
+ }
+ return whole;
+ });
+ text = text.replace(/\[([^\]]+)\]\(([^()\s]+)\)/g, (whole, label, href) => {
+ if (/^https?:\/\//i.test(href)) {
+ return `<a href="${href}" target="_blank" rel="noopener noreferrer nofollow">${label}</a>`;
+ }
+ return whole;
+ });
+
+ text = text.replace(/\*\*([^*]+)\*\*/g, "<strong>$1</strong>");
+ text = text.replace(/__([^_]+)__/g, "<strong>$1</strong>");
+ text = text.replace(/\*([^*\s][^*]*)\*/g, "<em>$1</em>");
+ text = text.replace(/(^|\s)_([^_]+)_(?=\s|[.,;:!?)]|$)/g, "$1<em>$2</em>");
+
+ return text.replace(/\u0000(\d+)\u0000/g, (_, index) => codeSpans[Number(index)]);
+}
+
+function renderCodeBlock(code, language) {
+ return (
+ '<div class="mcc-codewrap">' +
+ '<button type="button" class="mcc-btn mcc-copy-code">Copy</button>' +
+ `<pre><code class="language-${escapeHtml(language || "text")}">${escapeHtml(code)}</code></pre>` +
+ "</div>"
+ );
+}
+
+function isTableSeparator(line) {
+ return /^\s*\|?\s*:?-{2,}:?\s*(\|\s*:?-{2,}:?\s*)*\|?\s*$/.test(line);
+}
+
+function splitTableRow(line) {
+ const cells = line.split("|").map((cell) => cell.trim());
+ if (cells.length > 0 && cells[0] === "") cells.shift();
+ if (cells.length > 0 && cells[cells.length - 1] === "") cells.pop();
+ return cells;
+}
+
+const LIST_ITEM_PATTERN = /^(\s*)([-*+]|\d+[.)])\s+(.*)$/;
+
+function renderList(lines, start) {
+ // Returns { html, next }. Nesting follows indentation width; two or more
+ // extra spaces open a child list, matching how models format outlines.
+ const stack = [];
+ let html = "";
+ let index = start;
+
+ const closeTo = (depth) => {
+ while (stack.length > depth) {
+ const top = stack.pop();
+ html += `</li></${top.tag}>`;
+ }
+ };
+
+ while (index < lines.length) {
+ const match = LIST_ITEM_PATTERN.exec(lines[index]);
+ if (!match) break;
+ const indent = match[1].replace(/\t/g, " ").length;
+ const ordered = /\d/.test(match[2][0]);
+ const tag = ordered ? "ol" : "ul";
+
+ while (stack.length > 0 && indent < stack[stack.length - 1].indent) {
+ const top = stack.pop();
+ html += `</li></${top.tag}>`;
+ }
+
+ if (stack.length === 0 || indent > stack[stack.length - 1].indent + 1) {
+ stack.push({ indent, tag });
+ html += `<${tag}><li>${renderInline(match[3])}`;
+ } else {
+ html += `</li><li>${renderInline(match[3])}`;
+ }
+ index += 1;
+ }
+ closeTo(0);
+ return { html, next: index };
+}
+
+// Render a markdown fragment to card-styled HTML (no section folding).
+export function renderMarkdownFragment(markdown) {
+ const lines = String(markdown ?? "").replace(/\r\n?/g, "\n").split("\n");
+ const parts = [];
+ let paragraph = [];
+
+ const flushParagraph = () => {
+ if (paragraph.length === 0) return;
+ parts.push(`<p>${paragraph.map(renderInline).join("<br>")}</p>`);
+ paragraph = [];
+ };
+
+ let i = 0;
+ while (i < lines.length) {
+ const line = lines[i];
+ const trimmed = line.trim();
+
+ const fence = /^```\s*([a-zA-Z0-9+#._-]*)\s*$/.exec(trimmed);
+ if (fence) {
+ flushParagraph();
+ const code = [];
+ i += 1;
+ while (i < lines.length && !/^```\s*$/.test(lines[i].trim())) {
+ code.push(lines[i]);
+ i += 1;
+ }
+ i += 1;
+ parts.push(renderCodeBlock(code.join("\n"), fence[1]));
+ continue;
+ }
+
+ if (trimmed.length === 0) {
+ flushParagraph();
+ i += 1;
+ continue;
+ }
+
+ const heading = /^(#{1,6})\s+(.*?)\s*#*\s*$/.exec(trimmed);
+ if (heading) {
+ flushParagraph();
+ const level = heading[1].length;
+ parts.push(`<h${level}>${renderInline(heading[2])}</h${level}>`);
+ i += 1;
+ continue;
+ }
+
+ if (/^(-{3,}|\*{3,}|_{3,})$/.test(trimmed)) {
+ flushParagraph();
+ parts.push("<hr>");
+ i += 1;
+ continue;
+ }
+
+ if (trimmed.startsWith(">")) {
+ flushParagraph();
+ const quoted = [];
+ while (i < lines.length && lines[i].trim().startsWith(">")) {
+ quoted.push(lines[i].trim().replace(/^>\s?/, ""));
+ i += 1;
+ }
+ const inner = quoted
+ .join("\n")
+ .split(/\n{2,}/)
+ .map((block) => `<p>${block.split("\n").map(renderInline).join("<br>")}</p>`)
+ .join("");
+ parts.push(`<blockquote>${inner}</blockquote>`);
+ continue;
+ }
+
+ if (trimmed.includes("|") && i + 1 < lines.length && isTableSeparator(lines[i + 1])) {
+ flushParagraph();
+ const headers = splitTableRow(trimmed);
+ const rows = [];
+ i += 2;
+ while (i < lines.length && lines[i].includes("|") && lines[i].trim().length > 0) {
+ rows.push(splitTableRow(lines[i].trim()));
+ i += 1;
+ }
+ const thead = `<thead><tr>${headers.map((h) => `<th scope="col">${renderInline(h)}</th>`).join("")}</tr></thead>`;
+ const tbody = rows
+ .map((row) => `<tr>${headers.map((_, c) => `<td>${renderInline(row[c] ?? "")}</td>`).join("")}</tr>`)
+ .join("");
+ parts.push(
+ `<div class="mcc-table-scroll"><table class="mcc-table">${thead}<tbody>${tbody}</tbody></table></div>`,
+ );
+ continue;
+ }
+
+ if (LIST_ITEM_PATTERN.test(line)) {
+ flushParagraph();
+ const list = renderList(lines, i);
+ parts.push(list.html);
+ i = list.next;
+ continue;
+ }
+
+ paragraph.push(trimmed);
+ i += 1;
+ }
+ flushParagraph();
+ return parts.join("\n");
+}
+
+// Parse a markdown document for the document card: the first H1
+// becomes the title, and the body splits into sections on H2 headings (the
+// content before the first H2 is the intro section with a null heading).
+export function parseMarkdownDocument(markdown) {
+ const source = String(markdown ?? "").replace(/\r\n?/g, "\n");
+ const lines = source.split("\n");
+ let title;
+ const sections = [];
+ let current = { heading: null, lines: [] };
+ let inFence = false;
+
+ for (const line of lines) {
+ const trimmed = line.trim();
+ if (/^```/.test(trimmed)) inFence = !inFence;
+ if (!inFence) {
+ const h1 = /^#\s+(.*?)\s*#*\s*$/.exec(trimmed);
+ if (h1 && title === undefined) {
+ title = h1[1];
+ continue;
+ }
+ const h2 = /^##\s+(.*?)\s*#*\s*$/.exec(trimmed);
+ if (h2) {
+ if (current.lines.join("").trim().length > 0 || current.heading !== null) sections.push(current);
+ current = { heading: h2[1], lines: [] };
+ continue;
+ }
+ }
+ current.lines.push(line);
+ }
+ if (current.lines.join("").trim().length > 0 || current.heading !== null) sections.push(current);
+
+ return {
+ title,
+ sections: sections.map((section) => ({
+ heading: section.heading,
+ html: renderMarkdownFragment(section.lines.join("\n")),
+ })),
+ };
+}
+
+function renderMarkdownSections(sections, options = {}) {
+ const folded = options.folded !== false;
+ const headed = sections.filter((section) => section.heading !== null);
+ const parts = [];
+
+ if (!folded || headed.length === 0) {
+ for (const section of sections) {
+ if (section.heading !== null) parts.push(`<h2>${escapeHtml(section.heading)}</h2>`);
+ parts.push(section.html);
+ }
+ return parts.join("");
+ }
+
+ let firstOpenUsed = false;
+ let controlsAdded = false;
+ for (const section of sections) {
+ if (section.heading === null) {
+ parts.push(section.html);
+ continue;
+ }
+ if (!controlsAdded) {
+ controlsAdded = true;
+ parts.push(`<div style="display:flex;gap:6px;justify-content:flex-end;margin-bottom:8px">
+<button type="button" class="mcc-btn" data-mcc-expand="all">Show all</button>
+<button type="button" class="mcc-btn" data-mcc-expand="none">Hide all</button>
+</div>`);
+ }
+ const open = !firstOpenUsed && options.openFirst !== false ? " open" : "";
+ firstOpenUsed = true;
+ parts.push(`<details class="mcc-reveal"${open}>
+<summary>${escapeHtml(section.heading)}</summary>
+<div class="mcc-reveal-body">${section.html}</div>
+</details>`);
+ }
+ return parts.join("\n");
+}
+
+// ---------------------------------------------------------------------------
+// Chart rendering
+// ---------------------------------------------------------------------------
+// Axis, grid, and separator colors reference the card theme variables (with
+// the plain light values
+// as fallbacks) instead of fixed hex values. The canvas page inlines the SVG
+// in its own DOM, so the chart follows the light/dark theme for free.
+
+const PALETTE = ["#2b6cb0", "#2f855a", "#0e7490", "#5b6b7b", "#1d4e89", "#38a169", "#4c7ba8"];
+
+const CHART_WIDTH = 640;
+const CHART_HEIGHT = 340;
+const MARGIN = { top: 20, right: 20, bottom: 56, left: 52 };
+
+const GRID_STROKE = "var(--mcc-border, #d8e2ec)";
+const TICK_FILL = "var(--mcc-muted, #5b6b7b)";
+const LABEL_FILL = "var(--mcc-text, #1f2328)";
+const SLICE_STROKE = "var(--mcc-surface, #ffffff)";
+
+// Steps a reader can do arithmetic on, in ascending order within each decade.
+const STEP_MANTISSAS = [1, 2, 2.5, 5];
+
+// Choose an axis top and tick step covering [0, maxValue] in at most maxTicks
+// intervals, picking the SMALLEST readable step that fits rather than slicing
+// the range into a fixed number of equal parts. Integer data is additionally
+// held to an integer step, so a 1-5 rating scale reads 0, 1, 2, 3, 4, 5.
+export function niceScale(maxValue, maxTicks = 6, integerData = false) {
+ if (!(maxValue > 0) || !Number.isFinite(maxValue)) return { max: 1, step: 1, ticks: [0, 1] };
+
+ let step = 0;
+ const startExponent = Math.floor(Math.log10(maxValue)) - 2;
+ for (let exponent = startExponent; exponent <= startExponent + 9 && step === 0; exponent++) {
+ for (const mantissa of STEP_MANTISSAS) {
+ const candidate = mantissa * 10 ** exponent;
+ if (candidate <= 0) continue;
+ if (integerData && !Number.isInteger(candidate)) continue;
+ // The epsilon keeps a max that is an exact multiple of the candidate
+ // from being counted as one interval too many.
+ if (Math.ceil(maxValue / candidate - 1e-9) <= maxTicks) {
+ step = candidate;
+ break;
+ }
+ }
+ }
+ if (step === 0) step = maxValue / maxTicks;
+
+ const max = Number((Math.ceil(maxValue / step - 1e-9) * step).toFixed(6));
+ const ticks = [];
+ // Half a step of slack absorbs the float drift that would otherwise drop
+ // the top tick when max is an exact multiple of step.
+ for (let value = 0; value <= max + step / 2; value += step) {
+ ticks.push(Number(value.toFixed(6)));
+ }
+ return { max, step, ticks };
+}
+
+// Data made only of integers gets an integer axis. A 1-5 rating scale is the
+// common case, and fractional ticks on it are noise.
+function seriesScale(series) {
+ const values = series.flatMap((s) => s.values).filter((value) => Number.isFinite(value));
+ return niceScale(Math.max(...values, 0), 6, values.every((value) => Number.isInteger(value)));
+}
+
+// Only the decimals the step actually needs, so a 0.25 step reads "0.25" and
+// a whole-number step never prints "3.0".
+function decimalsForStep(step) {
+ if (Number.isInteger(step)) return 0;
+ const text = step.toPrecision(12).replace(/0+$/, "");
+ const dot = text.indexOf(".");
+ return dot === -1 ? 0 : Math.min(6, text.length - dot - 1);
+}
+
+function formatTick(value, step) {
+ if (Number.isInteger(value)) return String(value);
+ return value.toFixed(decimalsForStep(step));
+}
+
+function axisAndGrid(scale, plotWidth, plotHeight) {
+ let out = "";
+ for (const value of scale.ticks) {
+ const y = MARGIN.top + plotHeight - (plotHeight * value) / scale.max;
+ out += `<line x1="${MARGIN.left}" y1="${y.toFixed(1)}" x2="${MARGIN.left + plotWidth}" y2="${y.toFixed(1)}" stroke="${GRID_STROKE}" stroke-width="1"/>`;
+ out += `<text x="${MARGIN.left - 8}" y="${(y + 4).toFixed(1)}" text-anchor="end" font-size="11" fill="${TICK_FILL}">${escapeHtml(
+ formatTick(value, scale.step),
+ )}</text>`;
+ }
+ return out;
+}
+
+// Break a label across at most maxLines lines without splitting words. A word
+// too long to fit on its own line is left alone rather than hyphenated; the
+// full text is always reachable from the <title> either way.
+export function wrapLabel(label, maxChars, maxLines) {
+ const words = label.split(/\s+/).filter((word) => word.length > 0);
+ if (words.length === 0) return [label];
+ const lines = [];
+ let current = "";
+ for (const word of words) {
+ const candidate = current.length === 0 ? word : `${current} ${word}`;
+ if (candidate.length <= maxChars || current.length === 0) {
+ current = candidate;
+ } else {
+ lines.push(current);
+ current = word;
+ }
+ }
+ if (current.length > 0) lines.push(current);
+ if (lines.length <= maxLines) return lines;
+ const kept = lines.slice(0, maxLines);
+ kept[maxLines - 1] = `${kept[maxLines - 1]}...`;
+ return kept;
+}
+
+function xLabels(labels, plotWidth, plotHeight) {
+ const step = plotWidth / Math.max(1, labels.length);
+ const maxChars = Math.max(6, Math.floor(step / 6));
+ return labels
+ .map((label, i) => {
+ const x = MARGIN.left + step * i + step / 2;
+ const y = MARGIN.top + plotHeight + 16;
+ const lines = wrapLabel(label, maxChars, 2);
+ const tspans = lines
+ .map((line, index) => `<tspan x="${x.toFixed(1)}" dy="${index === 0 ? 0 : 12}">${escapeHtml(line)}</tspan>`)
+ .join("");
+ return (
+ `<text x="${x.toFixed(1)}" y="${y}" text-anchor="middle" font-size="11" fill="${LABEL_FILL}">` +
+ `<title>${escapeHtml(label)} ${tspans}`
+ );
+ })
+ .join("");
+}
+
+function barChartSvg(labels, series) {
+ const plotWidth = CHART_WIDTH - MARGIN.left - MARGIN.right;
+ const plotHeight = CHART_HEIGHT - MARGIN.top - MARGIN.bottom;
+ const scale = seriesScale(series);
+ const maxValue = scale.max;
+ const groupStep = plotWidth / Math.max(1, labels.length);
+ const barWidth = Math.max(4, (groupStep * 0.7) / Math.max(1, series.length));
+
+ let bars = "";
+ series.forEach((s, si) => {
+ s.values.slice(0, labels.length).forEach((value, li) => {
+ const height = Math.max(0, (value / maxValue) * plotHeight);
+ const x = MARGIN.left + groupStep * li + groupStep * 0.15 + barWidth * si;
+ const y = MARGIN.top + plotHeight - height;
+ bars +=
+ `${escapeHtml(`${s.name} - ${labels[li]}: ${value}`)} ` +
+ axisAndGrid(scale, plotWidth, plotHeight) +
+ bars +
+ xLabels(labels, plotWidth, plotHeight) +
+ " "
+ );
+}
+
+function lineChartSvg(labels, series) {
+ const plotWidth = CHART_WIDTH - MARGIN.left - MARGIN.right;
+ const plotHeight = CHART_HEIGHT - MARGIN.top - MARGIN.bottom;
+ const scale = seriesScale(series);
+ const maxValue = scale.max;
+ const step = plotWidth / Math.max(1, labels.length);
+
+ let lines = "";
+ series.forEach((s, si) => {
+ const color = PALETTE[si % PALETTE.length];
+ const points = s.values
+ .slice(0, labels.length)
+ .map((value, li) => {
+ const x = MARGIN.left + step * li + step / 2;
+ const y = MARGIN.top + plotHeight - (value / maxValue) * plotHeight;
+ return `${x.toFixed(1)},${y.toFixed(1)}`;
+ })
+ .join(" ");
+ lines += `` +
+ `${escapeHtml(`${s.name} - ${labels[li]}: ${value}`)} `;
+ });
+ });
+
+ return (
+ `` +
+ axisAndGrid(scale, plotWidth, plotHeight) +
+ lines +
+ xLabels(labels, plotWidth, plotHeight) +
+ " "
+ );
+}
+
+function pieChartSvg(slices, donut) {
+ const size = 300;
+ const cx = size / 2;
+ const cy = size / 2;
+ const radius = size / 2 - 10;
+ const total = slices.reduce((sum, slice) => sum + Math.max(0, slice.value), 0) || 1;
+
+ let angle = -Math.PI / 2;
+ let paths = "";
+ slices.forEach((slice, i) => {
+ const share = Math.max(0, slice.value) / total;
+ const sweep = share * Math.PI * 2;
+ const x1 = cx + radius * Math.cos(angle);
+ const y1 = cy + radius * Math.sin(angle);
+ const end = angle + sweep;
+ const x2 = cx + radius * Math.cos(end);
+ const y2 = cy + radius * Math.sin(end);
+ const largeArc = sweep > Math.PI ? 1 : 0;
+ const percent = (share * 100).toFixed(1);
+ if (share >= 0.999) {
+ paths += `${escapeHtml(
+ `${slice.label}: ${slice.value} (${percent}%)`,
+ )} ` +
+ `${escapeHtml(`${slice.label}: ${slice.value} (${percent}%)`)} `;
+ }
+ angle = end;
+ });
+ if (donut) {
+ paths += `${paths} `;
+}
+
+function chartLegend(entries) {
+ const items = entries
+ .map((entry) => `Label Value ${escapeHtml(slice.label)} ${escapeHtml(String(slice.value))} Series ' +
+ labels.map((label) => `${escapeHtml(label)} `).join("") +
+ "${escapeHtml(s.name)} ` +
+ labels.map((_, i) => `${escapeHtml(String(s.values[i] ?? ""))} `).join("") +
+ "View data ${escapeHtml(options.subtitle)}
`
+ : "";
+ const toggles =
+ 'Copy card ' +
+ '</> ' +
+ '⌃ ' +
+ '✕ ';
+
+ const articleHtml = `
+
+
+${body}
+
+
+ `;
+
+ return { id, articleHtml, config };
+}
+
+function finishCard(shellOptions, summary) {
+ const { id, articleHtml, config } = renderCardShell(shellOptions);
+ return {
+ id,
+ kind: shellOptions.kind,
+ title: shellOptions.title,
+ articleHtml,
+ config,
+ summary,
+ };
+}
+
+function requireTitle(options) {
+ const title = String(options?.title ?? "").trim();
+ if (title.length === 0) throw new Error("A non-empty title is required.");
+ return title;
+}
+
+// Tab panels and reveal sections accept markdown (with "content" as an
+// alias, because that is the key agents reach for unprompted), code, HTML
+// (sanitized to an allowlisted subset), or plain text, checked in that
+// order. A part with none of them is an error, not an empty panel:
+// rendering nothing silently is exactly the failure an agent cannot see
+// and correct.
+function richContent(part, what) {
+ const markdown = [part.markdown, part.content].find(
+ (value) => value !== undefined && String(value).trim().length > 0,
+ );
+ if (markdown !== undefined) {
+ return `${renderMarkdownFragment(markdown)}
`;
+ }
+ if (part.code !== undefined && String(part.code).trim().length > 0) {
+ return renderCodeBlock(String(part.code), part.language);
+ }
+ if (part.html !== undefined && String(part.html).trim().length > 0) {
+ return sanitizeHtml(part.html);
+ }
+ if (part.text !== undefined && String(part.text).trim().length > 0) {
+ return textToParagraphs(part.text);
+ }
+ throw new Error(
+ `${what} has no content. Provide non-empty "markdown" (alias "content"), "code", "html", or "text".`,
+ );
+}
+
+// ---------------------------------------------------------------------------
+// Card builders
+// ---------------------------------------------------------------------------
+
+export function buildTabCard(options) {
+ const title = requireTitle(options);
+ const tabs = Array.isArray(options.tabs) ? options.tabs : [];
+ if (tabs.length === 0) throw new Error("Provide at least one tab.");
+
+ const groupId = uid("tabs");
+ const buttons = tabs
+ .map((tab, index) => {
+ const selected = index === 0 ? "true" : "false";
+ return (
+ `` +
+ `${escapeHtml(tab.label ?? `Tab ${index + 1}`)} `
+ );
+ })
+ .join("\n");
+ const panels = tabs
+ .map((tab, index) => {
+ const hidden = index === 0 ? "" : " hidden";
+ return (
+ `${richContent(tab, `Tab "${tab.label ?? index + 1}"`)}
`
+ );
+ })
+ .join("\n");
+
+ const body = `
+
+${buttons}
+
+${panels}
+ `;
+
+ const labels = tabs.map((tab, index) => tab.label ?? `Tab ${index + 1}`).join(", ");
+ return finishCard(
+ {
+ title,
+ subtitle: options.subtitle,
+ kind: "tabs",
+ body,
+ tutorTerms: options.tutorTerms,
+ tutorTermsInCode: options.tutorTermsInCode,
+ contextActions: options.contextActions,
+ },
+ `Created tab card "${title}" with ${tabs.length} tab(s): ${labels}.`,
+ );
+}
+
+function renderTableCell(value, columnIndex, options) {
+ const autoLink = options.autoLinkUrls !== false;
+ const isLinkColumn = options.linkColumns?.includes(columnIndex) ?? false;
+ if ((isLinkColumn || autoLink) && looksLikeUrl(value)) {
+ const href = escapeHtml(value.trim());
+ return `${href} `;
+ }
+ return escapeHtml(value);
+}
+
+export function tableDataToHtml(data, options = {}) {
+ const caption = options.caption ? `${escapeHtml(options.caption)} ` : "";
+ const thead =
+ data.headers.length > 0
+ ? `${data.headers.map((h) => `${escapeHtml(h)} `).join("")} ${row.map((cell, index) => `${renderTableCell(cell, index, options)} `).join("")} `)
+ .join("\n");
+ return ``;
+}
+
+export function buildTableCard(options) {
+ const title = requireTitle(options);
+ if ((!options.rows || options.rows.length === 0) && !options.text) {
+ throw new Error("Provide either rows or text.");
+ }
+ const data =
+ options.rows && options.rows.length > 0
+ ? normalizeRows(options.rows, options.headers ?? [])
+ : textToTable(options.text ?? "", {
+ columns: options.columns,
+ headers: options.headers,
+ cellDelimiter: options.cellDelimiter,
+ });
+
+ const body = `
+${tableDataToHtml(data, options)}
+ `;
+
+ return finishCard(
+ {
+ title,
+ subtitle: options.subtitle,
+ kind: "table",
+ body,
+ tutorTerms: options.tutorTerms,
+ contextActions: options.contextActions,
+ },
+ `Created table card "${title}" with ${data.rows.length} row(s)` +
+ ` and ${Math.max(data.headers.length, data.rows[0]?.length ?? 0)} column(s).`,
+ );
+}
+
+export function buildChartCard(options) {
+ const title = requireTitle(options);
+ const type = options.type;
+ if (!["bar", "line", "pie", "donut"].includes(type)) {
+ throw new Error('Chart type must be one of "bar", "line", "pie", "donut".');
+ }
+ if ((type === "pie" || type === "donut") && (!options.values || options.values.length === 0)) {
+ throw new Error("Pie and donut charts require values.");
+ }
+ if ((type === "bar" || type === "line") && (!options.series?.length || !options.labels?.length)) {
+ throw new Error("Bar and line charts require labels and series.");
+ }
+ if (type === "bar" || type === "line") {
+ // The scale, bar geometry, and line placement all assume values from 0
+ // up. A negative or non-numeric value would render as a clamped bar or
+ // an off-canvas point, silently misrepresenting the data, so it is
+ // rejected here (and the action schema says the same) instead.
+ for (const s of options.series ?? []) {
+ for (const value of Array.isArray(s?.values) ? s.values : []) {
+ if (!Number.isFinite(value) || value < 0) {
+ throw new Error(
+ `Series "${s?.name ?? "?"}" contains ${String(value)}: ` +
+ "bar and line charts accept finite values of 0 or greater only.",
+ );
+ }
+ }
+ }
+ }
+
+ let svg;
+ let legendHtml;
+ if (type === "pie" || type === "donut") {
+ const slices = options.values ?? [];
+ svg = pieChartSvg(slices, type === "donut");
+ const total = slices.reduce((sum, slice) => sum + Math.max(0, slice.value), 0) || 1;
+ legendHtml = chartLegend(
+ slices.map((slice, i) => ({
+ label: `${slice.label} (${((Math.max(0, slice.value) / total) * 100).toFixed(1)}%)`,
+ color: PALETTE[i % PALETTE.length],
+ })),
+ );
+ } else {
+ const labels = options.labels ?? [];
+ const series = options.series ?? [];
+ svg = type === "line" ? lineChartSvg(labels, series) : barChartSvg(labels, series);
+ legendHtml =
+ series.length > 1
+ ? chartLegend(series.map((s, i) => ({ label: s.name, color: PALETTE[i % PALETTE.length] })))
+ : "";
+ }
+
+ const description = options.description ? `${escapeHtml(options.description)}
` : "";
+ const yLabel = options.yLabel ? `${escapeHtml(options.yLabel)}
` : "";
+
+ const body = `
+${description}${yLabel}
+${svg}
+${legendHtml}
+${chartDataTable(options)}
+ `;
+
+ const points =
+ type === "pie" || type === "donut"
+ ? `${options.values?.length ?? 0} slice(s)`
+ : `${options.series?.length ?? 0} series over ${options.labels?.length ?? 0} label(s)`;
+ return finishCard(
+ {
+ title,
+ subtitle: options.subtitle,
+ kind: `chart-${type}`,
+ body,
+ tutorTerms: options.tutorTerms,
+ contextActions: options.contextActions,
+ },
+ `Created ${type} chart card "${title}" (${points}) as an SVG with a collapsible data table.`,
+ );
+}
+
+function normalizeFieldOptions(options = []) {
+ return options.map((option) =>
+ typeof option === "string" ? { label: option, value: option } : { ...option, value: option.value ?? option.label },
+ );
+}
+
+function renderFormField(field, formId) {
+ const type = field.type ?? "text";
+ const fieldId = `${formId}-${String(field.name).replace(/[^a-zA-Z0-9_-]/g, "_")}`;
+ const name = escapeHtml(field.name);
+ const required = field.required ? " required" : "";
+ const requiredMark = field.required ? '* ' : "";
+ const label = escapeHtml(field.label ?? field.name);
+ const placeholder = field.placeholder ? ` placeholder="${escapeHtml(field.placeholder)}"` : "";
+ const value = field.value !== undefined ? escapeHtml(field.value) : "";
+ const help = field.help ? `${escapeHtml(field.help)} ` : "";
+
+ if (type === "hidden") {
+ return `${label}${requiredMark}
+${help}
`;
+ }
+ if (type === "select") {
+ const optionTags = normalizeFieldOptions(field.options)
+ .map((option) => {
+ const selected = option.value === field.value ? " selected" : "";
+ return `${escapeHtml(option.label)} `;
+ })
+ .join("");
+ return `${label}${requiredMark}
+${optionTags} ${help}
`;
+ }
+ if (type === "checkbox" || type === "radio") {
+ const choiceOptions = normalizeFieldOptions(field.options ?? [{ label: field.label ?? field.name, value: "yes" }]);
+ // Native required covers "pick one" radio groups and a lone confirmation
+ // checkbox. A required multi-checkbox group means "check at least one",
+ // which HTML cannot express (required on each box would demand all of
+ // them), so the fieldset is marked and the canvas page enforces it at
+ // submit time via setCustomValidity.
+ const nativeRequired = field.required && (type === "radio" || choiceOptions.length === 1) ? " required" : "";
+ const choices = choiceOptions
+ .map((option, index) => {
+ const choiceId = `${fieldId}-${index}`;
+ const checked = option.value === field.value ? " checked" : "";
+ return `
+ `;
+ })
+ .join("\n");
+ const requireOne = field.required && type === "checkbox" && choiceOptions.length > 1 ? " data-mcc-require-one" : "";
+ return `
+${label}${requiredMark}
+${choices}${help} `;
+ }
+ return `${label}${requiredMark}
+
`;
+}
+
+export function buildFormCard(options) {
+ const title = requireTitle(options);
+ const fields = Array.isArray(options.fields) ? options.fields : [];
+ if (fields.length === 0) throw new Error("Provide at least one field.");
+
+ const formId = uid("form");
+ const fieldHtml = fields.map((field) => renderFormField(field, formId)).join("\n");
+ const description = options.description ? `${escapeHtml(options.description)}
` : "";
+ const templateAttr = options.promptTemplate
+ ? ` data-prompt-template="${escapeHtml(options.promptTemplate)}"`
+ : "";
+
+ const body = ``;
+
+ return finishCard(
+ {
+ title,
+ subtitle: options.subtitle,
+ kind: "form",
+ body,
+ contextActions: options.contextActions,
+ // Forms stay pinned in place: dragging one away from its explanatory
+ // neighbors invites mis-submissions.
+ draggable: false,
+ },
+ `Created form card "${title}" with ${fields.length} field(s). ` +
+ "Submitting it sends the values back to the conversation as the next prompt.",
+ );
+}
+
+export function buildRevealCard(options) {
+ const title = requireTitle(options);
+ const sections = Array.isArray(options.sections) ? options.sections : [];
+ if (sections.length === 0) throw new Error("Provide at least one section.");
+
+ const sectionHtml = sections
+ .map((section) => {
+ const open = section.open ? " open" : "";
+ return `
+${escapeHtml(section.heading ?? "Section")}
+${richContent(section, `Section "${section.heading ?? "Section"}"`)}
+
+Show all
+Hide all
+
+${sectionHtml}`;
+
+ return finishCard(
+ {
+ title,
+ subtitle: options.subtitle,
+ kind: "show-hide",
+ body,
+ tutorTerms: options.tutorTerms,
+ contextActions: options.contextActions,
+ },
+ `Created show/hide card "${title}" with ${sections.length} collapsible section(s).`,
+ );
+}
+
+function countListItems(items) {
+ return items.reduce((sum, item) => sum + 1 + countListItems(item.children ?? []), 0);
+}
+
+function renderListItems(items) {
+ const lis = items
+ .map((item) => {
+ const children = item.children?.length ? renderListItems(item.children) : "";
+ return `${escapeHtml(item.text)}${children} `;
+ })
+ .join("\n");
+ return `\n${lis}\n `;
+}
+
+export function buildListCard(options) {
+ const title = requireTitle(options);
+ const items = Array.isArray(options.items) ? options.items : [];
+ if (items.length === 0) throw new Error("Provide at least one item.");
+
+ const intro = options.intro ? textToParagraphs(options.intro) : "";
+ const body = `
+${intro}
+${renderListItems(items)}
+ `;
+
+ return finishCard(
+ {
+ title,
+ subtitle: options.subtitle,
+ kind: "list",
+ body,
+ tutorTerms: options.tutorTerms,
+ contextActions: options.contextActions,
+ },
+ `Created sequential list card "${title}" with ${countListItems(items)} item(s).`,
+ );
+}
+
+export function buildMarkdownCard(options) {
+ const markdown = String(options.markdown ?? "");
+ if (markdown.trim().length === 0) throw new Error("Provide markdown content.");
+ const doc = parseMarkdownDocument(markdown);
+ const title = options.title ?? doc.title ?? "Document";
+
+ const bodyHtml = renderMarkdownSections(doc.sections, {
+ folded: options.splitSections,
+ openFirst: options.openFirst,
+ });
+ const body = ``;
+
+ const headings = doc.sections.filter((section) => section.heading !== null).map((section) => section.heading);
+ const described =
+ headings.length > 0
+ ? `${headings.length} collapsible section(s): ${headings.join(", ")}`
+ : "a single flowing section";
+ return finishCard(
+ {
+ title,
+ subtitle: options.subtitle,
+ kind: "document",
+ body,
+ tutorTerms: options.tutorTerms,
+ contextActions: options.contextActions,
+ },
+ `Created document card "${title}" from markdown with ${described}.`,
+ );
+}
+
+export function buildVideoCard(options) {
+ const title = requireTitle(options);
+ const src = String(options.src ?? "").trim();
+ if (!isPlayableMediaUrl(src)) {
+ throw new Error(
+ "src must be a direct http(s) video file URL, a data:video/* URI, or a blob: URL " +
+ "(not a streaming platform page).",
+ );
+ }
+ const poster =
+ options.poster && isDisplayableImageUrl(options.poster)
+ ? ` poster="${escapeHtml(String(options.poster).trim())}"`
+ : "";
+ const description = options.description ? `${escapeHtml(options.description)}
` : "";
+ const link = isHttpUrl(src)
+ ? `Open the clip directly
`
+ : "";
+
+ const body = `
+${description}
+
+
+${link}
+ `;
+
+ return finishCard(
+ {
+ title,
+ subtitle: options.subtitle,
+ kind: "video",
+ body,
+ contextActions: options.contextActions,
+ },
+ `Created video card "${title}" for ${src.slice(0, 120)}.`,
+ );
+}
+
+// Dispatch table used by extension.mjs for create and update actions.
+export const CARD_BUILDERS = {
+ tabs: buildTabCard,
+ table: buildTableCard,
+ chart: buildChartCard,
+ form: buildFormCard,
+ "show-hide": buildRevealCard,
+ list: buildListCard,
+ document: buildMarkdownCard,
+ video: buildVideoCard,
+};
+
+export function buildCard(kind, options) {
+ const builder = CARD_BUILDERS[kind];
+ if (!builder) {
+ throw new Error(`Unknown card kind "${kind}". Valid kinds: ${Object.keys(CARD_BUILDERS).join(", ")}.`);
+ }
+ return builder(options);
+}
diff --git a/extensions/chat-cards/copilot-extension.json b/extensions/chat-cards/copilot-extension.json
new file mode 100644
index 0000000000..5a2e907f10
--- /dev/null
+++ b/extensions/chat-cards/copilot-extension.json
@@ -0,0 +1,4 @@
+{
+ "name": "chat-cards",
+ "version": 1
+}
diff --git a/extensions/chat-cards/extension.mjs b/extensions/chat-cards/extension.mjs
new file mode 100644
index 0000000000..43d9a8e3b3
--- /dev/null
+++ b/extensions/chat-cards/extension.mjs
@@ -0,0 +1,1223 @@
+// Extension: chat-cards
+// A GitHub Copilot canvas extension. The agent builds interactive cards
+// (tabs, tables, charts, forms, show/hide sections, sequential lists,
+// markdown documents, video) through canvas actions; the canvas renders
+// them as a live deck. Form submissions and per-card context actions travel
+// back to the conversation as prompts via session.send.
+//
+// All rendering lives in cards-core.mjs (dependency-free, testable without
+// the SDK); this file wires the canvas/session lifecycle, the action
+// surface, and a per-panel page server: open() starts one, onClose() stops
+// it, so the process holds no sockets while no panel is showing.
+import http from "node:http";
+import crypto from "node:crypto";
+import {
+ mkdirSync,
+ readdirSync,
+ readFileSync,
+ renameSync,
+ rmSync,
+ statSync,
+ writeFileSync,
+} from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { joinSession, createCanvas } from "@github/copilot-sdk/extension";
+import { buildCard, CARD_BUILDERS } from "./cards-core.mjs";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const CANVAS_PAGE = readFileSync(path.join(__dirname, "assets", "canvas.html"), "utf8");
+
+// Deck limits. A live deck can hold plenty, but it is still a conversation
+// surface, not a database.
+const MAX_CARDS = 60;
+const MAX_SUBMISSIONS = 50;
+const MAX_BODY_BYTES = 1024 * 1024;
+const MAX_PROMPT_CHARS = 16000;
+
+let session = null;
+
+// instanceId -> { token, sessionId, cards: [], submissions: [], updatedAt }
+const instances = new Map();
+// instanceId -> Set of SSE responses
+const sseClients = new Map();
+
+// ---------------------------------------------------------------------------
+// Deck persistence
+// ---------------------------------------------------------------------------
+// Decks are written to per-user state on disk so the cards a conversation
+// produced are still there after the Copilot app (and this extension process
+// with it) restarts. Tokens are deliberately NOT persisted: they only
+// authenticate the canvas page against this process, so each run mints fresh
+// ones and open() hands the page a fresh URL.
+
+const STATE_VERSION = 1;
+const MAX_PERSISTED_DECKS = 8;
+const PERSIST_DEBOUNCE_MS = 300;
+
+function stateDirectory() {
+ if (process.platform === "win32") {
+ return path.join(
+ process.env.LOCALAPPDATA ?? path.join(os.homedir(), "AppData", "Local"),
+ "chat-cards",
+ );
+ }
+ if (process.platform === "darwin") {
+ return path.join(os.homedir(), "Library", "Application Support", "chat-cards");
+ }
+ return path.join(
+ process.env.XDG_STATE_HOME ?? path.join(os.homedir(), ".local", "state"),
+ "chat-cards",
+ );
+}
+
+// One file per deck rather than one shared document. Several extension
+// processes (parallel Copilot sessions) share this directory, and each one
+// only knows about the decks it holds open plus the snapshot it read at
+// startup. A process rewriting a shared document would flush that stale
+// snapshot over decks another process had since changed, and the two would
+// race on a single temp path. A file per deck means a process only ever
+// replaces the decks it owns, through a temp name scoped to its own pid.
+//
+// Every file also records which process has that deck open, so the other
+// cross-process question, whether a file may be deleted to hold the
+// directory to its cap, has an answer that does not assume one process.
+const DECKS_DIR = path.join(stateDirectory(), "decks");
+// The single-document layout this replaced: imported once, then removed.
+const LEGACY_STATE_FILE = path.join(stateDirectory(), "state.json");
+
+// Stamped into every deck this process holds open, and cleared on the way
+// out. The host name travels with the pid because a home directory can be
+// shared between machines, where a pid from one says nothing about another.
+const DECK_OWNER = { host: os.hostname(), pid: process.pid };
+
+// Canvas instance ids come from the host, so hash rather than trust one as a
+// path segment. The id itself is stored inside the file.
+function deckFile(instanceId) {
+ const name = crypto.createHash("sha256").update(instanceId).digest("hex").slice(0, 32);
+ return path.join(DECKS_DIR, `${name}.json`);
+}
+
+// Is the process that stamped a deck still running? Signal 0 asks the OS
+// whether a pid exists without touching the process. An owner recorded on
+// another machine cannot be checked at all, so it counts as running: holding
+// a deck longer than the cap only costs disk, while deleting a live one
+// costs the user cards a canvas is still showing.
+function ownerIsRunning(owner) {
+ if (!owner || typeof owner !== "object") return false;
+ if (owner.host !== DECK_OWNER.host) return true;
+ if (!Number.isInteger(owner.pid) || owner.pid <= 0) return false;
+ try {
+ process.kill(owner.pid, 0);
+ return true;
+ } catch (error) {
+ // ESRCH: the process is gone. EPERM: it is there, under another user.
+ return error?.code === "EPERM";
+ }
+}
+
+function readDeckOwner(file) {
+ try {
+ return JSON.parse(readFileSync(file, "utf8"))?.owner ?? null;
+ } catch {
+ return null;
+ }
+}
+
+// Replace one deck's file atomically. The temp name carries this process's
+// pid, so two processes writing this directory can never rename over each
+// other's half-written file. Pass owner as null to publish a deck this
+// process is no longer holding open.
+function writeDeckSync(instanceId, deck, owner = DECK_OWNER) {
+ const target = deckFile(instanceId);
+ const tmp = `${target}.${process.pid}.tmp`;
+ try {
+ mkdirSync(DECKS_DIR, { recursive: true, mode: 0o700 });
+ writeFileSync(
+ tmp,
+ JSON.stringify({
+ version: STATE_VERSION,
+ instanceId,
+ owner: owner ?? null,
+ sessionId: deck.sessionId ?? null,
+ cards: deck.cards ?? [],
+ submissions: deck.submissions ?? [],
+ updatedAt: deck.updatedAt ?? new Date().toISOString(),
+ }),
+ { mode: 0o600 },
+ );
+ renameSync(tmp, target);
+ } catch {
+ // Persistence is best effort; the live deck is unaffected.
+ try {
+ rmSync(tmp, { force: true });
+ } catch {}
+ }
+}
+
+function removeDeckSync(instanceId) {
+ try {
+ rmSync(deckFile(instanceId), { force: true });
+ } catch {}
+}
+
+function loadPersistedDecks() {
+ const decks = {};
+ let names;
+ try {
+ names = readdirSync(DECKS_DIR);
+ } catch {
+ return decks; // Nothing persisted yet.
+ }
+ for (const name of names) {
+ if (!name.endsWith(".json")) continue;
+ try {
+ const parsed = JSON.parse(readFileSync(path.join(DECKS_DIR, name), "utf8"));
+ if (parsed?.version !== STATE_VERSION || typeof parsed.instanceId !== "string") continue;
+ // A deck another running process has open belongs to that process:
+ // recalling it here would put the same cards in two canvases and have
+ // both flush copies of it.
+ if (ownerIsRunning(parsed.owner)) continue;
+ decks[parsed.instanceId] = {
+ sessionId: parsed.sessionId ?? null,
+ cards: Array.isArray(parsed.cards) ? parsed.cards : [],
+ submissions: Array.isArray(parsed.submissions) ? parsed.submissions : [],
+ updatedAt: parsed.updatedAt,
+ };
+ } catch {
+ // One unreadable file must not cost the user the other decks.
+ }
+ }
+ return decks;
+}
+
+// Carry decks written by the single-document layout over to per-deck files,
+// then drop that file so this runs at most once. They arrive unowned: no
+// process is holding any of them open yet.
+function migrateLegacyState() {
+ let parsed;
+ try {
+ parsed = JSON.parse(readFileSync(LEGACY_STATE_FILE, "utf8"));
+ } catch {
+ return; // Nothing left from the old layout.
+ }
+ if (parsed?.version === STATE_VERSION && parsed.instances && typeof parsed.instances === "object") {
+ for (const [instanceId, deck] of Object.entries(parsed.instances)) {
+ if (deck && typeof deck === "object") writeDeckSync(instanceId, deck, null);
+ }
+ }
+ try {
+ rmSync(LEGACY_STATE_FILE, { force: true });
+ } catch {}
+}
+
+migrateLegacyState();
+
+// instanceId -> { sessionId, cards, submissions, updatedAt } from earlier
+// runs or an exited process, not yet claimed by an in-memory instance this
+// run.
+const persistedDecks = loadPersistedDecks();
+
+let persistTimer = null;
+
+function schedulePersist() {
+ if (persistTimer) return;
+ persistTimer = setTimeout(() => {
+ persistTimer = null;
+ flushStateSync();
+ }, PERSIST_DEBOUNCE_MS);
+ // The debounce must never be what keeps this process alive.
+ persistTimer.unref();
+}
+
+// Synchronous so the process "exit" event and the shutdown path can use it.
+// Only the decks this process owns are written: a deck belonging to another
+// process, or to an earlier run, stays on disk exactly as its owner left it.
+function flushStateSync(owner = DECK_OWNER) {
+ if (persistTimer) {
+ clearTimeout(persistTimer);
+ persistTimer = null;
+ }
+ const owned = new Set();
+ for (const [instanceId, instance] of instances) {
+ writeDeckSync(
+ instanceId,
+ {
+ sessionId: instance.sessionId ?? null,
+ cards: instance.cards,
+ submissions: instance.submissions,
+ updatedAt: instance.updatedAt ?? new Date().toISOString(),
+ },
+ owner,
+ );
+ owned.add(path.basename(deckFile(instanceId)));
+ }
+ pruneDeckFiles(owned);
+}
+
+// The last write of a run: the same state with no owner stamp, so the next
+// run can recall these decks and prune them normally.
+function releaseDecksSync() {
+ flushStateSync(null);
+}
+
+// Hold the directory to MAX_PERSISTED_DECKS, newest first. Files are ranked
+// by mtime rather than by the updatedAt inside them: a deck's file is
+// rewritten whenever it changes, so mtime gives the same order without
+// reading every file, and it stays right for decks other processes own.
+function pruneDeckFiles(owned) {
+ let names;
+ try {
+ names = readdirSync(DECKS_DIR).filter((name) => name.endsWith(".json"));
+ } catch {
+ return;
+ }
+ if (names.length <= MAX_PERSISTED_DECKS) return;
+ const ranked = names
+ .map((name) => {
+ let mtimeMs = 0;
+ try {
+ mtimeMs = statSync(path.join(DECKS_DIR, name)).mtimeMs;
+ } catch {}
+ return { name, mtimeMs };
+ })
+ .sort((a, b) => b.mtimeMs - a.mtimeMs);
+ for (const { name } of ranked.slice(MAX_PERSISTED_DECKS)) {
+ // A deck someone still has open outranks the cap: dropping its file
+ // would lose cards a canvas is still showing. The set covers this
+ // process, the owner stamp covers every other one, so only a deck no
+ // running process claims is deleted here.
+ if (owned.has(name)) continue;
+ const file = path.join(DECKS_DIR, name);
+ if (ownerIsRunning(readDeckOwner(file))) continue;
+ try {
+ rmSync(file, { force: true });
+ } catch {}
+ }
+}
+
+function markDirty(instance) {
+ instance.updatedAt = new Date().toISOString();
+ schedulePersist();
+}
+
+// Recall a persisted deck for a canvas instance: an exact instance match
+// first, else the newest deck from the same session. The host may mint a new
+// canvas instance id after a restart while the conversation (and so the deck
+// the user expects to see again) is the same.
+function takePersistedDeck(instanceId, sessionId) {
+ let key = Object.prototype.hasOwnProperty.call(persistedDecks, instanceId) ? instanceId : null;
+ if (!key && sessionId) {
+ let newest = -1;
+ for (const [candidate, deck] of Object.entries(persistedDecks)) {
+ if (deck?.sessionId !== sessionId || instances.has(candidate)) continue;
+ const at = Date.parse(deck.updatedAt ?? "") || 0;
+ if (at > newest) {
+ newest = at;
+ key = candidate;
+ }
+ }
+ }
+ if (!key) return null;
+ const deck = persistedDecks[key];
+ delete persistedDecks[key];
+ // A deck recalled under a different canvas instance id is written back
+ // out under that id, so drop the file it came from: leaving it would let
+ // the same deck be recalled a second time.
+ if (key !== instanceId) removeDeckSync(key);
+ return deck;
+}
+
+function getInstance(instanceId, sessionId) {
+ let instance = instances.get(instanceId);
+ if (!instance) {
+ const restored = takePersistedDeck(instanceId, sessionId);
+ instance = {
+ token: crypto.randomBytes(16).toString("hex"),
+ sessionId: sessionId ?? restored?.sessionId ?? null,
+ cards: Array.isArray(restored?.cards) ? restored.cards : [],
+ submissions: Array.isArray(restored?.submissions) ? restored.submissions : [],
+ updatedAt: restored?.updatedAt,
+ };
+ instances.set(instanceId, instance);
+ if (restored) schedulePersist();
+ } else if (sessionId && !instance.sessionId) {
+ instance.sessionId = sessionId;
+ }
+ return instance;
+}
+
+function validateToken(instanceId, token) {
+ const instance = instances.get(instanceId);
+ return Boolean(instance && token && instance.token === token);
+}
+
+function broadcast(instanceId, event, data) {
+ const clients = sseClients.get(instanceId);
+ if (!clients) return;
+ const message = `event: ${event}\ndata: ${JSON.stringify(data)}\n\n`;
+ for (const res of clients) {
+ try {
+ res.write(message);
+ } catch {
+ clients.delete(res);
+ }
+ }
+}
+
+// Hand a prompt to the agent. Returns whether the handoff was accepted, so
+// the form card can fall back to its copyable prompt when it was not.
+async function sendPrompt(prompt) {
+ if (!session) return false;
+ try {
+ await Promise.resolve(session.send({ prompt }));
+ return true;
+ } catch {
+ return false;
+ }
+}
+
+function findCardIndex(instance, cardId) {
+ return instance.cards.findIndex((card) => card.id === cardId);
+}
+
+function cardListing(instance) {
+ return instance.cards.map((card) => ({ cardId: card.id, kind: card.kind, title: card.title }));
+}
+
+// Create a card of the given kind, append it to the deck (trimming the
+// oldest cards past the limit), and notify the canvas.
+function createCardAction(ctx, kind) {
+ const instance = getInstance(ctx.instanceId, ctx.sessionId);
+ const card = buildCard(kind, ctx.input ?? {});
+ instance.cards.push(card);
+ let note = "";
+ while (instance.cards.length > MAX_CARDS) {
+ const dropped = instance.cards.shift();
+ broadcast(ctx.instanceId, "remove", { cardId: dropped.id });
+ note = ` The deck was at its ${MAX_CARDS}-card limit, so the oldest card ("${dropped.title}") was removed.`;
+ }
+ markDirty(instance);
+ broadcast(ctx.instanceId, "upsert", { card });
+ return {
+ ok: true,
+ cardId: card.id,
+ kind: card.kind,
+ title: card.title,
+ summary:
+ card.summary +
+ note +
+ " The card is visible in the canvas; also state its key takeaway in the conversation for surfaces without the canvas.",
+ };
+}
+
+function actionError(error) {
+ return { error: error instanceof Error ? error.message : String(error) };
+}
+
+// ---------------------------------------------------------------------------
+// Shared schema fragments
+// ---------------------------------------------------------------------------
+
+const TUTOR_TERMS_SCHEMA = {
+ type: "array",
+ description:
+ "Educational terms to mark in the card. Hovering a marked term for a moment shows its tip as a tooltip.",
+ items: {
+ type: "object",
+ properties: {
+ term: { type: "string", description: "Exact term as it appears in the card text" },
+ tip: { type: "string", description: "Short plain-text definition shown on hover" },
+ },
+ required: ["term"],
+ },
+};
+
+const CONTEXT_ACTIONS_SCHEMA = {
+ type: "array",
+ description:
+ "Right-click actions for the card. Choosing one sends its prompt to the conversation; {{selection}} in a prompt is replaced with the user's selected text.",
+ items: {
+ type: "object",
+ properties: {
+ label: { type: "string", description: "Menu item label" },
+ prompt: { type: "string", description: "Prompt sent to the conversation when chosen" },
+ },
+ required: ["label", "prompt"],
+ },
+};
+
+const COMMON_CARD_PROPERTIES = {
+ title: { type: "string", description: "Card title (plain text; the extension escapes it)" },
+ subtitle: { type: "string", description: "Optional subtitle under the title" },
+ tutorTerms: TUTOR_TERMS_SCHEMA,
+ contextActions: CONTEXT_ACTIONS_SCHEMA,
+};
+
+const TAB_CARD_PROPERTIES = {
+ ...COMMON_CARD_PROPERTIES,
+ tabs: {
+ type: "array",
+ minItems: 1,
+ description:
+ "One entry per tab. Give each tab exactly one of markdown, code, html, or text (non-empty).",
+ items: {
+ type: "object",
+ properties: {
+ label: { type: "string", description: "Tab label" },
+ markdown: { type: "string", description: "Markdown content for the tab" },
+ content: { type: "string", description: "Alias of markdown" },
+ text: { type: "string", description: "Plain text content for the tab" },
+ code: { type: "string", description: "Code sample shown with a copy button" },
+ language: { type: "string", description: "Language for the code sample" },
+ html: { type: "string", description: "HTML content (sanitized to an allowlisted subset)" },
+ },
+ required: ["label"],
+ },
+ },
+ tutorTermsInCode: {
+ type: "boolean",
+ description: "Also mark tutor terms inside code samples (off by default)",
+ },
+};
+
+const TABLE_CARD_PROPERTIES = {
+ ...COMMON_CARD_PROPERTIES,
+ caption: { type: "string" },
+ headers: {
+ type: "array",
+ items: { type: "string" },
+ description: "Column titles; padded if fewer than columns",
+ },
+ rows: {
+ type: "array",
+ items: { type: "array", items: { type: "string" } },
+ description: "Explicit cell data, row-major",
+ },
+ text: { type: "string", description: "Raw text to convert when rows are not given (delimiter auto-detected)" },
+ columns: { type: "integer", minimum: 1, maximum: 12 },
+ cellDelimiter: { type: "string" },
+ linkColumns: {
+ type: "array",
+ items: { type: "integer", minimum: 0 },
+ description: "Zero-based column indexes whose cell values render as links",
+ },
+ autoLinkUrls: { type: "boolean", description: "Render URL-shaped cells as links (default true)" },
+};
+
+const CHART_CARD_PROPERTIES = {
+ ...COMMON_CARD_PROPERTIES,
+ type: { type: "string", enum: ["bar", "line", "pie", "donut"] },
+ labels: { type: "array", items: { type: "string" }, description: "X-axis labels (bar/line)" },
+ series: {
+ type: "array",
+ description: "Data series (bar/line); values must be 0 or greater",
+ items: {
+ type: "object",
+ properties: {
+ name: { type: "string" },
+ values: { type: "array", items: { type: "number", minimum: 0 } },
+ },
+ required: ["name", "values"],
+ },
+ },
+ values: {
+ type: "array",
+ description: "Slices (pie/donut)",
+ items: {
+ type: "object",
+ properties: {
+ label: { type: "string" },
+ value: { type: "number", minimum: 0 },
+ },
+ required: ["label", "value"],
+ },
+ },
+ yLabel: { type: "string" },
+ description: { type: "string" },
+};
+
+const FORM_CARD_PROPERTIES = {
+ ...COMMON_CARD_PROPERTIES,
+ description: { type: "string", description: "Help text shown above the fields" },
+ submitLabel: { type: "string" },
+ promptTemplate: {
+ type: "string",
+ description: "Prompt sent on submit; {{fieldName}} tokens are replaced with values",
+ },
+ fields: {
+ type: "array",
+ minItems: 1,
+ items: {
+ type: "object",
+ properties: {
+ name: { type: "string" },
+ label: { type: "string" },
+ type: {
+ type: "string",
+ enum: ["text", "textarea", "select", "checkbox", "radio", "number", "email", "url", "date", "hidden"],
+ },
+ options: {
+ type: "array",
+ description: "Choices for select/checkbox/radio; strings or { label, value } objects",
+ items: {},
+ },
+ required: { type: "boolean" },
+ placeholder: { type: "string" },
+ value: { type: "string" },
+ help: { type: "string" },
+ },
+ required: ["name"],
+ },
+ },
+};
+
+const REVEAL_CARD_PROPERTIES = {
+ ...COMMON_CARD_PROPERTIES,
+ sections: {
+ type: "array",
+ minItems: 1,
+ description:
+ "Collapsible sections. Give each section markdown, html, or text content (non-empty).",
+ items: {
+ type: "object",
+ properties: {
+ heading: { type: "string" },
+ markdown: { type: "string" },
+ content: { type: "string", description: "Alias of markdown" },
+ text: { type: "string" },
+ html: { type: "string", description: "HTML content (sanitized to an allowlisted subset)" },
+ open: { type: "boolean", description: "Start the section expanded" },
+ },
+ required: ["heading"],
+ },
+ },
+};
+
+const LIST_CARD_PROPERTIES = {
+ ...COMMON_CARD_PROPERTIES,
+ intro: { type: "string", description: "Optional plain-text intro shown above the outline" },
+ items: {
+ type: "array",
+ minItems: 1,
+ description: "Outline items; nest with children arrays of the same { text, children } shape",
+ items: {
+ type: "object",
+ properties: {
+ text: { type: "string" },
+ children: { type: "array", items: { type: "object" }, description: "Nested items of the same shape" },
+ },
+ required: ["text"],
+ },
+ },
+};
+
+const MARKDOWN_CARD_PROPERTIES = {
+ ...COMMON_CARD_PROPERTIES,
+ title: { type: "string", description: "Card title; defaults to the document's first H1" },
+ markdown: { type: "string", description: "The markdown document to render" },
+ splitSections: {
+ type: "boolean",
+ description: "Fold H2 sections into collapsible reveals (default true)",
+ },
+ openFirst: { type: "boolean", description: "With folding, open the first section initially (default true)" },
+};
+
+const VIDEO_CARD_PROPERTIES = {
+ ...COMMON_CARD_PROPERTIES,
+ src: {
+ type: "string",
+ description:
+ "Direct video file URL (mp4/webm), data:video/* URI, or blob: URL. Not a streaming platform page URL.",
+ },
+ poster: { type: "string", description: "Optional poster image URL" },
+ description: { type: "string", description: "Help text shown above the player" },
+};
+
+const KIND_SCHEMAS = {
+ tabs: TAB_CARD_PROPERTIES,
+ table: TABLE_CARD_PROPERTIES,
+ chart: CHART_CARD_PROPERTIES,
+ form: FORM_CARD_PROPERTIES,
+ "show-hide": REVEAL_CARD_PROPERTIES,
+ list: LIST_CARD_PROPERTIES,
+ document: MARKDOWN_CARD_PROPERTIES,
+ video: VIDEO_CARD_PROPERTIES,
+};
+
+// Required fields per kind, mirroring the matching create action. update_card
+// derives its discriminated per-kind schema from these plus KIND_SCHEMAS.
+const KIND_REQUIRED_FIELDS = {
+ tabs: ["title", "tabs"],
+ table: ["title"],
+ chart: ["title", "type"],
+ form: ["title", "fields"],
+ "show-hide": ["title", "sections"],
+ list: ["title", "items"],
+ document: ["markdown"],
+ video: ["title", "src"],
+};
+
+function cardActionSchema(properties, required) {
+ return { type: "object", properties, required };
+}
+
+function makeCreateAction(name, kind, description, properties, required) {
+ return {
+ name,
+ description,
+ inputSchema: cardActionSchema(properties, required),
+ handler: (ctx) => {
+ try {
+ return createCardAction(ctx, kind);
+ } catch (error) {
+ return actionError(error);
+ }
+ },
+ };
+}
+
+// ---------------------------------------------------------------------------
+// Canvas
+// ---------------------------------------------------------------------------
+
+const canvas = createCanvas({
+ id: "chat-cards",
+ displayName: "Chat Cards",
+ description:
+ "Interactive card deck for explaining things visually: tab cards, tables, SVG charts, forms whose " +
+ "submissions come back to the conversation as prompts, show/hide sections, numbered outlines, " +
+ "rendered markdown documents, and short video clips. " +
+ "Use it for research, education, professional and hobbyist skills, history, and news topics " +
+ "whenever a card communicates better than text. Cards render only in the canvas, so also state " +
+ "each card's key conclusion in the conversation.",
+ inputSchema: {
+ type: "object",
+ properties: {
+ title: { type: "string", description: "Optional canvas title" },
+ },
+ },
+ actions: [
+ makeCreateAction(
+ "create_tab_card",
+ "tabs",
+ "Render an interactive card with tabs, each showing a different context of the same subject " +
+ "(for example one tab per programming language, OS, or skill level). Tab content can be " +
+ "markdown, plain text, HTML, or code with a copy button.",
+ TAB_CARD_PROPERTIES,
+ ["title", "tabs"],
+ ),
+ makeCreateAction(
+ "create_table_card",
+ "table",
+ "Render an HTML table card from explicit rows, or convert loosely delimited text into a " +
+ "balanced table (delimiter auto-detected; newlines can mark cells). URL cells become links.",
+ TABLE_CARD_PROPERTIES,
+ ["title"],
+ ),
+ makeCreateAction(
+ "create_chart_card",
+ "chart",
+ "Render a dynamically generated SVG chart card (bar, line, pie, or donut) with a legend and " +
+ "a collapsible data table. Use for useful graphics summarizing referenced data.",
+ CHART_CARD_PROPERTIES,
+ ["title", "type"],
+ ),
+ makeCreateAction(
+ "create_form_card",
+ "form",
+ "Render a form card the user fills in to give the conversation context and direction. " +
+ "Submitting sends the values back to the conversation as the next prompt (optionally shaped " +
+ "by promptTemplate with {{fieldName}} tokens). Check get_form_responses if no prompt arrives.",
+ FORM_CARD_PROPERTIES,
+ ["title", "fields"],
+ ),
+ makeCreateAction(
+ "create_reveal_card",
+ "show-hide",
+ "Render a card of collapsible show/hide sections with show-all/hide-all controls. Good for " +
+ "FAQs, step-by-step detail, and progressive disclosure.",
+ REVEAL_CARD_PROPERTIES,
+ ["title", "sections"],
+ ),
+ makeCreateAction(
+ "create_list_card",
+ "list",
+ "Render a nested sequential outline card numbered 1., 1.1., 1.1.1. for plans, procedures, " +
+ "and structured overviews.",
+ LIST_CARD_PROPERTIES,
+ ["title", "items"],
+ ),
+ makeCreateAction(
+ "create_markdown_card",
+ "document",
+ "Render a markdown document (a guide or walkthrough you wrote) as one interactive card: the " +
+ "first H1 becomes the title, H2 sections fold into show/hide reveals, tables get card " +
+ "styling, and fenced code gets copy buttons. Pass the markdown content inline.",
+ MARKDOWN_CARD_PROPERTIES,
+ ["markdown"],
+ ),
+ makeCreateAction(
+ "create_video_card",
+ "video",
+ "Render a card with an HTML video player for a short clip. src must point straight at a " +
+ "video file (mp4/webm), not a streaming platform page: a direct http(s) URL, a small " +
+ "data:video/* URI, or a blob: URL.",
+ VIDEO_CARD_PROPERTIES,
+ ["title", "src"],
+ ),
+ {
+ name: "update_card",
+ description:
+ "Re-render an existing card in place, keeping its position in the deck. Pass the cardId, " +
+ "the card's kind, and the full replacement spec in the same shape the matching create " +
+ "action takes.",
+ inputSchema: {
+ type: "object",
+ description:
+ "Discriminated by kind: each branch takes cardId, kind, and the full replacement " +
+ "fields (with the same required fields) of the matching create action.",
+ oneOf: Object.entries(KIND_SCHEMAS).map(([kind, properties]) => ({
+ type: "object",
+ properties: {
+ cardId: { type: "string", description: "The id returned when the card was created" },
+ kind: { type: "string", enum: [kind] },
+ ...properties,
+ },
+ required: ["cardId", "kind", ...KIND_REQUIRED_FIELDS[kind]],
+ additionalProperties: true,
+ })),
+ },
+ handler: (ctx) => {
+ try {
+ const instance = getInstance(ctx.instanceId, ctx.sessionId);
+ const { cardId, kind, ...spec } = ctx.input ?? {};
+ const index = findCardIndex(instance, cardId);
+ if (index === -1) return { error: `No card with id "${cardId}". Use list_cards to see the deck.` };
+ const card = buildCard(kind, spec);
+ // Keep the original id so the canvas replaces the card in place.
+ card.articleHtml = card.articleHtml.replace(`data-card-id="${card.id}"`, `data-card-id="${cardId}"`);
+ card.config.id = cardId;
+ card.id = cardId;
+ instance.cards[index] = card;
+ markDirty(instance);
+ broadcast(ctx.instanceId, "upsert", { card });
+ return { ok: true, cardId, kind: card.kind, title: card.title, summary: `Updated card in place. ${card.summary}` };
+ } catch (error) {
+ return actionError(error);
+ }
+ },
+ },
+ {
+ name: "remove_card",
+ description: "Remove one card from the deck by id.",
+ inputSchema: {
+ type: "object",
+ properties: { cardId: { type: "string" } },
+ required: ["cardId"],
+ },
+ handler: (ctx) => {
+ const instance = getInstance(ctx.instanceId, ctx.sessionId);
+ const index = findCardIndex(instance, ctx.input?.cardId);
+ if (index === -1) return { error: `No card with id "${ctx.input?.cardId}".` };
+ const [removed] = instance.cards.splice(index, 1);
+ markDirty(instance);
+ broadcast(ctx.instanceId, "remove", { cardId: removed.id });
+ return { ok: true, removed: { cardId: removed.id, kind: removed.kind, title: removed.title } };
+ },
+ },
+ {
+ name: "clear_cards",
+ description: "Remove every card from the deck.",
+ inputSchema: { type: "object", properties: {}, additionalProperties: false },
+ handler: (ctx) => {
+ const instance = getInstance(ctx.instanceId, ctx.sessionId);
+ const count = instance.cards.length;
+ instance.cards = [];
+ markDirty(instance);
+ broadcast(ctx.instanceId, "clear", {});
+ return { ok: true, removedCount: count };
+ },
+ },
+ {
+ name: "list_cards",
+ description:
+ "List the cards currently in the deck (id, kind, title) in display order. The user may " +
+ "have reordered or removed cards since they were created.",
+ inputSchema: { type: "object", properties: {}, additionalProperties: false },
+ handler: (ctx) => {
+ const instance = getInstance(ctx.instanceId, ctx.sessionId);
+ return { ok: true, count: instance.cards.length, cards: cardListing(instance) };
+ },
+ },
+ {
+ name: "get_form_responses",
+ description:
+ "Read form submissions received from the canvas, newest first. Submissions normally arrive " +
+ "as conversation prompts too; use this when one did not come through or to review earlier " +
+ "answers.",
+ inputSchema: {
+ type: "object",
+ properties: {
+ cardId: { type: "string", description: "Only submissions from this form card" },
+ },
+ },
+ handler: (ctx) => {
+ const instance = getInstance(ctx.instanceId, ctx.sessionId);
+ const wanted = ctx.input?.cardId;
+ const responses = instance.submissions
+ .filter((submission) => !wanted || submission.cardId === wanted)
+ .slice()
+ .reverse();
+ return { ok: true, count: responses.length, responses };
+ },
+ },
+ ],
+ open: async (ctx) => {
+ const instance = getInstance(ctx.instanceId, ctx.sessionId);
+ const { port } = await startCanvasServer(ctx.instanceId);
+ return {
+ url: `http://127.0.0.1:${port}/?instance=${encodeURIComponent(ctx.instanceId)}&token=${instance.token}`,
+ title: ctx.input?.title || "Chat Cards",
+ status: instance.cards.length > 0 ? `${instance.cards.length} card(s)` : "Ready",
+ };
+ },
+ onClose: (ctx) => {
+ // Closing the panel (by the user, the agent, or the host on its way
+ // down) must not discard the deck; the canvas can be reopened and the
+ // cards are expected to still be there. Only the live SSE connections
+ // and this panel's page server go; the deck stays in memory and is
+ // flushed to disk.
+ const clients = sseClients.get(ctx.instanceId);
+ if (clients) {
+ for (const res of clients) {
+ try {
+ res.end();
+ } catch {}
+ }
+ sseClients.delete(ctx.instanceId);
+ }
+ stopCanvasServer(ctx.instanceId);
+ if (instances.has(ctx.instanceId)) flushStateSync();
+ },
+});
+
+// ---------------------------------------------------------------------------
+// Local HTTP server behind the canvas page
+// ---------------------------------------------------------------------------
+
+function json(res, code, data) {
+ res.writeHead(code, { "Content-Type": "application/json; charset=utf-8" });
+ res.end(JSON.stringify(data));
+}
+
+function readJsonBody(req) {
+ return new Promise((resolve, reject) => {
+ const chunks = [];
+ let received = 0;
+ req.on("data", (chunk) => {
+ received += chunk.length;
+ if (received > MAX_BODY_BYTES) {
+ req.destroy();
+ reject(new Error("Request body too large."));
+ return;
+ }
+ chunks.push(chunk);
+ });
+ req.on("end", () => {
+ const body = Buffer.concat(chunks).toString("utf8");
+ if (!body.trim()) {
+ resolve({});
+ return;
+ }
+ try {
+ resolve(JSON.parse(body));
+ } catch {
+ reject(new Error("Request body must be valid JSON."));
+ }
+ });
+ req.on("error", reject);
+ });
+}
+
+// A panel's server answers for exactly one canvas instance: the id is
+// bound when the server is created rather than taken from the request.
+// Ports are recycled as panels close and reopen, so a page orphaned by an
+// earlier panel can reach a later panel's server; its token is still in
+// memory and would otherwise let it go on reading and changing its old
+// deck through a port that now belongs to someone else.
+async function handleCanvasRequest(req, res, servedInstanceId) {
+ let url;
+ try {
+ url = new URL(req.url, `http://${req.headers.host ?? "127.0.0.1"}`);
+ } catch {
+ res.writeHead(400);
+ res.end("Bad request");
+ return;
+ }
+ const instanceId = url.searchParams.get("instance");
+ const token = url.searchParams.get("token");
+ if (instanceId !== servedInstanceId || !validateToken(instanceId, token)) {
+ res.writeHead(403);
+ res.end("Forbidden");
+ return;
+ }
+ const instance = getInstance(instanceId);
+
+ try {
+ if (req.method === "GET" && url.pathname === "/") {
+ res.writeHead(200, {
+ "Content-Type": "text/html; charset=utf-8",
+ "Referrer-Policy": "no-referrer",
+ });
+ res.end(CANVAS_PAGE);
+ return;
+ }
+
+ if (req.method === "GET" && url.pathname === "/events") {
+ res.writeHead(200, {
+ "Content-Type": "text/event-stream",
+ "Cache-Control": "no-cache",
+ Connection: "keep-alive",
+ });
+ if (!sseClients.has(instanceId)) sseClients.set(instanceId, new Set());
+ sseClients.get(instanceId).add(res);
+ req.on("close", () => {
+ const clients = sseClients.get(instanceId);
+ if (clients) clients.delete(res);
+ });
+ res.write(`event: init\ndata: ${JSON.stringify({ cards: instance.cards })}\n\n`);
+ return;
+ }
+
+ if (req.method === "GET" && url.pathname === "/api/state") {
+ json(res, 200, { cards: instance.cards });
+ return;
+ }
+
+ if (req.method === "POST" && url.pathname === "/api/submit") {
+ const body = await readJsonBody(req);
+ const prompt = String(body.prompt ?? "").slice(0, MAX_PROMPT_CHARS);
+ if (!prompt.trim()) {
+ json(res, 400, { error: "A non-empty prompt is required." });
+ return;
+ }
+ const cardId = typeof body.cardId === "string" ? body.cardId : null;
+ const cardIndex = cardId ? findCardIndex(instance, cardId) : -1;
+ const values = body.values && typeof body.values === "object" && !Array.isArray(body.values) ? body.values : {};
+ const delivered = await sendPrompt(prompt);
+ instance.submissions.push({
+ id: crypto.randomBytes(6).toString("hex"),
+ cardId,
+ cardTitle: cardIndex === -1 ? null : instance.cards[cardIndex].title,
+ values,
+ prompt,
+ delivered,
+ receivedAt: new Date().toISOString(),
+ });
+ while (instance.submissions.length > MAX_SUBMISSIONS) instance.submissions.shift();
+ markDirty(instance);
+ json(res, 200, { ok: true, delivered });
+ return;
+ }
+
+ if (req.method === "POST" && url.pathname === "/api/prompt") {
+ const body = await readJsonBody(req);
+ const prompt = String(body.prompt ?? "").slice(0, MAX_PROMPT_CHARS);
+ if (!prompt.trim()) {
+ json(res, 400, { error: "A non-empty prompt is required." });
+ return;
+ }
+ const delivered = await sendPrompt(prompt);
+ json(res, 200, { ok: true, delivered });
+ return;
+ }
+
+ if (req.method === "POST" && url.pathname === "/api/remove") {
+ const body = await readJsonBody(req);
+ const index = findCardIndex(instance, String(body.cardId ?? ""));
+ if (index !== -1) {
+ const [removed] = instance.cards.splice(index, 1);
+ markDirty(instance);
+ broadcast(instanceId, "remove", { cardId: removed.id });
+ }
+ json(res, 200, { ok: true });
+ return;
+ }
+
+ if (req.method === "POST" && url.pathname === "/api/reorder") {
+ const body = await readJsonBody(req);
+ const order = Array.isArray(body.order) ? body.order.map(String) : [];
+ const byId = new Map(instance.cards.map((card) => [card.id, card]));
+ const reordered = [];
+ for (const cardId of order) {
+ const card = byId.get(cardId);
+ if (card) {
+ reordered.push(card);
+ byId.delete(cardId);
+ }
+ }
+ // Cards missing from the requested order (for example one created while
+ // the drag was in flight) keep their relative position at the end.
+ for (const card of instance.cards) {
+ if (byId.has(card.id)) reordered.push(card);
+ }
+ instance.cards = reordered;
+ markDirty(instance);
+ broadcast(instanceId, "reorder", { order: instance.cards.map((card) => card.id) });
+ json(res, 200, { ok: true });
+ return;
+ }
+
+ res.writeHead(404);
+ res.end("Not found");
+ } catch (error) {
+ json(res, 400, { error: error instanceof Error ? error.message : "Bad request" });
+ }
+}
+
+// ---------------------------------------------------------------------------
+// Per-panel page servers
+// ---------------------------------------------------------------------------
+// A server exists only while its canvas panel is open: open() starts it and
+// onClose() stops it. While no panel is showing, this process holds no
+// sockets at all; it is just an RPC child of the host serving actions.
+//
+// Servers bind OUTSIDE the OS dynamic port range (49152+). The Copilot app's
+// own single-instance WebSocket takes an ephemeral port from that range, and
+// a canvas page orphaned by a stopped extension process keeps retrying its
+// old origin for a while; binding down here guarantees those retries can
+// only ever land on a port this extension family owns, never on a recycled
+// port the app's reopen handshake depends on.
+
+const PORT_RANGE_START = 21750;
+const PORT_RANGE_SIZE = 40;
+
+// instanceId -> { server, sockets: Set, port }
+const canvasServers = new Map();
+
+function tryListen(server, target) {
+ return new Promise((resolve, reject) => {
+ const onError = (error) => {
+ server.off("listening", onListening);
+ reject(error);
+ };
+ const onListening = () => {
+ server.off("error", onError);
+ resolve();
+ };
+ server.once("error", onError);
+ server.once("listening", onListening);
+ server.listen(target, "127.0.0.1");
+ });
+}
+
+async function startCanvasServer(instanceId) {
+ const existing = canvasServers.get(instanceId);
+ if (existing) return existing;
+
+ const server = http.createServer((req, res) => handleCanvasRequest(req, res, instanceId));
+ const sockets = new Set();
+ // Connections are tracked for teardown and unref'd on arrival so an open
+ // keep-alive or SSE socket can never keep this process alive by itself.
+ server.on("connection", (socket) => {
+ socket.unref();
+ sockets.add(socket);
+ socket.on("close", () => sockets.delete(socket));
+ });
+
+ const entry = { server, sockets, port: 0 };
+ const offset = crypto.randomInt(PORT_RANGE_SIZE);
+ for (let i = 0; i < PORT_RANGE_SIZE && entry.port === 0; i++) {
+ const candidate = PORT_RANGE_START + ((offset + i) % PORT_RANGE_SIZE);
+ try {
+ await tryListen(server, candidate);
+ entry.port = candidate;
+ } catch {
+ // In use (another open panel or another session's process): next slot.
+ }
+ }
+ if (entry.port === 0) {
+ // Every slot taken: fall back to an ephemeral port rather than failing.
+ await tryListen(server, 0);
+ entry.port = server.address().port;
+ }
+ // The listener itself must never be what keeps this process alive.
+ server.unref();
+ canvasServers.set(instanceId, entry);
+ return entry;
+}
+
+function stopCanvasServer(instanceId) {
+ const entry = canvasServers.get(instanceId);
+ if (!entry) return;
+ canvasServers.delete(instanceId);
+ try {
+ entry.server.close();
+ } catch {}
+ for (const socket of entry.sockets) {
+ try {
+ socket.destroy();
+ } catch {}
+ }
+}
+
+// ---------------------------------------------------------------------------
+// Lifecycle: this process must never outlive the Copilot app
+// ---------------------------------------------------------------------------
+// The SDK talks to the host over stdio and only flips an internal
+// "disconnected" flag when that pipe closes; nothing ends the process on
+// its own. Two layers keep this process from outliving the app: every
+// end-of-life signal below leads to an explicit flush-and-exit, and nothing
+// this extension owns (page servers, their sockets, the persistence timer)
+// refs the event loop, so the host's stdio pipe is the only thing keeping
+// it alive at all.
+
+let shuttingDown = false;
+
+function shutdown() {
+ if (shuttingDown) return;
+ shuttingDown = true;
+ releaseDecksSync();
+ for (const clients of sseClients.values()) {
+ for (const res of clients) {
+ try {
+ res.end();
+ } catch {}
+ }
+ }
+ sseClients.clear();
+ for (const instanceId of [...canvasServers.keys()]) {
+ stopCanvasServer(instanceId);
+ }
+ // Deliberately kept referenced: exit is guaranteed even if a handle the
+ // SDK or a dependency owns refuses to close.
+ setTimeout(() => process.exit(0), 150);
+}
+
+// The stdio pipe to the host is the ground truth: when the app goes away,
+// stdin ends. Signals cover a graceful stop, "disconnect" an IPC parent.
+process.stdin.on("end", shutdown);
+process.stdin.on("close", shutdown);
+process.on("disconnect", shutdown);
+for (const signal of ["SIGTERM", "SIGINT", "SIGHUP", "SIGBREAK"]) {
+ try {
+ process.on(signal, shutdown);
+ } catch {}
+}
+// If the event loop drains naturally instead, still write the deck out.
+process.on("exit", releaseDecksSync);
+
+// Nothing refs the event loop until the session join wires up stdio, so
+// hold it open across the join, then hand that job to the stdio pipe.
+const bootKeepalive = setInterval(() => {}, 60000);
+session = await joinSession({ canvases: [canvas] });
+clearInterval(bootKeepalive);
+
+// The host also announces the end of the session as a first-class event.
+try {
+ session.on("session.shutdown", shutdown);
+} catch {
+ // An SDK build without this event type still exits via the stdio hooks.
+}
diff --git a/extensions/chat-cards/package.json b/extensions/chat-cards/package.json
new file mode 100644
index 0000000000..2d1eb8916d
--- /dev/null
+++ b/extensions/chat-cards/package.json
@@ -0,0 +1,19 @@
+{
+ "name": "chat-cards",
+ "version": "0.1.0",
+ "type": "module",
+ "main": "extension.mjs",
+ "description": "Interactive card deck in a GHCP canvas: tab cards, tables, SVG charts, show/hide sections, numbered outlines, rendered markdown documents, video clips, and forms whose submissions come back to the conversation as prompts.",
+ "dependencies": {
+ "@github/copilot-sdk": "latest"
+ },
+ "keywords": [
+ "interactive-cards",
+ "charts",
+ "forms",
+ "education",
+ "research",
+ "visual-explanations",
+ "canvas"
+ ]
+}
diff --git a/plugins/chat-cards/README.md b/plugins/chat-cards/README.md
new file mode 100644
index 0000000000..0945830e5e
--- /dev/null
+++ b/plugins/chat-cards/README.md
@@ -0,0 +1,22 @@
+# Chat Cards Plugin
+
+Interactive card deck for GitHub Copilot canvas. Instead of walls of text, the
+agent explains things visually with a live deck of interactive cards: tab boxes,
+tables, SVG charts, forms, collapsible sections, numbered outlines, rendered
+markdown documents, and short video clips. Forms are two-way: submitting one
+sends the values back to the conversation as the agent's next prompt, so a card
+can gather context and steer the session as easily as it presents information.
+
+## Installation
+
+```bash
+copilot plugin install chat-cards@awesome-copilot
+```
+
+## Source
+
+This plugin is part of [Awesome Copilot](https://github.com/github/awesome-copilot).
+
+## License
+
+MIT
diff --git a/plugins/chat-cards/plugin.json b/plugins/chat-cards/plugin.json
new file mode 100644
index 0000000000..69823debcb
--- /dev/null
+++ b/plugins/chat-cards/plugin.json
@@ -0,0 +1,26 @@
+{
+ "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+ "name": "chat-cards",
+ "description": "Interactive card deck in a GHCP canvas: tab cards, tables, SVG charts, show/hide sections, numbered outlines, rendered markdown documents, video clips, and forms whose submissions come back to the conversation as prompts.",
+ "version": "0.1.0",
+ "keywords": [
+ "interactive-cards",
+ "charts",
+ "forms",
+ "education",
+ "visual-explanations"
+ ],
+ "author": { "name": "John Haugabook" },
+ "repository": "https://github.com/github/awesome-copilot",
+ "license": "MIT",
+ "extensions": {
+ "com.github.copilot": {
+ "logo": "assets/preview.png"
+ },
+ "com.github.awesome-copilot": {
+ "extensions": [
+ "./extensions/chat-cards"
+ ]
+ }
+ }
+}