0.2.0: images and canvas follow-up, and a DOM that matches lib.dom

[brainkim]

The follow-up to the images and canvas work in #136, and the changes for 0.2.0: what a program configures, what a page can reach, and how unloaded images, control styling and the cell canvas behave. It also carries a cleanup of code that had grown roundabout. Every commit passes the full suite on Node, Bun and Deno.

Breaking changes

• colorDepth is an option of TermDOM, not of its transport. new TermDOM({colorDepth: 24}) replaces transport.colorDepth and transportFromProcess(proc, {colorDepth}). It takes the bits screen.colorDepth reports, 24, 8 or 4, or "auto", the default, which asks the terminal. "rgb", "256" and "ansi" still name the same three. Any other value throws.
• "ansi" draws with all 16 SGR colors and reports 4 bits. A color goes to the nearest of xterm's 16 default colors, so bright colors go out as SGR 90–97 and 100–107. screen.colorDepth is 4 and (color-index: 16) matches.
• The cell canvas is getContext("termdom-cellgrid"). It is TermDOM's own, so it carries TermDOM's prefix, as "moz-webgl" and "webkit-3d" carried theirs, and each cell carries a glyph and its styling. Its interface, CanvasCellGridContext, is exported from the package and is no longer on window. (The old name never shipped in a release.)
• A page's ::part() no longer reaches into the built-in controls, as in every browser. A page styles them through the pseudo-elements browsers ship: ::placeholder, ::details-content, ::picker(select) and ::picker-icon. A <progress> draws its fill in its accent-color. The rest of a control's insides, such as a meter's level colors and a button's brackets, are the UA sheet's alone. The data-level, data-highlighted, data-disabled and data-grouped attributes on control parts are gone.
• --math-glyphs and --math-variant-glyphs are gone. They were custom properties the MathML renderer read from the author's own namespace. MathML always draws with the Unicode pieces and terminal italics it used by default.
• DOMRectList is its own interface, no longer an Array, with length, item(), indexed properties and the standard iterator. As in browsers, a page cannot construct one.
• Members a page could see that no standard defines are gone, among them colorAt on CanvasGradient and CanvasPattern, the live collections' compute, namedProperties and getChangedMembers, the CSS rules' prelude, atKeyword and static atRule, a computed style's getComputedValue, innerText on MathMLElement, and takeRecords on ResizeObserver.

The version is 0.2.0.

New options

• graphics: how a document draws pixels for <img> and a canvas's "2d" context. "auto", the default, uses the best way the terminal has, which today is always cells. "cells" forces half blocks. "none" draws no pixels: an <img> loads nothing and shows its alt text, as HTML's "images are disabled" does, and getContext("2d") returns null, so a canvas shows its fallback content.
• colorDepth, above.

The images guide now opens its loading section with the three csp recipes: images from the web, a mail client's cid: attachments, and "" for no policy.

An image that won't load is its alt text

HTML's rendering rules (§15.4.2) keep an image that isn't showing a box only when it has a size and may still load, has no alt text, or is in a quirks-mode document. Otherwise its alt text is ordinary inline text. TermDOM drew every such image as a bordered box three rows tall, which made a mail client's link lists with blocked thumbnails much longer. The alt text lives in the image's UA shadow tree, as Chromium keeps it.

The DOM a page sees matches lib.dom

The drift script builds a TermDOM and walks every interface on its window, the objects a page reaches without a constructor (navigator, screen, the 2D context, a computed style), and what calls such as getElementsByClassName() return. It fails on any member lib.dom doesn't declare and on any prototype in a chain that isn't a standard interface. Members a current standard defines that this lib.dom lacks are listed with where they're defined. The members it found are removed, listed above.

The engine's own classes are out of every prototype chain a page can see. LayoutObserver is gone: each observer keeps its own state and calls three functions. The CSS rules' shared bases are init functions. getComputedStyle() returns a plain CSSStyleProperties that reads through to the engine's computed declaration. getElementsBy*() return a plain HTMLCollection. LiveList's methods are copied onto each list interface.

Fixes

• A style change reaches the shadow trees under it, closed and built-in ones included. Setting color on a form's container now recolors its fields' text.

Cleanup

These commits change no behavior, except the whitespace fix noted under Duplication.

Per-document values now live on the attached document. attachDocument takes one object of named parts, instead of eight positional arguments plus side registries.

• The cell size: the 8×16 guess and the terminal's reported cell live only in the framebuffer, read through getCellPixels. The cellSize option is stored on the document, and getCellSize reads it there. Gone: the FALLBACK_CELL re-export from cssom, the second "not interactive" choice in index.ts, the setScreenCellSource and setCellSizeSource callback registries, and the separate kMeasuresCell flag. The renderANSI engine is built with its parent's cell, and cells are compared by size, not by object identity.
• The color scheme is decided once, in Exchange.colorScheme: the terminal's answer, then the transport's, then light. cssom reads it through the document's exchange. The setColorSchemeSource registry and index.ts's copy are gone.
• The resource loader and its abort signal go through attachDocument, in place of resources.ts's setResourceLoader registry.
• Hover listeners are counted in one map, not two maps and a closure.

Imports and exports.

• layout.ts and painter.ts import isReplacedElement from images.ts, where it lives, not through replaced.ts's re-export.
• Three files that imported one module in two statements now use one.
• getNestedRules was used nowhere and is deleted.
• 25 functions, constants and types that only their own module uses are no longer exported.

Duplication.

• isControlByte lives in text.ts, not in both framebuffer.ts and exchange.ts.
• The 80×24 default terminal size and the 1 s terminal-question timeout are named constants in exchange.ts, not literals written 5 and 8 times.
• Trimming and splitting HTML's ASCII whitespace uses one pair of helpers in text.ts, in place of nine hand-written trims in dom.ts, two split functions, and a trim in hints.ts. The CSP parser now trims only ASCII whitespace, as CSP3 says, instead of String.prototype.trim, which also strips Unicode spaces.

Comments and names.

• dom.ts no longer claims its isTextControl is the only definition. editing.ts's different test (an input, textarea or select, which keeps its keys) is renamed isFormControl.
• A layout comment named a nonexistent bidi.ts.
• Comments describing past bugs or past code now describe what the code does.

Looked at and left as is:

• hints.ts's local HTML_NAMESPACE, which keeps a leaf module from importing dom.ts.
• The namespace literals in dom.ts, which are type-level overloads mirroring lib.dom.
• The two isShadowRoot functions, which agree in practice.
• The two domException helpers, which build exceptions in different realms.

🤖 Generated with Claude Code

https://claude.ai/code/session_015Bw3yEu4cfkuDkaZ3RSy4D