Images after #125: opt-in loading, worker decoding, limits, alt boxes, CellContext grids

[brainkim]

Follow-on work after #125 (images and canvas) merged.

Loading is decided by a Content Security Policy

TermDOM used to fetch every image source itself. It loaded http(s) through the runtime's fetch, read file: from disk and parsed data: itself. A program showing untrusted HTML couldn't stop a tracking image or a read of a local file, and an email's cid: images had no way to load.

Which loads a document may make is now its Content Security Policy, the standard built for exactly this question:

new TermDOM({csp: "img-src https: data:"}); // the web and data: URLs
new TermDOM({csp: "img-src cid: data:"});   // a mail client
new TermDOM();                                                // "default-src 'none'": nothing

• Directives: an <img> loads what img-src allows, or default-src without it. Later resource types take their own directives with no new API.
• Matching follows CSP Level 3: 'none', 'self', * (the network schemes and the document's own, not data: or cid:), schemes, and hosts with *. wildcards, ports and paths. A host without a scheme takes the document's, and for a document not served over the network (about:blank, file:), the network schemes.
• Pages can only tighten it: a <meta http-equiv="Content-Security-Policy"> inserted into the document's head is enforced too, and a load must pass every policy. As HTML says, it holds from its insertion: removing the tag or changing its content later changes nothing.
• Redirects are checked again. Each redirect is checked against the policy, matched without its path as CSP3 says, goes only to another http: or https: URL (never a file or data:), and at most 20 are followed.
• Blocked loads are reported the standard way: securitypolicyviolation fires at the element, a new SecurityPolicyViolationEvent (complete per CSP3) that bubbles to the document with the URL, directive and policy. The URL is the one the document asked for, never a redirect's target, without its fragment, and only its scheme when it isn't HTTP(S). When the program set no policy, the first block is also reported once where uncaught errors go, saying what to set.
• file: only from file pages. As in a browser, a document whose URL isn't file: loads no file: URL, whatever the policy says.
• csp: "" sets no policy and allows every load, as an empty header does.

What the policy allows goes to the TermDOM as a Service Worker's FetchEvent, for answers decided request by request, and to the runtime's fetch when no listener answers:

term.addEventListener("fetch", (event) => {
  event.request;              // a Request; destination is "image", signal aborts on a new src
  event.respondWith(response); // stops the other listeners; Response.error() fails the load
  event.preventDefault();      // without an answer, also fails the load
  event.waitUntil(promise);    // dispose() waits for it
  event.handled;               // settles once answered; rejects with a NetworkError on failure
});

• The order is a browser's: policy, then listeners, then network. A load a listener answers must be allowed too, so serving cid: takes img-src cid: and a listener. A redirect, from the network or a listener's Response.redirect(), is followed on the network without the listeners, as Fetch follows one without its Service Worker.
• The spec's fields: request, handled, preloadResponse, clientId, resultingClientId, replacesClientId, respondWith(), and waitUntil() from ExtendableEvent. Both classes are exported. A FetchEvent a program makes and dispatches itself can't be answered or extended, as in a Service Worker.
• Per-image decisions belong in the markup, such as no remote images in quoted mail: the program cleans it before inserting it, as a mail client does. WebKit's beforeload event tried this and was removed.
• A listener's response is checked where it came from. A listener that answers with fetch(event.request) lets the runtime follow redirects, so its response is checked against the policy at its final URL, as a browser checks a Service Worker's response.
• dispose() aborts loads still in flight and waits for waitUntil() promises. A load waiting on a listener's answer ends when its src changes or the TermDOM is disposed, whether or not the answer comes, and handled rejects with a NetworkError.
• window.fetch is the runtime's and resolves a relative URL against the document. No policy governs it and it dispatches no event, since in a terminal the program, not untrusted markup, calls it.
• Loads wait a microtask, as HTML's "update the image data" does, so a listener added right after the constructor's markup still sees its images.
• Fixed along the way: images in the constructor's html never loaded before. The parser built them before the document had a window, and nothing restarted them. The window now does.
• Examples and docs: examples/images.ts sets img-src file: data: https: and answers file: URLs in a fetch listener, since Node's fetch doesn't read files. The guide's "Loading" section covers the policy and the event.

Decoding on the runtime's Worker, or on the page's thread

A 12-megapixel JPEG blocked the page for about 840 ms. Images now decode in src/decode-worker.ts, plain web worker code built next to index.js as its own entry (listed in exports, since libuild only builds entries exports names). It runs on the runtime's own global Worker: Bun's, Deno's, a browser's, and Node's from 26.9 with --experimental-web-worker (nodejs/node#64894). There, the longest block for that JPEG is 10 to 22 ms. TermDOM does not touch process or worker_threads for this, and does not offer window.Worker to pages.

• Without a Worker (Node without the flag, the CommonJS build, libuild's test bundles), every image decodes on the page's thread, in the same line. The PNG and JPEG decoders yield every 16 ms, so input and frames go on between slices, and a decode past the same 10 seconds stops at its next yield.
• Node without the flag can get a worker with two lines and @b9g/node-webworker 0.2.2, which the images guide shows: globalThis.Worker ??= Worker. TermDOM does not depend on it.
• One at a time: images decode in the order they ask, one on the worker at a time. A page holds one decode's memory at once, and an image's timer counts its own decode, not time waiting in line or the worker starting.
• Stale decodes are dropped: a decode still waiting when its image's src changes, or its TermDOM is disposed, leaves the line with its bytes.
• Timeout: a decode past 10 seconds ends the worker and fails that image alone; a new worker takes the next one.
• Ending the worker: a running worker keeps Node, Bun and Deno alive, and the standard Worker has no unref(). So the worker ends a second after its last decode, and when the last TermDOM is disposed, along with any decode it was running.
• Crashes: a worker that started and then failed on an image fails that image alone, and a new worker takes the next. One that never starts sends every image to the page's thread.

At most a megapixel kept per image

An image used to stay decoded at full size, up to 2^26 pixels (256 MB), though a terminal shows a few hundred thousand pixels at most. A 12-megapixel photo held 48 MB to draw in 40 columns. An image past MAX_KEPT_PIXELS (2^20 pixels, 4 MB) is now averaged down to it as it decodes, on the worker or the main thread, and keeps its natural size beside the pixels: that photo keeps 1182×886 pixels, 4.2 MB.

Everything a page measures still uses the natural size: naturalWidth/naturalHeight, layout and aspect ratio, drawImage's source rectangle, createImageBitmap's crop and size (each side scaled by its own ratio, transparent past the image's edge), and the tile a pattern repeats at. sampleBitmap takes its rectangle in natural pixels and maps it to the pixels kept.

Limits against image bombs

Checked before anything is allocated:

• every decoder: at most 32,768 pixels per side and 2^26 in all
• PNG: data is inflated only as far as the image needs
• JPEG: one to four components, sampled one to four times, and at most 500 scans
• GIF: a code size of 2 to 8 bits
• responses: at most 64 MB, by the declared length and again while reading
• a new src aborts the request the old one started
• ImageData past 2^26 pixels throws a RangeError
• a charactergrid's drawImage samples only the cells that land on the grid, however large the destination
• an image box that would sample past 2^26 pixels draws nothing
• a character grid stops at 2^22 cells

An image that isn't showing is a box with its alt text

An image that's loading, broken or blocked showed its alt text inline, or nothing at all while loading. It's now a bordered box with the alt text inside, cut with "…" to fit. The box takes the image's size when the page gives one, and otherwise fits the text, three rows tall. One too small for a border holds the text alone. alt="" shows nothing, and neither does an <img> with no src and no alt. The border is a placeholder, not a CSS border: it's drawn inside the content box in the text color.

charactergrid through CellContext, with lines and boxes

The charactergrid context and image half blocks each kept cells in their own type and copied them into the frame one cell at a time. Both are CellGrids now, and CellContext.drawGrid copies either into the frame. The context gains canvas-style lines:

g.strokeStyle = "#5fafff"; // a CSS color, currentcolor by default
g.lineStyle = "double";    // a CSS border-style
g.lineJoin = "round";      // rounds strokeRect()'s corners
g.strokeRect(0, 0, 20, 5);
g.strokeLine(0, 2, 19, 2); // joins the box's sides as tees

Lines join into corners, tees and crosses where they meet. They're drawn as glyphs before reaching the frame, so they don't join the page's borders around the canvas.

Two pixels as a lower half block

A two-color cell is now ▄ (bottom pixel) over a background (top pixel), not ▀ over a background. Most terminals draw block characters themselves and show either exactly (kitty, Ghostty, WezTerm, Alacritty, foot, VTE, Windows Terminal, xterm.js with WebGL). Terminal.app draws them from the font, and of 22 coding fonts measured, 12 put the split between the halves off center, mostly low (Menlo and SF Mono at 57–59% of the cell, and their blocks also start 14–16% below the top). With ▀, that left a stripe of the wrong color at each cell's top and banded every gradient. With ▄ the background fills whatever the glyph misses, so only the seam is off, and ▄ matches or beats ▀ in 18 of the 19 fonts that have half blocks. timg, viu and rich-pixels use ▄ for the same reason. A cell where only the top pixel shows keeps ▀, since the color under it is the page's.

Smaller changes

• Typed listeners: TermDOMEventMap and keyed addEventListener/removeEventListener overloads, so a "fetch" listener gets a FetchEvent without a cast.

• A leak test for images and canvases: 80 rounds of four 256×256 images and two drawn canvases, shown and removed, with half the images removed before they load. It measures the heap plus external memory, since decoded pixels are array buffers the heap doesn't count. With every decoded image deliberately kept, it reads 86 MB and fails; it passes on Node, Bun and Deno.

• One cell size for images: the screen owns the one 8×16 fallback, and getImageCellSize gives the cell an image's pixels divide by.

• Guide: now says how image sizes work with and without cellSize.

Not done

• No memory budget across a page's images. Each image is capped at a megapixel, but a page with very many images still holds them all.
• renderANSI(html) and print(html) never show images: they render before an image decodes.
• No quadrant, sextant or octant rendering yet, and no pixel protocols (kitty, sixel).

🤖 Generated with Claude Code

https://claude.ai/code/session_015Bw3yEu4cfkuDkaZ3RSy4D