@feelgxxd/textel 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Berk Beken
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,181 @@
-# Temporary Holding Version
+# textel
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Turn 3D models into animated ASCII art, in the terminal and on the web.
+
+```
+          /-----------------\
+      /---/-----------------\----\
+   /--//-------------------------\\--\
+ ////-----%@@@@@@@@@@@@##########----||
+/##%//%%%%@@@@@@@@@@@@@%############\|
+\\***##%@@@@@@@@@@@@@@@@%#####*++++==|
+  \\\**##############%%%%+==========//
+    \-\\*###############*====://////
+       \\\----------------///--///
+         \\\----------------//-/
+           \--\-----------///
+              \-\------//-/
+                \-\--///
+                  \--/
+```
+
+```sh
+npx @feelgxxd/textel model.glb                   # spins in your terminal
+npx @feelgxxd/textel --example gem               # built-in scenes: donut, dice, rocket, planet, mug, gem
+npx @feelgxxd/textel model.stl --once > art.txt  # one frame as plain text
+```
+
+Install it once with `npm install -g @feelgxxd/textel` and the command is just `textel`. Needs Node 22 or newer.
+
+Reads `.glb`, `.gltf`, `.obj` and `.stl`. Everything runs locally; nothing is uploaded.
+
+## Terminal
+
+```
+textel <model> [options]       spin it in the terminal (same as textel preview)
+textel render <model> [-o f]   record a spinning loop into a .textel.json file
+textel play <file>             play a recorded file
+textel list                    built-in examples and charsets
+textel help <command>          all options of a command
+
+look
+  -c, --chars <ramp|name>   charset name or a custom ramp, darkest first
+  -p, --preset <file.json>  style file; flags override it
+      --color <#hex>        one color; --color #301000,#ffb000 for a gradient
+      --edges [depth]       outline the silhouette (and depth steps)
+      --light <x,y,z>       direction toward the light
+camera
+      --pitch <rad>  --spin <rad/s>  --zoom <n>  --distance <n>
+  -s, --size <WxH>   -a, --aspect <n>
+output
+      --once  --yaw <rad>  --fps <n>  --no-color
+```
+
+Keys while it runs: `←→↑↓` rotate, `+/-` zoom, `c` charset, `e` edges, `l` light, `space` pause, `r` reset, `q` quit.
+
+### Recording and playing
+
+```sh
+textel render logo.glb --color "#301000,#ffb000"   # writes logo.textel.json (120 frames, 112x56)
+textel play logo.textel.json                       # space pause, ←→ step, +/- speed, q quit
+```
+
+A frames file is played without the 3D renderer, so it is cheap to show anywhere.
+The format is documented in [docs/format.md](docs/format.md).
+
+### In your own CLI
+
+```ts
+import { playSplash } from '@feelgxxd/textel/terminal';
+
+await playSplash('logo.textel.json', { seconds: 2 }); // any key skips it
+```
+
+`play(recording, options)` from the same module gives full control: looping, keys, an
+`AbortSignal`, the output stream. Both restore the terminal however playback ends, and print a single
+frame when the output is not a terminal.
+
+## On a web page
+
+Record once, then play the file with `<textel-player>`: about 3 KB, no 3D code in the page.
+
+```sh
+textel render logo.glb --aspect 1.5 -o logo.textel.json
+```
+
+```html
+<script type="module" src="https://cdn.jsdelivr.net/npm/@feelgxxd/textel@0.2/dist/textel-player.js"></script>
+<textel-player src="logo.textel.json"></textel-player>
+```
+
+Or from npm in a bundled app: `npm install @feelgxxd/textel`, then `import '@feelgxxd/textel/player'`.
+
+It fills its width and keeps the proportions the file was rendered for, whatever the page font.
+Drag sideways to scrub. It pauses off screen and in background tabs, shows a still frame when the
+visitor prefers reduced motion, and is labeled for screen readers.
+
+| attribute | |
+|---|---|
+| `src` | the `.textel.json` file |
+| `fps` | playback rate; default from the file |
+| `paused` | start paused |
+| `nodrag` | turn off drag to scrub |
+| `color` | default color for cells without one; otherwise the element's CSS `color` |
+| `label` | accessible name; default from the file's title |
+
+Style it with CSS: `font-family`, `color`, `--textel-glow` (a `text-shadow`), `--textel-dim-opacity`,
+or `::part(screen)`. From JavaScript: `player.play()`, `player.pause()`, `player.frame`,
+`player.recording = json`, and the `load` and `error` events.
+
+`npm run demo` serves a page with several players and a drop zone for your own files.
+
+## Presets
+
+A preset is the whole look in one JSON file. The same file works with the CLI and the library.
+
+```json
+{
+  "charset": "hard",
+  "color": ["#301000", "#ffb000"],
+  "edges": "outline",
+  "pitch": 0.2,
+  "spin": 0.8,
+  "light": [-0.3, 0.35, 0.88],
+  "materials": { "Glass": "carved", "Trim": "dim" }
+}
+```
+
+Materials are matched by the names in the model file:
+
+| style | effect |
+|---|---|
+| `"solid"` | the normal ramp |
+| `"carved"` | blank, but still hides what is behind it: holes, sockets, engravings |
+| `"dim"` | lower intensity |
+| `{ "chars": "...", "color": "#hex", "opacity": 0.5 }` | its own ramp and color |
+
+Charsets: `classic`, `hard`, `detailed`, `blocks`, `dots`, `minimal`, or any string of your own.
+
+## Library
+
+```ts
+import { parseModel, createRenderer, toANSI, toHTML, toText } from '@feelgxxd/textel';
+
+const mesh = parseModel(bytes, 'model.glb');
+const renderer = createRenderer(mesh, { width: 112, height: 56, aspect: 1.5, charset: 'hard' });
+
+const frame = renderer.render({ yaw: 0.5 });
+pre.innerHTML = toHTML(frame);            // browser
+process.stdout.write(toANSI(frame).join('\n'));  // terminal
+```
+
+### Shapes in code
+
+`@feelgxxd/textel/sdf` meshes signed distance fields, so a scene can be written as a function instead of modeled:
+
+```ts
+import { sdfToMesh, sdBox, sdSphere } from '@feelgxxd/textel/sdf';
+
+const mesh = sdfToMesh(
+  (x, y, z) => Math.max(sdBox(x, y, z, 1, 1, 1, 0.1), -sdSphere(x, y, z, 1.25)),
+  { min: [-1.2, -1.2, -1.2], max: [1.2, 1.2, 1.2], step: 0.03 },
+);
+```
+
+`sdfToMeshSteps` does the same as a generator, so a page can build big shapes in idle time.
+
+## How it works
+
+A small software rasterizer draws into a character grid. Each cell is sampled several times
+(`supersample`); the cell takes the mean brightness of the samples that hit the model, and that
+picks a glyph from the ramp. The grid is corrected for character cells being taller than wide
+(`aspect`). Edge mode runs a Sobel filter over depth and draws `- / | \` along the outline, at the
+angles those glyphs actually have in a cell of that shape.
+
+## Roadmap
+
+See [ROADMAP.md](ROADMAP.md).
+
+## License
+
+MIT

package/dist/ansi.d.ts

@@ -0,0 +1,13 @@
+import type { RGB } from './style.ts';
+export type ColorDepth = 'truecolor' | '256' | 'none';
+export declare const RESET = "\u001B[0m";
+export declare const FAINT = "\u001B[2m";
+/** nearest xterm-256 color: grays get the 24-step ramp, everything else the 6x6x6 cube */
+export declare function rgbTo256([r, g, b]: RGB): number;
+export declare function fg(c: RGB, depth: ColorDepth): string;
+export declare function bg(c: RGB | null, depth: ColorDepth): string;
+/**
+ * Builds one line from cells, writing a code only when it changes.
+ * `code(i)` gives the code for cell i ('' for the default color); spaces keep the current code.
+ */
+export declare function line(chars: (i: number) => string, code: (i: number) => string, from: number, count: number, background?: string): string;

package/dist/ansi.js

@@ -0,0 +1,46 @@
+export const RESET = '\x1b[0m';
+export const FAINT = '\x1b[2m';
+/** nearest xterm-256 color: grays get the 24-step ramp, everything else the 6x6x6 cube */
+export function rgbTo256([r, g, b]) {
+    if (Math.abs(r - g) < 10 && Math.abs(g - b) < 10) {
+        const v = (r + g + b) / 3;
+        if (v < 8)
+            return 16;
+        if (v > 238)
+            return 231;
+        return 232 + Math.round(((v - 8) / 230) * 23);
+    }
+    const q = (x) => Math.round((x / 255) * 5);
+    return 16 + 36 * q(r) + 6 * q(g) + q(b);
+}
+export function fg(c, depth) {
+    if (depth === 'none')
+        return '';
+    return depth === 'truecolor' ? `\x1b[38;2;${c[0]};${c[1]};${c[2]}m` : `\x1b[38;5;${rgbTo256(c)}m`;
+}
+export function bg(c, depth) {
+    if (!c || depth === 'none')
+        return '';
+    return depth === 'truecolor' ? `\x1b[48;2;${c[0]};${c[1]};${c[2]}m` : `\x1b[48;5;${rgbTo256(c)}m`;
+}
+/**
+ * Builds one line from cells, writing a code only when it changes.
+ * `code(i)` gives the code for cell i ('' for the default color); spaces keep the current code.
+ */
+export function line(chars, code, from, count, background = '') {
+    let s = background, cur = '';
+    for (let i = from; i < from + count; i++) {
+        const ch = chars(i);
+        if (ch !== ' ') {
+            const c = code(i);
+            if (c !== cur) {
+                s += cur ? RESET + background + c : c;
+                cur = c;
+            }
+        }
+        s += ch;
+    }
+    if (cur || background)
+        s += RESET;
+    return s;
+}

package/dist/browser/player-core.d.ts

@@ -0,0 +1,23 @@
+import type { Recording } from '../format.ts';
+/** what goes into the <pre> for one frame: plain text when the file has no styles, otherwise HTML */
+export interface Markup {
+    html: boolean;
+    content: string;
+}
+export declare function frameMarkup(rec: Recording, index: number): Markup;
+/** the accessible name: an explicit label, the file's title, or a generic one */
+export declare function accessibleLabel(rec: Recording | null, label: string | null): string;
+/** frame position after `dt` seconds; gaps longer than 0.1 s (tab switches) do not jump ahead */
+export declare function advance(pos: number, dt: number, fps: number, frames: number): number;
+/** dragging across the whole width moves through the whole loop once */
+export declare function scrub(pos: number, dx: number, width: number, frames: number): number;
+/**
+ * How to show a grid of `cols`×`rows` cells drawn in a font whose cells measure `cellW`×`cellH`,
+ * so it fills `boxW`×`boxH` (boxH 0 = width decides) with the proportions it was rendered for:
+ * `stretchY` corrects the font's cell shape to the file's `aspect`, `scale` fits the result.
+ */
+export declare function fit(cols: number, rows: number, aspect: number, cellW: number, cellH: number, boxW: number, boxH: number): {
+    scale: number;
+    stretchY: number;
+    ratio: number;
+};

package/dist/browser/player-core.js

@@ -0,0 +1,68 @@
+const esc = (ch) => (ch === '<' ? '&lt;' : ch === '>' ? '&gt;' : ch === '&' ? '&amp;' : ch);
+export function frameMarkup(rec, index) {
+    const { width: W, height: H, glyphs, styles } = rec, fr = rec.frames[index];
+    if (!styles || !fr.style) {
+        let s = '';
+        for (let r = 0; r < H; r++) {
+            for (let c = 0; c < W; c++)
+                s += glyphs[fr.glyph[r * W + c]];
+            if (r < H - 1)
+                s += '\n';
+        }
+        return { html: false, content: s };
+    }
+    // one span per run of cells with the same style; spaces never open a span
+    const open = styles.map((st) => (st === '' ? '' : st === '~' ? '<span class="d">' : `<span style="color:${st}">`));
+    let s = '';
+    for (let r = 0; r < H; r++) {
+        let cur = 0;
+        for (let c = 0; c < W; c++) {
+            const i = r * W + c, ch = glyphs[fr.glyph[i]];
+            if (ch !== ' ') {
+                const st = fr.style[i];
+                if (st !== cur) {
+                    if (cur)
+                        s += '</span>';
+                    s += open[st];
+                    cur = st;
+                }
+            }
+            s += esc(ch);
+        }
+        if (cur)
+            s += '</span>';
+        if (r < H - 1)
+            s += '\n';
+    }
+    return { html: true, content: s };
+}
+/** the accessible name: an explicit label, the file's title, or a generic one */
+export function accessibleLabel(rec, label) {
+    if (label)
+        return label;
+    const t = rec?.meta.title;
+    return typeof t === 'string' && t ? `${t}, ASCII animation` : 'ASCII animation';
+}
+/** frame position after `dt` seconds; gaps longer than 0.1 s (tab switches) do not jump ahead */
+export function advance(pos, dt, fps, frames) {
+    return (pos + Math.min(Math.max(dt, 0), 0.1) * fps) % frames;
+}
+/** dragging across the whole width moves through the whole loop once */
+export function scrub(pos, dx, width, frames) {
+    if (!(width > 0))
+        return pos;
+    return (((pos + (dx / width) * frames) % frames) + frames) % frames;
+}
+/**
+ * How to show a grid of `cols`×`rows` cells drawn in a font whose cells measure `cellW`×`cellH`,
+ * so it fills `boxW`×`boxH` (boxH 0 = width decides) with the proportions it was rendered for:
+ * `stretchY` corrects the font's cell shape to the file's `aspect`, `scale` fits the result.
+ */
+export function fit(cols, rows, aspect, cellW, cellH, boxW, boxH) {
+    const stretchY = cellW > 0 && cellH > 0 ? (aspect * cellW) / cellH : 1;
+    const w = cols * cellW, h = rows * cellH * stretchY;
+    if (!(w > 0 && h > 0))
+        return { scale: 1, stretchY, ratio: 1 };
+    const scale = boxH > 0 ? Math.min(boxW / w, boxH / h) : boxW / w;
+    return { scale, stretchY, ratio: w / h };
+}

package/dist/browser/player.d.ts

@@ -0,0 +1,25 @@
+import { type FramesFile, type Recording } from '../format.ts';
+declare const Base: typeof HTMLElement;
+export declare class TextelPlayer extends Base {
+    #private;
+    static observedAttributes: string[];
+    constructor();
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    attributeChangedCallback(name: string, old: string | null, value: string | null): void;
+    /** the loaded recording; set it directly to play one without a file */
+    get recording(): Recording | null;
+    set recording(rec: Recording | FramesFile | null);
+    /** current frame index */
+    get frame(): number;
+    set frame(i: number);
+    get paused(): boolean;
+    play(): void;
+    pause(): void;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'textel-player': TextelPlayer;
+    }
+}
+export {};

package/dist/browser/player.js

@@ -0,0 +1,198 @@
+// <textel-player>: plays a .textel.json file. No dependencies; no 3D code.
+//
+//   <script type="module" src="https://cdn.jsdelivr.net/npm/@feelgxxd/textel@0.2/dist/textel-player.js"></script>
+//   <textel-player src="logo.textel.json"></textel-player>
+import { fromFramesFile } from "../format.js";
+import { accessibleLabel, advance, fit, frameMarkup, scrub } from "./player-core.js";
+const CSS = `:host{display:block;position:relative;overflow:hidden;aspect-ratio:var(--textel-ratio,auto);min-height:1px;font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,monospace}
+:host(:not([nodrag])){cursor:grab;touch-action:pan-y}
+:host(:not([nodrag]):active){cursor:grabbing}
+pre{position:absolute;left:50%;top:50%;margin:0;transform-origin:50% 50%;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}
+.d{opacity:var(--textel-dim-opacity,.6)}`;
+// Lets the module load where there is no DOM (server rendering, type imports).
+const Base = (typeof HTMLElement === 'undefined' ? class {
+} : HTMLElement);
+export class TextelPlayer extends Base {
+    static observedAttributes = ['src', 'fps', 'paused', 'color', 'label'];
+    #rec = null;
+    #markup = [];
+    #pre;
+    #pos = 0;
+    #shown = -1;
+    #playing = true;
+    #visible = true;
+    #raf = 0;
+    #last = 0;
+    #drag = 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');
+        root.append(style, this.#pre);
+        this.addEventListener('pointerdown', this.#onDown);
+        this.addEventListener('pointermove', this.#onMove);
+        this.addEventListener('pointerup', this.#onUp);
+        this.addEventListener('pointercancel', this.#onUp);
+    }
+    connectedCallback() {
+        this.setAttribute('role', 'img');
+        this.#updateLabel();
+        this.#playing = !this.hasAttribute('paused') && !this.#reduced;
+        // both are optional: without them the player just keeps running and fits once
+        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.#fit());
+            this.#ro.observe(this);
+        }
+        document.addEventListener('visibilitychange', this.#kick);
+        document.fonts?.ready.then(() => this.#fit());
+        this.#kick();
+    }
+    disconnectedCallback() {
+        this.#io?.disconnect();
+        this.#ro?.disconnect();
+        document.removeEventListener('visibilitychange', this.#kick);
+        cancelAnimationFrame(this.#raf);
+        this.#raf = 0;
+    }
+    attributeChangedCallback(name, old, value) {
+        if (old === value)
+            return;
+        if (name === 'src') {
+            if (value)
+                this.#fetch(value);
+        }
+        else if (name === 'paused') {
+            value === null ? this.play() : this.pause();
+        }
+        else if (name === 'color')
+            this.#pre.style.color = value ?? '';
+        else if (name === 'label')
+            this.#updateLabel();
+    }
+    /** the loaded recording; set it directly to play one without a file */
+    get recording() { return this.#rec; }
+    set recording(rec) {
+        this.#rec = rec && 'data' in rec ? fromFramesFile(rec) : rec;
+        this.#markup = [];
+        this.#pos = 0;
+        this.#shown = -1;
+        this.#updateLabel();
+        this.#draw();
+        this.#fit();
+        this.#kick();
+    }
+    /** current frame index */
+    get frame() { return Math.floor(this.#pos); }
+    set frame(i) {
+        const n = this.#rec?.frames.length ?? 1;
+        this.#pos = ((Math.floor(i) % n) + n) % n;
+        this.#draw();
+    }
+    get paused() { return !this.#playing; }
+    play() { this.#playing = true; this.#kick(); }
+    pause() { this.#playing = false; this.#kick(); }
+    async #fetch(src) {
+        this.#load?.abort();
+        const ac = (this.#load = new AbortController());
+        try {
+            const res = await fetch(src, { signal: ac.signal });
+            if (!res.ok)
+                throw new Error(`${res.status} ${res.statusText} for ${src}`);
+            const file = await res.json();
+            if (ac.signal.aborted)
+                return;
+            this.recording = fromFramesFile(file);
+            this.dispatchEvent(new CustomEvent('load', { detail: { frames: this.#rec.frames.length } }));
+        }
+        catch (error) {
+            if (ac.signal.aborted)
+                return;
+            this.dispatchEvent(new CustomEvent('error', { detail: { error } }));
+        }
+    }
+    #updateLabel() {
+        if (this.isConnected)
+            this.setAttribute('aria-label', accessibleLabel(this.#rec, this.getAttribute('label')));
+    }
+    #fps() {
+        const a = Number(this.getAttribute('fps'));
+        return a > 0 ? a : this.#rec?.fps ?? 30;
+    }
+    #draw() {
+        const rec = this.#rec;
+        if (!rec)
+            return;
+        const i = Math.floor(this.#pos) % rec.frames.length;
+        if (i === this.#shown)
+            return;
+        this.#shown = i;
+        const m = (this.#markup[i] ??= frameMarkup(rec, i));
+        if (m.html)
+            this.#pre.innerHTML = m.content;
+        else
+            this.#pre.textContent = m.content;
+    }
+    #fit() {
+        const rec = this.#rec;
+        if (!rec)
+            return;
+        const pre = this.#pre, cellW = pre.offsetWidth / rec.width, cellH = pre.offsetHeight / rec.height;
+        const f = fit(rec.width, rec.height, rec.aspect, cellW, cellH, this.clientWidth, this.clientHeight);
+        this.style.setProperty('--textel-ratio', String(f.ratio));
+        pre.style.transform = `translate(-50%,-50%) scale(${f.scale},${f.scale * f.stretchY})`;
+    }
+    /** runs the animation only while it is playing, on screen and in a visible tab */
+    #kick = () => {
+        const run = this.#playing && this.#visible && !document.hidden && !!this.#rec && !this.#drag && this.isConnected;
+        if (run && !this.#raf) {
+            // the first tick only sets the clock: time is measured between frame timestamps alone,
+            // never mixed with performance.now(), whose reading can be later than the next frame's
+            this.#last = -1;
+            this.#raf = requestAnimationFrame(this.#tick);
+        }
+        else if (!run && this.#raf) {
+            cancelAnimationFrame(this.#raf);
+            this.#raf = 0;
+        }
+    };
+    #tick = (now) => {
+        const rec = this.#rec;
+        if (this.#last >= 0)
+            this.#pos = advance(this.#pos, (now - this.#last) / 1000, this.#fps(), rec.frames.length);
+        this.#last = now;
+        this.#draw();
+        this.#raf = requestAnimationFrame(this.#tick);
+    };
+    #onDown = (e) => {
+        if (this.hasAttribute('nodrag') || !this.#rec || e.button !== 0)
+            return;
+        this.#drag = { x: e.clientX, pos: this.#pos };
+        this.setPointerCapture(e.pointerId);
+        this.#kick();
+    };
+    #onMove = (e) => {
+        if (!this.#drag || !this.#rec)
+            return;
+        this.#pos = scrub(this.#drag.pos, e.clientX - this.#drag.x, this.clientWidth, this.#rec.frames.length);
+        this.#draw();
+    };
+    #onUp = () => {
+        if (!this.#drag)
+            return;
+        this.#drag = null;
+        this.#kick();
+    };
+}
+if (typeof customElements !== 'undefined' && !customElements.get('textel-player'))
+    customElements.define('textel-player', TextelPlayer);

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;
+}