@feelgxxd/textel 0.0.0-stage → 0.2.0

package/dist/loaders/gltf.js

@@ -0,0 +1,187 @@
+import { MeshBuilder } from "../mesh.js";
+const COMPONENTS = { SCALAR: 1, VEC2: 2, VEC3: 3, VEC4: 4, MAT2: 4, MAT3: 9, MAT4: 16 };
+/** `.glb` (binary) or `.gltf` (JSON) bytes. Applies node transforms; all triangle primitives go into one mesh. */
+export function parseGLTF(bytes, opts = {}) {
+    let json, bin = null;
+    const dv = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    if (bytes.length >= 12 && dv.getUint32(0, true) === 0x46546c67) {
+        // GLB: header, then a JSON chunk and an optional BIN chunk
+        let o = 12;
+        json = {};
+        while (o + 8 <= bytes.length) {
+            const len = dv.getUint32(o, true), type = dv.getUint32(o + 4, true);
+            const body = bytes.subarray(o + 8, o + 8 + len);
+            if (type === 0x4e4f534a)
+                json = JSON.parse(new TextDecoder().decode(body));
+            else if (type === 0x004e4942)
+                bin = body;
+            o += 8 + len;
+        }
+    }
+    else {
+        json = JSON.parse(new TextDecoder().decode(bytes));
+    }
+    // quantized attributes (KHR_mesh_quantization) are fine: `read` handles every component type
+    const unsupported = (json.extensionsRequired ?? []).filter((e) => e === 'KHR_draco_mesh_compression' || e === 'EXT_meshopt_compression');
+    if (unsupported.length)
+        throw new Error(`compressed glTF (${unsupported.join(', ')}) is not supported yet; export it without compression`);
+    const buffers = (json.buffers ?? []).map((buf, i) => {
+        if (buf.uri === undefined) {
+            if (!bin)
+                throw new Error(`buffer ${i} has no data`);
+            return bin;
+        }
+        const m = /^data:[^,]*;base64,(.*)$/.exec(buf.uri);
+        if (m)
+            return base64(m[1]);
+        if (!opts.resolve)
+            throw new Error(`external buffer "${buf.uri}" needs a resolver`);
+        return opts.resolve(decodeURIComponent(buf.uri));
+    });
+    const read = (index) => {
+        const acc = json.accessors?.[index];
+        if (!acc)
+            throw new Error(`missing accessor ${index}`);
+        const size = COMPONENTS[acc.type] ?? 1, out = new Float32Array(acc.count * size);
+        if (acc.bufferView === undefined)
+            return { data: out, size, count: acc.count };
+        const bv = json.bufferViews[acc.bufferView], buf = buffers[bv.buffer];
+        const view = new DataView(buf.buffer, buf.byteOffset, buf.byteLength);
+        const ct = acc.componentType;
+        const csize = ct === 5126 || ct === 5125 ? 4 : ct === 5123 || ct === 5122 ? 2 : 1;
+        const stride = bv.byteStride || csize * size, base = (bv.byteOffset ?? 0) + (acc.byteOffset ?? 0);
+        const norm = !!acc.normalized;
+        for (let e = 0; e < acc.count; e++)
+            for (let c = 0; c < size; c++) {
+                const o = base + e * stride + c * csize;
+                let x;
+                switch (ct) {
+                    case 5126:
+                        x = view.getFloat32(o, true);
+                        break;
+                    case 5125:
+                        x = view.getUint32(o, true);
+                        break;
+                    case 5123:
+                        x = view.getUint16(o, true);
+                        if (norm)
+                            x /= 65535;
+                        break;
+                    case 5122:
+                        x = view.getInt16(o, true);
+                        if (norm)
+                            x = Math.max(x / 32767, -1);
+                        break;
+                    case 5121:
+                        x = view.getUint8(o);
+                        if (norm)
+                            x /= 255;
+                        break;
+                    case 5120:
+                        x = view.getInt8(o);
+                        if (norm)
+                            x = Math.max(x / 127, -1);
+                        break;
+                    default: throw new Error(`unknown component type ${ct}`);
+                }
+                out[e * size + c] = x;
+            }
+        return { data: out, size, count: acc.count };
+    };
+    const b = new MeshBuilder();
+    const matName = (i) => (i === undefined ? 'default' : json.materials?.[i]?.name || `material${i}`);
+    const visit = (ni, parent, depth) => {
+        if (depth > 64)
+            throw new Error('node hierarchy too deep');
+        const node = json.nodes?.[ni];
+        if (!node)
+            return;
+        const world = mul(parent, local(node));
+        if (node.mesh !== undefined)
+            addMesh(node.mesh, world);
+        for (const c of node.children ?? [])
+            visit(c, world, depth + 1);
+    };
+    const addMesh = (mi, M) => {
+        const nm = normalMatrix(M);
+        for (const prim of json.meshes?.[mi]?.primitives ?? []) {
+            const mode = prim.mode ?? 4;
+            if (mode !== 4 && mode !== 5 && mode !== 6)
+                continue; // points and lines
+            if (prim.attributes.POSITION === undefined)
+                continue;
+            const pos = read(prim.attributes.POSITION);
+            const nor = prim.attributes.NORMAL !== undefined ? read(prim.attributes.NORMAL) : null;
+            const mat = b.material(matName(prim.material));
+            const first = b.positions.length / 3;
+            for (let v = 0; v < pos.count; v++) {
+                const x = pos.data[v * 3], y = pos.data[v * 3 + 1], z = pos.data[v * 3 + 2];
+                const X = M[0] * x + M[4] * y + M[8] * z + M[12], Y = M[1] * x + M[5] * y + M[9] * z + M[13], Z = M[2] * x + M[6] * y + M[10] * z + M[14];
+                if (nor) {
+                    const a = nor.data[v * 3], bb = nor.data[v * 3 + 1], c = nor.data[v * 3 + 2];
+                    b.vertex(X, Y, Z, nm[0] * a + nm[3] * bb + nm[6] * c, nm[1] * a + nm[4] * bb + nm[7] * c, nm[2] * a + nm[5] * bb + nm[8] * c);
+                }
+                else
+                    b.vertex(X, Y, Z);
+            }
+            const idx = prim.indices !== undefined ? read(prim.indices).data : null;
+            const n = idx ? idx.length : pos.count;
+            const get = (k) => first + (idx ? idx[k] : k);
+            if (mode === 4)
+                for (let k = 0; k + 2 < n; k += 3)
+                    b.triangle(get(k), get(k + 1), get(k + 2), mat);
+            else if (mode === 5)
+                for (let k = 0; k + 2 < n; k++)
+                    k % 2 ? b.triangle(get(k + 1), get(k), get(k + 2), mat) : b.triangle(get(k), get(k + 1), get(k + 2), mat);
+            else
+                for (let k = 1; k + 1 < n; k++)
+                    b.triangle(get(0), get(k), get(k + 1), mat);
+        }
+    };
+    const I = [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1];
+    const scene = json.scenes?.[json.scene ?? 0];
+    let roots = scene?.nodes;
+    if (!roots) {
+        // no scene: every node that is nobody's child
+        const kids = new Set((json.nodes ?? []).flatMap((n) => n.children ?? []));
+        roots = (json.nodes ?? []).map((_, i) => i).filter((i) => !kids.has(i));
+    }
+    for (const r of roots)
+        visit(r, I, 0);
+    if (!b.indices.length)
+        throw new Error('no triangle meshes found in the glTF');
+    return b.build();
+}
+/** column-major 4x4 */
+function mul(a, b) {
+    const o = new Array(16).fill(0);
+    for (let c = 0; c < 4; c++)
+        for (let r = 0; r < 4; r++)
+            for (let k = 0; k < 4; k++)
+                o[c * 4 + r] += a[k * 4 + r] * b[c * 4 + k];
+    return o;
+}
+function local(n) {
+    if (n.matrix)
+        return n.matrix;
+    const [tx, ty, tz] = n.translation ?? [0, 0, 0], [x, y, z, w] = n.rotation ?? [0, 0, 0, 1], [sx, sy, sz] = n.scale ?? [1, 1, 1];
+    return [
+        (1 - 2 * (y * y + z * z)) * sx, 2 * (x * y + z * w) * sx, 2 * (x * z - y * w) * sx, 0,
+        2 * (x * y - z * w) * sy, (1 - 2 * (x * x + z * z)) * sy, 2 * (y * z + x * w) * sy, 0,
+        2 * (x * z + y * w) * sz, 2 * (y * z - x * w) * sz, (1 - 2 * (x * x + y * y)) * sz, 0,
+        tx, ty, tz, 1,
+    ];
+}
+/** inverse transpose of the upper 3x3, column-major 3x3 */
+function normalMatrix(m) {
+    const a = m[0], b = m[1], c = m[2], d = m[4], e = m[5], f = m[6], g = m[8], h = m[9], i = m[10];
+    const A = e * i - f * h, B = -(d * i - f * g), C = d * h - e * g;
+    const det = a * A + b * B + c * C || 1;
+    // cofactor matrix / det = inverse transpose
+    return [A / det, B / det, C / det, -(b * i - c * h) / det, (a * i - c * g) / det, -(a * h - b * g) / det, (b * f - c * e) / det, -(a * f - c * d) / det, (a * e - b * d) / det];
+}
+function base64(s) {
+    if (typeof atob === 'function')
+        return Uint8Array.from(atob(s), (c) => c.charCodeAt(0));
+    throw new Error('base64 decoding is not available');
+}

package/dist/loaders/index.d.ts

@@ -0,0 +1,8 @@
+import type { Mesh } from '../mesh.ts';
+import { parseGLTF, type GltfOptions } from './gltf.ts';
+import { parseOBJ } from './obj.ts';
+import { parseSTL } from './stl.ts';
+export { parseGLTF, parseOBJ, parseSTL };
+export declare const MODEL_EXTENSIONS: string[];
+/** Picks a parser from the file name, falling back to sniffing the bytes. */
+export declare function parseModel(bytes: Uint8Array, filename?: string, opts?: GltfOptions): Mesh;

package/dist/loaders/index.js

@@ -0,0 +1,24 @@
+import { parseGLTF } from "./gltf.js";
+import { parseOBJ } from "./obj.js";
+import { parseSTL } from "./stl.js";
+export { parseGLTF, parseOBJ, parseSTL };
+export const MODEL_EXTENSIONS = ['.glb', '.gltf', '.obj', '.stl'];
+/** Picks a parser from the file name, falling back to sniffing the bytes. */
+export function parseModel(bytes, filename = '', opts = {}) {
+    const ext = filename.toLowerCase().match(/\.[a-z0-9]+$/)?.[0] ?? '';
+    if (ext === '.glb' || ext === '.gltf')
+        return parseGLTF(bytes, opts);
+    if (ext === '.obj')
+        return parseOBJ(new TextDecoder().decode(bytes));
+    if (ext === '.stl')
+        return parseSTL(bytes);
+    // no or unknown extension
+    if (bytes.length >= 4 && bytes[0] === 0x67 && bytes[1] === 0x6c && bytes[2] === 0x54 && bytes[3] === 0x46)
+        return parseGLTF(bytes, opts);
+    const head = new TextDecoder().decode(bytes.subarray(0, 512)).trimStart();
+    if (head.startsWith('{'))
+        return parseGLTF(bytes, opts);
+    if (/^(v|vn|vt|o|g|mtllib|#)\s/m.test(head))
+        return parseOBJ(new TextDecoder().decode(bytes));
+    return parseSTL(bytes);
+}

package/dist/loaders/obj.d.ts

@@ -0,0 +1,3 @@
+import { type Mesh } from '../mesh.ts';
+/** Wavefront OBJ: v, vn, f (any polygon, fan-triangulated), usemtl. Texture coordinates are ignored. */
+export declare function parseOBJ(text: string): Mesh;

package/dist/loaders/obj.js

@@ -0,0 +1,52 @@
+import { MeshBuilder } from "../mesh.js";
+/** Wavefront OBJ: v, vn, f (any polygon, fan-triangulated), usemtl. Texture coordinates are ignored. */
+export function parseOBJ(text) {
+    const v = [], vn = [];
+    const b = new MeshBuilder();
+    const seen = new Map();
+    let mat = -1;
+    const lines = text.split(/\r?\n/);
+    for (let ln = 0; ln < lines.length; ln++) {
+        const line = lines[ln].trim();
+        if (!line || line[0] === '#')
+            continue;
+        const parts = line.split(/\s+/), tag = parts[0];
+        if (tag === 'v')
+            v.push(+parts[1], +parts[2], +parts[3]);
+        else if (tag === 'vn')
+            vn.push(+parts[1], +parts[2], +parts[3]);
+        else if (tag === 'usemtl') {
+            mat = b.material(parts.slice(1).join(' ') || 'default');
+            seen.clear();
+        }
+        else if (tag === 'f') {
+            if (mat < 0)
+                mat = b.material('default');
+            const poly = [];
+            for (let p = 1; p < parts.length; p++) {
+                const key = parts[p];
+                let idx = seen.get(key);
+                if (idx === undefined) {
+                    const [vs, , ns] = key.split('/');
+                    let vi = parseInt(vs, 10);
+                    vi = vi < 0 ? v.length / 3 + vi : vi - 1;
+                    if (!(vi >= 0 && vi < v.length / 3))
+                        throw new Error(`obj line ${ln + 1}: bad vertex index "${key}"`);
+                    if (ns) {
+                        let ni = parseInt(ns, 10);
+                        ni = ni < 0 ? vn.length / 3 + ni : ni - 1;
+                        idx = b.vertex(v[vi * 3], v[vi * 3 + 1], v[vi * 3 + 2], vn[ni * 3], vn[ni * 3 + 1], vn[ni * 3 + 2]);
+                    }
+                    else {
+                        idx = b.vertex(v[vi * 3], v[vi * 3 + 1], v[vi * 3 + 2]);
+                    }
+                    seen.set(key, idx);
+                }
+                poly.push(idx);
+            }
+            for (let k = 1; k + 1 < poly.length; k++)
+                b.triangle(poly[0], poly[k], poly[k + 1], mat);
+        }
+    }
+    return b.build();
+}

package/dist/loaders/stl.d.ts

@@ -0,0 +1,3 @@
+import type { Mesh } from '../mesh.ts';
+/** STL, binary or ASCII. STL has no shared vertices or usable normals, so the mesh is flat shaded by default. */
+export declare function parseSTL(bytes: Uint8Array): Mesh;

package/dist/loaders/stl.js

@@ -0,0 +1,29 @@
+/** STL, binary or ASCII. STL has no shared vertices or usable normals, so the mesh is flat shaded by default. */
+export function parseSTL(bytes) {
+    const dv = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    if (bytes.length >= 84) {
+        const n = dv.getUint32(80, true);
+        if (84 + n * 50 === bytes.length) {
+            const pos = new Float32Array(n * 9);
+            for (let t = 0; t < n; t++) {
+                const o = 84 + t * 50 + 12;
+                for (let k = 0; k < 9; k++)
+                    pos[t * 9 + k] = dv.getFloat32(o + k * 4, true);
+            }
+            return soup(pos);
+        }
+    }
+    const text = new TextDecoder().decode(bytes);
+    const nums = [];
+    for (const m of text.matchAll(/vertex\s+(\S+)\s+(\S+)\s+(\S+)/g))
+        nums.push(+m[1], +m[2], +m[3]);
+    if (!nums.length || nums.length % 9)
+        throw new Error('not a valid STL file');
+    return soup(new Float32Array(nums));
+}
+function soup(pos) {
+    const n = pos.length / 3, idx = new Uint32Array(n);
+    for (let i = 0; i < n; i++)
+        idx[i] = i;
+    return { positions: pos, normals: null, indices: idx, triMaterial: new Uint16Array(n / 3), materials: ['default'] };
+}

package/dist/mesh.d.ts

@@ -0,0 +1,35 @@
+/** An indexed triangle mesh. Every loader and the SDF mesher produce this. */
+export interface Mesh {
+    /** xyz per vertex */
+    positions: Float32Array;
+    /** xyz per vertex, unit length; null means "flat shade from the triangles" */
+    normals: Float32Array | null;
+    /** three vertex indices per triangle */
+    indices: Uint32Array;
+    /** material index per triangle, into `materials` */
+    triMaterial: Uint16Array;
+    /** material names; styles are looked up by these names */
+    materials: string[];
+}
+export declare const vertexCount: (m: Mesh) => number;
+export declare const triangleCount: (m: Mesh) => number;
+/** Collects triangles into a Mesh. Loaders push into it and call `build()` once. */
+export declare class MeshBuilder {
+    positions: number[];
+    normals: number[];
+    indices: number[];
+    triMaterial: number[];
+    materials: string[];
+    /** false as soon as one vertex arrives without a normal */
+    hasNormals: boolean;
+    private matIndex;
+    material(name: string): number;
+    vertex(x: number, y: number, z: number, nx?: number, ny?: number, nz?: number): number;
+    triangle(a: number, b: number, c: number, material: number): void;
+    build(): Mesh;
+}
+/**
+ * Smooth vertex normals for a mesh that has none. Vertices at the same position are welded first,
+ * so a triangle soup (STL) still shades smoothly. Each face contributes its area-weighted normal.
+ */
+export declare function computeSmoothNormals(m: Mesh): Float32Array;

package/dist/mesh.js

@@ -0,0 +1,106 @@
+export const vertexCount = (m) => m.positions.length / 3;
+export const triangleCount = (m) => m.indices.length / 3;
+/** Collects triangles into a Mesh. Loaders push into it and call `build()` once. */
+export class MeshBuilder {
+    positions = [];
+    normals = [];
+    indices = [];
+    triMaterial = [];
+    materials = [];
+    /** false as soon as one vertex arrives without a normal */
+    hasNormals = true;
+    matIndex = new Map();
+    material(name) {
+        let i = this.matIndex.get(name);
+        if (i === undefined) {
+            i = this.materials.length;
+            this.materials.push(name);
+            this.matIndex.set(name, i);
+        }
+        return i;
+    }
+    vertex(x, y, z, nx, ny, nz) {
+        const i = this.positions.length / 3;
+        this.positions.push(x, y, z);
+        if (nx === undefined || ny === undefined || nz === undefined) {
+            this.hasNormals = false;
+            this.normals.push(0, 0, 0);
+        }
+        else {
+            this.normals.push(nx, ny, nz);
+        }
+        return i;
+    }
+    triangle(a, b, c, material) {
+        this.indices.push(a, b, c);
+        this.triMaterial.push(material);
+    }
+    build() {
+        if (this.materials.length === 0)
+            this.material('default');
+        return {
+            positions: new Float32Array(this.positions),
+            normals: this.hasNormals && this.positions.length ? normalizeAll(new Float32Array(this.normals)) : null,
+            indices: new Uint32Array(this.indices),
+            triMaterial: new Uint16Array(this.triMaterial),
+            materials: this.materials,
+        };
+    }
+}
+function normalizeAll(n) {
+    for (let i = 0; i < n.length; i += 3) {
+        const l = Math.hypot(n[i], n[i + 1], n[i + 2]) || 1;
+        n[i] /= l;
+        n[i + 1] /= l;
+        n[i + 2] /= l;
+    }
+    return n;
+}
+/**
+ * Smooth vertex normals for a mesh that has none. Vertices at the same position are welded first,
+ * so a triangle soup (STL) still shades smoothly. Each face contributes its area-weighted normal.
+ */
+export function computeSmoothNormals(m) {
+    const P = m.positions, I = m.indices, nV = P.length / 3;
+    // weld by quantized position
+    const ids = new Uint32Array(nV);
+    const keys = new Map();
+    let b = [Infinity, -Infinity];
+    for (let i = 0; i < P.length; i++) {
+        b[0] = Math.min(b[0], P[i]);
+        b[1] = Math.max(b[1], P[i]);
+    }
+    const q = 1e5 / Math.max(b[1] - b[0], 1e-9);
+    for (let v = 0; v < nV; v++) {
+        const k = `${Math.round(P[v * 3] * q)},${Math.round(P[v * 3 + 1] * q)},${Math.round(P[v * 3 + 2] * q)}`;
+        let id = keys.get(k);
+        if (id === undefined) {
+            id = keys.size;
+            keys.set(k, id);
+        }
+        ids[v] = id;
+    }
+    const acc = new Float64Array(keys.size * 3);
+    for (let t = 0; t < I.length; t += 3) {
+        const a = I[t] * 3, bb = I[t + 1] * 3, c = I[t + 2] * 3;
+        const e1x = P[bb] - P[a], e1y = P[bb + 1] - P[a + 1], e1z = P[bb + 2] - P[a + 2];
+        const e2x = P[c] - P[a], e2y = P[c + 1] - P[a + 1], e2z = P[c + 2] - P[a + 2];
+        // cross product length is twice the area, which is the weight we want
+        const nx = e1y * e2z - e1z * e2y, ny = e1z * e2x - e1x * e2z, nz = e1x * e2y - e1y * e2x;
+        for (const v of [I[t], I[t + 1], I[t + 2]]) {
+            const w = ids[v] * 3;
+            acc[w] += nx;
+            acc[w + 1] += ny;
+            acc[w + 2] += nz;
+        }
+    }
+    const out = new Float32Array(nV * 3);
+    for (let v = 0; v < nV; v++) {
+        const w = ids[v] * 3;
+        const l = Math.hypot(acc[w], acc[w + 1], acc[w + 2]) || 1;
+        out[v * 3] = acc[w] / l;
+        out[v * 3 + 1] = acc[w + 1] / l;
+        out[v * 3 + 2] = acc[w + 2] / l;
+    }
+    return out;
+}

package/dist/output.d.ts

@@ -0,0 +1,18 @@
+import type { Frame } from './render.ts';
+import { type ColorDepth } from './ansi.ts';
+import type { RGB } from './style.ts';
+export type { ColorDepth };
+/** Plain text, one line per row. */
+export declare function toText(frame: Frame): string;
+/**
+ * Color of one cell, or null when the style has no color for it (use the default color).
+ * `faint` asks for a dimmed default color, for dim materials in colorless styles.
+ */
+export declare function cellColor(frame: Frame, i: number): {
+    rgb: RGB | null;
+    faint: boolean;
+};
+/** ANSI-colored lines for a terminal. Color codes are only written when they change. */
+export declare function toANSI(frame: Frame, depth?: ColorDepth): string[];
+/** HTML for a `<pre>`: colored runs become spans. Without colors, dim materials get reduced opacity. */
+export declare function toHTML(frame: Frame): string;

package/dist/output.js

@@ -0,0 +1,76 @@
+import { bg, FAINT, fg, line } from "./ansi.js";
+/** Plain text, one line per row. */
+export function toText(frame) {
+    const { width: W, height: H, chars } = frame;
+    const rows = [];
+    for (let r = 0; r < H; r++)
+        rows.push(chars.slice(r * W, r * W + W).join(''));
+    return rows.join('\n');
+}
+const lerp = (a, b, t) => [a[0] + (b[0] - a[0]) * t, a[1] + (b[1] - a[1]) * t, a[2] + (b[2] - a[2]) * t];
+function gradient(stops, t) {
+    if (stops.length === 1)
+        return stops[0];
+    const x = Math.min(1, Math.max(0, t)) * (stops.length - 1), i = Math.min(stops.length - 2, Math.floor(x));
+    return lerp(stops[i], stops[i + 1], x - i);
+}
+/**
+ * Color of one cell, or null when the style has no color for it (use the default color).
+ * `faint` asks for a dimmed default color, for dim materials in colorless styles.
+ */
+export function cellColor(frame, i) {
+    const m = frame.mat[i];
+    if (m < 0)
+        return { rgb: null, faint: false };
+    const ms = frame.materials[m], cs = frame.style.color;
+    let rgb = ms.color ?? (cs.mode === 'gradient' ? gradient(cs.stops, frame.lum[i]) : cs.mode === 'mono' ? cs.fg : null);
+    if (!rgb)
+        return { rgb: null, faint: ms.opacity < 1 };
+    if (ms.opacity < 1)
+        rgb = lerp(cs.bg ?? [0, 0, 0], rgb, ms.opacity);
+    return { rgb: [Math.round(rgb[0]), Math.round(rgb[1]), Math.round(rgb[2])], faint: false };
+}
+/** ANSI-colored lines for a terminal. Color codes are only written when they change. */
+export function toANSI(frame, depth = 'truecolor') {
+    const { width: W, height: H, chars } = frame;
+    const background = bg(frame.style.color.bg, depth);
+    const code = (i) => {
+        const { rgb, faint } = cellColor(frame, i);
+        return rgb && depth !== 'none' ? fg(rgb, depth) : faint ? FAINT : '';
+    };
+    const lines = [];
+    for (let r = 0; r < H; r++)
+        lines.push(line((i) => chars[i], code, r * W, W, background));
+    return lines;
+}
+const esc = (ch) => (ch === '<' ? '&lt;' : ch === '>' ? '&gt;' : ch === '&' ? '&amp;' : ch);
+const hex = (c) => '#' + c.map((v) => v.toString(16).padStart(2, '0')).join('');
+/** HTML for a `<pre>`: colored runs become spans. Without colors, dim materials get reduced opacity. */
+export function toHTML(frame) {
+    const { width: W, height: H, chars } = frame;
+    let s = '';
+    for (let r = 0; r < H; r++) {
+        let open = '';
+        for (let c = 0; c < W; c++) {
+            const i = r * W + c, ch = chars[i];
+            if (ch !== ' ') {
+                const { rgb, faint } = cellColor(frame, i);
+                const m = frame.mat[i], op = m >= 0 ? frame.materials[m].opacity : 1;
+                const attr = rgb ? `color:${hex(rgb)}` : faint ? `opacity:${op}` : '';
+                if (attr !== open) {
+                    if (open)
+                        s += '</span>';
+                    if (attr)
+                        s += `<span style="${attr}">`;
+                    open = attr;
+                }
+            }
+            s += esc(ch);
+        }
+        if (open)
+            s += '</span>';
+        if (r < H - 1)
+            s += '\n';
+    }
+    return s;
+}

package/dist/render.d.ts

@@ -0,0 +1,36 @@
+import { type Mesh } from './mesh.ts';
+import { type ResolvedMaterial, type Style, type StyleInput } from './style.ts';
+export interface View {
+    /** rotation around the vertical axis, radians */
+    yaw?: number;
+    /** tilt toward the viewer, radians; defaults to the style's pitch */
+    pitch?: number;
+    /** rotation around the view axis, radians */
+    roll?: number;
+}
+/** One rendered frame. Output adapters (text, ANSI, HTML) only read this. */
+export interface Frame {
+    width: number;
+    height: number;
+    /** one glyph per cell, row-major */
+    chars: string[];
+    /** surface brightness per cell, 0..1 (0 for background) */
+    lum: Float32Array;
+    /** material index per cell, -1 for background */
+    mat: Int16Array;
+    materials: ResolvedMaterial[];
+    style: Style;
+}
+export interface Renderer {
+    readonly mesh: Mesh;
+    readonly style: Style;
+    /** merge into the current style input */
+    setStyle(input: StyleInput): void;
+    render(view?: View): Frame;
+}
+/**
+ * A small software rasterizer that draws into a character grid.
+ * The model is centered and scaled to a unit sphere; the camera sits on +z looking at the origin.
+ * Each cell is sampled `supersample`² times; the cell takes the mean brightness of the samples that hit.
+ */
+export declare function createRenderer(mesh: Mesh, input?: StyleInput): Renderer;