Skip to content

Commit 36c03fc

Browse files
committed
feat: img element — public surface, validation, and test suite
The Graphics Specification's public TypeScript API: - ops.ts: the void img() directive (image registry id, required alt, sizing axes, evidence-gated variant override, element bg) and its transfer encoding, mirroring the C decode. - term.ts: Term.setImage/removeImage - the two-phase native surface (begin validates and reserves at an absolute address, the host copies pixels, commit bumps the version) with closed RangeErrors; update() forwards the kitty-graphics capability into the renderer's mirror and surfaces the TINV-5 cleanup bytes the engine emits on denial and resize; createTerm takes imagePoolBytes. - validate.ts: the Img op shape (registry id range, required alt, variant union). - test/graphics.test.ts: the §14 suite - tier resolution, kitty conformance (chunking, replace cycles, steady-state silence, move re-places), cleanup/removal, capability invalidation, resize, ascii art determinism and alpha, alt tier, registry validation, input-stream cleanliness.
1 parent 47b70e5 commit 36c03fc

5 files changed

Lines changed: 685 additions & 7 deletions

File tree

‎.changeset/img-element.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
---
2+
"@bomb.sh/tty": minor
3+
---
4+
5+
Adds the `img()` directive — declarative images rendered through a fidelity ladder: kitty graphics protocol pixels, shape-aware ASCII character art, or alt text, resolved from capability evidence (`RuntimeCapabilities.kittyGraphics`).
6+
7+
Surfaces are caller-owned decoded RGBA buffers managed by the Term:
8+
9+
```ts
10+
term.setImage(1, { width: 128, height: 64, pixels: rgba8 });
11+
term.removeImage(1); // returns deletion bytes to write now
12+
term.render([img("cover", { image: 1, alt: "cover art" })]);
13+
```
14+
15+
`createTerm` takes an `imagePoolBytes` option (default 4 MiB) sizing the fixed pixel pool. Transmission is lazy; re-transmission only on data change; steady-state renders are byte-silent. `update()` emits cleanup bytes immediately when a capability denial or resize kills live placements (TINV-5). Line mode caps the ladder at ascii. Errors surface as `IMAGE_NOT_FOUND`, `IMAGE_PLACEMENTS_EXCEEDED`, and `IMAGE_PLACEMENT_COLLISION`.

‎ops.ts‎

Lines changed: 93 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,8 @@ const OP_OPEN_ELEMENT = 0x02;
2525
const OP_TEXT = 0x03;
2626
const OP_CLOSE_ELEMENT = 0x04;
2727
const OP_SNAPSHOT = 0x05;
28+
/* the void image directive (Graphics Specification §6.1) */
29+
const OP_IMG = 0x06;
2830

2931
/* Property group masks for OPEN_ELEMENT */
3032
const PROP_LAYOUT = 0x01;
@@ -323,6 +325,37 @@ export function pack(
323325
o = packString(view, str, o, end, "text content");
324326
break;
325327
}
328+
329+
case OP_IMG: {
330+
view.setUint32(o, OP_IMG, true);
331+
o += 4;
332+
333+
o = packString(view, encoder.encode(op.id), o, end, "element id");
334+
335+
// image registry id; 0 = omitted (alt-only element)
336+
view.setUint32(o, op.image ?? 0, true);
337+
o += 4;
338+
339+
// variant (low byte) | bg_flag (byte 1) | pad
340+
view.setUint32(
341+
o,
342+
IMG_VARIANT_CODE[op.variant ?? "auto"] |
343+
((op.bg !== undefined ? 1 : 0) << 8),
344+
true,
345+
);
346+
o += 4;
347+
348+
o = packAxis(view, o, op.width ?? fit());
349+
o = packAxis(view, o, op.height ?? fit());
350+
351+
o = packString(view, encoder.encode(op.alt), o, end, "alt text");
352+
353+
if (op.bg !== undefined) {
354+
view.setUint32(o, op.bg, true);
355+
o += 4;
356+
}
357+
break;
358+
}
326359
}
327360
if (o > end) {
328361
throw new RangeError(
@@ -488,12 +521,61 @@ export interface Text {
488521
caret?: number;
489522
}
490523

524+
export type ImgVariant = "auto" | "kitty" | "ascii" | "alt";
525+
526+
export interface ImgProps {
527+
/** Registry id of the image to render. Omit for an alt-only element. */
528+
image?: number;
529+
/** Required. Text fallback and description. "" = decorative. */
530+
alt: string;
531+
width?: SizingAxis;
532+
height?: SizingAxis;
533+
/** Tier override; evidence-gated — falls through the auto ladder when the
534+
* tier's evidence is missing (Graphics Specification §9.1). */
535+
variant?: ImgVariant;
536+
/** Element background, same value space as open({ bg }). */
537+
bg?: number;
538+
}
539+
540+
/** The void image element: one self-closing directive, no children, not
541+
* paired with close() (Graphics Specification §6.1). */
542+
export interface Img {
543+
directive: typeof OP_IMG;
544+
id: string;
545+
image?: number;
546+
alt: string;
547+
width?: SizingAxis;
548+
height?: SizingAxis;
549+
variant?: ImgVariant;
550+
bg?: number;
551+
}
552+
553+
const IMG_VARIANT_CODE: Record<ImgVariant, number> = {
554+
auto: 0,
555+
kitty: 1,
556+
ascii: 2,
557+
alt: 3,
558+
};
559+
560+
export function img(id: string, props: ImgProps): Img {
561+
return {
562+
directive: OP_IMG,
563+
id,
564+
image: props.image,
565+
alt: props.alt,
566+
width: props.width ?? fit(),
567+
height: props.height ?? fit(),
568+
variant: props.variant ?? "auto",
569+
bg: props.bg,
570+
};
571+
}
572+
491573
interface Snapshot {
492574
directive: typeof OP_SNAPSHOT;
493575
data: Uint8Array;
494576
}
495577

496-
export type Op = OpenElement | Text | CloseElement | Snapshot;
578+
export type Op = OpenElement | Text | CloseElement | Snapshot | Img;
497579

498580
export function open(
499581
id: string,
@@ -542,6 +624,16 @@ function packSize(ops: Op[]): number {
542624
n += 4 + Math.ceil(encoder.encode(op.content).length / 4) * 4; // string
543625
break;
544626
}
627+
case OP_IMG: {
628+
n += 4; // opcode
629+
n += 4 + Math.ceil(encoder.encode(op.id).length / 4) * 4; // id string
630+
n += 4; // image registry id
631+
n += 4; // variant | bg_flag | pad
632+
n += 6 * 4; // width + height axes
633+
n += 4 + Math.ceil(encoder.encode(op.alt).length / 4) * 4; // alt string
634+
if (op.bg !== undefined) n += 4; // element background
635+
break;
636+
}
545637
}
546638
}
547639
return n;

‎term.ts‎

Lines changed: 123 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,21 @@ export interface TermOptions {
1414
* baseline.
1515
*/
1616
terminfo?: TerminalInfo;
17+
/**
18+
* Sizes the Term's carved image pixel pool (Graphics Specification §5.3).
19+
* Default 4 MiB. The registry never grows at runtime (INV-I8).
20+
*/
21+
imagePoolBytes?: number;
22+
}
23+
24+
/**
25+
* Decoded raster pixels for the image registry (Graphics Specification
26+
* §6.2): straight (non-premultiplied) RGBA8, top-to-bottom rows.
27+
*/
28+
export interface ImageData {
29+
width: number; // positive integer
30+
height: number; // positive integer
31+
pixels: Uint8Array; // exactly width * height * 4 bytes
1732
}
1833

1934
/**
@@ -126,6 +141,9 @@ const ERROR_TYPES = [
126141
"UNBALANCED_OPEN_CLOSE",
127142
"CLIP_DEPTH_EXCEEDED",
128143
"COMBINING_MARKS_EXCEEDED",
144+
"IMAGE_NOT_FOUND",
145+
"IMAGE_PLACEMENTS_EXCEEDED",
146+
"IMAGE_PLACEMENT_COLLISION",
129147
] as const;
130148

131149
export interface ClayError {
@@ -157,17 +175,45 @@ export interface Term {
157175
*/
158176
update(events: readonly InputEvent[]): Uint8Array;
159177

178+
/**
179+
* Put a decoded image into the Term's pixel-surface registry (Graphics
180+
* Specification §6.2). Synchronous, byte-free: transmission is lazy, on
181+
* the first render that places the image. Throws RangeError on
182+
* validation failure or pool/registry exhaustion. Re-setting a live id
183+
* replaces the image and re-transmits on the next placing render.
184+
*/
185+
setImage(id: number, data: ImageData): void;
186+
187+
/**
188+
* Remove a registry image. Returns bytes to write now: the terminal's
189+
* data-freeing deletion block when the id was live, empty otherwise.
190+
* Idempotent; the covered cells are reconciled so the next render
191+
* repaints them.
192+
*/
193+
removeImage(id: number): Uint8Array;
194+
160195
/** Frozen snapshot of the current merged capability state. */
161196
readonly capabilities: RuntimeCapabilities;
162197
}
163198

199+
const IMAGE_ERROR_MESSAGES: Record<number, string> = {
200+
[-1]: "registry id outside [1, 4294967295]",
201+
[-2]: "width and height must be positive integers",
202+
[-4]: "image registry table full",
203+
[-5]: "image pixel pool exhausted (raise the imagePoolBytes option)",
204+
[-6]: "unknown registry id",
205+
};
206+
207+
function imageRangeError(n: number): RangeError {
208+
return new RangeError(
209+
`setImage failed: ${IMAGE_ERROR_MESSAGES[n] ?? `native error ${n}`}`,
210+
);
211+
}
212+
164213
export async function createTerm(options: TermOptions): Promise<Term> {
165-
let { width, height, terminfo } = options;
214+
let { width, height, terminfo, imagePoolBytes } = options;
166215

167-
let native = await createTermNative(
168-
width,
169-
height,
170-
);
216+
let native = await createTermNative(width, height, imagePoolBytes);
171217
let { memory } = native;
172218

173219
let currentCaps: RuntimeCapabilities = runtimeFromStatic(
@@ -283,6 +329,50 @@ export async function createTerm(options: TermOptions): Promise<Term> {
283329
return { output, events, info, errors, animating };
284330
},
285331

332+
setImage(id: number, data: ImageData): void {
333+
if (!Number.isInteger(id) || id < 1 || id > 4294967295) {
334+
throw new RangeError(`invalid image registry id ${id}`);
335+
}
336+
if (
337+
!Number.isInteger(data.width) || data.width < 1 ||
338+
!Number.isInteger(data.height) || data.height < 1
339+
) {
340+
throw new RangeError(
341+
`invalid image dimensions ${data.width}x${data.height}`,
342+
);
343+
}
344+
if (data.pixels.length !== data.width * data.height * 4) {
345+
throw new RangeError(
346+
`image pixels length ${data.pixels.length} !== ${data.width} * ${data.height} * 4`,
347+
);
348+
}
349+
let addr = native.imageBegin(
350+
native.statePtr,
351+
id,
352+
data.width,
353+
data.height,
354+
);
355+
if (addr < 0) {
356+
throw imageRangeError(addr);
357+
}
358+
new Uint8Array(memory.buffer).set(data.pixels, addr);
359+
let committed = native.imageCommit(native.statePtr, id);
360+
if (committed < 0) {
361+
throw imageRangeError(committed);
362+
}
363+
},
364+
365+
removeImage(id: number): Uint8Array {
366+
let n = native.imageRemove(native.statePtr, id);
367+
if (n <= 0) {
368+
return new Uint8Array(0);
369+
}
370+
// copy: the native output buffer is reused by the next call; these
371+
// bytes are the caller's to write now (TINV-5)
372+
return new Uint8Array(memory.buffer, native.output(native.statePtr), n)
373+
.slice();
374+
},
375+
286376
update(events: readonly InputEvent[]): Uint8Array {
287377
let out: Uint8Array[] = [];
288378

@@ -298,6 +388,18 @@ export async function createTerm(options: TermOptions): Promise<Term> {
298388
throw new RangeError(`invalid terminal dimensions ${w}x${h}`);
299389
}
300390
if (w !== width || h !== height) {
391+
// Graphics Specification §10.5: deletion bytes for live
392+
// placements precede the placements record's discard
393+
let prepared = native.graphicsResizePrepare(native.statePtr);
394+
if (prepared > 0) {
395+
out.push(
396+
new Uint8Array(
397+
memory.buffer,
398+
native.output(native.statePtr),
399+
prepared,
400+
).slice(),
401+
);
402+
}
301403
width = w;
302404
height = h;
303405
native.update(width, height);
@@ -307,6 +409,22 @@ export async function createTerm(options: TermOptions): Promise<Term> {
307409
lastRenderAt = undefined;
308410
wasAnimating = false;
309411
}
412+
} else if (
413+
c.type === "capability" && c.key === "kitty-graphics"
414+
) {
415+
// the renderer's capability mirror (terminfo-spec §4.2); the
416+
// denial path emits §11.2's deletion bytes immediately (TINV-5)
417+
let kitty = c.value ? 1 : 0;
418+
let wrote = native.graphicsCapability(native.statePtr, kitty);
419+
if (wrote > 0) {
420+
out.push(
421+
new Uint8Array(
422+
memory.buffer,
423+
native.output(native.statePtr),
424+
wrote,
425+
).slice(),
426+
);
427+
}
310428
}
311429

312430
currentCaps = next;

0 commit comments

Comments
 (0)