@livx.cc/bare-v3 0.1.0-alpha.53 → 0.1.0-alpha.57

package/README.md

@@ -17,7 +17,7 @@ The comparison UI needs the fixture server for example links. Model outputs repl
 
 Install the published alpha with `bun add @livx.cc/bare-v3@alpha`; use `bun pm pack` for an unpublished local build. Import CSS from `@livx.cc/bare-v3/css` or `/css/min`. Put `class="b3-root"` on html and set `data-b3-theme="dark"` explicitly for dark mode. Component references are exported under `/references/*.md`; start with `/references/start.md`. Place generic link defaults in `@layer bare.reset` so they do not override button/navigation colors. Unlayered consumer CSS overrides library layers: scope custom palette colors to each theme rather than applying light-only colors unconditionally to `:root`.
 
-`bun lab plan config.json` creates a seeded, capped development job plan. `bun lab prepare run.json` prepares one isolated workspace and manifest without invoking a model. The [visual playground](http://127.0.0.1:4313/fixtures/playground.html) demonstrates the current component contracts and shows the bare-v2 coverage audit. Composed apps include Signal (system performance), Elsewhere (local discovery/booking), Daylight (iOS/Android web studies), Relay, Gather setup and sign-in, Counter, Margin, Still, Fieldnotes, Interval, and the Forma project workspace. New components are an implemented subset, not full bare-v2 parity or a qualified release. Optional interactions are exported from `@livx.cc/bare-v3/ui`; call `mount(document)` once and use its returned cleanup on teardown. Genuinely hard interactive widgets ship separately as light-DOM custom elements — currently `@livx.cc/bare-v3/elements/image-viewer` (`<b3-image-viewer>`) and `/elements/date-picker` (`<b3-date-picker>`). Read `recipes/image-viewer.md` or `recipes/date-picker.md` for fallback markup and lifecycle. The plain/React/Vue demos in `fixtures/elements/` exercise the image viewer; run `bun scripts/verify-image-viewer.ts` through the authorized AgentX browser workflow to verify measured transforms.
+`bun lab plan config.json` creates a seeded, capped development job plan. `bun lab prepare run.json` prepares one isolated workspace and manifest without invoking a model. The [visual playground](http://127.0.0.1:4313/fixtures/playground.html) demonstrates the current component contracts and shows the bare-v2 coverage audit. Composed apps include Signal (system performance), Elsewhere (local discovery/booking), Daylight (iOS/Android web studies), Relay, Gather setup and sign-in, Counter, Margin, Still, Fieldnotes, Interval, and the Forma project workspace. New components are an implemented subset, not full bare-v2 parity or a qualified release. Optional interactions are exported from `@livx.cc/bare-v3/ui`; call `mount(document)` once and use its returned cleanup on teardown. Genuinely hard interactive widgets ship separately as light-DOM custom elements — currently `@livx.cc/bare-v3/elements/image-viewer` (`<b3-image-viewer>`) and `/elements/date-picker` (`<b3-date-picker>`), plus the `/elements/markdown-stream` module (`MarkdownStream`) for streaming LLM markdown into bare-v3 components. Read `recipes/image-viewer.md`, `recipes/date-picker.md` or `recipes/markdown-stream.md` for markup and lifecycle; `fixtures/elements/markdown-stream.html` demos the stream; `bun run chat` serves it as a live chat against a real model (needs `OPENROUTER_API_KEY` or `OPENAI_API_KEY`; offline it replays canned replies). The plain/React/Vue demos in `fixtures/elements/` exercise the image viewer; run `bun scripts/verify-image-viewer.ts` through the authorized AgentX browser workflow to verify measured transforms.
 
 Playground previews accept shareable app/width links, for example [Signal at 390px](http://127.0.0.1:4313/fixtures/playground.html?demo=metrics&width=390#demos). The controls keep these query parameters in sync; unknown values fall back to the authored defaults. This is an iframe layout preview, not mobile-device qualification.
 

package/dist/elements/markdown-stream.js

@@ -0,0 +1,374 @@
+// src/elements/markdown-stream.js
+var esc = (s) => String(s).replace(/[&<>"]/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;" })[c]);
+var parseAttrs = (s) => Object.fromEntries([...(s || "").matchAll(/(\w+)=(?:"([^"]*)"|(\S+))/g)].map((m) => [m[1], m[2] ?? m[3]]));
+var isNum = (s) => /^[-+$€£]?[\d,.]+%?$/.test(String(s).trim());
+var toneAttr = (tone) => tone ? ` data-b3-tone="${esc(tone)}"` : "";
+var directives = {
+  callout(t, ctx) {
+    const title = t.attrs.title ? `<strong>${esc(t.attrs.title)}</strong>` : "";
+    return `<div class="b3-alert"${toneAttr(t.attrs.tone)}><div>${title}${ctx.parse(t.tokens)}</div></div>`;
+  },
+  stats(t, ctx) {
+    const inline = ctx?.inline ?? esc;
+    const cards = t.body.split(`
+`).filter((l) => l.trim()).map((line) => {
+      const [label, value, note = ""] = line.replace(/^\s*\|/, "").replace(/\|\s*$/, "").split("|").map((s) => s.trim());
+      const tone = /^[↑+]/.test(note) ? "success" : /^[↓-]/.test(note) ? "danger" : "";
+      return `<div class="b3-stat b3-surface"><span class="b3-label">${inline(label)}</span><strong class="b3-stat-value">${value ? inline(value.replace(/^\*\*(.*)\*\*$/, "$1")) : "…"}</strong>${note ? `<span class="b3-badge"${toneAttr(tone)}>${inline(note)}</span>` : ""}</div>`;
+    });
+    return `<div class="b3-md-stats">${cards.join("")}</div>`;
+  }
+};
+var fences = {
+  chart(text) {
+    const rows = text.split(`
+`).map((l) => l.split(":")).filter((p) => p.length > 1 && !isNaN(parseFloat(p[1])));
+    const max = Math.max(...rows.map((r) => parseFloat(r[1])), 1);
+    return `<figure class="b3-md-bars b3-surface">${rows.map(([k, v]) => `<div class="b3-md-bar"><span>${esc(k.trim())}</span><i style="inline-size:${Math.max(parseFloat(v), 0) / max * 100}%"></i><b>${esc(v.trim())}</b></div>`).join("")}</figure>`;
+  }
+};
+directives.callout.doc = '`:::callout{tone=info|success|warning|danger title="Short title"}` newline, markdown body, newline `:::` — a highlighted note, tip, warning or recommendation.';
+directives.stats.doc = "`:::stats` newline, one card per line `Label | Value | note`, newline `:::` — headline numbers; a note starting with ↑ or + shows as good, ↓ or - as bad.";
+fences.chart.doc = "```chart fence, one bar per line `Label: number` (plain number, no units) — a horizontal bar chart for comparing a few values.";
+function promptGuide(options = {}) {
+  const all = { ...directives, ...options.directives, ...fences, ...options.fences };
+  const tones = Object.entries(options.tones ?? new MarkdownStreamOptions().tones).reduce((by, [word, tone]) => ((by[tone] ??= []).push(word), by), {});
+  return [
+    "Your replies are Markdown rendered live into UI components. Use GitHub-flavoured Markdown (headings, **bold**, lists, links, `inline code`, fenced code with a language, > quotes) plus:",
+    `- Tables: GFM pipe tables with a header row and a \`| --- |\` delimiter row. Never add a Status column the data does not already have. Only when a row really has one of these states (e.g. an invoice that is paid), write the plain word alone in the cell and it is shown as a coloured badge automatically (no images, emoji or badge URLs): ${Object.entries(tones).map(([tone, words]) => `${words.join(", ")} (${tone})`).join("; ")}. Numeric columns align right.`,
+    "- Task lists: `- [x] done` and `- [ ] to do`.",
+    ...Object.values(all).filter((render) => render?.doc).map((render) => `- ${render.doc}`),
+    "Use a component only when it makes the answer clearer; plain prose is fine. Put every block on its own lines with a blank line around it, always close ::: and ``` blocks, and never write raw HTML."
+  ].join(`
+`);
+}
+var codeBlock = (text, lang) => `<div class="b3-md-code"><header><span class="b3-muted">${esc(lang || "text")}</span><button type="button" class="b3-button" data-b3-emphasis="quiet" data-b3-md-copy>Copy</button></header><pre><code>${esc(text)}</code></pre></div>`;
+function settle(buf) {
+  let s = buf;
+  const lines = s.split(`
+`);
+  const tail = [];
+  while (lines.length && /^\s*\|/.test(lines.at(-1)))
+    tail.unshift(lines.pop());
+  const complete = buf.endsWith(`
+`) ? tail : tail.slice(0, -1);
+  let pendingTable = false;
+  if (tail.length && !complete.some((l) => /^\s*\|?\s*:?-{2,}/.test(l))) {
+    pendingTable = true;
+    s = lines.join(`
+`);
+  }
+  s = s.replace(/(^|\n) {0,3}(`{3}[^\n]*|~{3}[^\n]*|:{3}[^\n]*|`{1,2}|~{1,2}|:{1,2})$/, "$1");
+  if ((s.match(/^ {0,3}(`{3}|~{3})/gm) || []).length % 2)
+    return { src: s, pendingTable };
+  s = s.replace(/\[([^\]\n]*)\]?\([^)\n]*$/, "$1").replace(/\[([^\]\n]*)$/, "$1").replace(/(\*{1,3}|_{1,3}|~{1,2}|`)$/, "");
+  const fenceEnd = [...s.matchAll(/^ {0,3}(`{3}|~{3})[^\n]*\n?/gm)].at(-1);
+  const para = s.slice(Math.max(s.lastIndexOf(`
+
+`) + 1, fenceEnd ? fenceEnd.index + fenceEnd[0].length : 0));
+  let close = "";
+  for (const m of ["`", "~~"])
+    if (para.split(m).length % 2 === 0)
+      close = m + close;
+  close += openEmphasis(para);
+  return { src: close ? s.trimEnd() + close : s, pendingTable };
+}
+function openEmphasis(para) {
+  const bare = para.replace(/`[^`\n]*`?/g, "").replace(/\\[*_]/g, "").replace(/\]\([^)\n]*\)?|https?:\/\/\S*/g, "]");
+  const stack = [];
+  for (const { 0: run, index } of bare.matchAll(/\*+|_+/g)) {
+    const before = bare[index - 1] ?? " ", after = bare[index + run.length] ?? " ";
+    let n = run.length;
+    if (/\S/.test(before) && (run[0] === "*" || !/\w/.test(after))) {
+      while (n && stack.at(-1)?.[0] === run[0]) {
+        const top = stack.pop();
+        const k = Math.min(n, top.length);
+        n -= k;
+        if (top.length > k)
+          stack.push(top.slice(k));
+      }
+    }
+    const opens = /[\p{L}\p{N}]/u.test(after) || run.length > 1 && /\s/.test(before) && /^[^\s\w*_-]\S*$/.test(bare.slice(index + run.length));
+    if (n && opens && !(/\w/.test(before) && (run[0] === "_" || n === 1)))
+      stack.push(run.slice(0, n));
+  }
+  return stack.reverse().join("");
+}
+var ALERTS = { note: "info", info: "info", tip: "success", important: "info", warning: "warning", caution: "danger", danger: "danger" };
+var STYLE_ID = "b3-markdown-stream-style";
+var STYLE = `
+.b3-md-appear{animation:b3-md-in var(--b3-duration,.2s) ease-out;}
+@keyframes b3-md-in{from{opacity:0;transform:translateY(3px);}}
+.b3-md-caret{display:inline-block;inline-size:.5em;block-size:1em;vertical-align:-.15em;margin-inline-start:2px;background:currentColor;animation:b3-md-blink 1s steps(2) infinite;}
+@keyframes b3-md-blink{50%{opacity:0;}}
+.b3-md-code{border:1px solid var(--b3-color-border);border-radius:var(--b3-radius);overflow:hidden;}
+.b3-md-code>header{display:flex;justify-content:space-between;align-items:center;gap:.5rem;padding:.25rem .5rem .25rem .75rem;font-size:.8rem;background:var(--b3-color-surface);border-block-end:1px solid var(--b3-color-border);}
+.b3-md-code>pre{margin:0;padding:.75rem;overflow-x:auto;}
+.b3-md-bars{display:grid;gap:.4rem;margin-inline:0;padding:var(--b3-space,1rem);}
+.b3-md-bar{display:grid;grid-template-columns:minmax(0,7rem) 1fr 3rem;gap:.5rem;align-items:center;font-size:.9rem;}
+.b3-md-bar>span{overflow:hidden;text-overflow:ellipsis;white-space:nowrap;}
+.b3-md-bar>i{display:block;block-size:.7rem;border-radius:999px;background:var(--b3-color-accent);transition:inline-size var(--b3-duration,.2s);}
+.b3-md-bar>b{text-align:end;font-variant-numeric:tabular-nums;}
+.b3-md-stats{display:grid;gap:.75rem;grid-template-columns:repeat(auto-fit,minmax(min(10rem,100%),1fr));}
+.b3-md-tasks{list-style:none;padding-inline-start:0;}
+.b3-md-tasks input{margin-inline-end:.5rem;vertical-align:-.1em;}
+.b3-md-tasks>li>input+p{display:inline;}
+.b3-md-num{text-align:end;font-variant-numeric:tabular-nums;}
+.b3-md-pending{display:grid;gap:.5rem;}
+.b3-md-pending>.b3-skeleton{block-size:1.5rem;}
+.b3-md-pending>.b3-skeleton+.b3-skeleton{inline-size:80%;}
+@media (prefers-reduced-motion:reduce){.b3-md-appear,.b3-md-caret{animation:none;}}
+`;
+function ensureStyle(document2) {
+  if (!document2?.head || document2.getElementById(STYLE_ID))
+    return;
+  const style = document2.createElement("style");
+  style.id = STYLE_ID;
+  style.textContent = STYLE;
+  document2.head.append(style);
+}
+
+class MarkdownStreamOptions {
+  Marked = null;
+  sanitize = null;
+  directives = directives;
+  fences = fences;
+  code = codeBlock;
+  tones = { paid: "success", done: "success", ok: "success", active: "success", pending: "warning", overdue: "danger", failed: "danger", blocked: "danger", draft: "info" };
+  html = "escape";
+  markedOptions = {};
+}
+
+class MarkdownStream {
+  el = null;
+  buf = "";
+  nodes = [];
+  ended = false;
+  #md;
+  #onClick = (event) => this.#copy(event);
+  constructor(options) {
+    this.options = { ...new MarkdownStreamOptions, ...options };
+    this.options.directives = { ...directives, ...options?.directives };
+    this.options.fences = { ...fences, ...options?.fences };
+    const { Marked, sanitize } = this.options;
+    if (typeof Marked !== "function")
+      throw new TypeError('MarkdownStream: options.Marked (from "marked") is required');
+    if (typeof sanitize !== "function")
+      throw new TypeError("MarkdownStream: options.sanitize is required (e.g. html => DOMPurify.sanitize(html))");
+    this.#md = this.#createParser();
+  }
+  attach(el) {
+    this.detach();
+    this.el = el;
+    this.buf = "";
+    this.nodes = [];
+    this.ended = false;
+    ensureStyle(el.ownerDocument);
+    el.addEventListener("click", this.#onClick);
+    return this;
+  }
+  detach() {
+    this.el?.removeEventListener("click", this.#onClick);
+    this.el = null;
+  }
+  push(chunk) {
+    if (this.ended) {
+      console.warn("MarkdownStream: push() after end() ignored; call attach(el) to start a new stream");
+      return;
+    }
+    this.buf += chunk;
+    this.render(true);
+  }
+  end() {
+    this.ended = true;
+    this.render(false);
+  }
+  toHtml(src) {
+    return this.options.sanitize(this.#md.parse(src));
+  }
+  render(streaming) {
+    const { el } = this;
+    if (!el)
+      throw new Error("MarkdownStream: call attach(el) before push()");
+    const doc = el.ownerDocument;
+    const { src, pendingTable } = streaming ? settle(this.buf) : { src: this.buf, pendingTable: false };
+    const tokens = this.#md.lexer(src).filter((t) => t.type !== "space");
+    tokens.forEach((tok, i) => {
+      const prev = this.nodes[i];
+      if (prev && prev.raw === tok.raw)
+        return;
+      const holder = doc.createElement("div");
+      holder.innerHTML = this.options.sanitize(this.#md.parser([tok]));
+      const only = holder.childElementCount === 1 && [...holder.childNodes].every((n) => n.nodeType === 1 || !n.textContent.trim()) ? holder.firstElementChild : null;
+      const node = only ?? holder;
+      if (!prev)
+        node.classList.add("b3-md-appear");
+      prev ? prev.el.replaceWith(node) : el.append(node);
+      this.nodes[i] = { raw: tok.raw, el: node };
+    });
+    this.nodes.splice(tokens.length).forEach((n) => n.el.remove());
+    el.querySelector(":scope .b3-md-caret, :scope > .b3-md-pending")?.remove();
+    if (pendingTable)
+      el.insertAdjacentHTML("beforeend", '<div class="b3-md-pending" aria-hidden="true"><div class="b3-skeleton"></div><div class="b3-skeleton"></div></div>');
+    else if (streaming) {
+      const last = this.nodes.at(-1)?.el;
+      const at = last?.matches("p, li, td, th, pre") ? last : last?.querySelector("p:last-of-type, li:last-child, td:last-child") || last || el;
+      at.insertAdjacentHTML("beforeend", '<span class="b3-md-caret" aria-hidden="true"></span>');
+    }
+  }
+  #copy(event) {
+    const button = event.target.closest?.("[data-b3-md-copy]");
+    if (!button || !this.el?.contains(button))
+      return;
+    const text = button.closest(".b3-md-code")?.querySelector("code")?.textContent ?? "";
+    const show = (label) => {
+      button.textContent = label;
+      setTimeout(() => {
+        button.textContent = "Copy";
+      }, 1200);
+    };
+    const fail = (error) => {
+      console.warn("MarkdownStream: copy failed", error);
+      show("Copy failed");
+    };
+    const clip = this.el.ownerDocument.defaultView?.navigator?.clipboard;
+    if (clip?.writeText)
+      clip.writeText(text).then(() => show("Copied"), fail);
+    else
+      fail(new Error("navigator.clipboard is unavailable (insecure context?)"));
+  }
+  #createParser() {
+    const opts = this.options;
+    const directive = {
+      name: "directive",
+      level: "block",
+      start: (src) => src.match(/^:::/m)?.index,
+      tokenizer(src) {
+        const m = /^:::(\w+)(?:\{([^}\n]*)\})?[^\n]*(?:\n|$)/.exec(src);
+        if (!m)
+          return;
+        const lines = src.slice(m[0].length).split(`
+`);
+        let fence = null, end = lines.length;
+        for (let i = 0;i < lines.length; i++) {
+          const f = /^ {0,3}(`{3,}|~{3,})/.exec(lines[i])?.[1];
+          if (fence) {
+            if (f && f[0] === fence[0] && f.length >= fence.length && !lines[i].trim().slice(f.length))
+              fence = null;
+          } else if (f)
+            fence = f;
+          else if (/^:::[^\S\n]*$/.test(lines[i])) {
+            end = i;
+            break;
+          }
+        }
+        const body = lines.slice(0, end).join(`
+`).replace(/\n$/, "");
+        const closed = end < lines.length;
+        const raw = m[0] + lines.slice(0, closed ? end + 1 : end).join(`
+`) + (closed && end + 1 < lines.length ? `
+` : "");
+        return { type: "directive", raw, name: m[1], attrs: parseAttrs(m[2]), body, tokens: this.lexer.blockTokens(body, []) };
+      },
+      renderer(t) {
+        const render = opts.directives[t.name] ?? opts.directives.callout;
+        return render(t, { parse: (tokens) => this.parser.parse(tokens), parseInline: (tokens) => this.parser.parseInline(tokens), inline: (text) => md.parseInline(text), esc });
+      }
+    };
+    const md = new opts.Marked({ gfm: true, extensions: [directive] });
+    md.use({
+      renderer: {
+        blockquote(t) {
+          const m = /^\s*(?:\[!(\w+)\][^\S\n]*\n?|\*\*(\w+):?\*\*:?[^\S\n]*)/.exec(t.text);
+          const kind = (m?.[1] ?? m?.[2])?.toLowerCase();
+          if (!Object.hasOwn(ALERTS, kind))
+            return false;
+          const title = kind[0].toUpperCase() + kind.slice(1);
+          return opts.directives.callout({ attrs: { tone: ALERTS[kind], title }, tokens: md.lexer(t.text.slice(m[0].length)) }, { parse: (tokens) => this.parser.parse(tokens), parseInline: (tokens) => this.parser.parseInline(tokens), inline: (text) => md.parseInline(text), esc });
+        },
+        table(t) {
+          const numeric = t.header.map((_, i) => t.rows.length > 0 && t.rows.every((r) => isNum(r[i]?.text || "0")));
+          const cell = (c, i, tag) => {
+            const html = this.parser.parseInline(c.tokens);
+            const tone = tag === "td" && opts.tones[c.text.trim().toLowerCase()];
+            const body = tone ? `<span class="b3-badge" data-b3-tone="${esc(tone)}">${html}</span>` : html;
+            return `<${tag}${tag === "th" ? ' scope="col"' : ""}${numeric[i] ? ' class="b3-md-num"' : ""}>${body}</${tag}>`;
+          };
+          return `<div class="b3-table-wrap" tabindex="0" role="region" aria-label="Table"><table class="b3-table"><thead><tr>${t.header.map((c, i) => cell(c, i, "th")).join("")}</tr></thead><tbody>${t.rows.map((r) => `<tr>${r.map((c, i) => cell(c, i, "td")).join("")}</tr>`).join("")}</tbody></table></div>`;
+        },
+        code({ text, lang }) {
+          const name = (lang || "").trim().split(/\s/)[0];
+          const fence = Object.hasOwn(opts.fences, name) ? opts.fences[name] : null;
+          return fence ? fence(text, { esc, lang: name }) : opts.code(text, name);
+        },
+        html(t) {
+          return opts.html === "render" ? false : t.block ? `<p>${esc(t.text.trim())}</p>` : esc(t.text);
+        },
+        list(t) {
+          if (!t.items.some((i) => i.task))
+            return false;
+          return `<ul class="b3-md-tasks">${t.items.map((i) => {
+            const tokens = i.tokens.filter((k) => k.type !== "checkbox");
+            const head = tokens.find((k) => k.type === "text" || k.type === "paragraph");
+            if (head?.tokens)
+              head.tokens = head.tokens.filter((k) => k.type !== "checkbox");
+            const body = tokens.map((k) => k.type === "text" && !i.loose ? this.parser.parseInline(k.tokens ?? [k]) : this.parser.parse([k])).join("");
+            return `<li><input type="checkbox" disabled${i.checked ? " checked" : ""}>${body}</li>`;
+          }).join("")}</ul>`;
+        }
+      }
+    });
+    if (opts.markedOptions && Object.keys(opts.markedOptions).length)
+      md.use(opts.markedOptions);
+    return md;
+  }
+}
+function stickToBottom(scroller = document.scrollingElement, { threshold = 80 } = {}) {
+  const doc = scroller.ownerDocument ?? scroller;
+  const win = doc.defaultView;
+  const target = scroller === doc.scrollingElement ? win : scroller;
+  let pinned = true, lastTop = scroller.scrollTop;
+  const measure = () => {
+    const top = scroller.scrollTop;
+    if (scroller.scrollHeight - top - scroller.clientHeight >= threshold)
+      pinned = false;
+    else if (top >= lastTop)
+      pinned = true;
+    lastTop = top;
+  };
+  const up = (e) => {
+    if (e.target?.closest?.('input, textarea, select, [contenteditable]:not([contenteditable="false"])'))
+      return;
+    if (scroller.scrollTop > 0 && (e.deltaY < 0 || /^(ArrowUp|PageUp|Home)$/.test(e.key)))
+      pinned = false;
+  };
+  const on = [["scroll", measure], ["wheel", up], ["keydown", up]];
+  on.forEach(([type, f]) => target.addEventListener(type, f, { passive: true }));
+  return {
+    get pinned() {
+      return pinned;
+    },
+    stick(force = false) {
+      if (force || pinned) {
+        scroller.scrollTop = scroller.scrollHeight;
+        pinned = true;
+      }
+    },
+    destroy() {
+      on.forEach(([type, f]) => target.removeEventListener(type, f));
+    }
+  };
+}
+export {
+  MarkdownStream,
+  MarkdownStreamOptions,
+  codeBlock,
+  directives,
+  esc,
+  fences,
+  isNum,
+  parseAttrs,
+  promptGuide,
+  settle,
+  stickToBottom
+};

package/dist/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.1.0-alpha.53",
+  "version": "0.1.0-alpha.57",
   "cssSha256": "5b3fec9da13833361cfa59510dd9bcf25719455f1b20cf6f7692d58a45303fe7",
   "classes": [
     "b3-accordion",
@@ -473,8 +473,10 @@
     "editable-filtered-rows.md",
     "icons.md",
     "image-viewer.md",
+    "markdown-stream.md",
     "motion.md",
     "scroll-entry.md",
-    "start.md"
+    "start.md",
+    "markdown-stream-prompt.md"
   ]
 }

package/dist/references/markdown-stream-prompt.md

@@ -0,0 +1,13 @@
+# Markdown stream: model prompt
+
+System-prompt snippet from `promptGuide()` in `@livx.cc/bare-v3/elements/markdown-stream`.
+
+~~~~text
+Your replies are Markdown rendered live into UI components. Use GitHub-flavoured Markdown (headings, **bold**, lists, links, `inline code`, fenced code with a language, > quotes) plus:
+- Tables: GFM pipe tables with a header row and a `| --- |` delimiter row. Never add a Status column the data does not already have. Only when a row really has one of these states (e.g. an invoice that is paid), write the plain word alone in the cell and it is shown as a coloured badge automatically (no images, emoji or badge URLs): paid, done, ok, active (success); pending (warning); overdue, failed, blocked (danger); draft (info). Numeric columns align right.
+- Task lists: `- [x] done` and `- [ ] to do`.
+- `:::callout{tone=info|success|warning|danger title="Short title"}` newline, markdown body, newline `:::` — a highlighted note, tip, warning or recommendation.
+- `:::stats` newline, one card per line `Label | Value | note`, newline `:::` — headline numbers; a note starting with ↑ or + shows as good, ↓ or - as bad.
+- ```chart fence, one bar per line `Label: number` (plain number, no units) — a horizontal bar chart for comparing a few values.
+Use a component only when it makes the answer clearer; plain prose is fine. Put every block on its own lines with a blank line around it, always close ::: and ``` blocks, and never write raw HTML.
+~~~~

package/dist/references/markdown-stream.md

@@ -0,0 +1,91 @@
+# Streaming markdown
+
+`MarkdownStream` renders an LLM's streaming markdown into bare-v3 components. Finished blocks are
+frozen (their DOM is never replaced, so selection and copy buttons stay put), only the tail
+re-renders, and half-written syntax never shows raw. Opt-in; not part of `ui.js`.
+
+It bundles no parser or sanitizer: pass marked's `Marked` class and a sanitize function.
+
+```js
+import { Marked } from 'marked';
+import DOMPurify from 'dompurify';
+import { MarkdownStream, stickToBottom } from '@livx.cc/bare-v3/elements/markdown-stream';
+
+const view = new MarkdownStream({ Marked, sanitize: (html) => DOMPurify.sanitize(html) });
+const scroll = stickToBottom(); // pins while streaming; the reader scrolling up un-pins
+view.attach(document.querySelector('article.b3-prose'));
+for await (const chunk of res.body.pipeThrough(new TextDecoderStream())) { view.push(chunk); scroll.stick(); }
+view.end();
+```
+
+## What renders
+
+Any markdown-speaking model works with no prompt: standard markdown is upgraded on its own. The `:::` directives and `chart` fence are extras a model only writes once taught (see `promptGuide` below).
+
+| Markdown | Renders as |
+| --- | --- |
+| GFM table | `b3-table` in `b3-table-wrap`; status words (paid, pending, overdue…) become toned `b3-badge`s; all-numeric columns align end |
+| `:::callout{tone=warning title="…"}` … `:::` | `b3-alert` with tone and title; body is markdown |
+| `:::stats` lines `Label \| Value \| ↑ note` `:::` | `b3-stat` cards; `↑`/`+` notes success, `↓`/`-` danger |
+| ```` ```chart ```` lines `Label: number` | horizontal bars scaled to the max |
+| ```` ```lang ```` | code block with language label and Copy button |
+| `- [x] task` | list with disabled checkboxes |
+| `> [!NOTE]` / `> [!WARNING]` (GitHub alerts) or `> **Note:** …` | `b3-alert`; note/important → info, tip → success, warning → warning, caution/danger → danger |
+
+## Options
+
+`Marked`, `sanitize` (both required), `directives` (name → `(token, ctx) => html`; unknown names
+fall back to `callout`), `fences` (lang → `(text, ctx) => html`), `code` (`(text, lang) => html`),
+`tones` (cell text → tone), `markedOptions` (extra `marked.use()` input), `html` (`'escape'` default |
+`'render'`). Maps merge over the built-ins, so adding one renderer keeps the rest. Everything a renderer
+returns is sanitized.
+
+- **Raw HTML is shown as text by default**: `Use <Button variant="x">` or `a <div> … </div>` in model
+  output (coding agents write JSX) renders as literal tags, not live DOM. `html: 'render'` passes it
+  through `sanitize` instead, for hosts whose content is trusted HTML.
+- **Footnotes and other GFM extras** are not built in; add a marked extension via `markedOptions`, e.g.
+  `markedOptions: markedFootnote()` (from `marked-footnote`) for `Note[^1]` / `[^1]: x`.
+
+Methods: `attach(el)`, `push(chunk)`, `end()`, `toHtml(src)`, `detach()`. `end()` finalises the
+stream: a later `push()` is ignored with a console warning; call `attach(el)` to start a new one. `settle(buffer)`, `promptGuide(options)` and
+`stickToBottom(scroller)` are exported on their own.
+
+## Agent / LLM integration
+
+**System prompt (optional).** Skip it and plain markdown still renders fully; add it to unlock callouts, stats and charts. `promptGuide(options?)` returns a short snippet teaching a model the vocabulary
+above. It is generated from the same `directives`/`fences`/`tones` the stream uses, so pass the same
+options: a custom renderer contributes a line by carrying a `.doc` string. The default text ships as
+`references/markdown-stream-prompt.md`.
+
+```js
+import { promptGuide } from '@livx.cc/bare-v3/elements/markdown-stream';
+steps.doc = '`:::steps` … `:::` — a numbered walkthrough';
+const system = promptGuide({ directives: { steps } }) + '\nBe helpful and concise.';
+```
+
+**Server contract.** `POST /api/chat` with `{ messages: [{ role, content }] }` answers `text/plain`
+chunks of the reply: parse the provider's SSE and forward only the text deltas. Abort the upstream
+request when the client disconnects. `scripts/chat-server.ts` is a working example (`bun run chat`;
+OpenRouter or OpenAI via plain HTTP; `CHAT_MODEL`, `CHAT_MAX_TOKENS` and `CHAT_PORT` override).
+
+**Client loop.**
+
+```js
+const history = [];
+async function ask(text, signal) {
+  history.push({ role: 'user', content: text });
+  const view = new MarkdownStream({ Marked, sanitize: (html) => DOMPurify.sanitize(html) }).attach(newArticle());
+  try {
+    const res = await fetch('/api/chat', { method: 'POST', signal, headers: { 'content-type': 'application/json' }, body: JSON.stringify({ messages: history }) });
+    if (!res.ok) throw new Error(await res.text());
+    for await (const chunk of res.body.pipeThrough(new TextDecoderStream())) { view.push(chunk); scroll.stick(); }
+  } finally { view.end(); history.push({ role: 'assistant', content: view.buf }); }
+}
+```
+
+- **History is raw markdown** (`view.buf`), never rendered HTML; a stopped reply keeps its partial text.
+- **Always sanitize**: model output is untrusted input, and renderers' HTML goes through `sanitize` too.
+- Stop = `AbortController.abort()`; the fetch rejects and the server aborts the provider call.
+
+`fixtures/elements/markdown-stream.html` is the full chat (composer, Stop, multi-turn). Under
+`bun run chat` it talks to the model; under any plain static server it falls back to canned replies.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@livx.cc/bare-v3",
-  "version": "0.1.0-alpha.53",
+  "version": "0.1.0-alpha.57",
   "type": "module",
   "files": [
     "dist",
@@ -13,12 +13,14 @@
     "./references/*": "./dist/references/*",
     "./ui": "./dist/ui.js",
     "./elements/image-viewer": "./dist/elements/image-viewer.js",
-    "./elements/date-picker": "./dist/elements/date-picker.js"
+    "./elements/date-picker": "./dist/elements/date-picker.js",
+    "./elements/markdown-stream": "./dist/elements/markdown-stream.js"
   },
   "scripts": {
     "build": "bun scripts/build.ts",
     "test": "bun test",
     "lab": "bun lab/cli.ts",
+    "chat": "bun scripts/chat-server.ts",
     "check:package": "bun scripts/check-package.ts",
     "typecheck": "tsc"
   },
@@ -31,8 +33,10 @@
     "ai.libx.js": "0.18.29",
     "basecoat-css": "1.0.2",
     "daisyui": "5.7.28",
+    "happy-dom": "20.14.5",
     "lightningcss": "1.33.0",
     "lucide-static": "1.31.0",
+    "marked": "18.0.14",
     "pug": "3.0.4",
     "tailwindcss": "4.3.3",
     "typescript": "7.0.2"