@feelgxxd/textel 0.0.0-stage → 0.3.0

package/dist/browser/viewer-core.js

@@ -0,0 +1,67 @@
+// The parts of <textel-viewer> that do not touch the DOM, so they can be tested anywhere.
+/**
+ * The grid for a box: `cols` is fixed, rows follow from the box shape in this font.
+ * A box without a height gets a square picture.
+ */
+export function gridFor(cols, cellW, cellH, boxW, boxH) {
+    const c = Math.max(8, Math.round(cols));
+    const cw = cellW > 0 ? cellW : 0.6, ch = cellH > 0 ? cellH : 1;
+    const wantRatio = boxW > 0 && boxH > 0 ? boxW / boxH : 1;
+    const rows = Math.max(4, Math.min(400, Math.round((c * cw) / (ch * wantRatio))));
+    const w = c * cw, h = rows * ch;
+    return { cols: c, rows, aspect: ch / cw, scale: boxW > 0 ? boxW / w : 1, ratio: w / h };
+}
+const ease = (rate, dt) => 1 - Math.exp(-rate * dt);
+/**
+ * Advances the turntable by `dt` seconds. After a drag the flick keeps going and eases back to the
+ * resting spin, and the tilt drifts back to the resting pitch.
+ */
+export function step(m, t, dt) {
+    const d = Math.min(Math.max(dt, 0), 0.1);
+    const vyaw = m.vyaw + (t.spin - m.vyaw) * ease(2, d);
+    const vpitch = m.vpitch * (1 - ease(4, d));
+    let pitch = m.pitch + vpitch * d;
+    pitch += (t.pitch - pitch) * ease(1.5, d);
+    pitch = Math.max(-t.maxPitch, Math.min(t.maxPitch, pitch));
+    return { yaw: m.yaw + vyaw * d, pitch, vyaw, vpitch };
+}
+/**
+ * A pointer moved by (dx, dy) pixels over `dt` seconds on a box `width` wide: a drag across the
+ * whole width turns the model once. The speed is kept so a release turns into a flick.
+ */
+export function drag(m, dx, dy, dt, width, maxPitch) {
+    const k = width > 0 ? (Math.PI * 2) / width : 0.01;
+    const dyaw = dx * k, dpitch = dy * k;
+    const pitch = Math.max(-maxPitch, Math.min(maxPitch, m.pitch + dpitch));
+    const inv = dt > 0.001 ? 1 / dt : 0;
+    return { yaw: m.yaw + dyaw, pitch, vyaw: dyaw * inv, vpitch: dpitch * inv };
+}
+/** attribute values to style fields; unknown or empty values are left out */
+export function styleFromAttributes(get) {
+    const out = {};
+    const n = (name) => {
+        const v = get(name);
+        if (v === null || v.trim() === '')
+            return undefined;
+        const x = Number(v);
+        return Number.isFinite(x) ? x : undefined;
+    };
+    const charset = get('charset');
+    if (charset)
+        out.charset = charset;
+    const chars = get('chars');
+    if (chars)
+        out.chars = chars;
+    const color = get('color');
+    if (color)
+        out.color = color.includes(',') ? color.split(',').map((s) => s.trim()) : color.trim();
+    const edges = get('edges');
+    if (edges !== null)
+        out.edges = edges === 'depth' ? 'depth' : edges === 'off' || edges === 'false' ? false : 'outline';
+    for (const k of ['spin', 'pitch', 'zoom', 'distance', 'ambient']) {
+        const v = n(k);
+        if (v !== undefined)
+            out[k] = v;
+    }
+    return out;
+}

package/dist/browser/viewer.d.ts

@@ -0,0 +1,29 @@
+import type { Mesh } from '../mesh.ts';
+import { type StyleInput } from '../style.ts';
+declare const Base: typeof HTMLElement;
+export declare class TextelViewer extends Base {
+    #private;
+    static observedAttributes: string[];
+    constructor();
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    attributeChangedCallback(name: string, old: string | null, value: string | null): void;
+    /** extra style from JavaScript, on top of the preset and the attributes */
+    get look(): StyleInput;
+    set look(s: StyleInput);
+    /** the model being shown; set a Mesh to show one built in code */
+    get mesh(): Mesh | null;
+    set mesh(m: Mesh | null);
+    get paused(): boolean;
+    play(): void;
+    /** stops at once: the spin and any flick still coasting are dropped */
+    pause(): void;
+    /** loads a model from a URL, a File, or bytes */
+    load(source: string | Blob | ArrayBuffer | Uint8Array, name?: string): Promise<void>;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'textel-viewer': TextelViewer;
+    }
+}
+export {};

package/dist/browser/viewer.js

@@ -0,0 +1,338 @@
+// <textel-viewer>: renders a 3D model live in the page; drag to turn it.
+//
+//   <script type="module" src="https://cdn.jsdelivr.net/npm/@feelgxxd/textel@0.3/dist/textel-viewer.js"></script>
+//   <textel-viewer src="model.glb" charset="hard" color="#301000,#ffb000"></textel-viewer>
+import { parseModelAsync } from "../loaders/index.js";
+import { toHTML, toText } from "../output.js";
+import { createRenderer } from "../render.js";
+import { mergeStyles } from "../style.js";
+import { drag, gridFor, step, styleFromAttributes } from "./viewer-core.js";
+const CSS = `:host{display:block;position:relative;overflow:hidden;aspect-ratio:var(--textel-ratio,1);font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,monospace;outline:none}
+:host(:not([nodrag])){cursor:grab;touch-action:pan-y}
+:host(:not([nodrag]):active){cursor:grabbing}
+:host(:focus-visible){box-shadow:0 0 0 2px currentColor}
+pre{position:absolute;left:0;top:0;margin:0;transform-origin:0 0;font:inherit;font-size:16px;line-height:1;letter-spacing:0;white-space:pre;color:inherit;text-shadow:var(--textel-glow,none);-webkit-text-size-adjust:none;text-size-adjust:none;user-select:none;pointer-events:none}
+.probe{visibility:hidden}`;
+const MAX_PITCH = 1.2;
+const STYLE_ATTRS = ['charset', 'chars', 'color', 'edges', 'spin', 'pitch', 'zoom', 'distance', 'ambient'];
+const Base = (typeof HTMLElement === 'undefined' ? class {
+} : HTMLElement);
+/** fetches a model; a .gltf brings its external buffers along */
+async function fetchModel(url, signal) {
+    const get = async (u) => {
+        const res = await fetch(u, { signal });
+        if (!res.ok)
+            throw new Error(`${res.status} ${res.statusText} for ${u}`);
+        return new Uint8Array(await res.arrayBuffer());
+    };
+    const bytes = await get(url);
+    const buffers = new Map();
+    if (/\.gltf(\?|#|$)/i.test(url)) {
+        const json = JSON.parse(new TextDecoder().decode(bytes));
+        for (const b of json.buffers ?? []) {
+            if (b.uri && !b.uri.startsWith('data:'))
+                buffers.set(decodeURIComponent(b.uri), await get(new URL(b.uri, new URL(url, location.href)).href));
+        }
+    }
+    return parseModelAsync(bytes, url.split(/[?#]/)[0], {
+        resolve: (uri) => {
+            const b = buffers.get(uri);
+            if (!b)
+                throw new Error(`missing buffer ${uri}`);
+            return b;
+        },
+    });
+}
+export class TextelViewer extends Base {
+    static observedAttributes = ['src', 'preset', 'cols', 'paused', 'label', ...STYLE_ATTRS];
+    #pre;
+    #probe;
+    #mesh = null;
+    #renderer = null;
+    #preset = {};
+    #look = {};
+    #grid = null;
+    #motion = { yaw: 0, pitch: 0, vyaw: 0, vpitch: 0 };
+    #zoom = 1;
+    #playing = true;
+    #visible = true;
+    #raf = 0;
+    #last = -1;
+    #dirty = true;
+    #pointer = null;
+    #load = null;
+    #io;
+    #ro;
+    #reduced = typeof matchMedia === 'function' && matchMedia('(prefers-reduced-motion: reduce)').matches;
+    constructor() {
+        super();
+        const root = this.attachShadow({ mode: 'open' });
+        const style = document.createElement('style');
+        style.textContent = CSS;
+        this.#pre = document.createElement('pre');
+        this.#pre.setAttribute('part', 'screen');
+        this.#probe = document.createElement('pre');
+        this.#probe.className = 'probe';
+        // 40 glyphs on each of 4 lines: one glyph's width and one line's height, averaged
+        this.#probe.textContent = Array(4).fill('M'.repeat(40)).join('\n');
+        root.append(style, this.#probe, this.#pre);
+        this.addEventListener('pointerdown', this.#onDown);
+        this.addEventListener('pointermove', this.#onMove);
+        this.addEventListener('pointerup', this.#onUp);
+        this.addEventListener('pointercancel', this.#onUp);
+        this.addEventListener('keydown', this.#onKey);
+        this.addEventListener('wheel', this.#onWheel, { passive: false });
+    }
+    connectedCallback() {
+        this.setAttribute('role', 'img');
+        if (!this.hasAttribute('tabindex'))
+            this.tabIndex = 0;
+        this.#updateLabel();
+        this.#playing = !this.hasAttribute('paused');
+        if (typeof IntersectionObserver === 'function') {
+            this.#io = new IntersectionObserver(([e]) => { this.#visible = e.isIntersecting; this.#kick(); });
+            this.#io.observe(this);
+        }
+        if (typeof ResizeObserver === 'function') {
+            this.#ro = new ResizeObserver(() => this.#layout());
+            this.#ro.observe(this);
+        }
+        this.ownerDocument.addEventListener('visibilitychange', this.#kick);
+        this.ownerDocument.fonts?.ready.then(() => this.#layout());
+        this.#layout();
+        this.#kick();
+    }
+    disconnectedCallback() {
+        this.#io?.disconnect();
+        this.#ro?.disconnect();
+        this.ownerDocument.removeEventListener('visibilitychange', this.#kick);
+        cancelAnimationFrame(this.#raf);
+        this.#raf = 0;
+    }
+    attributeChangedCallback(name, old, value) {
+        if (old === value)
+            return;
+        if (name === 'src') {
+            if (value)
+                this.load(value);
+        }
+        else if (name === 'preset') {
+            if (value)
+                this.#fetchPreset(value);
+        }
+        else if (name === 'paused') {
+            value === null ? this.play() : this.pause();
+        }
+        else if (name === 'label')
+            this.#updateLabel();
+        else if (name === 'cols')
+            this.#layout();
+        else
+            this.#restyle();
+    }
+    /** extra style from JavaScript, on top of the preset and the attributes */
+    get look() { return this.#look; }
+    set look(s) { this.#look = s ?? {}; this.#restyle(); }
+    /** the model being shown; set a Mesh to show one built in code */
+    get mesh() { return this.#mesh; }
+    set mesh(m) {
+        this.#mesh = m;
+        this.#renderer = null;
+        this.#motion = { yaw: 0, pitch: this.#style().pitch ?? 0.3, vyaw: 0, vpitch: 0 };
+        this.#layout();
+        this.#kick();
+    }
+    get paused() { return !this.#playing; }
+    play() { this.#playing = true; this.#kick(); }
+    /** stops at once: the spin and any flick still coasting are dropped */
+    pause() {
+        this.#playing = false;
+        this.#motion = { ...this.#motion, vyaw: 0, vpitch: 0 };
+        this.#kick();
+    }
+    /** loads a model from a URL, a File, or bytes */
+    async load(source, name = '') {
+        this.#load?.abort();
+        const ac = (this.#load = new AbortController());
+        try {
+            let mesh;
+            if (typeof source === 'string')
+                mesh = await fetchModel(source, ac.signal);
+            else {
+                const bytes = source instanceof Uint8Array ? source : new Uint8Array(source instanceof Blob ? await source.arrayBuffer() : source);
+                mesh = await parseModelAsync(bytes, name || (source instanceof File ? source.name : ''));
+            }
+            if (ac.signal.aborted)
+                return;
+            this.mesh = mesh;
+            this.dispatchEvent(new CustomEvent('load', { detail: { triangles: mesh.indices.length / 3, materials: mesh.materials } }));
+        }
+        catch (error) {
+            if (ac.signal.aborted)
+                return;
+            this.dispatchEvent(new CustomEvent('error', { detail: { error } }));
+        }
+    }
+    async #fetchPreset(url) {
+        try {
+            const res = await fetch(url);
+            if (!res.ok)
+                throw new Error(`${res.status} ${res.statusText} for ${url}`);
+            this.#preset = await res.json();
+            this.#restyle();
+        }
+        catch (error) {
+            this.dispatchEvent(new CustomEvent('error', { detail: { error } }));
+        }
+    }
+    /** preset < attributes < .look, then the parts the viewer owns */
+    #style() {
+        return mergeStyles(this.#preset, styleFromAttributes((n) => this.getAttribute(n)), this.#look);
+    }
+    #restyle() {
+        if (!this.#renderer || !this.#grid)
+            return this.#layout();
+        const s = this.#style();
+        this.#renderer.setStyle({ ...s, ...this.#gridStyle(s) });
+        // show the change now, even while paused
+        this.#draw();
+        this.#kick();
+    }
+    #gridStyle(s) {
+        const g = this.#grid;
+        return { width: g.cols, height: g.rows, aspect: g.aspect, zoom: (s.zoom ?? 1) * this.#zoom, fitPitch: this.hasAttribute('nodrag') ? 0 : MAX_PITCH };
+    }
+    #layout() {
+        if (!this.isConnected)
+            return;
+        const p = this.#probe, cellW = p.offsetWidth / 40, cellH = p.offsetHeight / 4;
+        const cols = Number(this.getAttribute('cols')) || 96;
+        // A page-set height shapes the grid. Without one the box follows --textel-ratio (square at
+        // first), so its height already matches the grid and the layout settles on the same rows.
+        this.#grid = gridFor(cols, cellW, cellH, this.clientWidth, this.clientHeight);
+        this.style.setProperty('--textel-ratio', String(this.#grid.ratio));
+        this.#pre.style.transform = `scale(${this.#grid.scale})`;
+        if (!this.#mesh)
+            return;
+        const s = this.#style();
+        try {
+            if (!this.#renderer)
+                this.#renderer = createRenderer(this.#mesh, { ...s, ...this.#gridStyle(s) });
+            else
+                this.#renderer.setStyle({ ...s, ...this.#gridStyle(s) });
+        }
+        catch (error) {
+            this.dispatchEvent(new CustomEvent('error', { detail: { error } }));
+            return;
+        }
+        this.#dirty = true;
+        this.#draw();
+    }
+    #draw() {
+        if (!this.#renderer)
+            return;
+        const frame = this.#renderer.render({ yaw: this.#motion.yaw, pitch: this.#motion.pitch });
+        // without any color or dimming the frame is plain text, which is the cheapest thing to draw
+        const plain = frame.style.color.mode === 'none' && frame.materials.every((m) => !m.color && m.opacity === 1);
+        if (plain)
+            this.#pre.textContent = toText(frame);
+        else
+            this.#pre.innerHTML = toHTML(frame);
+        this.#dirty = false;
+    }
+    #updateLabel() {
+        if (this.isConnected)
+            this.setAttribute('aria-label', this.getAttribute('label') || '3D model drawn in ASCII');
+    }
+    #spin() {
+        return this.#playing && !this.#reduced ? this.#style().spin ?? 0.66 : 0;
+    }
+    /** animates while it spins, coasts after a flick, or is being dragged; otherwise it stays still */
+    #kick = () => {
+        const m = this.#motion;
+        const moving = this.#spin() !== 0 || Math.abs(m.vyaw) > 1e-3 || Math.abs(m.vpitch) > 1e-3 || !!this.#pointer;
+        const run = !!this.#renderer && this.#visible && !this.ownerDocument.hidden && this.isConnected && (moving || this.#dirty);
+        if (run && !this.#raf) {
+            this.#last = -1;
+            this.#raf = requestAnimationFrame(this.#tick);
+        }
+        else if (!run && this.#raf) {
+            cancelAnimationFrame(this.#raf);
+            this.#raf = 0;
+        }
+    };
+    #tick = (now) => {
+        this.#raf = 0;
+        const dt = this.#last < 0 ? 0 : (now - this.#last) / 1000;
+        this.#last = now;
+        if (!this.#pointer) {
+            this.#motion = step(this.#motion, { spin: this.#spin(), pitch: this.#style().pitch ?? 0.3, maxPitch: MAX_PITCH }, dt);
+        }
+        this.#draw();
+        this.#raf = requestAnimationFrame(this.#tick);
+        // stop once everything has settled
+        const m = this.#motion;
+        if (this.#spin() === 0 && !this.#pointer && Math.abs(m.vyaw) < 1e-3 && Math.abs(m.vpitch) < 1e-3) {
+            cancelAnimationFrame(this.#raf);
+            this.#raf = 0;
+        }
+    };
+    #onDown = (e) => {
+        if (this.hasAttribute('nodrag') || !this.#renderer || e.button !== 0)
+            return;
+        this.#pointer = { x: e.clientX, y: e.clientY, t: performance.now() };
+        this.setPointerCapture(e.pointerId);
+        this.#kick();
+    };
+    #onMove = (e) => {
+        const p = this.#pointer;
+        if (!p)
+            return;
+        const now = performance.now();
+        this.#motion = drag(this.#motion, e.clientX - p.x, e.clientY - p.y, (now - p.t) / 1000, this.clientWidth, MAX_PITCH);
+        this.#pointer = { x: e.clientX, y: e.clientY, t: now };
+        this.#kick();
+    };
+    #onUp = () => {
+        if (!this.#pointer)
+            return;
+        // a pause before letting go means no flick
+        if (performance.now() - this.#pointer.t > 80)
+            this.#motion = { ...this.#motion, vyaw: 0, vpitch: 0 };
+        this.#pointer = null;
+        this.#kick();
+    };
+    #onKey = (e) => {
+        const m = this.#motion, step = 0.15;
+        const moves = {
+            ArrowLeft: () => (m.yaw -= step),
+            ArrowRight: () => (m.yaw += step),
+            ArrowUp: () => (m.pitch = Math.max(-MAX_PITCH, m.pitch - step)),
+            ArrowDown: () => (m.pitch = Math.min(MAX_PITCH, m.pitch + step)),
+            ' ': () => (this.#playing ? this.pause() : this.play()),
+        };
+        if (this.hasAttribute('zoomable')) {
+            moves['+'] = moves['='] = () => this.#setZoom(this.#zoom * 1.1);
+            moves['-'] = () => this.#setZoom(this.#zoom / 1.1);
+        }
+        const f = moves[e.key];
+        if (!f)
+            return;
+        e.preventDefault();
+        f();
+        this.#dirty = true;
+        this.#kick();
+    };
+    #onWheel = (e) => {
+        if (!this.hasAttribute('zoomable') || !this.#renderer)
+            return;
+        e.preventDefault();
+        this.#setZoom(this.#zoom * Math.exp(-e.deltaY * 0.001));
+    };
+    #setZoom(z) {
+        this.#zoom = Math.max(0.3, Math.min(4, z));
+        this.#restyle();
+    }
+}
+if (typeof customElements !== 'undefined' && !customElements.get('textel-viewer'))
+    customElements.define('textel-viewer', TextelViewer);

package/dist/cli/commands/list.d.ts

@@ -0,0 +1,3 @@
+export declare const summary = "built-in examples and charsets";
+export declare const HELP = "textel list: built-in examples and charsets\n\nusage\n  textel list\n";
+export declare function run(argv: string[]): undefined;

package/dist/cli/commands/list.js

@@ -0,0 +1,21 @@
+import { EXAMPLES } from "../../examples.js";
+import { CHARSETS } from "../../style.js";
+import { HELP_OPTIONS, parse } from "../shared.js";
+export const summary = 'built-in examples and charsets';
+export const HELP = `textel list: built-in examples and charsets
+
+usage
+  textel list
+`;
+export function run(argv) {
+    const { values: o } = parse(argv, HELP_OPTIONS);
+    if (o.help)
+        return void process.stdout.write(HELP);
+    const out = ['examples'];
+    for (const e of EXAMPLES)
+        out.push(`  ${e.name.padEnd(10)} ${e.description}`);
+    out.push('', 'charsets');
+    for (const [k, v] of Object.entries(CHARSETS))
+        out.push(`  ${k.padEnd(10)} ${JSON.stringify(v.length > 40 ? v.slice(0, 40) + '…' : v)}`);
+    process.stdout.write(out.join('\n') + '\n');
+}

package/dist/cli/commands/play.d.ts

@@ -0,0 +1,3 @@
+export declare const summary = "play a .textel.json file in the terminal";
+export declare const HELP = "textel play: play a .textel.json file in the terminal\n\nusage\n  textel play <file.textel.json> [options]\n\noptions\n      --once                print one frame and exit (also when output is not a terminal)\n      --frame <n>           which frame --once prints (default 0)\n      --fps <n>             playback rate (default: the file's)\n      --seconds <n>         stop after this long\n      --no-color            plain characters\n\nkeys  space pause  \u2190\u2192 step a frame  +/- speed  q quit\n";
+export declare function run(argv: string[]): Promise<undefined>;

package/dist/cli/commands/play.js

@@ -0,0 +1,55 @@
+import { basename, resolve } from 'node:path';
+import { recordingANSI, recordingText } from "../../frames.js";
+import { loadFrames, play } from "../../terminal.js";
+import { colorDepth, fail, HELP_OPTIONS, num, parse } from "../shared.js";
+export const summary = 'play a .textel.json file in the terminal';
+export const HELP = `textel play: play a .textel.json file in the terminal
+
+usage
+  textel play <file.textel.json> [options]
+
+options
+      --once                print one frame and exit (also when output is not a terminal)
+      --frame <n>           which frame --once prints (default 0)
+      --fps <n>             playback rate (default: the file's)
+      --seconds <n>         stop after this long
+      --no-color            plain characters
+
+keys  space pause  ←→ step a frame  +/- speed  q quit
+`;
+const OPTIONS = {
+    ...HELP_OPTIONS,
+    once: { type: 'boolean' },
+    frame: { type: 'string' },
+    fps: { type: 'string' },
+    seconds: { type: 'string' },
+    'no-color': { type: 'boolean' },
+};
+export async function run(argv) {
+    const { values: o, positionals } = parse(argv, OPTIONS);
+    if (o.help || !positionals[0])
+        return void process.stdout.write(HELP);
+    if (positionals.length > 1)
+        fail(`unexpected argument "${positionals[1]}"`);
+    const file = resolve(positionals[0]);
+    let rec;
+    try {
+        rec = loadFrames(file);
+    }
+    catch (e) {
+        const err = e;
+        fail(err.code === 'ENOENT' ? `cannot read ${positionals[0]}` : `${basename(file)}: ${err.message}`);
+    }
+    const depth = colorDepth(o['no-color']);
+    if (o.once || !process.stdout.isTTY || !process.stdin.isTTY) {
+        const i = num(o.frame, '--frame') ?? 0;
+        if (!(Number.isInteger(i) && i >= 0 && i < rec.frames.length))
+            fail(`--frame is 0 to ${rec.frames.length - 1}`);
+        process.stdout.write((depth === 'none' ? recordingText(rec, i) : recordingANSI(rec, i, depth).join('\n')) + '\n');
+        return;
+    }
+    const title = typeof rec.meta.title === 'string' ? rec.meta.title : basename(file);
+    const result = await play(rec, { interactive: true, depth, fps: num(o.fps, '--fps'), seconds: num(o.seconds, '--seconds'), title });
+    if (result === 'interrupt')
+        process.exitCode = 130;
+}

package/dist/cli/commands/preview.d.ts

@@ -0,0 +1,3 @@
+export declare const summary = "spin a model in the terminal (the default command)";
+export declare const HELP = "textel preview: spin a model in the terminal\n\nusage\n  textel [preview] <model> [options]\n  textel [preview] --example <name> [options]\n\ninput\n  <model>                   a .glb, .gltf, .obj or .stl file\n  -e, --example <name>      a built-in scene instead (textel list)\n\nlook\n  -c, --chars <ramp|name>   charset name or a custom ramp, darkest first\n  -p, --preset <file.json>  style file; flags override it\n      --color <#hex>        one color; --color #301000,#ffb000 for a gradient\n      --no-color            plain characters\n      --edges [depth]       outline the silhouette; depth also marks depth steps; off\n      --light <x,y,z>       direction toward the light (x right, y up, z toward you)\n      --ambient <0..1>      brightness floor\n      --shading <mode>      auto | flat | smooth\n\ncamera\n      --pitch <rad>         resting tilt; positive shows the top\n      --spin <rad/s>        auto rotation speed (0 = still)\n      --zoom <n>            1 fills the grid\n      --distance <n>        camera distance in model radii (perspective)\n  -s, --size <WxH>          grid size\n  -a, --aspect <n>          character height / width (default 2)\n\noutput\n      --once                print one frame and exit (also when output is not a terminal)\n      --yaw <rad>           rotation of that frame (default 0.6)\n      --fps <n>             frame rate while it runs (default 30)\n\nkeys  \u2190\u2192\u2191\u2193 rotate  +/- zoom  c chars  e edges  l light  space pause  r reset  q quit\n";
+export declare function run(argv: string[]): undefined;

package/dist/cli/commands/preview.js

@@ -0,0 +1,57 @@
+import { toANSI, toText } from "../../output.js";
+import { createRenderer } from "../../render.js";
+import { live } from "../live.js";
+import { colorDepth, fail, HELP_OPTIONS, INPUT_HELP, INPUT_OPTIONS, loadInput, num, parse, parseSize, STYLE_HELP, STYLE_OPTIONS, styleFrom } from "../shared.js";
+export const summary = 'spin a model in the terminal (the default command)';
+export const HELP = `textel preview: spin a model in the terminal
+
+usage
+  textel [preview] <model> [options]
+  textel [preview] --example <name> [options]
+
+${INPUT_HELP}
+
+${STYLE_HELP}
+
+output
+      --once                print one frame and exit (also when output is not a terminal)
+      --yaw <rad>           rotation of that frame (default 0.6)
+      --fps <n>             frame rate while it runs (default 30)
+
+keys  ←→↑↓ rotate  +/- zoom  c chars  e edges  l light  space pause  r reset  q quit
+`;
+const OPTIONS = {
+    ...INPUT_OPTIONS,
+    ...STYLE_OPTIONS,
+    ...HELP_OPTIONS,
+    once: { type: 'boolean' },
+    yaw: { type: 'string' },
+    fps: { type: 'string' },
+};
+export function run(argv) {
+    const { values: o, positionals } = parse(argv, OPTIONS);
+    if (o.help)
+        return void process.stdout.write(HELP);
+    if (positionals.length > 1)
+        fail(`unexpected argument "${positionals[1]}"`);
+    const input = loadInput(o, positionals);
+    if (!input)
+        return void process.stdout.write(HELP);
+    const style = styleFrom(o, input.style);
+    const depth = colorDepth(o['no-color']);
+    const tty = !!process.stdout.isTTY;
+    if (o.once || !tty || !process.stdin.isTTY) {
+        const [w, h] = style.width && style.height ? [style.width, style.height] : tty ? [process.stdout.columns, Math.max(5, process.stdout.rows - 1)] : [80, 40];
+        let r;
+        try {
+            r = createRenderer(input.mesh, { ...style, width: w, height: h });
+        }
+        catch (e) {
+            fail(e.message);
+        }
+        const frame = r.render({ yaw: num(o.yaw, '--yaw') ?? 0.6 });
+        process.stdout.write((depth === 'none' ? toText(frame) : toANSI(frame, depth).join('\n')) + '\n');
+        return;
+    }
+    live({ mesh: input.mesh, name: input.name, style, fixedSize: parseSize(o.size), depth, fps: num(o.fps, '--fps') ?? 30 });
+}

package/dist/cli/commands/render.d.ts

@@ -0,0 +1,3 @@
+export declare const summary = "record a spinning loop into a .textel.json file";
+export declare const HELP = "textel render: record a spinning loop into a .textel.json file\n\nusage\n  textel render <model> [-o out.textel.json] [options]\n  textel render --example <name> [options]\n\ninput\n  <model>                   a .glb, .gltf, .obj or .stl file\n  -e, --example <name>      a built-in scene instead (textel list)\n\nrecording\n  -o, --out <file>          output file (default: <name>.textel.json here)\n      --frames <n>          frames in the loop (default 120)\n      --fps <n>             playback rate (default 30)\n      --turns <n>           turns over the loop; negative spins the other way (default 1)\n      --force               overwrite an existing file\n\nlook\n  -c, --chars <ramp|name>   charset name or a custom ramp, darkest first\n  -p, --preset <file.json>  style file; flags override it\n      --color <#hex>        one color; --color #301000,#ffb000 for a gradient\n      --no-color            plain characters\n      --edges [depth]       outline the silhouette; depth also marks depth steps; off\n      --light <x,y,z>       direction toward the light (x right, y up, z toward you)\n      --ambient <0..1>      brightness floor\n      --shading <mode>      auto | flat | smooth\n\ncamera\n      --pitch <rad>         resting tilt; positive shows the top\n      --spin <rad/s>        auto rotation speed (0 = still)\n      --zoom <n>            1 fills the grid\n      --distance <n>        camera distance in model radii (perspective)\n  -s, --size <WxH>          grid size\n  -a, --aspect <n>          character height / width (default 2)\n\n  the grid defaults to 112x56 at aspect 2 (terminals); for a web page pass the\n  aspect of its font, for example --aspect 1.5\n";
+export declare function run(argv: string[]): undefined;