task_progress 0.0.1

data/js/local_tasks.d.ts

@@ -0,0 +1,44 @@
+import type { Batch, Node, Status, Path } from "./task_tree.js"
+
+export interface LocalTaskOptions {
+  total?: number
+  weight?: number
+  expect?: number
+  indeterminate?: boolean
+  unit?: string
+  cancelable?: boolean
+  autofinish?: boolean
+}
+
+/** Tasks that run in this browser, grafted under a server task with TaskTree#graft */
+export class LocalTasks {
+  constructor(name: string, options?: LocalTaskOptions & { clock?: () => number })
+  readonly log: string
+  readonly root: LocalTask
+  subscribe(fn: (batch: Batch) => void): () => void
+  squash(): Batch
+  at(path: Path): LocalTask | null
+}
+
+export class LocalTask {
+  readonly path: Path
+  readonly node: Node
+  readonly status: Status
+  readonly finished: boolean
+  readonly canceled: boolean
+  /** Aborts when the task is canceled - for fetch, say */
+  readonly signal: AbortSignal
+  subtask(name: string, options?: LocalTaskOptions): LocalTask | null
+  advance(by?: number, options?: { message?: string }): this
+  tick(options?: { message?: string }): this
+  update(percent: number, options?: { message?: string }): this
+  note(message: string): this
+  setTotal(total: number): this
+  done(): this
+  fail(error?: unknown): this
+  cancel(reason?: string): this
+  onCancel(handler: (reason?: string) => void): this
+  whenFinished(): Promise<Status>
+}
+
+export function trackUpload(xhr: XMLHttpRequest, task: LocalTask, options?: { abortOnCancel?: boolean }): LocalTask

data/js/local_tasks.js

@@ -0,0 +1,229 @@
+// Tasks that run in this browser - hashing files before an upload, say - written the way the
+// server writes its own: every change a batch, numbered, folded into a tree. Graft them under a
+// server task with TaskTree#graft and the renderers draw them as its children.
+//
+//   const work = new LocalTasks("Hash files", { cancelable: true })
+//   tree.graft(serverTask.path, work)
+//   const file = work.root.subtask("video.mp4", { total: blob.size, unit: "bytes" })
+//   file.onCancel(() => controller.abort())
+//   file.advance(chunk.byteLength)
+//
+// The rules are the server's: a counted task is done at its total, done() closes everything
+// still open under it, fail() and cancel() cancel it. Changing a task that has ended does
+// nothing - check `canceled` in loops that would otherwise carry on.
+//
+// Ids start with "_", which a server id never does, so a graft cannot clash with the tree it
+// is grafted to, and a task can tell it runs here.
+
+import { TaskTree } from "./task_tree.js"
+
+const FINISHED = new Set(["done", "failed", "canceled"])
+const randomId = (length) => "_" + Array.from({ length }, () => Math.floor(Math.random() * 36).toString(36)).join("")
+
+const attributes = ({ name, total, weight, expect, indeterminate, unit, cancelable }) =>
+  Object.fromEntries(Object.entries({ name, total, weight, expect, indeterminate: indeterminate || undefined, unit, cancelable: cancelable || undefined })
+    .filter(([, value]) => value !== undefined && value !== null))
+
+export class LocalTasks {
+  constructor(name, { clock = () => Date.now() / 1000, autofinish = true, ...options } = {}) {
+    this.log = randomId(10)
+    this.seq = 0
+    this.clock = clock
+    this.tree = new TaskTree({ clock })
+    this.listeners = new Set()
+    this.handlers = new Map() // key -> [onCancel callbacks]
+    this.waiting = new Map() // key -> [whenFinished resolvers]
+    this.signals = new Map() // key -> AbortSignal, made on first ask
+    this.autofinish = new Map()
+    this.commit([[[], "open", attributes({ name, ...options })]])
+    this.autofinish.set("", autofinish)
+    this.root = new LocalTask(this, [])
+  }
+
+  // Calls fn(batch) with every batch from now on. Returns a function that stops it
+  subscribe(fn) {
+    this.listeners.add(fn)
+    return () => this.listeners.delete(fn)
+  }
+
+  // The tree so far as one batch of puts, prev 0 - what a graft starts from
+  squash() {
+    const ops = [...this.tree.each()].map((node) => [node.path, "put", putValue(node)])
+    return { v: 1, log: this.log, prev: 0, seq: this.seq, at: this.clock(), ops }
+  }
+
+  commit(ops) {
+    if (ops.length === 0) return
+    const batch = { v: 1, log: this.log, prev: this.seq, seq: this.seq + 1, at: this.clock(), ops }
+    this.tree.apply(batch)
+    this.seq = batch.seq
+    for (const listener of this.listeners) listener(batch)
+    for (const [path, op, reason] of ops) {
+      if (op !== "cancel" && op !== "done" && op !== "fail") continue
+      const key = path.join("-")
+      const handlers = this.handlers.get(key) ?? []
+      this.handlers.delete(key)
+      if (op === "cancel") for (const handler of handlers) handler(reason ?? null)
+      for (const resolve of this.waiting.get(key) ?? []) resolve(this.tree.get(path).status)
+      this.waiting.delete(key)
+    }
+  }
+
+  newId() {
+    let id
+    do id = randomId(4)
+    while ([...this.tree.nodes.values()].some((node) => node.path[node.path.length - 1] === id))
+    return id
+  }
+
+  // The task at `path`, or null
+  at(path) { return this.tree.get(path) ? new LocalTask(this, path) : null }
+
+  // Every task under `path` still open, deepest first
+  openUnder(path) {
+    const node = this.tree.get(path)
+    return [...this.tree.each(node)].slice(1).filter((n) => !FINISHED.has(n.status)).map((n) => n.path).reverse()
+  }
+}
+
+class LocalTask {
+  constructor(tasks, path) {
+    this.tasks = tasks
+    this.path = path
+  }
+
+  get node() { return this.tasks.tree.get(this.path) }
+  get status() { return this.node.status }
+  get finished() { return FINISHED.has(this.status) }
+  get canceled() { return this.status === "canceled" }
+
+  subtask(name, { autofinish = true, ...options } = {}) {
+    if (this.finished) return null
+    const path = [...this.path, this.tasks.newId()]
+    this.tasks.commit([[path, "open", attributes({ name, ...options })]])
+    this.tasks.autofinish.set(path.join("-"), autofinish)
+    return new LocalTask(this.tasks, path)
+  }
+
+  advance(by = 1, { message } = {}) {
+    if (this.finished) return this
+    const ops = [[this.path, "add", by]]
+    if (message != null) ops.push([this.path, "note", message])
+    const { count, total } = this.node
+    if (this.tasks.autofinish.get(this.path.join("-")) && total != null && count + by >= total) ops.push(...this.#closing("done"))
+    this.tasks.commit(ops)
+    return this
+  }
+
+  tick(options) { return this.advance(1, options) }
+
+  update(percent, { message } = {}) {
+    if (this.finished) return this
+    const ops = message != null ? [[this.path, "note", message]] : []
+    ops.push(...(percent >= 100 ? this.#closing("done") : [[this.path, "set", percent]]))
+    this.tasks.commit(ops)
+    return this
+  }
+
+  note(message) {
+    if (!this.finished) this.tasks.commit([[this.path, "note", message]])
+    return this
+  }
+
+  // An AbortSignal that aborts, with the reason, once this task is canceled. Nothing is wired
+  // to it: a cancel stops only what you hand it to - `fetch(url, { signal: task.signal })`
+  get signal() {
+    const key = this.path.join("-")
+    if (!this.tasks.signals.has(key)) {
+      const controller = new AbortController()
+      this.tasks.signals.set(key, controller.signal)
+      this.onCancel((reason) => controller.abort(reason ?? "Canceled"))
+    }
+    return this.tasks.signals.get(key)
+  }
+
+  // Resolves with "done", "failed" or "canceled" once the task ends - at once, if it has
+  whenFinished() {
+    if (this.finished) return Promise.resolve(this.status)
+    const key = this.path.join("-")
+    return new Promise((resolve) => this.tasks.waiting.set(key, [...(this.tasks.waiting.get(key) ?? []), resolve]))
+  }
+
+  // For a total only learned once the work has started - the size of an upload, say
+  setTotal(total) {
+    if (!this.finished) this.tasks.commit([[this.path, "meta", { total }]])
+    return this
+  }
+
+  done() {
+    if (!this.finished) this.tasks.commit(this.#closing("done"))
+    return this
+  }
+
+  fail(error) {
+    if (this.finished) return this
+    const value = { class: error?.name ?? "Error", message: String(error?.message ?? error ?? `${this.node.name} failed`) }
+    this.tasks.commit([...this.tasks.openUnder(this.path).map((path) => [path, "cancel"]), [this.path, "fail", value]])
+    return this
+  }
+
+  cancel(reason) {
+    if (!this.finished) this.tasks.commit(this.#closing("cancel", reason))
+    return this
+  }
+
+  // Runs once this task is canceled - at once, if it already was. Hook an AbortController here
+  onCancel(handler) {
+    if (this.canceled) handler(this.node.message)
+    else if (!this.finished) {
+      const key = this.path.join("-")
+      this.tasks.handlers.set(key, [...(this.tasks.handlers.get(key) ?? []), handler])
+    }
+    return this
+  }
+
+  // done closes what is still open under it with a done of its own, cancel with a cancel
+  #closing(op, value) {
+    const own = op === "cancel" && value != null ? [this.path, op, value] : [this.path, op]
+    return [...this.tasks.openUnder(this.path).map((path) => (value != null ? [path, op, value] : [path, op])), own]
+  }
+}
+
+// Tracks an XMLHttpRequest's upload with a task: its count is the bytes sent, its total the
+// body's size, learned from the first progress event. A 2xx response finishes it; any other
+// status, a network error or a timeout fails it, and an abort cancels it. Call it before
+// `xhr.send`, which is when the progress events start.
+//
+// It only reports. Whether canceling the task - its cancel button, or the server task it is
+// grafted under ending badly - stops the upload is yours to say: `abortOnCancel: true` aborts
+// the request then
+//
+//   const xhr = new XMLHttpRequest()
+//   xhr.open("PUT", url)
+//   trackUpload(xhr, work.root.subtask(file.name, { unit: "bytes", cancelable: true }), { abortOnCancel: true })
+//   xhr.send(file)
+export function trackUpload(xhr, task, { abortOnCancel = false } = {}) {
+  // All the bytes out is not the upload done, so the count reaching the total must not finish it
+  task.tasks.autofinish.set(task.path.join("-"), false)
+  let sent = 0
+  xhr.upload.addEventListener("progress", (event) => {
+    if (event.lengthComputable && task.node.total == null) task.setTotal(event.total)
+    if (event.loaded > sent) task.advance(event.loaded - sent)
+    sent = Math.max(sent, event.loaded)
+  })
+  xhr.addEventListener("load", () => {
+    if (xhr.status >= 200 && xhr.status < 300) task.done()
+    else task.fail(new Error(`The server answered ${xhr.status}${xhr.statusText ? ` ${xhr.statusText}` : ""}`))
+  })
+  xhr.addEventListener("error", () => task.fail(new Error("The upload failed - the network, or the server going away")))
+  xhr.addEventListener("timeout", () => task.fail(new Error("The upload timed out")))
+  xhr.addEventListener("abort", () => task.cancel("Aborted"))
+  if (abortOnCancel) task.onCancel(() => xhr.abort())
+  return task
+}
+
+const FIELDS = ["name", "total", "count", "percent", "weight", "expect", "indeterminate", "unit", "cancelable", "attempt", "message", "status", "error", "stale", "opened_at", "started_at", "finished_at"]
+
+function putValue(node) {
+  return Object.fromEntries(FIELDS.filter((field) => node[field] !== null && node[field] !== undefined && node[field] !== false).map((field) => [field, node[field]]))
+}

data/js/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "task_progress",
+  "private": true,
+  "version": "0.0.1",
+  "description": "The browser half of the task_progress gem, vendored from it - see `task_progress vendor`",
+  "license": "MIT",
+  "type": "module",
+  "repository": { "type": "git", "url": "git+https://github.com/julik/task_progress.git", "directory": "js" },
+  "homepage": "https://github.com/julik/task_progress",
+  "exports": {
+    ".": { "types": "./task_tree.d.ts", "default": "./task_tree.js" },
+    "./react": { "types": "./react_task_tree.d.ts", "default": "./react_task_tree.js" },
+    "./stimulus": { "types": "./stimulus_controller.d.ts", "default": "./stimulus_controller.js" },
+    "./local_tasks": { "types": "./local_tasks.d.ts", "default": "./local_tasks.js" },
+    "./row_view": { "types": "./row_view.d.ts", "default": "./row_view.js" },
+    "./clock": { "types": "./task_progress_clock.d.ts", "default": "./task_progress_clock.js" },
+    "./task_tree.css": "./task_tree.css"
+  },
+  "files": ["*.js", "*.d.ts", "*.css"],
+  "sideEffects": ["./task_progress_clock.js", "*.css"],
+  "peerDependencies": {
+    "@hotwired/stimulus": ">=3",
+    "react": ">=18",
+    "react-dom": ">=18"
+  },
+  "peerDependenciesMeta": {
+    "@hotwired/stimulus": { "optional": true },
+    "react": { "optional": true },
+    "react-dom": { "optional": true }
+  }
+}

data/js/paths.d.ts

@@ -0,0 +1,5 @@
+/** A task's place in the tree: its ancestors' ids, then its own - `[]` is the root */
+export type Path = string[]
+/** A path's key - its ids joined with a dash, `""` for the root */
+export function pathKey(path: Path): string
+export function pathFromKey(key: string): Path

data/js/paths.js

@@ -0,0 +1,7 @@
+// A path as one string: its ids joined with a dash. Ids are [0-9a-z], so a dash never occurs in
+// one, and the key needs no escaping in a URL, a class name or a data attribute. The root's key
+// is the empty string - where it has to be seen, call it "root". As a DOM id, prefix it: an id
+// that starts with a digit needs CSS.escape in a selector
+export const pathKey = (path) => path.join("-")
+
+export const pathFromKey = (key) => (key === "" ? [] : key.split("-"))

data/js/react_task_tree.d.ts

@@ -0,0 +1,49 @@
+import type { ReactElement } from "react"
+import type { TaskTree, Progress, Path } from "./task_tree.js"
+import type { RowView } from "./row_view.js"
+import type { LocalTasks } from "./local_tasks.js"
+
+export type { Progress } from "./task_tree.js"
+export type { RowView } from "./row_view.js"
+
+export interface Graft { path: Path; local: LocalTasks }
+
+export interface FollowOptions {
+  transport?: "auto" | "sse" | "poll"
+  /** Seconds between polls */
+  poll?: number
+  /** Seconds to long-poll */
+  wait?: number
+  grafts?: Graft[]
+  /** Called once, when the root is done - `() => router.reload({ only: ["video"] })` */
+  onComplete?: (tree: TaskTree) => void
+  /** Called once, when the root failed or was canceled */
+  onFail?: (tree: TaskTree) => void
+}
+
+export interface UseTaskTree {
+  tree: TaskTree | null
+  rows: RowView[]
+  /** Asks for the row's task to be canceled; resolves false if it could not ask */
+  cancel(row: RowView): Promise<boolean | undefined> | boolean | undefined
+  canCancel: boolean
+}
+
+/** Follows what TaskProgress.for_page hands a page, the url of an SSE stream or Poll endpoint, or tasks running in this browser */
+export function useTaskTree(source: Progress | string | LocalTasks | null | undefined, options?: FollowOptions): UseTaskTree
+
+export interface TaskTreeViewProps extends FollowOptions {
+  progress?: Progress
+  url?: string
+  /** Tasks running in this browser, drawn on their own */
+  local?: LocalTasks
+  cancelUrl?: string
+  cancelToken?: string
+  /** Return false to release the button */
+  onCancel?: (row: RowView) => unknown
+}
+
+/** The rows, for an element of yours with the `tree` class around them */
+export function TaskTreeView(props: TaskTreeViewProps): ReactElement | null
+
+export function createTaskTreeRoot(element: Element): { render(props: TaskTreeViewProps): void; unmount(): void }

data/js/react_task_tree.js

@@ -0,0 +1,123 @@
+import React, { useEffect, useRef, useState } from "react"
+import { createRoot } from "react-dom/client"
+import { followEventSourceAt, followLocal, followPollingAt, followProgress, requestCancel } from "./task_tree.js"
+import { rowView, CANCEL_ICON } from "./row_view.js"
+
+// No JSX, so it runs as it is - in a Vite app, or straight off an import map with no build step
+const h = React.createElement
+
+const NO_GRAFTS = []
+const FINISHED = new Set(["done", "failed", "canceled"])
+
+// Follows a tree: what TaskProgress.for_page hands a page - { events, poll, cancel, snapshot },
+// drawn from its snapshot at once - or the url of a TaskProgress::SSE stream, or of a
+// TaskProgress::Poll endpoint given `poll` (seconds between polls) or `wait` (seconds to
+// long-poll). `transport` picks for a for_page object, see followProgress. Or a LocalTasks, for
+// tasks that run in this browser alone - uploads, say - drawn as they change, with no server.
+//
+// Returns { tree, rows, cancel }: the tree, what to draw (see rowView), and a function that asks
+// for a row's task to be canceled - a task running in this browser is canceled here. `onComplete`
+// and `onFail` are called once, when the root has finished one way or the other - for an
+// Inertia page, `onComplete: () => router.reload({ only: ["video"] })`. `grafts` - [{ path, local }]
+// - draws tasks running in this browser under server tasks, see TaskTree#graft
+export function useTaskTree(source, { transport, poll = 0, wait = 0, grafts = NO_GRAFTS, onComplete, onFail } = {}) {
+  const [state, setState] = useState({ tree: null, version: 0 })
+  const callbacks = useRef({})
+  callbacks.current = { onComplete, onFail }
+  const local = typeof source?.subscribe === "function" ? source : null
+  const progress = typeof source === "string" || local ? null : source
+  const url = typeof source === "string" ? source : null
+  // A for_page object is a new object every render; what it points at is what matters
+  const followKey = local ? local.log : progress ? `${progress.events} ${progress.poll}` : url
+  useEffect(() => {
+    setState({ tree: null, version: 0 })
+    if (!followKey) return
+    let told = false
+    const draw = (tree) => {
+      setState((s) => ({ tree, version: s.version + 1 }))
+      const status = tree.root?.status
+      if (told || !FINISHED.has(status)) return
+      told = true
+      if (status === "done") callbacks.current.onComplete?.(tree)
+      else callbacks.current.onFail?.(tree)
+    }
+    const following = local
+      ? followLocal(local, draw)
+      : progress
+      ? followProgress(progress, draw, { transport, poll: poll || 1, wait })
+      : poll || wait ? followPollingAt(url, draw, { poll: poll || 1, wait }) : followEventSourceAt(url, draw)
+    return () => following.close()
+  }, [followKey, transport, poll, wait]) // eslint-disable-line react-hooks/exhaustive-deps
+  // Keyed on what the grafts are, not on the array: one written inline is a new array every
+  // render, and grafting anew draws again - which would render again, every frame, for ever
+  const graftsKey = grafts.map(({ path, local }) => `${path.join("-")}:${local.log}`).join(" ")
+  useEffect(() => {
+    if (!state.tree) return
+    const ungrafts = grafts.map(({ path, local }) => state.tree.graft(path, local))
+    return () => ungrafts.forEach((ungraft) => ungraft())
+  }, [state.tree, graftsKey]) // eslint-disable-line react-hooks/exhaustive-deps
+  const { tree } = state
+  const rows = tree ? [...tree.rows()].map((node) => rowView(tree, node)) : []
+  const cancelUrl = progress?.cancel
+  const cancel = async (row) => {
+    if (row.local) return tree?.cancelLocal(row.path, "Canceled in this browser")
+    if (!cancelUrl) return false
+    try { return (await requestCancel(cancelUrl, row.path)).ok } catch { return false }
+  }
+  return { tree, rows, cancel: cancelUrl ? cancel : (row) => (row.local ? cancel(row) : false), canCancel: !!cancelUrl }
+}
+
+// A cancel button, right of the bar. It stays pressed until the cancel comes down the stream -
+// the row is then not cancelable any more, and the button hides. Hidden, it keeps its place
+function CancelButton({ row, onCancel, offered }) {
+  const [pressed, setPressed] = useState(false)
+  const press = async () => {
+    setPressed(true)
+    if ((await onCancel(row)) === false) setPressed(false)
+  }
+  return h("button", {
+    type: "button", className: "cancel", hidden: !(offered && row.cancelable), disabled: pressed,
+    "aria-label": `Cancel ${row.name}`, onClick: press, dangerouslySetInnerHTML: { __html: CANCEL_ICON }
+  })
+}
+
+function Row({ row, onCancel, offered }) {
+  return h("div", { className: `row ${row.status}${row.stale ? " stale" : ""}${row.folded ? " folded" : ""}` },
+    h("div", { className: "label", style: { paddingLeft: row.depth * 18 } },
+      h("span", { className: "icon", dangerouslySetInnerHTML: { __html: row.icon } }),
+      h("span", { className: "name" }, row.name),
+      h("span", { className: "message" }, row.message)),
+    h("div", { className: `bar${row.indeterminate ? " indeterminate" : ""}` }, h("span", { style: { width: `${row.percent}%` } })),
+    h(CancelButton, { row, onCancel, offered }),
+    h("div", { className: "measure" }, row.measure))
+}
+
+// The tree as rows, styled by task_tree.css. Give it `progress` - what TaskProgress.for_page
+// hands a page - or a `url`, as useTaskTree takes them, or `local`, a LocalTasks. With a `url`, `cancelUrl` and
+// `cancelToken` say where cancel buttons ask; with `progress` they ask where it says. For
+// anything else, pass `onCancel(row)` - return false from it to release the button. `onComplete`
+// and `onFail` are called once the root has finished
+export function TaskTreeView({ progress, url, local, cancelUrl, cancelToken, onCancel, onComplete, onFail, grafts, transport, poll, wait }) {
+  const { tree, rows, cancel, canCancel } = useTaskTree(local ?? progress ?? url, { transport, poll, wait, grafts, onComplete, onFail })
+  if (!tree) return null
+  const remote = !progress && cancelUrl && (async (row) => {
+    try { return (await requestCancel(cancelUrl, row.path, { token: cancelToken })).ok } catch { return false }
+  })
+  const onPress = onCancel ?? ((row) => (row.local || !remote ? cancel(row) : remote(row)))
+  // A server task can only be asked to cancel where there is somewhere to ask
+  const offered = (row) => !!(onCancel || canCancel || remote || row.local)
+  // Rows alone, for an element of yours with the `tree` class around them
+  return h(React.Fragment, null, rows.map((row) => h(Row, { key: row.key, row, onCancel: onPress, offered: offered(row) })))
+}
+
+// For pages that are not React apps, as React's own createRoot: render it into an element, and
+// render again with other props - another url, `poll` - to change what it follows
+//
+//   createTaskTreeRoot(element).render({ progress })   // or { url: "/jobs/42/progress" }
+export function createTaskTreeRoot(element) {
+  const root = createRoot(element)
+  return {
+    render: (props) => root.render(h(TaskTreeView, props)),
+    unmount: () => root.unmount()
+  }
+}

data/js/render_queue.d.ts

@@ -0,0 +1,24 @@
+import type { TaskTree } from "./task_tree.js"
+
+/** What changed since the last draw - see "Drawing once a frame" in the MANUAL */
+export interface Changes {
+  batches: number
+  /** Keys of the nodes changed, and every one above them */
+  touched: Set<string>
+  /** What a renderer must not miss, in order: done, fail, cancel, say, reset, gap */
+  events: Array<{ op: string; path: string[]; value?: unknown }>
+  /** Rows came, went or moved */
+  structure: boolean
+  local: boolean
+}
+
+export type Schedule = (draw: () => void) => void
+export const nextFrame: Schedule
+
+export class RenderQueue {
+  constructor(tree: TaskTree, onFrame: (tree: TaskTree, changes: Changes) => void, options?: { schedule?: Schedule })
+  apply(batch: Batch): ApplyOutcome
+  close(): void
+}
+
+import type { Batch, ApplyOutcome } from "./task_tree.js"

data/js/render_queue.js

@@ -0,0 +1,79 @@
+// A stream can carry thousands of batches a second, far more than a screen can show. Every batch is
+// still folded into the tree as it arrives - the seq chain and the parity with Ruby depend on that -
+// but the renderer gets called at most once a frame, with what changed since the last call.
+//
+// A set, add or note only matters for the state it leaves behind, so those collapse into the paths
+// they touched. What a renderer must hear about even when a later batch in the same frame hides it
+// goes into `events`, in order: done, fail (with the error) and cancel, say lines (the tree never holds
+// them), and the stream starting over (reset) or breaking off (gap).
+
+import { pathKey as key } from "./paths.js"
+
+// requestAnimationFrame follows the display and pauses in a background tab; Node has neither
+export const nextFrame = globalThis.requestAnimationFrame
+  ? (fn) => globalThis.requestAnimationFrame(fn)
+  : (fn) => setTimeout(fn, 16)
+
+const STRUCTURAL = new Set(["open", "put", "prune"])
+const NOTABLE = new Set(["done", "fail", "cancel", "say"])
+
+const blankChanges = () => ({ batches: 0, touched: new Set(), events: [], structure: false, local: false })
+
+export class RenderQueue {
+  // onFrame(tree, changes) - changes is { batches, touched, events, structure }. `structure` says
+  // rows came, went or moved, so a renderer that patches rows in place has to lay them out again
+  constructor(tree, onFrame, { schedule = nextFrame } = {}) {
+    this.tree = tree
+    this.onFrame = onFrame
+    this.schedule = schedule
+    this.changes = blankChanges()
+    this.pending = false
+    this.closed = false
+    // What a graft of browser tasks changes is drawn the same way, in the same frames
+    tree.onLocalChange = (ops) => {
+      for (const [path, op, value] of ops) this.#note(path, op, value, null)
+      this.changes.local = true
+      this.#request()
+    }
+  }
+
+  apply(batch) {
+    const result = this.tree.apply(batch)
+    const changes = this.changes
+    changes.batches++
+    if (batch.prev === 0) {
+      changes.events.push({ op: "reset", seq: batch.seq })
+      changes.structure = true
+    }
+    if (result === "gap") changes.events.push({ op: "gap", seq: batch.seq, prev: batch.prev })
+    if (result === "applied") for (const [path, op, value] of batch.ops) this.#note(path, op, value, batch.seq)
+    this.#request()
+    return result
+  }
+
+  // Hands over what has piled up right away, without waiting for the frame
+  flush() {
+    this.pending = false
+    if (this.closed) return
+    const changes = this.changes
+    if (changes.batches === 0 && !changes.local) return
+    this.changes = blankChanges()
+    this.onFrame(this.tree, changes)
+  }
+
+  // A frame already asked for must not draw an old stream into a renderer that moved on
+  close() { this.closed = true }
+
+  #note(path, op, value, seq) {
+    // Percents roll up, so a change anywhere shows in every row above it too
+    for (let length = path.length; length >= 0; length--) this.changes.touched.add(key(path.slice(0, length)))
+    if (STRUCTURAL.has(op)) this.changes.structure = true
+    if (NOTABLE.has(op)) this.changes.events.push({ op, path, value: value ?? null, seq })
+  }
+
+  #request() {
+    if (this.pending || this.closed) return
+    this.pending = true
+    this.schedule(() => this.flush())
+  }
+}

data/js/row_view.d.ts

@@ -0,0 +1,25 @@
+import type { TaskTree, Node, Fold, Status, Path } from "./task_tree.js"
+
+/** What one row shows */
+export interface RowView {
+  key: string
+  path: Path
+  depth: number
+  name: string
+  status: Status
+  stale: boolean
+  /** Runs in this browser, see LocalTasks */
+  local: boolean
+  cancelable: boolean
+  /** Siblings folded into this one row */
+  folded?: boolean
+  percent: number
+  indeterminate: boolean
+  measure: string
+  /** HTML for the icon */
+  icon: string
+  message: string
+}
+
+export const CANCEL_ICON: string
+export function rowView(tree: TaskTree, node: Node | Fold): RowView