0.2.0 API review: canvas sizing and contexts, gauge styling, colorScheme, disposal, default actions

[brainkim]

A pass over the public API before 0.2.0, so that 0.2.0 can mark general stability. Canvases, images and most of what changes here are new in 0.2.0, so only the items under Breaking change anything 0.1.x shipped.

Breaking

• colorScheme is a TermDOM option, beside colorDepth: new TermDOM({colorScheme: "dark"}). It is gone from TerminalTransport and from the options of transportFromProcess and transportFromSSH. It holds until the terminal reports its background.
• Disposal is asynchronous only. TermDOM has Symbol.asyncDispose, so await using term = new TermDOM() waits for the restores as await term.dispose() does. Symbol.dispose is gone: a disposal that writes to a terminal cannot promise it is done when it returns.
• attach() takes no transport. The transport comes only from the constructor, new TermDOM({transport}). Swapping one in at attach time only duplicated the constructor option: the default transport does nothing until attach(), and a transport that isn't ready yet resolves ready when it is.
• The keys scroll, as in a browser (Enumerate and specify default actions, i.e. behavior which is prevented with preventDefault() #84). ArrowUp and ArrowDown scroll a row, PageUp, PageDown and Space a page, Home and End to an edge, as the default action of a keydown nothing canceled, moving the nearest scrollable box around the focus and the document otherwise. A program that handles those keys itself needs preventDefault(); the git-log, tree, hacker-news, markdown and solitaire examples now call it.
• Exit statuses follow the shell. Ctrl-C exits 130; window.close() exits 1 if the page let an exception escape, 0 otherwise; SIGINT, SIGHUP and SIGTERM exit 130, 129 and 143. All exited 0 before.
• A page's ::part() does not reach inside built-in controls, as in browsers (this landed in 0.2.0: images and canvas follow-up, and a DOM that matches lib.dom #141; the launch post's demo no longer uses it).

Canvas sizing

A canvas's width and height are unitless, and HTML lays the canvas out at that many CSS pixels. TermDOM now does exactly that, whichever context the canvas gets, so asking for a context never changes a canvas's size.

• Under the default cellSize: "unit" a CSS pixel is a cell, so <canvas width="40" height="10"> is 40×10 cells. With cellSize set they are pixels.
• Without the attributes, under "unit", width and height default to 38 and 9, HTML's 300×150 pixels over an 8×16 cell, so a bare canvas is not 300 columns wide.
• Images keep measuring their file's pixels against the terminal's cell under "unit".

The cell grid context

• Size: it holds the cells its canvas's box holds, reported as cols and rows. CSS width: 40ch; height: 10ch sizes it exactly in any mode. When the box changes size, the cells that still fit keep what was drawn.
• Typed: importing the package declares getContext("termdom-cellgrid") as returning a CanvasCellGridContext, so no caller casts. canvas is an HTMLCanvasElement, and settings read back as their own types.
• Behaves as a 2d context does:
  • fillStyle and strokeStyle serialize as a 2d context's. currentcolor is the canvas's color when set, and CanvasText and Canvas, the defaults, are the terminal's own. A translucent fill blends.
  • font is a parsed CSS font shorthand.
  • textAlign (default start) and direction (default inherit); right-to-left text draws in display order.
  • save(), restore(), isContextLost().
  • Coordinates round in every method, getCell included.
  • maxWidth, lineJoin: "bevel", lineStyle: "none", and negative drawImage sizes as a 2d context treats them.
• Text attributes: textDecoration takes line-through; getCell reports dim, strikethrough and inverse.
• Only getContext makes a context. new CanvasCellGridContext() and new CanvasRenderingContext2D() throw Illegal constructor, as in browsers.

The 2d context gained the same fixes where it fell short: direction: "inherit" takes the canvas's direction, its right-to-left text draws in display order, and font rejects values the shorthand grammar rejects.

Gauges

A page styles <progress> and <meter> through CSS Form Control Styling (css-forms-1):

• ::slider-track and ::slider-fill
• meter:optimal-value, :low-value and :high-value for a meter's levels
• WebKit's ::-webkit-progress-* and ::-webkit-meter-* and Firefox's ::-moz-progress-bar, ::-moz-meter-bar and :-moz-meter-* as aliases, as its §4.10 asks

accent-color no longer colors a progress bar's fill.

Default actions (#84)

• Ctrl+Z suspends, as a shell's job control does. The terminal is handed back and the program stops until fg; a document in flow is written to the scrollback and starts again below the shell's lines, and a fullscreen one leaves and re-enters the alternate screen. The document is hidden meanwhile, with visibilitychange on each edge. Transports opt in with an optional suspend(); the process transport leaves raw mode and sends itself SIGTSTP until SIGCONT, except on Windows. Over SSH, Ctrl+Z is an ordinary key. Checked by hand in zsh under tmux on Node, Bun and Deno.
• The arrows move through a radio group, checking the next radio and wrapping.
• Left out of Enumerate and specify default actions, i.e. behavior which is prevented with preventDefault() #84: a second Ctrl+C that closes regardless (undecided), and the Tab-wrapping question. Implicit form submission already landed.

Packaging

• The image decoder is built as a worker entry, src/image-decode.worker.ts, with libuild 0.2.26, and is no longer in exports. The built package starts it and decodes on Bun, Deno and Node 26 with --experimental-web-worker.
• ColorDepth (24 | 8 | 4 | "rgb" | "256" | "ansi") is exported.

Docs and site

The images guide, the API guide and the styling guide match. The canvas and images examples run on the site.

Tests

New tests cover each change above.

• A full run on the commit before the last passed on Node and Deno, with one Bun failure in tests/transitions.test.ts. That file fails intermittently on Bun on main too (about 5 in 15 runs). This PR fixes the delayed-transition case, which allowed only 60 ms; the rest are a pre-existing timing flake left for later.
• The full suite on the final commit was still running when this was opened.

document.close() keeps its scrollback behavior for now but is no longer documented, until document.open(), write() and close() are worked out for the scrollback. window.screenTop stays the row the document's region starts at, the terminal's version of how far down the screen the window is.

🤖 Generated with Claude Code