From f41985e407890a57c4171d43bc272abf7dd1e22f Mon Sep 17 00:00:00 2001
From: clover caruso <git@paperclover.net>
Date: Wed, 14 Oct 2026 02:08:36 -0700
Subject: [PATCH] feat(lib/progress): attachToDocument and formatHtml

Beautiful Windows7 progress bars in the browser!

Assisted-by: claude-opus-5.5
---
 lib/Events.test.ts    |  19 ++
 lib/Events.ts         |   9 +-
 lib/progress.test.ts  | 127 +++++++++++
 lib/progress.ts       | 492 +++++++++++++++++++++++++++++++++++++++---
 lib/readme.changes.md |   5 +
 lib/readme.md         |   2 +-
 6 files changed, 620 insertions(+), 34 deletions(-)
 create mode 100644 lib/Events.test.ts

diff --git a/lib/Events.test.ts b/lib/Events.test.ts
new file mode 100644
index 0000000000000000000000000000000000000000..a4a3bc77214a2d2cc7da66867bab38ddfd386981
--- /dev/null
+++ b/lib/Events.test.ts
@@ -0,0 +1,19 @@
+test("disposing a listener leaves the others", () => {
+  const events = new Events<{ ping: [] }>();
+  const calls: string[] = [];
+  const offA = events.on("ping", () => calls.push("a"));
+  events.on("ping", () => calls.push("b"));
+  const offAny = events.onAny(() => calls.push("any a"));
+  events.onAny(() => calls.push("any b"));
+
+  offA();
+  offA();
+  offAny();
+  offAny();
+  events.emit("ping");
+  assert.deepEqual(calls, ["b", "any b"]);
+});
+
+import assert from "node:assert/strict";
+import { test } from "vitest";
+import { Events } from "./Events.ts";
diff --git a/lib/Events.ts b/lib/Events.ts
index c2bd2b0c72e596eb80f7470805f00de4e4668862..410c43322d72c2812d9fd0625917aad178218770 100644
--- a/lib/Events.ts
+++ b/lib/Events.ts
@@ -31,7 +31,7 @@ export class Events<Map extends Events.Map> {
   on<C extends keyof Map>(channel: C, cb: Events.Handler<Map[C]>): ts.Dispose {
     const list = this.#channels[channel] ??= [];
     list.push(cb);
-    return ts.defer(() => void (list.splice(list.indexOf(cb)), 1));
+    return ts.defer(() => remove(list, cb));
   }
   /**
    * listen for one event on the specified channel
@@ -77,7 +77,7 @@ export class Events<Map extends Events.Map> {
   /** listen for any event */
   onAny(cb: (channel: keyof Map, args: unknown[]) => void): ts.Dispose {
     this.#global.push(cb);
-    return ts.defer(() => void (this.#global.splice(this.#global.indexOf(cb)), 1));
+    return ts.defer(() => remove(this.#global, cb));
   }
   /** emit an event on the specified channel */
   emit<C extends keyof Map>(channel: C, ...args: Map[C]): void {
@@ -95,6 +95,11 @@ export class Events<Map extends Events.Map> {
   }
 }
 
+function remove<T>(list: T[], item: T) {
+  const i = list.indexOf(item);
+  if (i !== -1) list.splice(i, 1);
+}
+
 export namespace Events {
   export type Map = { [key: string]: unknown[] };
   export type Handler<Args extends unknown[]> = (...args: Args) => void;
diff --git a/lib/progress.test.ts b/lib/progress.test.ts
index 280a11dcfe9096780e332c49b582863c36e4fdd8..f14bc30fe55f11d05f1472edeae36522e1e26ba2 100644
--- a/lib/progress.test.ts
+++ b/lib/progress.test.ts
@@ -309,6 +309,132 @@ test("Ema tracks warmup samples without resetting the first sample", () => {
   assert.ok(Math.abs(completion - 26_737.70491803279) < 1e-9);
 });
 
+// ## html
+test("formatHtml draws visible nodes into a declarative shadow root", () => {
+  const root = new progress.Root();
+  const build = root.start("build <site>");
+  build.start("secret", { hidden: true });
+  root.start("empty group", { passive: true });
+
+  const html = progress.formatHtml(root.active);
+  assert.match(html, /^<template shadowrootmode="open"><style>[^]*<\/style><ol class=tree role=list>/);
+  assert.match(html, /<\/ol><\/template>$/);
+  assert(html.includes(">build &lt;site&gt;</span>"));
+  assert(!html.includes("secret"));
+  assert(!html.includes("empty group"));
+});
+
+test("bars carry their value, busy rings do not", () => {
+  const root = new progress.Root();
+  root.start("download", { total: 200, value: 50 });
+  root.start("connect");
+  root.start("done", { total: 3, value: 3 });
+
+  const [download, connect, done] = items(progress.formatHtml(root.active));
+  assert.match(download!, /^<li class="bar">/);
+  assert.match(
+    download!,
+    /role=progressbar aria-labelledby=(n\d+) aria-valuenow="50" aria-valuemax="200" style="--p:0.25">/,
+  );
+  assert.match(download!, /<span class=label id=n\d+>download<\/span>/);
+  assert.match(connect!, /^<li class="spin">/);
+  assert(!connect!.includes("aria-valuenow"));
+  // a full bar stops its glow
+  assert.match(done!, /^<li class="bar full">/);
+});
+
+test("counts split at the slash, so the total can be styled apart", () => {
+  const root = new progress.Root();
+  root.start("count", { total: 48, value: 31 });
+  root.start("unstarted", { total: 48 });
+  root.start("no total", { total: 48, value: 3, showTotal: false });
+  root.start("bytes", { units: "bytes", total: 2_370_000_000, value: 1_020_000_000 });
+  root.start("percent", { units: "percent", total: 7, value: 2 });
+  root.start("custom", { value: 42, valueFormatter: (value) => `${value} fps` });
+
+  assert.deepEqual(items(progress.formatHtml(root.active)).map(count), [
+    "<b>31</b><span>48</span>",
+    "<b></b><span></span>",
+    "<b>3</b><span></span>",
+    "<b>1.02GB</b><span>2.37GB</span>",
+    "<b>28.6%</b><span></span>",
+    "<b>42 fps</b><span></span>",
+  ]);
+});
+
+test("estimates count down, and only the latest in a subtree shows", () => {
+  vi.useFakeTimers({ now: 1_000_000_000 });
+  try {
+    const root = new progress.Root();
+    const parent = root.start("parent", { estimateCompletion: false });
+    parent.estimatedTime = Date.now() + 30_000;
+    const child = parent.start("child", { estimateCompletion: false });
+    child.estimatedTime = Date.now() + 124_000;
+
+    const [parentHtml, childHtml] = items(progress.formatHtml(root.active));
+    assert.match(parentHtml!, /<span class=eta><\/span>/);
+    assert.match(childHtml!, /<span class=eta>2m 4s left<\/span>/);
+  } finally {
+    vi.useRealTimers();
+  }
+});
+
+test("logs show their last three lines", () => {
+  const root = new progress.Root();
+  const node = root.start("job");
+  node.log.info("first");
+  node.log.write("par");
+  node.log.write("tial\n");
+  node.log.warn("careful");
+  node.log.error("broke\n  at frame");
+
+  assert.equal(
+    logs(progress.formatHtml(root.active)),
+    "<div class=warn>careful</div><div class=error>broke</div><div class=more>  at frame</div>",
+  );
+});
+
+test("partial writes join into lines of their own", () => {
+  const root = new progress.Root();
+  const node = root.start("job");
+  node.log.info("hello");
+  node.log.write("one ");
+  node.log.write("two\nthree");
+  node.log.scoped("db").info("<connected>");
+
+  assert.equal(
+    logs(progress.formatHtml(root.active)),
+    "<div class=raw>one two</div><div class=raw>three</div>"
+      + "<div class=info><span class=scope>db</span> &lt;connected&gt;</div>",
+  );
+});
+
+test("ansi styles become spans, and carry across lines of a message", () => {
+  const root = new progress.Root();
+  const node = root.start("job");
+  node.log.write(`${ansi.fgGreen}ok${ansi.fgReset} \x1b[1;38;5;196mhot\nstill hot${ansi.reset}\x1b[2K`);
+
+  assert.equal(
+    logs(progress.formatHtml(root.active)),
+    "<div class=raw><span style=\"color:var(--ansi2);\">ok</span> "
+      + "<span style=\"color:rgb(255 0 0);font-weight:bold;\">hot</span></div>"
+      + "<div class=raw><span style=\"color:rgb(255 0 0);font-weight:bold;\">still hot</span></div>",
+  );
+});
+
+/** the markup of each drawn node, in order */
+function items(html: string) {
+  return html.split("<li ").slice(1).map((item) => "<li " + item);
+}
+
+function count(item: string) {
+  return UNWRAP(/<span class=count>(.*?)<\/span><span class=eta>/.exec(item))[1];
+}
+
+function logs(html: string) {
+  return UNWRAP(/<div class=logs>(.*?)<\/div><\/li>/.exec(html))[1];
+}
+
 // ## internals
 test("event encoding round trip cases", async () => {
   const fakeNode = progress.nullNode;
@@ -408,6 +534,7 @@ test("event encoding round trip cases", async () => {
       l: [
         { level: "warn", text: "deprecated pixel format", time: 1768210850000 },
         { level: "info", text: "hello", time: 1768210851000 },
+        { level: "info", text: "partial ", time: 1768210851500, newline: false },
         {
           level: "error",
           text: "scoped + stacked",
diff --git a/lib/progress.ts b/lib/progress.ts
index 03e14c0d05cafae19fc9f01fb6777c203e2d3a58..499a8ecfd6137c76eafa11afb1c25487f2202bd4 100644
--- a/lib/progress.ts
+++ b/lib/progress.ts
@@ -2,8 +2,9 @@
  * a progress reporting API that allows creating CLI spinners and progress bars
  * that can be easily nested to visualize complex, parallel work. in addition
  * to providing rich feedback in the terminal, a headless {@linkcode Root} node
- * can be constructed, which can be used to bind to {@link formatHtml|the DOM}
- * or transmit progress information {@link encodeStream|across a network}.
+ * can be constructed, which can be used to bind to
+ * {@link attachToDocument|the DOM} or transmit progress information
+ * {@link encodeEventStream|across a network}.
  *
  * the progress API takes advantage of the `using` keyword to make nodes
  * scoped. the convention is to make functions take a {@linkcode Ref|progress.Ref},
@@ -636,14 +637,28 @@ function endNode<R, M extends Events.Map>(owner: Root<R, M>, state: Internal) {
 export function formatAnsi(now: number, list: readonly ReadOnlyNode[]): string {
   let out = "";
   for (const top of list) {
-    if (top.passive && !hasChildren(top)) continue;
+    if (!isVisible(top)) continue;
     out += renderAnsiMainLine(top, now, 0) + "\n";
     out += renderChildren(top, now, []);
   }
   return out.trimEnd();
 }
 
+function isVisible(node: ReadOnlyNode): boolean {
+  return !node.hidden && (!node.passive || node.children.some(isVisible));
+}
+
+function remainingSeconds(node: ReadOnlyNode): number | null {
+  const { estimatedTime } = node;
+  if (!estimatedTime) return null;
+  const ms = estimatedTime - Date.now();
+  return ms > 1000 && !findLongerEstimate(node, estimatedTime)
+    ? Math.round(ms / 1000)
+    : null;
+}
+
 const spinnerFps = 12.5;
+const maxLogLines = 3;
 const box = { tee: "├─ ", line: "│  ", langle: "└─ " };
 const barChars = [" ", "▏", "▎", "▍", "▌", "▋", "▊", "▉"];
 const fullBar = "█";
@@ -651,13 +666,9 @@ const spinner = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇",
   .map((frame) => ansi.style(ansi.fgBlue, frame));
 
 function renderAnsiMainLine(state: ReadOnlyNode, now: number, depth: number) {
-  const { text, total, showTotal, value, estimatedTime } = state;
-  const dateNow = Date.now();
-  const showEstimate = estimatedTime && !findLongerEstimate(state, estimatedTime);
-  const estimate = showEstimate && (estimatedTime > dateNow + 1000)
-    ? ", "
-      + string.formatDurationLetters(Math.round((estimatedTime - dateNow) / 1000))
-    : "";
+  const { text, total, showTotal, value } = state;
+  const remaining = remainingSeconds(state);
+  const estimate = remaining ? ", " + string.formatDurationLetters(remaining) : "";
   const valueFormatted = state.valueFormatter(value, total);
   if (total && showTotal) {
     return ansi.style(
@@ -675,30 +686,18 @@ function renderAnsiMainLine(state: ReadOnlyNode, now: number, depth: number) {
     + (valueFormatted ? `[${valueFormatted}] ` : "") + text);
 }
 
-function hasChildren(states: ReadOnlyNode): boolean {
-  return states.children.some((x) => !x.hidden && (!x.passive || hasChildren(x)));
-}
-
-function findLongerEstimate(
-  state: ReadOnlyNode,
-  estimatedTime: number,
-): boolean {
-  for (const child of state.children) {
-    if (child.hidden || (child.passive && !hasChildren(child))) continue;
-    if (child.estimatedTime != null && child.estimatedTime > estimatedTime) {
-      return true;
-    }
-    if (findLongerEstimate(child, estimatedTime)) return true;
-  }
-  return false;
+function findLongerEstimate(state: ReadOnlyNode, estimatedTime: number): boolean {
+  return state.children.some((child) =>
+    isVisible(child)
+    && ((child.estimatedTime ?? 0) > estimatedTime || findLongerEstimate(child, estimatedTime))
+  );
 }
 
 function renderChildren(state: ReadOnlyNode, now: number, depth: boolean[]) {
   let maxHeight = 50; // TODO: flexible layout
   let truncated = 0;
   let out = "";
-  let { children } = state;
-  children = children.filter((x) => !x.hidden && (!x.passive || hasChildren(x)));
+  const children = state.children.filter(isVisible);
   if (children.length === 0) return "";
   for (let i = 0, { length } = children; i < length; i += 1) {
     const child = UNWRAP(children[i]);
@@ -717,7 +716,7 @@ function renderChildren(state: ReadOnlyNode, now: number, depth: boolean[]) {
       .join("")
       .trim();
     if (logLines) {
-      for (const line of logLines.split("\n").slice(-Math.min(3, maxHeight))) {
+      for (const line of logLines.split("\n").slice(-Math.min(maxLogLines, maxHeight))) {
         item += left + (i === length - 1 && !truncated ? "   " : box.line)
           + " "
           + ansi.style(ansi.fgBrightBlack, ">")
@@ -829,6 +828,435 @@ function hasEstimate(nodes: readonly ReadOnlyNode[]): boolean {
   return nodes.some((n) => n.estimatedTime != null || hasEstimate(n.children));
 }
 
+/**
+ * draw `root` into the shadow root of `host`, after the Windows 7 progress bar
+ * and busy cursor, on the animation frame after each change, until disposed.
+ * the shadow root keeps the page and the tree from styling each other, and the
+ * tree follows the page's `color-scheme`. `host` must accept a shadow root,
+ * such as a `div`; one rendered by {@linkcode formatHtml} is taken over.
+ * ```ts
+ * const root = new progress.Root();
+ * const detach = progress.attachToDocument(root, document.getElementById("progress")!);
+ * await build(root);
+ * detach();
+ * ```
+ */
+export function attachToDocument<R, M extends Events.Map>(
+  root: Root<R, M>,
+  host: Element,
+): ts.Dispose {
+  const shadow = host.shadowRoot ?? host.attachShadow({ mode: "open" });
+  shadow.innerHTML = formatShadow("");
+  const tree = UNWRAP(shadow.lastElementChild);
+  const template = document.createElement("template");
+  const elements = new WeakMap<ReadOnlyNode, Element>();
+  const changedAt = new WeakMap<ReadOnlyNode, number>();
+  const staleLogs = new Set<ReadOnlyNode>();
+  let frame: number | null = null;
+  let tick: ts.Timer | undefined;
+  let tickIn = Infinity;
+
+  const redraw = () => void (frame ??= requestAnimationFrame(draw));
+  function draw() {
+    frame = null;
+    for (const node of staleLogs) {
+      const logs = elements.get(node)?.children[2];
+      if (logs) logs.innerHTML = formatLogs(node.logs);
+    }
+    staleLogs.clear();
+    clearTimeout(tick);
+    tickIn = Infinity;
+    sync(tree, root.active);
+    if (tickIn !== Infinity) tick = setTimeout(redraw, tickIn);
+  }
+  function sync(list: Element, nodes: readonly ReadOnlyNode[]) {
+    let next = list.firstElementChild;
+    for (const node of nodes) {
+      if (!isVisible(node)) continue;
+      // estimates show whole seconds, rounded, so each changes on a half second
+      const ms = (node.estimatedTime ?? 0) - Date.now();
+      if (ms > 0) tickIn = Math.min(tickIn, (ms + 500) % 1000 + 5);
+      let li = elements.get(node);
+      if (li) {
+        update(li, node, changedAt);
+      } else {
+        template.innerHTML = formatNode(node, "");
+        elements.set(node, li = UNWRAP(template.content.firstElementChild));
+        changedAt.set(node, performance.now());
+      }
+      if (li === next) next = li.nextElementSibling;
+      else list.insertBefore(li, next);
+      sync(UNWRAP(li.children[1]), node.children);
+    }
+    while (next) {
+      const stale = next;
+      next = next.nextElementSibling;
+      stale.remove();
+    }
+  }
+
+  const listeners = [
+    root.on("node-start", redraw),
+    root.on("node-change", (node, key) => {
+      if (key === "logs") staleLogs.add(node);
+      redraw();
+    }),
+    root.on("node-end", redraw),
+  ];
+  draw();
+  return ts.defer(() => {
+    for (const off of listeners) off();
+    if (frame !== null) cancelAnimationFrame(frame);
+    clearTimeout(tick);
+    shadow.replaceChildren();
+  });
+}
+
+/**
+ * the markup {@linkcode attachToDocument} draws for `list`, as a declarative
+ * shadow root to place inside the element it later takes over. browsers attach
+ * it only while parsing a document, such as a server rendered page.
+ */
+export function formatHtml(list: readonly ReadOnlyNode[]): string {
+  const format = (nodes: readonly ReadOnlyNode[]): string =>
+    nodes.filter(isVisible)
+      .map((node) => formatNode(node, format(node.children)))
+      .join("");
+  return `<template shadowrootmode="open">${formatShadow(format(list))}</template>`;
+}
+
+const formatShadow = (items: string) => `<style>${css}</style><ol class=tree role=list>${items}</ol>`;
+
+/** the parts of a node's markup that change after it is drawn */
+function fields(node: ReadOnlyNode) {
+  const fraction = node.showTotal && node.total > 0
+    ? math.clamp(node.value / node.total, 0, 1)
+    : null;
+  const remaining = remainingSeconds(node);
+  return {
+    className: fraction === null ? "spin" : fraction === 1 ? "bar full" : "bar",
+    fraction,
+    count: formatCount(node),
+    eta: remaining
+      ? string.formatDurationLetters(remaining).replace(/(?<=\D)(?=\d)/g, " ") + " left"
+      : "",
+  };
+}
+
+/** `attachToDocument` relies on this layout: row, children, logs */
+function formatNode(node: ReadOnlyNode, children: string): string {
+  const { className, fraction, count, eta } = fields(node);
+  const id = `n${node.key}`;
+  const value = fraction === null
+    ? ""
+    : ` aria-valuenow="${node.value}" aria-valuemax="${node.total}" style="--p:${fraction}"`;
+  return `<li class="${className}"><div class=row>`
+    + `<div class=indicator role=progressbar aria-labelledby=${id}${value}><i></i></div>`
+    + `<span class=count><b>${esc(count[0])}</b><span>${esc(count[1])}</span></span>`
+    + `<span class=eta>${eta}</span>`
+    + `<span class=label id=${id}>${esc(node.text)}</span>`
+    + `</div><ol role=list>${children}</ol><div class=logs>${formatLogs(node.logs)}</div></li>`;
+}
+
+/**
+ * bring `li` from {@linkcode formatNode} up to date, except its children and
+ * logs. `changedAt` holds when each bar last moved.
+ */
+function update(
+  li: Element,
+  node: ReadOnlyNode,
+  changedAt: WeakMap<ReadOnlyNode, number>,
+) {
+  const { className, fraction, count, eta } = fields(node);
+  const [indicator, counter, estimate, label] = UNWRAP(li.firstElementChild).children;
+  const [value, total] = UNWRAP(counter).children;
+  const progressbar = UNWRAP(indicator);
+  setAttribute(li, "class", className);
+  setText(UNWRAP(value), count[0]);
+  setText(UNWRAP(total), count[1]);
+  setText(UNWRAP(estimate), eta);
+  setText(UNWRAP(label), node.text);
+  if (fraction === null) {
+    for (const name of ["aria-valuenow", "aria-valuemax", "style"]) setAttribute(progressbar, name, null);
+    return;
+  }
+  const shown = math.clamp(
+    Number(progressbar.getAttribute("aria-valuenow")) / Number(progressbar.getAttribute("aria-valuemax")),
+    0,
+    1,
+  );
+  setAttribute(progressbar, "aria-valuenow", String(node.value));
+  setAttribute(progressbar, "aria-valuemax", String(node.total));
+  if (fraction === shown) return;
+  // a forward glide lasts as long as the last update took to arrive, so steady
+  // progress moves steadily; going back snaps, as the original does
+  const now = performance.now();
+  const glide = fraction > shown ? Math.min(now - (changedAt.get(node) ?? now), 1000) : 0;
+  changedAt.set(node, now);
+  setAttribute(progressbar, "style", `--p:${fraction};--glide:${Math.round(glide)}ms`);
+}
+
+function setAttribute(element: Element, name: string, value: string | null) {
+  if (element.getAttribute(name) === value) return;
+  if (value === null) element.removeAttribute(name);
+  else element.setAttribute(name, value);
+}
+
+function setText(element: Element, text: string) {
+  if (element.textContent !== text) element.textContent = text;
+}
+
+/** `[value, total]`, split at the formatter's slash so the total can be styled apart */
+function formatCount({ value, total, showTotal, valueFormatter }: ReadOnlyNode): [string, string] {
+  const text = valueFormatter(value, total);
+  const slash = text.lastIndexOf("/");
+  if (slash === -1) return [text, ""];
+  return [text.slice(0, slash), showTotal ? text.slice(slash + 1) : ""];
+}
+
+/** the last lines of `logs`. partial writes join into lines of their own. */
+function formatLogs(logs: readonly log.Message[]): string {
+  let start = logs.length;
+  for (let breaks = 0; start > 0 && breaks <= maxLogLines;) {
+    const { text, newline } = UNWRAP(logs[--start]);
+    breaks += string.countNewlines(text) + (newline === false ? 0 : 1);
+  }
+  const lines: { kind: string; html: string }[] = [];
+  let partial: { kind: string; html: string } | null = null;
+  for (const { text, newline, level = "info", scope } of logs.slice(start)) {
+    const style = plainStyle();
+    text.split("\n").forEach((part, i) => {
+      const html = ansiLineToHtml(part, style);
+      if (newline !== false) {
+        // a message starts its own line, so a write's trailing newline leaves no blank one
+        if (i === 0 && partial?.html === "") lines.pop();
+        const prefix = i === 0 && scope ? `<span class=scope>${esc(scope)}</span> ` : "";
+        lines.push({ kind: i === 0 ? level : "more", html: prefix + html });
+      } else if (i === 0 && partial) {
+        partial.html += html;
+      } else {
+        lines.push(partial = { kind: "raw", html });
+      }
+    });
+    if (newline !== false) partial = null;
+  }
+  while (lines.at(-1)?.html === "") lines.pop();
+  return lines.slice(-maxLogLines)
+    .map(({ kind, html }) => `<div class=${kind}>${html}</div>`)
+    .join("");
+}
+
+interface Style {
+  fg: string;
+  bg: string;
+  weight: string;
+  italic: boolean;
+  underline: boolean;
+}
+const plainStyle = (): Style => ({ fg: "", bg: "", weight: "", italic: false, underline: false });
+
+const escapes = /\x1b(?:\[([\x30-\x3f]*)[\x20-\x2f]*([\x40-\x7e])|\][^\x07\x1b]*(?:\x07|\x1b\\)?|.)/g;
+
+/** one line of ansi text as html. `style` carries over, so a style may span lines. */
+function ansiLineToHtml(text: string, style: Style): string {
+  let html = "";
+  let last = 0;
+  for (const match of text.matchAll(escapes)) {
+    html += formatRun(text.slice(last, match.index), style);
+    last = match.index + match[0].length;
+    if (match[2] === "m") applySgr(style, (match[1] || "0").split(/[;:]/).map(Number));
+  }
+  return html + formatRun(text.slice(last), style);
+}
+
+function formatRun(text: string, { fg, bg, weight, italic, underline }: Style) {
+  if (!text) return "";
+  const css = (fg && `color:${fg};`) + (bg && `background:${bg};`) + weight
+    + (italic ? "font-style:italic;" : "") + (underline ? "text-decoration:underline;" : "");
+  return css ? `<span style="${css}">${esc(text)}</span>` : esc(text);
+}
+
+function applySgr(style: Style, codes: number[]) {
+  for (let i = 0; i < codes.length; i += 1) {
+    const code = UNWRAP(codes[i]);
+    if (code === 0) Object.assign(style, plainStyle());
+    else if (code === 1) style.weight = "font-weight:bold;";
+    else if (code === 2) style.weight = "opacity:.65;";
+    else if (code === 22) style.weight = "";
+    else if (code === 3 || code === 23) style.italic = code === 3;
+    else if (code === 4 || code === 24) style.underline = code === 4;
+    else if (code === 39) style.fg = "";
+    else if (code === 49) style.bg = "";
+    else if ((code >= 30 && code <= 37) || (code >= 90 && code <= 97)) {
+      style.fg = `var(--ansi${code % 10 + (code >= 90 ? 8 : 0)})`;
+    } else if ((code >= 40 && code <= 47) || (code >= 100 && code <= 107)) {
+      style.bg = `var(--ansi${code % 10 + (code >= 100 ? 8 : 0)})`;
+    } else if (code === 38 || code === 48) {
+      const indexed = codes[i + 1] === 5;
+      const [r = 0, g = 0, b = 0] = codes.slice(i + 2, i + 5);
+      const color = indexed ? color256(r) : `rgb(${r} ${g} ${b})`;
+      i += indexed ? 2 : 4;
+      if (code === 38) style.fg = color;
+      else style.bg = color;
+    }
+  }
+}
+
+function color256(n: number) {
+  if (n < 16) return `var(--ansi${n})`;
+  if (n >= 232) return `rgb(${Array(3).fill(8 + (n - 232) * 10).join(" ")})`;
+  n -= 16;
+  const level = (c: number) => c && 55 + c * 40;
+  return `rgb(${level(Math.floor(n / 36))} ${level(Math.floor(n / 6) % 6)} ${level(n % 6)})`;
+}
+
+const esc = string.escapeHtmlContent;
+
+/** inline svg for a background image */
+const svg = (body: string) =>
+  `url("data:image/svg+xml,${
+    encodeURIComponent(`<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 12 12'>${body}</svg>`)
+  }")`;
+
+// light-dark() resolves against `color-scheme`, which is inherited from the
+// host; `all: initial` keeps every other inherited property out.
+const css = /* @__PURE__ */ (() => `
+:host{display:block}
+.tree{all:initial;display:block;color-scheme:inherit;container-type:inline-size;
+  font:12px/23px "Segoe UI",system-ui,sans-serif;color:light-dark(#1e1e1e,#e3e5e8);
+  --line:light-dark(#a9b3bd,#5a626c);--muted:light-dark(#56616c,#a4aeb9);
+  --ansi0:light-dark(#000,#666);--ansi1:#cd3131;--ansi2:light-dark(#00a000,#0dbc79);
+  --ansi3:light-dark(#949800,#e5e510);--ansi4:light-dark(#0451a5,#2472c8);--ansi5:#bc3fbc;
+  --ansi6:light-dark(#0598bc,#11a8cd);--ansi7:light-dark(#555,#e5e5e5);--ansi8:#666;
+  --ansi9:light-dark(#cd3131,#f14c4c);--ansi10:light-dark(#14ce14,#23d18b);
+  --ansi11:light-dark(#b5ba00,#f5f543);--ansi12:light-dark(#0451a5,#3b8eea);
+  --ansi13:light-dark(#bc05bc,#d670d6);--ansi14:light-dark(#0598bc,#29b8db);
+  --ansi15:light-dark(#a5a5a5,#e5e5e5)}
+ol{margin:0;padding:0}
+li{display:flow-root;position:relative}
+.tree>li+li{margin-top:4px}
+.row{display:flex;flex-wrap:wrap;align-items:center;column-gap:6px;min-height:23px;white-space:nowrap}
+.label{overflow:hidden;text-overflow:ellipsis;min-width:0}
+.tree>li>.row>.label{font-size:13px;color:light-dark(#039,#8fb4ff)}
+.count,.eta{flex:none;margin:4px 0;padding:0 6px;border-radius:8px;font-size:11px;line-height:15px;
+  font-variant-numeric:tabular-nums;color:var(--muted);
+  background:linear-gradient(light-dark(#fdfeff,#363b43),light-dark(#edf1f5,#2b3037));
+  box-shadow:inset 0 0 0 1px light-dark(#d5dce4,#40474f)}
+.count:has(>b:empty),.eta:empty{display:none}
+.count>b{font-weight:600;color:light-dark(#2c3640,#d5dbe1)}
+.count>span:not(:empty)::before{content:"/";margin:0 .2em;opacity:.55}
+
+/* bars lead the row, wider at the top level, as in the terminal. the track is
+   a 1px frame, 6px of gloss, a stretched body, and 5px of bottom light */
+.tree>li{--bar:176}
+li li{--bar:96}
+@container (width < 400px){.tree>li{--bar:112}li li{--bar:64}}
+.bar>.row>.indicator{position:relative;flex:none;box-sizing:border-box;width:calc(var(--bar) * 1px);
+  height:15px;margin:4px 0;border:1px solid transparent;border-radius:2px;
+  background:
+    linear-gradient(light-dark(#f3f3f3,#34383e),light-dark(#fcfcfc,#3b3f45) 1.5px,
+      light-dark(#dbdbdb,#2f3237) 6px,light-dark(#cacaca,#26292d) 6px,
+      light-dark(#cacaca,#26292d) calc(100% - 5px),light-dark(#d5d5d5,#2b2e33) calc(100% - 1px),
+      light-dark(#eaeaea,#33373c)) padding-box,
+    linear-gradient(light-dark(#b2b2b2,#4b5058) 0 1px,light-dark(#bdbdbd,#464b53) 1px,
+      light-dark(#919191,#393d44) calc(100% - 1px),light-dark(#8c8c8c,#393d44) calc(100% - 1px))
+      border-box}
+.indicator>i{position:absolute;top:0;bottom:0;left:0;width:calc(var(--p) * 100%);overflow-x:clip;
+  --gloss:#d2f1fc 1.5px,#addcf3 3.5px,#9ad3ef;--body:#0794d1;--rest:#1ea0d8;--edge:#035f8f;
+  --glow:160 225 255;--shade:color-mix(in srgb,var(--edge) 40%,#0000);
+  background:
+    linear-gradient(90deg,#0000 1px,var(--shade) 1px,var(--shade) 5px,#0000 27px),
+    linear-gradient(270deg,#0000 1px,var(--shade) 1px,#0000 14px),
+    linear-gradient(var(--gloss) 6px,var(--body) 6px,var(--body) calc(100% - 5px),var(--rest));
+  transition:width var(--glide,0s) linear}
+/* a glow sweeps the fill at one speed for every bar, over the frame too, while
+   the bottom light swells under it */
+.indicator>i::before{content:"";position:absolute;left:0;right:0;bottom:0;height:5px;
+  background:linear-gradient(#0000,rgb(var(--glow)/.6));animation:swell 2.4s ease-in-out infinite}
+.indicator>i::after{content:"";position:absolute;top:-1px;bottom:-1px;left:0;width:64px;
+  background:linear-gradient(90deg,#0000,rgb(var(--glow)/.03) 8.3%,rgb(var(--glow)/.08) 16.7%,
+    rgb(var(--glow)/.2) 25%,rgb(var(--glow)/.36) 33.3%,rgb(var(--glow)/.53) 41.7%,
+    rgb(var(--glow)/.6),rgb(var(--glow)/.53) 58.3%,rgb(var(--glow)/.36) 66.7%,
+    rgb(var(--glow)/.2) 75%,rgb(var(--glow)/.08) 83.3%,rgb(var(--glow)/.03) 91.7%,#0000);
+  animation:glow 2.4s linear infinite}
+@keyframes glow{from{translate:-100%}50%,to{translate:176px}}
+@keyframes swell{from{opacity:.4}25%{opacity:1}65%,88%{opacity:0}to{opacity:.4}}
+:is(.full,li:has(>.logs>:is(.warn,.error)))>.row>.indicator>i::before,
+:is(.full,li:has(>.logs>:is(.warn,.error)))>.row>.indicator>i::after{content:none}
+li:has(>.logs>.warn)>.row>.indicator>i{
+  --gloss:#fffdcd 1.5px,#fffba1 3.5px,#fffa8b;--body:#d2ca00;--rest:#fef400;--edge:#8f8600}
+li:has(>.logs>.error)>.row>.indicator>i{
+  --gloss:#ffcdcd 1.5px,#ffa1a1 3.5px,#ff8b8b;--body:#d20000;--rest:#fe0000;--edge:#8f0000}
+
+/* the busy ring leads a top-level row, lit from above, with a highlight
+   running clockwise; below the top level the terminal shows no spinner */
+.spin>.row>.indicator{position:relative;flex:none;width:15px;height:15px;margin:4px 0;border-radius:50%;
+  background:conic-gradient(#9bc6da,#8dc2d0 30deg,#6daebd 60deg,#2b8982 90deg,#319f9d 120deg,
+    #4dc7bb 150deg,#5ecfc5 180deg,#4fc6bb 210deg,#2da09e 240deg,#238382 270deg,#6db2bb 300deg,
+    #91c5d1 330deg,#9bc6da);
+  mask:radial-gradient(closest-side,#0000 61%,#000 67%)}
+li li.spin>.row>.indicator{display:none}
+.spin>.row>.indicator::before,.spin>.row>.indicator::after{content:"";position:absolute;inset:0;border-radius:50%}
+.spin>.row>.indicator::before{animation:spin .9s linear infinite;
+  background:conic-gradient(from -150deg,#0000,#2fd4dc99 40deg,#4fe6eae6 90deg,#8ff3f4 125deg,
+    #e8fcfd 150deg,#b4eef0b3 162deg,#0000 180deg)}
+.spin>.row>.indicator::after{background:radial-gradient(closest-side,#00323c73 64%,#00323c00 76%,
+  #fff3 86%,#00323c00 92%,#00323c80)}
+.spin>.row>.indicator>i{display:none}
+@keyframes spin{to{rotate:1turn}}
+
+/* tree lines: a node's children hang from the start of its row, and each child
+   is drawn with the terminal's ├─, │ and └─ */
+li li{padding-left:22px}
+li>ol{position:relative}
+li>ol:not(:empty)::before{content:"";position:absolute;left:7px;top:-4px;height:5px;
+  border-left:1px solid var(--line)}
+li li::before,li li::after{content:"";position:absolute;left:7px;border:0 solid var(--line)}
+li li::before{top:0;bottom:-1px;border-left-width:1px}
+li li::after{top:11px;width:11px;border-top-width:1px}
+li li:last-child::before{bottom:auto;height:12px}
+
+.logs{margin:1px 0 4px;padding:3px 8px;border-radius:4px;
+  background:light-dark(#f3f5f8,#24282e);box-shadow:inset 0 0 0 1px light-dark(#e1e6ec,#31363d);
+  font:11px/16px ui-monospace,"Cascadia Mono",Consolas,"SF Mono",Menlo,monospace;color:var(--muted)}
+.logs:empty{display:none}
+.logs>div{overflow:hidden;text-overflow:ellipsis;white-space:pre}
+.logs>.more{padding-left:16px}
+.logs>.debug{opacity:.7}
+.logs>:is(.info,.warn,.error)::before{content:"";display:inline-block;width:11px;height:11px;
+  margin-right:5px;vertical-align:-2px;background:center/contain no-repeat}
+.logs>.info::before{background-image:${
+  svg(
+    "<defs><radialGradient id='g' cx='.35' cy='.3' r='.8'><stop stop-color='#7cbaf6'/><stop offset='1' stop-color='#1557b8'/></radialGradient></defs><circle cx='6' cy='6' r='5.5' fill='url(#g)' stroke='#0c3f8c' stroke-width='.6'/><rect x='5.25' y='5' width='1.5' height='4.2' rx='.5' fill='#fff'/><circle cx='6' cy='3.3' r='.9' fill='#fff'/>",
+  )
+}}
+.logs>.warn::before{background-image:${
+  svg(
+    "<defs><linearGradient id='g' x2='0' y2='1'><stop stop-color='#ffe680'/><stop offset='1' stop-color='#f0b400'/></linearGradient></defs><path d='M6 .8l5.4 10H.6z' stroke-linejoin='round' fill='url(#g)' stroke='#b58300' stroke-width='.7'/><rect x='5.3' y='4' width='1.4' height='3.8' rx='.5' fill='#333'/><circle cx='6' cy='9.2' r='.8' fill='#333'/>",
+  )
+}}
+.logs>.error::before{background-image:${
+  svg(
+    "<defs><radialGradient id='g' cx='.35' cy='.3' r='.8'><stop stop-color='#ff8a80'/><stop offset='1' stop-color='#c41a1a'/></radialGradient></defs><circle cx='6' cy='6' r='5.5' fill='url(#g)' stroke='#8a0f0f' stroke-width='.6'/><path d='M4 4l4 4m0-4l-4 4' stroke='#fff' stroke-width='1.5' stroke-linecap='round'/>",
+  )
+}}
+.scope{color:light-dark(#7a6a9e,#b5a6d8)}
+
+@media (prefers-reduced-motion:reduce){
+  .indicator>i{transition:none}
+  .indicator>i::before,.indicator>i::after{content:none}
+  .spin>.row>.indicator::before{animation:pulse 1.8s ease-in-out infinite alternate}
+}
+@keyframes pulse{from{opacity:.25}}
+@media (forced-colors:active){
+  .indicator{forced-color-adjust:none}
+  .bar>.row>.indicator{background:Canvas;border-color:CanvasText}
+  .indicator>i{background:Highlight}
+  .indicator>i::before,.indicator>i::after{content:none}
+  .spin>.row>.indicator{background:Highlight}
+}
+`)();
+
 const header = /* @__PURE__ */ string.encodeUtf8("clover's progress <3\n");
 
 /** the 'Content-Type' of {@linkcode encodeByteStream}'s return value */
@@ -1524,6 +1952,7 @@ function writeStreamEvent(
         if (level === -1) level = 0;
         w.u8(
           level
+            + (msg.newline === false ? 1 << 4 : 0)
             + (msg.scope ? 1 << 5 : 0)
             + (msg.stack && msg.stack.length > 0 ? 1 << 6 : 0)
             + (msg.custom !== undefined ? 1 << 7 : 0),
@@ -1543,7 +1972,6 @@ function writeStreamEvent(
         if (msg.custom !== undefined) {
           w.stringWithLength(JSON.stringify(msg.custom));
         }
-        // TODO: serialize newline attribute
       }
     }
     if (childrenSet !== undefined) {
@@ -1655,6 +2083,7 @@ async function readStreamEvent(r: stream.BufferedReader): Promise<StreamEvent> {
         // bitwise tests: `msgFlags && (1 << 5) > 0` parsed as
         // `msgFlags && true`, which fabricated scope/stack/custom reads for
         // any message with a non-zero level and desynced the entire stream
+        const partial = (msgFlags & (1 << 4)) !== 0;
         const hasScope = (msgFlags & (1 << 5)) !== 0;
         const hasStack = (msgFlags & (1 << 6)) !== 0;
         const hasCustom = (msgFlags & (1 << 7)) !== 0;
@@ -1681,7 +2110,7 @@ async function readStreamEvent(r: stream.BufferedReader): Promise<StreamEvent> {
         const custom = hasCustom
           ? JSON.parse(await r.stringWithLength())
           : undefined;
-        l.push({ level, text, time, scope, stack, custom });
+        l.push({ level, text, time, scope, stack, custom, newline: partial ? false : undefined });
       }
     }
     let c: undefined | EncodedKey[] = undefined;
@@ -1945,6 +2374,7 @@ import { Events } from "./Events.ts";
 import * as exceptions from "./exception.ts";
 import * as log from "./log.ts";
 import * as stack from "./log/stack.ts";
+import * as math from "./math.ts";
 import * as node from "./node.ts";
 import * as stream from "./stream.ts";
 import * as string from "./string.ts";
diff --git a/lib/readme.changes.md b/lib/readme.changes.md
index 6a8ebf9dd08b4fc7c4d505e164292ed9d3d5f9e8..229bc459cf3f622213bc0d56552fa436e938e24a 100644
--- a/lib/readme.changes.md
+++ b/lib/readme.changes.md
@@ -19,6 +19,8 @@
   - finally fixes resize corruptions for long running widgets
 - `string/ansi`: add `inverse`, `resetInverse`, and `cursorHome`.
 - `meta` auto-embed will now set `twitter:url`.
+- `progress.attachToDocument` draws progress in the browser, and
+  `progress.formatHtml` renders the same markup for server rendering.
 
 ### fixes
 
@@ -26,6 +28,9 @@
   caller error handling.
 - `progress`: `StartOptions.messages` is no longer ignored, so a decoded stream
   keeps the logs that a node had when it started.
+- `progress`: the byte stream keeps partial writes (`node.log.write`) apart from
+  log messages, and the terminal no longer draws a hidden top-level node.
+- `Events`: disposing a listener no longer removes the listeners added after it.
 
 ## v7
 
diff --git a/lib/readme.md b/lib/readme.md
index 9489679af246793d5943e825b1bd44cb8e625553..b4299c3d9777be15d16c1761006e0d423f21c3a4 100644
--- a/lib/readme.md
+++ b/lib/readme.md
@@ -25,7 +25,7 @@ depend on each other. there are no external dependencies; code is easy to audit.
 - `math` - trivial helpers
 - `mime` - trimmed database of ext -> mime types
 - `node` - the Node.js javascript runtime
-- `progress` - cli progress bars, nesting status indication
+- `progress` - cli and dom progress bars, nesting status indication
 - `queue` - priority queue with rescheduling
 - `repl` - interactive prompt for long running programs
 - `stream` - ReadableStream helpers
-- 
2.54.0