Add a CSS + @media demo over tty capability maps (examples/css-tty)

A `@bomb.sh/dom` document is snapshotted into `@bomb.sh/css` and styled
with an environment built from `@bomb.sh/tty`'s capability maps, so the
terminal's own facts drive the stylesheet:

- `environmentFromCapabilities` builds the `env` record for
  `computeTree({ env })`: terminal size becomes the viewport at 8×16px
  per cell (matching the engine's `ch` unit, so `@media (min-width:
  80ch)` selects an 80-column terminal), the probed background color
  becomes `prefers-color-scheme` via relative luminance, the host wires
  its own reduced-motion switch, and resolution is 1.
- `foldCapabilities` folds probe responses onto the static terminfo
  capabilities, mirroring `term.update()`'s merge.
- `capabilityVariables` renders facts without an environment slot
  (color depth, kitty protocols) as root custom properties through the
  root's inline style.

The demo detects the terminal (terminfo plus a bounded raw-mode probe
round-trip when stdin is a TTY), prints the capability → env mapping and
per-node computed styles, and re-evaluates the `@media` queries live on
resize; the stylesheet is compiled once and reused per evaluation.
Piped, it performs one evaluation with a dark fallback scheme.

The stylesheet demonstrates both mechanisms: `@media` blocks flip the
board's column count and main axis on width/orientation and honor the
motion switch, while colors go through `light-dark()` resolved against
the probed scheme — on `color`/`*-color` properties only, so panels use
`background-color` and borders use `border-color`.

Bump the `@bomb.sh/tty` catalog to ^0.10.0 (terminfo capability maps).
Tests cover the adapter in isolation and the stylesheet's behavior
through the real engine; typecheck pins the css ABI with a local type
stub.

Author: natemoo-re

examples/css-tty/README.md

@@ -0,0 +1,57 @@
+# `@examples/css-tty`
+
+CSS + `@media` queries driven by terminal capabilities: a `@bomb.sh/dom`
+document is snapshotted into `@bomb.sh/css`, whose environment is built from
+`@bomb.sh/tty`'s capability maps.
+
+```
+detectTerminal() ──▶ Capabilities ──▶ foldCapabilities(probe responses)
+                                            │
+                                            ▼
+                     environmentFromCapabilities(caps, size) ──▶ env
+                                            │
+computeTree(sheet, { nodes, parents, env }) ◀┘
+```
+
+## The wiring
+
+| Terminal capability          | CSS surface                                      |
+| ---------------------------- | ------------------------------------------------ |
+| columns / rows               | `env.viewportWidth` / `Height` (8×16px per cell) |
+| probed background color      | `env.colorScheme` (background luminance)         |
+| host motion switch           | `env.reducedMotion` (terminals expose none)      |
+| cell aspect                  | `env.resolution: 1`                              |
+| color depth, kitty protocols | root custom properties via `capabilityVariables` |
+
+Two paths carry capabilities into values:
+
+- **`@media`** reads the environment record: `@media (min-width: 80ch)`
+  flips the board to two columns (1ch = 8px, so `80ch` = 80 columns),
+  `@media (orientation: …)` picks the main axis, and
+  `@media (prefers-reduced-motion: reduce)` responds to the host switch.
+- **`light-dark()`** resolves at computed-value time against the color
+  scheme derived from the probed background. Resolution covers `color` and
+  `*-color` properties, so the stylesheet uses `background-color` and
+  `border-color` rather than the shorthands.
+
+## Run
+
+```
+pnpm --filter @examples/css-tty demo
+```
+
+With a TTY the demo probes the terminal (raw-mode stdin for ~250ms), folds
+the responses into the capability map, and re-evaluates the `@media` queries
+on every resize; Ctrl-C exits. Piped, it performs one evaluation with the
+static capabilities and a dark fallback scheme.
+
+## Test
+
+```
+pnpm --filter @examples/css-tty test
+```
+
+The suite covers the adapter in isolation and the stylesheet's behavior
+through the real engine: the 80ch breakpoint flip, the orientation axis,
+the motion switch, `light-dark()` under both schemes, and the computed-value
+drop for malformed inline calls.

examples/css-tty/package.json

@@ -0,0 +1,28 @@
+{
+	"name": "@examples/css-tty",
+	"private": true,
+	"license": "MIT",
+	"type": "module",
+	"exports": {
+		".": "./src/index.ts"
+	},
+	"scripts": {
+		"demo": "node --experimental-transform-types src/demo.ts",
+		"typecheck": "tsgo --noEmit -p tsconfig.json",
+		"test": "vitest run",
+		"format": "bsh format",
+		"format:check": "bsh format --check",
+		"lint": "bsh lint"
+	},
+	"dependencies": {
+		"@bomb.sh/css": "workspace:*",
+		"@bomb.sh/dom": "workspace:*",
+		"@bomb.sh/tty": "catalog:"
+	},
+	"devDependencies": {
+		"@bomb.sh/tools": "^0.6.1",
+		"@types/node": "^22",
+		"@typescript/native-preview": "7.0.0-dev.20260623.1",
+		"vitest": "^4.1.2"
+	}
+}

examples/css-tty/src/css-types.d.ts

@@ -0,0 +1,63 @@
+// Type stub for `@bomb.sh/css`: the package ships untyped JS, so this file
+// pins the surface the example uses. Wired up through `paths` in the
+// example tsconfig (type-checking only; runtime always loads the real
+// package). The WIT world `bombshell:css@0.4.0` is the source of truth.
+
+/// Rendering environment consulted by `@media` evaluation.
+export interface Environment {
+	viewportWidth?: number;
+	viewportHeight?: number;
+	colorScheme?: 'light' | 'dark';
+	reducedMotion?: boolean;
+	resolution?: number;
+}
+
+/// One element of the host tree: trees ship as a flat, document-ordered
+/// list plus a parallel parent-index list (`NO_PARENT` marks a root).
+export interface CssNode {
+	tag: string;
+	id?: string;
+	classes?: string[];
+	attributes?: [string, string][];
+	/// WIT `node-state` bits: focus = 1, hover = 2, active = 4.
+	state?: number;
+	width?: number;
+	height?: number;
+	/// Inline style declarations; a real cascade slot.
+	style?: string;
+}
+
+export interface Diagnostic {
+	/// 0 = error, 1 = warning.
+	severity: 0 | 1;
+	code: string;
+	message: string;
+}
+
+/// A `[name, value]` computed declaration.
+export type ComputedProperty = [string, string];
+
+export interface Sheet {
+	readonly ir: Uint8Array;
+	readonly diagnostics: Diagnostic[];
+	compute(
+		nodes: CssNode[],
+		options: { parents: number[]; target: number; env?: Environment },
+	): ComputedProperty[];
+	computeTree(
+		nodes: CssNode[],
+		options: { parents: number[]; env?: Environment },
+	): ComputedProperty[][];
+	release(): void;
+	[Symbol.dispose](): void;
+}
+
+export declare function compile(css: string, origin?: number): Sheet;
+
+export declare function computeTree(
+	sheet: Sheet,
+	options: { nodes: CssNode[]; parents: number[]; env?: Environment },
+): ComputedProperty[][];
+
+/// Parent index marking a root with no parent (u32::MAX).
+export declare const NO_PARENT: number;

examples/css-tty/src/demo.ts

@@ -0,0 +1,165 @@
+// CSS + @media queries driven by terminal capabilities.
+//
+// Detects the terminal (terminfo, plus a bounded probe round-trip when
+// stdin is a TTY), folds the capability maps into the CSS environment,
+// snapshots a `@bomb.sh/dom` document, and computes styles with
+// `@bomb.sh/css`. While the demo stays open, resizing the terminal
+// re-evaluates the `@media` queries live; the parsed stylesheet is reused
+// across evaluations, exactly like the engine's per-frame story.
+//
+// Usage: pnpm --filter @examples/css-tty demo
+import { compile, type ComputedProperty, type CssNode } from '@bomb.sh/css';
+import { createInput, detectTerminal, type CapabilityEvent, type TerminalInfo } from '@bomb.sh/tty';
+import {
+	capabilityVariables,
+	environmentFromCapabilities,
+	foldCapabilities,
+	type MergedCapabilities,
+	type TerminalSize,
+} from './index.ts';
+import { createDemoDocument, snapshotDocument } from './tree.ts';
+import { DEMO_CSS } from './styles.ts';
+
+/// How long to wait for probe responses before proceeding with whatever
+/// arrived. Terminals that never answer keep the static capabilities.
+const PROBE_TIMEOUT_MS = 250;
+
+function currentSize(): TerminalSize {
+	return {
+		columns: process.stdout.columns ?? 80,
+		rows: process.stdout.rows ?? 24,
+	};
+}
+
+const isCapability = (event: { type: string }): event is CapabilityEvent =>
+	event.type === 'capability';
+
+/// Write the terminfo probe, collect responses through the input parser
+/// until the theme answers (or the timeout lapses), and fold the events
+/// onto the static capabilities. Runs in a short raw-mode window so the
+/// responses reach the parser byte-for-byte.
+async function probeCapabilities(terminfo: TerminalInfo): Promise<MergedCapabilities> {
+	const input = await createInput({ terminfo });
+	const events: CapabilityEvent[] = [];
+	const stream = process.stdin;
+	const wasRaw = stream.isRaw ?? false;
+
+	await new Promise<void>((resolve) => {
+		let done = false;
+		const finish = () => {
+			if (done) {
+				return;
+			}
+			done = true;
+			clearTimeout(timer);
+			stream.off('data', onData);
+			// A response ending mid-burst can leave a buffered lone ESC;
+			// one argument-less scan flushes it.
+			for (const event of input.scan().events) {
+				if (isCapability(event)) {
+					events.push(event);
+				}
+			}
+			resolve();
+		};
+		const onData = (chunk: Buffer | string): void => {
+			const bytes = typeof chunk === 'string' ? Buffer.from(chunk) : chunk;
+			for (const event of input.scan(new Uint8Array(bytes)).events) {
+				if (isCapability(event)) {
+					events.push(event);
+				}
+			}
+			if (events.some((event) => event.key === 'background-color')) {
+				finish();
+			}
+		};
+		const timer = setTimeout(finish, PROBE_TIMEOUT_MS);
+		stream.setRawMode(true);
+		stream.resume();
+		stream.on('data', onData);
+		process.stdout.write(terminfo.probe);
+	});
+
+	stream.setRawMode(wasRaw);
+	stream.pause();
+	return foldCapabilities(terminfo.capabilities, events);
+}
+
+/// Snapshot the demo document and compute every node's style against the
+/// environment built from the capability maps. The stylesheet is compiled
+/// once and reused; each evaluation is one `computeTree` call.
+function evaluate(sheet: ReturnType<typeof compile>, capabilities: MergedCapabilities) {
+	const size = currentSize();
+	const document = createDemoDocument();
+	const { nodes, parents } = snapshotDocument(document, {
+		rootStyle: capabilityVariables(capabilities),
+		viewport: size,
+	});
+	const env = environmentFromCapabilities(capabilities, { size });
+	return { env, nodes, computed: sheet.computeTree(nodes, { parents, env }) };
+}
+
+const formatDeclarations = (declarations: ComputedProperty[]): string =>
+	declarations.map(([name, value]) => `${name}: ${value}`).join('; ');
+
+const formatNodeLabel = (node: CssNode): string =>
+	[node.tag, node.id ? `#${node.id}` : '', (node.classes ?? []).map((c) => `.${c}`).join('')].join(
+		'',
+	);
+
+function report(capabilities: MergedCapabilities, evaluated: ReturnType<typeof evaluate>): string {
+	const { env, nodes, computed } = evaluated;
+	const theme = capabilities.theme;
+	const lines: string[] = [
+		`capabilities  colors=${capabilities.colors} truecolor=${capabilities.trueColor ? 'yes' : 'no'}`,
+		`              theme=${theme.background ? `bg ${rgb(theme.background)}` : 'unprobed'}`,
+		`              kitty-keyboard=${capabilities.kittyKeyboard} kitty-graphics=${capabilities.kittyGraphics}`,
+		`env           viewport=${env.viewportWidth}×${env.viewportHeight}px color-scheme=${env.colorScheme}`,
+		`              reduced-motion=${env.reducedMotion ? 'reduce' : 'no-preference'} resolution=${env.resolution}`,
+		'',
+	];
+	for (let index = 0; index < nodes.length; index++) {
+		lines.push(
+			`${String(index).padStart(2, ' ')} ${formatNodeLabel(nodes[index]!)}`,
+			`    ${formatDeclarations(computed[index]!)}`,
+		);
+	}
+	return lines.join('\n');
+}
+
+function rgb({ r, g, b }: { r: number; g: number; b: number }): string {
+	const hex = (channel: number) => channel.toString(16).padStart(2, '0');
+	return `#${hex(r)}${hex(g)}${hex(b)}`;
+}
+
+const sheet = compile(DEMO_CSS, 2);
+for (const diagnostic of sheet.diagnostics) {
+	console.warn(`css ${diagnostic.severity === 0 ? 'error' : 'warning'}: ${diagnostic.message}`);
+}
+
+const terminfo = await detectTerminal();
+const capabilities = process.stdin.isTTY
+	? await probeCapabilities(terminfo)
+	: foldCapabilities(terminfo.capabilities, []);
+
+let first = true;
+const print = () => {
+	const text = report(capabilities, evaluate(sheet, capabilities));
+	// Repaints clear the screen so the @media flip is visible in place.
+	process.stdout.write(first ? `\n${text}\n` : `\x1b[H\x1b[2J${text}\n`);
+	first = false;
+};
+
+print();
+
+if (process.stdin.isTTY) {
+	console.info('\nresize the terminal to re-evaluate @media · Ctrl-C exits');
+	process.stdout.on('resize', print);
+	process.on('SIGINT', () => {
+		sheet.release();
+		process.exit(0);
+	});
+} else {
+	// Piped or non-interactive: one evaluation, then done.
+	sheet.release();
+}