@namiml/cli 3.4.12-dev.202610051759 → 3.4.12-dev.202610060208

package/dist/placements/page.js

@@ -0,0 +1,34 @@
+import { getPaywallDataFromLabel } from "@namiml/sdk-core";
+import { currentPageName } from "../render/composite.js";
+import { pageModel } from "../render/page-model.js";
+/**
+ * The render model for a placement, from core's own lookup.
+ *
+ * The twin of `compositeForPlacement` in `src/placements/launch.ts`: the same
+ * `getPaywallDataFromLabel(label, "label")` the launch itself performs, so the
+ * frame draws the page the launch served. It lives in its own file because
+ * NAM-4542's `launch.ts` is closed to changes; the two must resolve the same
+ * page, so change them together.
+ *
+ * A placement only resolves a paywall when that paywall was in the set the SDK
+ * fetched for the configured device's form factor, which is why an empty page
+ * is usually a device mismatch — `unresolved` carries that distinction on to
+ * the screen exactly as the outline's does.
+ */
+const NO_PAGE = {
+    pageName: "",
+    root: { kind: "box", style: {}, children: [] },
+    unresolved: true,
+};
+export function renderPageForPlacement(label) {
+    try {
+        const { paywall } = getPaywallDataFromLabel(label, "label");
+        if (!paywall)
+            return NO_PAGE;
+        return pageModel(paywall, currentPageName(paywall));
+    }
+    catch {
+        // A placement the SDK cannot resolve is an empty frame, never a crash.
+        return NO_PAGE;
+    }
+}

package/dist/render/capabilities.js

@@ -0,0 +1,63 @@
+import { colorDisabled } from "../utils/terminal.js";
+/**
+ * What this terminal can do, from the environment alone — no probing, no escape
+ * sequences written to a terminal that may not answer.
+ *
+ * `NO_COLOR` wins over everything, which is the rule `src/utils/terminal.ts`
+ * already sets for animation: a user who asked for a quiet terminal gets no
+ * colour and no images, even inside kitty. A non-TTY gets the same treatment,
+ * because a redirected stdout is a file or a pipe, not a screen.
+ */
+export function detectCaps(env = process.env, isTTY = false) {
+    if (colorDisabled(env) || !isTTY)
+        return { trueColor: false, imageTier: "placeholder" };
+    return { trueColor: hasTrueColor(env), imageTier: imageProtocol(env) === "kitty" ? "kitty" : "glyphs" };
+}
+/** `COLORTERM` is the only portable 24-bit signal; the two values terminals actually set. */
+function hasTrueColor(env) {
+    const colorterm = env.COLORTERM?.toLowerCase();
+    return colorterm === "truecolor" || colorterm === "24bit";
+}
+/**
+ * Which block glyphs to draw images with.
+ *
+ * Sextants (Unicode 13, 2020) give the most detail and are the default, but a
+ * font without them draws tofu, which is worse than a coarser image — and there
+ * is no way to ask a terminal what its font covers. `NAMI_IMAGE_BLOCKS` is the
+ * escape hatch: set it to `quadrant` (four subpixels, in fonts for decades) or
+ * `half` (two, universal).
+ */
+export function blockMode(env = process.env) {
+    const asked = env.NAMI_IMAGE_BLOCKS?.trim().toLowerCase();
+    if (asked === "quadrant" || asked === "half" || asked === "sextant")
+        return asked;
+    return "sextant";
+}
+/**
+ * Whether this terminal will take an image as pixels rather than as glyphs.
+ *
+ * Read from the environment rather than asked. The protocol has a query — an
+ * escape the terminal answers `OK` to — but asking means putting stdin in raw
+ * mode and waiting for a reply that may never come, at the moment the CLI is
+ * starting up, and getting that wrong hangs the program on a terminal that
+ * simply does not answer. The set of terminals that speak kitty graphics is
+ * short and identifies itself plainly, so this is a lookup until there is a
+ * second protocol to tell apart.
+ *
+ * `NAMI_IMAGE_PROTOCOL=none` forces the glyph renderers, which is the escape
+ * hatch if a terminal claims the protocol and draws nothing.
+ */
+export function imageProtocol(env = process.env) {
+    const asked = env.NAMI_IMAGE_PROTOCOL?.trim().toLowerCase();
+    if (asked === "none")
+        return "none";
+    if (asked === "kitty")
+        return "kitty";
+    // Ghostty (`xterm-ghostty`) and kitty itself. Verified against Ghostty: it
+    // answers the protocol's query with OK and draws a chunked RGBA transmission.
+    if (env.TERM === "xterm-ghostty" || env.TERM_PROGRAM === "ghostty")
+        return "kitty";
+    if (env.TERM === "xterm-kitty" || env.KITTY_WINDOW_ID)
+        return "kitty";
+    return "none";
+}

package/dist/render/graphics.js

@@ -0,0 +1,203 @@
+/**
+ * Images as pixels rather than glyphs, for terminals that can take them.
+ *
+ * A character cell can hold at most two colours, so a block-glyph image is
+ * capped at two colours per cell however finely the glyph subdivides it — six
+ * subpixels (`sextantRows`) is about the ceiling. A terminal that speaks a
+ * graphics protocol draws the real thing instead, at its own pixel resolution.
+ *
+ * This module is the protocol half and is **pure**: it builds escape sequences
+ * and does the arithmetic, and never writes to a stream or reads a clock. The
+ * writing, and the ordering problem that comes with it, live in
+ * `src/screens/useTerminalImages.ts`.
+ *
+ * Only the kitty protocol is implemented. It is what Ghostty and kitty speak;
+ * iTerm2 and sixel are the same shape of problem (transmit, place, delete) and
+ * belong behind the same three functions when their turn comes.
+ *
+ * ## Why RGBA and not PNG
+ *
+ * `f=100` means PNG and `f=32` means raw RGBA. We already decode both PNG and
+ * JPEG to RGBA for the glyph renderers, so sending RGBA needs no encoder and
+ * cannot mismatch the file's actual format — sending a JPEG under `f=100` is
+ * exactly the bug that made the first spike draw nothing, silently, because the
+ * error reply was suppressed. Raw pixels cost more bytes, so `rgbaFor` scales
+ * to the cells the image will occupy before transmitting rather than sending
+ * a 4000-pixel asset to fill 30 columns.
+ */
+/** Bytes of base64 per escape. The protocol's own limit is 4096. */
+export const CHUNK = 4096;
+/**
+ * Roughly how many pixels a cell is. Used only to decide how much resolution to
+ * transmit — the terminal does the real scaling from `cols`/`rows`, so being a
+ * little off costs sharpness or bytes, never correctness.
+ */
+export const CELL_PIXELS = { width: 9, height: 18 };
+/**
+ * Stacking levels, and the one number in this file that is not arbitrary.
+ *
+ * The protocol draws an image below the terminal's text at any negative `z`,
+ * but only below a cell that carries its **own background colour** when `z` is
+ * under −1073741824. That distinction is the difference between a paywall's
+ * buttons keeping their fills and disappearing into the page's background
+ * photograph, so every image here sits under that line. The page's background
+ * goes one lower again, so a logo drawn over it stays over it.
+ */
+export const UNDER_FILLS = -1073741825;
+export const BACKGROUND_Z = UNDER_FILLS - 1000;
+/**
+ * The cells an image should be drawn into, and the part of it to draw, so that
+ * it keeps its own shape.
+ *
+ * The protocol scales an image into exactly the cells it is given, so placing a
+ * wide logo in a square box stretches it — which is what `imageBox` already
+ * protects the glyph renderers from. `fit` shrinks the cells to the image's
+ * shape and centres them; `fill` keeps the cells and crops the image instead,
+ * which is what covering a box means.
+ */
+export function fitToBox(pixels, box, mode, 
+/** Where the picture sits in a box wider than it is: 0 left, 0.5 centred, 1 right. */
+align = {}, cellAspect = 2) {
+    if (mode === "fill") {
+        // Pixels the box is worth, in the image's own aspect terms.
+        const want = box.w / (box.h * cellAspect);
+        const have = pixels.width / pixels.height;
+        const w = have > want ? Math.max(1, Math.round(pixels.height * want)) : pixels.width;
+        const h = have > want ? pixels.height : Math.max(1, Math.round(pixels.width / want));
+        return {
+            x: box.x,
+            y: box.y,
+            cols: box.w,
+            rows: box.h,
+            crop: {
+                x: Math.floor((pixels.width - w) / 2),
+                y: Math.floor((pixels.height - h) / 2),
+                w: Math.min(w, pixels.width),
+                h: Math.min(h, pixels.height),
+            },
+        };
+    }
+    const scale = Math.min(1, Math.min(box.w / pixels.width, (box.h * cellAspect) / pixels.height));
+    const cols = Math.max(1, Math.min(box.w, Math.round(pixels.width * scale)));
+    const rows = Math.max(1, Math.min(box.h, Math.round((pixels.height * scale) / cellAspect)));
+    return {
+        x: box.x + Math.floor((box.w - cols) * (align.x ?? 0.5)),
+        y: box.y + Math.floor((box.h - rows) * (align.y ?? 0.5)),
+        cols,
+        rows,
+    };
+}
+/**
+ * The escapes that send an image's pixels to the terminal under `id`.
+ *
+ * Transmission is separate from placement on purpose: the pixels go once, and
+ * then every redraw and every scroll step is a single short `place`. Sending
+ * 200 KB on each frame would be visible.
+ */
+export function transmit(id, rgba, width, height, chunk = CHUNK) {
+    const data = Buffer.from(rgba.buffer, rgba.byteOffset, rgba.byteLength).toString("base64");
+    const head = `f=32,t=d,a=t,i=${id},s=${Math.max(1, Math.floor(width))},v=${Math.max(1, Math.floor(height))},q=2`;
+    if (data.length <= chunk)
+        return [`\u001b_G${head},m=0;${data}\u001b\\`];
+    const out = [`\u001b_G${head},m=1;${data.slice(0, chunk)}\u001b\\`];
+    let at = chunk;
+    while (at < data.length - chunk) {
+        out.push(`\u001b_Gm=1,q=2;${data.slice(at, at + chunk)}\u001b\\`);
+        at += chunk;
+    }
+    out.push(`\u001b_Gm=0,q=2;${data.slice(at)}\u001b\\`);
+    return out;
+}
+/** The escape that draws a transmitted image at the cursor. */
+export function place(id, { cols, rows, source, z }) {
+    const parts = [`a=p`, `i=${id}`, `p=1`, `c=${Math.max(1, Math.floor(cols))}`, `r=${Math.max(1, Math.floor(rows))}`];
+    if (source)
+        parts.push(`x=${source.x}`, `y=${source.y}`, `w=${source.w}`, `h=${source.h}`);
+    if (z !== undefined)
+        parts.push(`z=${z}`);
+    // C=1 keeps the cursor where it was, so the caller's own positioning holds.
+    parts.push("C=1", "q=2");
+    return `\u001b_G${parts.join(",")}\u001b\\`;
+}
+/** The escape that forgets an image and every placement of it. */
+export function forget(id) {
+    return `\u001b_Ga=d,d=I,i=${id}\u001b\\`;
+}
+/** Move the cursor to a row and column of the app's own output, and back after. */
+export function at(col, rowsUp, body) {
+    const up = rowsUp > 0 ? `\u001b[${rowsUp}A` : "";
+    const right = col > 0 ? `\u001b[${col}C` : "";
+    return `\u001b7${up}\r${right}${body}\u001b8`;
+}
+/**
+ * An image box clipped to a scrolling window, as cells to draw and the part of
+ * the image to draw there.
+ *
+ * The terminal does not know about our window: it draws where it is told, so a
+ * frame that clips its content has to clip the placement too, or the image
+ * spills past the border. `null` means the box is entirely outside the window.
+ *
+ * `top` is the box's first row in the page's own coordinates, `offset` the rows
+ * scrolled off, `windowRows` the rows on screen.
+ */
+export function clipToWindow(box, offset, windowRows, pixelHeight, pixelWidth) {
+    const first = Math.max(box.y, offset);
+    const last = Math.min(box.y + box.rows, offset + windowRows);
+    const rows = last - first;
+    if (rows <= 0 || box.rows <= 0)
+        return null;
+    const hidden = first - box.y;
+    const y = Math.round((hidden / box.rows) * pixelHeight);
+    const h = Math.max(1, Math.round((rows / box.rows) * pixelHeight));
+    return {
+        row: first - offset,
+        rows,
+        source: { x: 0, y, w: pixelWidth, h: Math.min(h, pixelHeight - y) },
+    };
+}
+/**
+ * The image scaled to the pixels its cells are worth, as RGBA, composited over
+ * `backdrop` if one is given.
+ *
+ * Nearest neighbour on purpose: the terminal resamples again when it fits the
+ * pixels to the cells, so a careful filter here would be thrown away. What
+ * matters is not sending a 4000-pixel asset to fill thirty columns.
+ *
+ * **The compositing is not optional.** A terminal is free to ignore the alpha
+ * channel it was sent, and one that does draws the bare colour underneath it —
+ * which for a white logo on a transparent ground is a white rectangle with the
+ * mark invisible inside it. Flattening here makes the pixels say what they
+ * should look like rather than trusting the terminal to work it out, and it is
+ * the same thing `halfBlockRows` and friends do with their own `backdrop`.
+ */
+export function rgbaFor(pixels, cols, rows, backdrop, 
+/** Take only this part of the image, for a `fill` that crops rather than squashes. */
+crop) {
+    const take = crop ?? { x: 0, y: 0, w: pixels.width, h: pixels.height };
+    const width = Math.max(1, Math.min(take.w, Math.floor(cols * CELL_PIXELS.width)));
+    const height = Math.max(1, Math.min(take.h, Math.floor(rows * CELL_PIXELS.height)));
+    const data = new Uint8Array(width * height * 4);
+    for (let y = 0; y < height; y += 1) {
+        const sy = Math.min(pixels.height - 1, take.y + Math.floor((y * take.h) / height));
+        for (let x = 0; x < width; x += 1) {
+            const sx = Math.min(pixels.width - 1, take.x + Math.floor((x * take.w) / width));
+            const from = (sy * pixels.width + sx) * 4;
+            const to = (y * width + x) * 4;
+            const alpha = pixels.data[from + 3];
+            if (backdrop && alpha < 255) {
+                const weight = alpha / 255;
+                data[to] = Math.round(pixels.data[from] * weight + backdrop.r * (1 - weight));
+                data[to + 1] = Math.round(pixels.data[from + 1] * weight + backdrop.g * (1 - weight));
+                data[to + 2] = Math.round(pixels.data[from + 2] * weight + backdrop.b * (1 - weight));
+                data[to + 3] = 255;
+            }
+            else {
+                data[to] = pixels.data[from];
+                data[to + 1] = pixels.data[from + 1];
+                data[to + 2] = pixels.data[from + 2];
+                data[to + 3] = alpha;
+            }
+        }
+    }
+    return { data, width, height };
+}

package/dist/render/image.js

@@ -0,0 +1,362 @@
+import { createHash } from "node:crypto";
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { decode as decodeJpeg } from "jpeg-js";
+import { PNG } from "pngjs";
+import { configDir } from "../paths.js";
+/** Upper half block: its foreground is the upper pixel, its background the lower one. */
+const UPPER_HALF = "▀";
+/** Lower half block, for a cell whose upper pixel is absent or transparent. */
+const LOWER_HALF = "▄";
+const PNG_SIGNATURE = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a];
+const JPEG_SIGNATURE = [0xff, 0xd8, 0xff];
+/**
+ * The fallback every terminal can draw: `▀` with the **foreground** carrying the
+ * upper pixel and the **background** the lower one, so each cell shows two
+ * vertical pixels.
+ *
+ * The image is nearest-neighbour sampled to fill the `cols` × `rows` box, except
+ * that it is **never upscaled**: the grid is `min(cols, width)` wide and
+ * `min(rows * 2, height)` pixel-rows tall, so a 12×12 logo in a 40×12 box comes
+ * back as 12 columns of 6 rows rather than smeared across 40. The caller places
+ * the smaller result inside its box.
+ *
+ * An odd pixel-row count leaves the bottom cell without a lower pixel; its `bg`
+ * is empty so the terminal's own background shows through. A fully transparent
+ * pixel counts as absent the same way, which is what turns a cell into `▄` or a
+ * blank.
+ */
+/**
+ * The cell box an image occupies inside `cols x rows`, keeping its shape.
+ *
+ * A half block splits a cell into two, so a half-block pixel is about square
+ * while a whole cell is about twice as tall as it is wide. The source's aspect
+ * is therefore matched against `cols x (rows * 2)`. Without this a square logo
+ * authored `width: 100%, height: 32` was stretched across the full width and
+ * squashed into two rows — a wide, short smear of something that is not wide or
+ * short. `fit` (the mode 17 of the 19 authored images use) contains the image
+ * inside the box; `fill` covers the box and crops the overflow. Neither ever
+ * upscales past the source's own resolution.
+ */
+export function imageBox(pixels, cols, rows, mode) {
+    if (cols <= 0 || rows <= 0 || pixels.width <= 0 || pixels.height <= 0)
+        return { cols: 0, rows: 0 };
+    const halfRows = rows * 2;
+    const byWidth = cols / pixels.width;
+    const byHeight = halfRows / pixels.height;
+    // `fill` covers the box, `fit` stays inside it. Never magnify the source.
+    const scale = Math.min(1, mode === "fill" ? Math.max(byWidth, byHeight) : Math.min(byWidth, byHeight));
+    return {
+        cols: Math.max(1, Math.min(cols, Math.round(pixels.width * scale))),
+        rows: Math.max(1, Math.min(rows, Math.ceil((pixels.height * scale) / 2))),
+    };
+}
+export function halfBlockRows(pixels, cols, rows, 
+/**
+ * What shows through a partly transparent pixel — the fill the image is being
+ * drawn over. Without it a logo's anti-aliased edge, which is mostly
+ * transparent white, paints as solid white and the whole mark looks blown out.
+ */
+backdrop, 
+/** `fit` (contain, the default) or `fill` (cover). */
+mode) {
+    if (cols <= 0 || rows <= 0 || pixels.width <= 0 || pixels.height <= 0)
+        return [];
+    const box = imageBox(pixels, cols, rows, mode);
+    const pixelCols = Math.max(1, box.cols);
+    const pixelRows = Math.max(1, Math.min(box.rows * 2, pixels.height));
+    const out = [];
+    for (let row = 0; row * 2 < pixelRows; row += 1) {
+        const cells = [];
+        for (let col = 0; col < pixelCols; col += 1) {
+            cells.push(cell(sample(pixels, col, row * 2, pixelCols, pixelRows, backdrop), sample(pixels, col, row * 2 + 1, pixelCols, pixelRows, backdrop)));
+        }
+        out.push(cells);
+    }
+    return out;
+}
+/**
+ * The one place a format is decoded, so a format we cannot read degrades to the
+ * `placeholder` tier instead of throwing. PNG through `pngjs`, JPEG through
+ * `jpeg-js`, anything else (and anything malformed) → null.
+ */
+export function decodeImage(bytes) {
+    try {
+        if (startsWith(bytes, PNG_SIGNATURE)) {
+            const png = PNG.sync.read(Buffer.from(bytes));
+            return { data: new Uint8Array(png.data), width: png.width, height: png.height };
+        }
+        if (startsWith(bytes, JPEG_SIGNATURE)) {
+            const jpg = decodeJpeg(bytes, { useTArray: true, formatAsRGBA: true });
+            return { data: new Uint8Array(jpg.data), width: jpg.width, height: jpg.height };
+        }
+    }
+    catch {
+        return null;
+    }
+    return null;
+}
+/**
+ * The image bytes for a URL, cached on disk under `configDir()/image-cache/<sha256 of url>`.
+ *
+ * **Never throws and never rejects**: an unreachable host, a 404, a corrupt cache
+ * or an unwritable cache directory all come back as `null` (or, when only the
+ * cache write failed, as the bytes anyway). A paywall image that cannot be
+ * fetched must never take the page render down with it.
+ *
+ * `fetch` is injected so tests never touch the network.
+ */
+export async function fetchImage(url, deps = {}) {
+    const dir = deps.cacheDir ?? join(configDir(), "image-cache");
+    const file = join(dir, createHash("sha256").update(url).digest("hex"));
+    const cached = await readCached(file);
+    if (cached)
+        return cached;
+    let bytes;
+    try {
+        const get = deps.fetch ?? globalThis.fetch;
+        const response = await get(url);
+        if (!response.ok)
+            return null;
+        bytes = new Uint8Array(await response.arrayBuffer());
+    }
+    catch {
+        return null;
+    }
+    await writeCached(dir, file, bytes);
+    return bytes;
+}
+async function readCached(file) {
+    try {
+        const buffer = await readFile(file);
+        return buffer.length > 0 ? new Uint8Array(buffer) : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Atomic, `0600` in a `0700` directory — the same shape as the token and config stores. */
+async function writeCached(dir, file, bytes) {
+    try {
+        await mkdir(dir, { recursive: true, mode: 0o700 });
+        const temp = `${file}.tmp`;
+        await writeFile(temp, bytes, { mode: 0o600 });
+        await rename(temp, file);
+    }
+    catch {
+        // A cache we cannot write is not a reason to lose an image we already have.
+    }
+}
+function startsWith(bytes, signature) {
+    if (bytes.length < signature.length)
+        return false;
+    return signature.every((byte, i) => bytes[i] === byte);
+}
+/** The colour of one source pixel, or null when it is outside the image or fully transparent. */
+/**
+ * The average of every source pixel a cell covers, composited over `backdrop`.
+ *
+ * Two things this fixes, both of which made logos look blown out. Taking one
+ * pixel per cell threw away almost the whole image when downscaling — an 830px
+ * mark into 40 columns sampled one pixel in several hundred, so a bright one
+ * spiked and thin strokes vanished. And treating alpha as binary painted every
+ * anti-aliased edge at full opacity, which is a white halo around a white mark.
+ * Averaging in premultiplied space, then compositing the accumulated alpha, is
+ * what an image resizer does.
+ */
+function sample(pixels, col, pixelRow, cols, pixelRows, backdrop) {
+    const rgb = sampleRgb(pixels, col, pixelRow, cols, pixelRows, backdrop);
+    return rgb ? hex(rgb.r, rgb.g, rgb.b) : null;
+}
+/** The same average, kept as a colour — what the quadrant renderer needs. */
+function sampleRgb(pixels, col, pixelRow, cols, pixelRows, backdrop) {
+    if (pixelRow >= pixelRows)
+        return null;
+    const x0 = Math.floor((col * pixels.width) / cols);
+    const x1 = Math.max(x0 + 1, Math.floor(((col + 1) * pixels.width) / cols));
+    const y0 = Math.floor((pixelRow * pixels.height) / pixelRows);
+    const y1 = Math.max(y0 + 1, Math.floor(((pixelRow + 1) * pixels.height) / pixelRows));
+    let r = 0;
+    let g = 0;
+    let b = 0;
+    let alpha = 0;
+    let count = 0;
+    for (let y = y0; y < Math.min(y1, pixels.height); y += 1) {
+        for (let x = x0; x < Math.min(x1, pixels.width); x += 1) {
+            const at = (y * pixels.width + x) * 4;
+            if (at + 3 >= pixels.data.length)
+                continue;
+            const a = pixels.data[at + 3] / 255;
+            // Premultiplied, so a transparent pixel's colour cannot drag the average.
+            r += pixels.data[at] * a;
+            g += pixels.data[at + 1] * a;
+            b += pixels.data[at + 2] * a;
+            alpha += a;
+            count += 1;
+        }
+    }
+    if (count === 0)
+        return null;
+    const coverage = alpha / count;
+    // Below this the cell is background, not a faint smear of the mark.
+    if (coverage < 0.02)
+        return null;
+    // Un-premultiply to the mark's own colour, then composite it over what shows
+    // through. With no backdrop the colour stands alone, as it did before.
+    const own = { r: r / alpha, g: g / alpha, b: b / alpha };
+    if (!backdrop || coverage >= 0.999)
+        return own;
+    return {
+        r: own.r * coverage + backdrop.r * (1 - coverage),
+        g: own.g * coverage + backdrop.g * (1 - coverage),
+        b: own.b * coverage + backdrop.b * (1 - coverage),
+    };
+}
+function cell(upper, lower) {
+    if (upper && lower)
+        return { ch: UPPER_HALF, fg: upper, bg: lower };
+    if (upper)
+        return { ch: UPPER_HALF, fg: upper, bg: "" };
+    if (lower)
+        return { ch: LOWER_HALF, fg: lower, bg: "" };
+    return { ch: " ", fg: "", bg: "" };
+}
+function hex(r, g, b) {
+    return `#${channel(Math.round(r))}${channel(Math.round(g))}${channel(Math.round(b))}`;
+}
+const channel = (value) => Math.max(0, Math.min(255, value)).toString(16).padStart(2, "0");
+/**
+ * The sixteen quadrant glyphs, indexed by a bitmask of which quarters take the
+ * foreground: 1 top-left, 2 top-right, 4 bottom-left, 8 bottom-right.
+ */
+const QUADRANTS = [" ", "\u2598", "\u259d", "\u2580", "\u2596", "\u258c", "\u259e", "\u259b", "\u2597", "\u259a", "\u2590", "\u259c", "\u2584", "\u2599", "\u259f", "\u2588"];
+/**
+ * An image as quadrant cells: **four** subpixels per cell instead of a half
+ * block's two, so horizontal detail doubles at the same size on screen.
+ *
+ * A cell still carries exactly two colours, which is what keeps this
+ * compositable — the cells drop into the same grid as everything else, and text
+ * can sit over them. The two colours are chosen per cell by splitting its four
+ * subpixels around their mean brightness and averaging each side, so an edge
+ * running through a cell keeps both the colours that meet there rather than
+ * being flattened to their average.
+ *
+ * `ink-picture` reaches higher resolution with braille (eight dots), but its
+ * dots are monochrome and its renderers emit pre-coloured strings rather than
+ * cells, so neither its colour nor its output would survive this compositor.
+ */
+export function quadrantRows(pixels, cols, rows, backdrop, mode) {
+    if (cols <= 0 || rows <= 0 || pixels.width <= 0 || pixels.height <= 0)
+        return [];
+    const box = imageBox(pixels, cols, rows, mode);
+    const gridCols = Math.max(1, box.cols) * 2;
+    const gridRows = Math.max(1, box.rows) * 2;
+    const out = [];
+    for (let row = 0; row < box.rows; row += 1) {
+        const cells = [];
+        for (let col = 0; col < box.cols; col += 1) {
+            const quarters = [
+                sampleRgb(pixels, col * 2, row * 2, gridCols, gridRows, backdrop),
+                sampleRgb(pixels, col * 2 + 1, row * 2, gridCols, gridRows, backdrop),
+                sampleRgb(pixels, col * 2, row * 2 + 1, gridCols, gridRows, backdrop),
+                sampleRgb(pixels, col * 2 + 1, row * 2 + 1, gridCols, gridRows, backdrop),
+            ];
+            cells.push(quadrantCell(quarters));
+        }
+        out.push(cells);
+    }
+    return out;
+}
+/** Split a cell's four quarters into a foreground and a background colour. */
+function quadrantCell(quarters) {
+    return twoColourCell(quarters, (mask) => QUADRANTS[mask]);
+}
+/**
+ * One cell from any number of subpixels: pick the two colours that best carry
+ * what is in it, then ask `glyph` for the shape.
+ *
+ * The split is around the subpixels' mean brightness, so an edge running
+ * through a cell keeps both of the colours that meet there instead of being
+ * flattened to their average.
+ */
+function twoColourCell(parts, glyph) {
+    const present = parts.filter((part) => part !== null);
+    if (present.length === 0)
+        return { ch: " ", fg: "", bg: "" };
+    const luma = (c) => (c.r * 299 + c.g * 587 + c.b * 114) / 1000;
+    const mean = present.reduce((sum, c) => sum + luma(c), 0) / present.length;
+    const light = present.filter((c) => luma(c) >= mean);
+    const dark = present.filter((c) => luma(c) < mean);
+    // One colour in the cell: paint it flat rather than inventing an edge.
+    if (light.length === 0 || dark.length === 0)
+        return { ch: " ", fg: "", bg: hexOf(average(present)) };
+    const fg = average(light);
+    const bg = average(dark);
+    let mask = 0;
+    parts.forEach((part, index) => {
+        // A subpixel with nothing in it takes the background, so a transparent
+        // corner does not pull the glyph toward the mark.
+        if (part && luma(part) >= mean)
+            mask |= 1 << index;
+    });
+    return { ch: glyph(mask), fg: hexOf(fg), bg: hexOf(bg) };
+}
+function average(colors) {
+    const total = colors.reduce((sum, c) => ({ r: sum.r + c.r, g: sum.g + c.g, b: sum.b + c.b }), { r: 0, g: 0, b: 0 });
+    return { r: total.r / colors.length, g: total.g / colors.length, b: total.b / colors.length };
+}
+const hexOf = (c) => hex(c.r, c.g, c.b);
+/**
+ * A sextant glyph for a bitmask of six subpixels: bit 0 upper-left, 1
+ * upper-right, 2 middle-left, 3 middle-right, 4 lower-left, 5 lower-right.
+ *
+ * Unicode 13's Symbols for Legacy Computing allocates U+1FB00..U+1FB3B for
+ * sixty of the sixty-four combinations. It leaves out the four that already had
+ * glyphs: empty, full, the left column and the right column. Those are the
+ * three special cases below, and they are where this mapping goes wrong if it
+ * goes wrong at all.
+ */
+export function sextantGlyph(mask) {
+    const value = mask & 0b111111;
+    if (value === 0)
+        return " ";
+    if (value === 0b111111)
+        return "\u2588";
+    if (value === 0b010101)
+        return "\u258c"; // left column
+    if (value === 0b101010)
+        return "\u2590"; // right column
+    const skipped = (value > 0b010101 ? 1 : 0) + (value > 0b101010 ? 1 : 0);
+    return String.fromCodePoint(0x1fb00 + value - 1 - skipped);
+}
+/**
+ * An image as sextant cells: **six** subpixels per cell, two across and three
+ * down, against a quadrant's four and a half block's two.
+ *
+ * Same two-colour contract as the others, so these cells composite like any
+ * other. The catch is font coverage: sextants arrived in Unicode 13 (2020) and
+ * a font without them draws tofu, which is worse than a coarser image. The
+ * renderer is therefore chosen by `blockMode()` rather than assumed.
+ */
+export function sextantRows(pixels, cols, rows, backdrop, mode) {
+    if (cols <= 0 || rows <= 0 || pixels.width <= 0 || pixels.height <= 0)
+        return [];
+    const box = imageBox(pixels, cols, rows, mode);
+    const gridCols = Math.max(1, box.cols) * 2;
+    const gridRows = Math.max(1, box.rows) * 3;
+    const out = [];
+    for (let row = 0; row < box.rows; row += 1) {
+        const cells = [];
+        for (let col = 0; col < box.cols; col += 1) {
+            const parts = [];
+            for (let dy = 0; dy < 3; dy += 1) {
+                for (let dx = 0; dx < 2; dx += 1) {
+                    parts.push(sampleRgb(pixels, col * 2 + dx, row * 3 + dy, gridCols, gridRows, backdrop));
+                }
+            }
+            cells.push(twoColourCell(parts, sextantGlyph));
+        }
+        out.push(cells);
+    }
+    return out;
+}